Update documentation

Remove SDFat2 warning
Add several sanity check
Fix some edge cases in authentication process
Remove debug messages
Clarify some status in http handler responses

Author: luc-github

docs/Commands.md

@@ -300,9 +300,9 @@ label can be: light/framesize/quality/contrast/brightness/saturation/gainceiling
 
 * Get state / Set Enable / Disable Serial Bridge Communication   
     `[ESP930]<ENABLE/DISABLE> json=<no> pwd=<admin/user password>`    
+
 * Get / Set Serial Bridge Baud Rate
     `[ESP931]<BAUD RATE> json=<no> pwd=<admin/user password>`
 
-
 * Set quiet boot if strapping pin is High   
     `[ESP999]QUIETBOOT pwd=<admin/user password>`

docs/Handlers.md

@@ -1,43 +1,161 @@
-# Web Handlers in ESP3D
+# Web Handlers 
 
-#### /
+### /
 root is the default handler where all files will be served, if no file is defined, it looks for index.html or index.html.gz (compressed)
 if you call specific file, it will look for the filename and filename.gz (compressed)
 if no file is defined and there is not index.html(.gz) it will display embedded page
 another way to show the embedded page is /?forcefallback=yes
 
-#### /sd/
-it will serve any file from SD card if there is one
+### /sd/
+it will serve any file from SD card if there is one, it is only a wrapper to read SD card, no upload
 
-#### /files
-this handler handle all commands for FS, including upload on FS
+### /files
+this handler handle all commands for FS, including upload on FS.   
+    possible options/arguments are:   
+- `quiet=yes` can be used when you don't want list files but just upload them    
+- `path=...` define the path to the file    
+- `action=...` define the action to execute which can be:  
+        - delete   
+            delete the file defined by `filename=...` it will also use `path=...` to do full path  
+        - deletedir  
+            delete the directory defined by `filename=...` it will also use `path=...` to do full path    
+        - createdir
+             create the directory defined by `filename=...` it will also use `path=...` to do full path  
+- `createPath=yes` when doing upload and the path do not exists, it will create it, POST only
+- `<filename>S=...` give the size of uploaded file with <filename> name, need to be set before file is set in upload, POST only   
 
-#### /sdfiles
+the output is a json file:  
+
+    ```
+    {   
+        "files":[ //the files list  
+            {  
+                "name":"index.html.gz", //the name of the file
+                "size":"83.46 KB", //the formated size of the file 
+                "time":"2022-09-04 11:56:05" //the time when the file was modified last time, this one is optional and depend on (FILESYSTEM_TIMESTAMP_FEATURE)
+            },
+            {
+                "name":"subdir", //the name of the file / directory
+                "size":"-1", //the size is -1 because it is a directory
+                "time":"" //no time for directories optional as depend on (FILESYSTEM_TIMESTAMP_FEATURE)
+            }
+        ],
+        "path":"/", //current path
+        "occupation":"52", //% of occupation
+        "status":"subdir created", //status 
+        "total":"192.00 KB", //Formated total space of Filesystem
+        "used":"100.00 KB" //Formated used space of Filesystem
+    }
+    ```
+### /sdfiles
 this handler handle all commands for SD, including upload on SD (only shared and direct SD)
+this handler handle all commands for FS, including upload on FS.   
+    possible options/arguments are:   
+- `quiet=yes` can be used when you don't want list files but just upload them    
+- `path=...` define the path to the file    
+- `action=...` define the action to execute which can be:  
+        - list
+            Will refresh the stats of the files
+        - delete   
+            delete the file defined by `filename=...` it will also use `path=...` to do full path  
+        - deletedir  
+            delete the directory defined by `filename=...` it will also use `path=...` to do full path    
+        - createdir
+             create the directory defined by `filename=...` it will also use `path=...` to do full path  
+- `createPath=yes` when doing upload and the path do not exists, it will create it, POST only
+- `<filename>S=...` give the size of uploaded file with <filename> name, need to be set before file is set in upload, POST only   
+
+the output is a json file:   
 
-#### /upload
-this handler is for MKS boards using MKS communication protocol if enabled, it handle all commands for SD, including upload on SD 
+    ```
+    {
+        "files":[ //the files list
+            {
+                "name":"3Oc-pika2.gco",//the name of the file
+                "shortname":"3Oc-pika2.gco", //the 8.3 shortname if available, if not the name of the file
+                "size":"83.46 KB", //the formated size of the file 
+                "time":"2022-09-04 11:56:05" //the time when the file was modified last time, this one is optional and depend on (SD_TIMESTAMP_FEATURE)
+            },
+            {
+                "name":"subdir", //the name of the file / directory
+                "size":"-1", //the size is -1 because it is a directory
+                "time":"" //no time for directories optional as depend on (SD_TIMESTAMP_FEATURE)
+            }
+        ],
+        "path":"/", //current path
+        "occupation":"52", //% of occupation
+        "status":"subdir created", //status 
+        "total":"192.00 KB", //Formated total space of Filesystem
+        "used":"100.00 KB" //Formated used space of Filesystem
+    }
+    ```
+### /upload
+this handler is for MKS boards using MKS communication protocol if enabled, it handle only upload on SD    
 
-#### /command
-this handler is for all commands 
+### /command
+this handler is for all commands the parameter is `cmd=...`
+if it is an `[ESPXXX]` command the answer is the `[ESPXXX]` response
+if it is not an `[ESPXXX]` command the answer is `ESP3D says: command forwarded` and can be ignored
 
-#### /login 
+### /login 
 this handler is for authentication function if enabled
+    possible options/arguments are:  
+        - `DISCONNECT=YES`
+            it will clear current session, remove authentication cookie, set status to `disconnected` and response code to 401
+        - `SUBMIT=YES`
+            to login it will need also `PASSWORD=...` and `USER=...`, the answer will be 200 if success and 401 if failed
+            if user is already authenticated it can use `NEWPASSWORD=...` instead of `PASSWORD=...` to change his password, if successful answer will be returned with code 200, otherwise code will be 500 if change failed or if password format is invalid
+
+Output:
 
-#### /config 
-this handler is a shortcut to [ESP420] command
+- if authentified and no submission:   
+    `{"status":"Identified","authentication_lvl":"admin"}` and code 200
+- if not authenticated and no submission:  
+    `{"status":"Wrong authentication!","authentication_lvl":"guest"}` and code 401
 
-#### /updatefw
+
+### /config 
+this handler is a shortcut to [ESP420] command in text mode, to get output in json add `json=yes`
+
+### /updatefw
 this handler is for FW upload and update
+Answer output is :
+`{"status":"..."}` if upload is successful the ESP will restart
 
-#### /snap
+### /snap
 this handler is on esp32cam with camera enabled to capture a Frame
+it answer by sending a jpg image 
 
-#### /description.xml
-this handler is for SSDP if enabled to present device informations
+### /description.xml
+this handler is for SSDP if enabled to present device informations  
 
-#### Captive portal bypass handlers
+```
+<root xmlns="urn:schemas-upnp-org:device-1-0">
+    <specVersion>
+        <major>1</major>
+        <minor>0</minor>
+    </specVersion>
+    <URLBase>http://192.168.2.178:80/</URLBase>
+    <device>
+        <deviceType>urn:schemas-upnp-org:device:upnp:rootdevice:1</deviceType>
+        <friendlyName>esp3d</friendlyName>
+        <presentationURL>/</presentationURL>
+        <serialNumber>52332</serialNumber>
+        <modelName>ESP Board</modelName>
+        <modelDescription/>
+        <modelNumber>ESP3D 3.0</modelNumber>
+        <modelURL>https://www.espressif.com/en/products/devkits</modelURL>
+        <manufacturer>Espressif Systems</manufacturer>
+        <manufacturerURL>https://www.espressif.com</manufacturerURL>
+        <UDN>uuid:38323636-4558-4dda-9188-cda0e600cc6c</UDN>
+        <serviceList/>
+        <iconList/>
+    </device>
+</root>
+```
+### Captive portal bypass handlers
 to avoid a redirect to index.html and so a refresh of the page, some classic handler have been added so they all go to / handler actually
  - /generate_204
  - /gconnectivitycheck.gstatic.com
  - /fwlink/
+

esp3d/src/include/version.h

@@ -22,7 +22,7 @@
 #define _VERSION_ESP3D_H
 
 //version and sources location
-#define FW_VERSION "3.0.0.a210"
+#define FW_VERSION "3.0.0.a211"
 #define REPOSITORY "https://github.com/luc-github/ESP3D/tree/3.0"
 
 #endif //_VERSION_ESP3D_H

esp3d/src/modules/http/handles/handle-SD-files.cpp

@@ -48,8 +48,8 @@ void HTTP_Server::handleSDFileList ()
 
     if (_webserver->hasArg ("quiet")) {
         if(_webserver->arg ("quiet") == "yes") {
-            Serial.println("quiet");
-            _webserver->send (200, "text/plain", "{\"status\":\"ok\"}");
+            status = "{\"status\":\"" + status + "\"}";
+            _webserver->send (200, "text/plain", status.c_str());
             return;
         }
     }
@@ -184,11 +184,13 @@ void HTTP_Server::handleSDFileList ()
                 }
 #ifdef FILESYSTEM_TIMESTAMP_FEATURE
                 buffer2send+="\",\"time\":\"";
-                time_t t = sub.getLastWrite();
-                struct tm * tmstruct = localtime(&t);
-                char str[20]; //buffer should be 20
-                sprintf(str,"%d-%02d-%02d %02d:%02d:%02d",(tmstruct->tm_year)+1900,( tmstruct->tm_mon)+1, tmstruct->tm_mday,tmstruct->tm_hour, tmstruct->tm_min, tmstruct->tm_sec);
-                buffer2send+=str;
+                if (!sub.isDirectory()) {
+                    time_t t = sub.getLastWrite();
+                    struct tm * tmstruct = localtime(&t);
+                    char str[20]; //buffer should be 20
+                    sprintf(str,"%d-%02d-%02d %02d:%02d:%02d",(tmstruct->tm_year)+1900,( tmstruct->tm_mon)+1, tmstruct->tm_mday,tmstruct->tm_hour, tmstruct->tm_min, tmstruct->tm_sec);
+                    buffer2send+=str;
+                }
 #endif //FILESYSTEM_TIMESTAMP_FEATURE
                 buffer2send+="\"}";
                 if (buffer2send.length() > 1100) {

esp3d/src/modules/http/handles/handle-config.cpp

@@ -35,6 +35,9 @@ void HTTP_Server::handle_config ()
 {
     level_authenticate_type auth_level = AuthenticationService::authenticated_level();
     String cmd = "[ESP420]";
+    if (_webserver->hasArg("json")) {
+        cmd = "[ESP420]json="+_webserver->arg("json");
+    }
     ESP3DOutput  output(_webserver);
     output.printMSGLine("<pre>");
     esp3d_commands.process((uint8_t*)cmd.c_str(), cmd.length(), &output, auth_level);

esp3d/src/modules/http/handles/handle-files.cpp

@@ -50,8 +50,8 @@ void HTTP_Server::handleFSFileList ()
     }
     if (_webserver->hasArg ("quiet")) {
         if(_webserver->arg ("quiet") == "yes") {
-            Serial.println("quiet");
-            _webserver->send (200, "text/plain", "{\"status\":\"ok\"}");
+            status = "{\"status\":\"" + status + "\"}";
+            _webserver->send (200, "text/plain", status.c_str());
             return;
         }
     }
@@ -165,7 +165,9 @@ void HTTP_Server::handleFSFileList ()
                 }
 #ifdef FILESYSTEM_TIMESTAMP_FEATURE
                 buffer2send+="\",\"time\":\"";
-                buffer2send+=timeserver.current_time(sub.getLastWrite());
+                if (!sub.isDirectory()) {
+                    buffer2send+=timeserver.current_time(sub.getLastWrite());
+                }
 #endif //FILESYSTEM_TIMESTAMP_FEATURE
                 buffer2send+="\"}";
                 if (buffer2send.length() > 1100) {

esp3d/src/modules/http/handles/handle-login.cpp

@@ -37,7 +37,7 @@ void HTTP_Server::handle_login()
     int code = 401;
     String status = "Wrong authentication!";
     //Disconnect can be done anytime no need to check credential
-    if (_webserver->hasArg("DISCONNECT")) {
+    if (_webserver->hasArg("DISCONNECT") && _webserver->arg("DISCONNECT")=="YES") {
         AuthenticationService::ClearCurrentSession();
         _webserver->sendHeader("Set-Cookie","ESPSESSIONID=0");
         _webserver->sendHeader("Cache-Control","no-cache");
@@ -96,7 +96,12 @@ void HTTP_Server::handle_login()
                 }
             }
         }
-    }//SUBMIT
+    } else {
+        if (auth_level == LEVEL_USER || auth_level == LEVEL_ADMIN) {
+            status = "Identified";
+            code = 200;
+        }
+    }
     _webserver->sendHeader("Cache-Control","no-cache");
     String smsg = "{\"status\":\"";
     smsg+=status;
@@ -110,6 +115,7 @@ void HTTP_Server::handle_login()
     }
     smsg += "\"}";
     _webserver->send(code, "application/json", smsg);
+    return;
 #else // No AUTHENTICATION_FEATURE
     _webserver->sendHeader("Cache-Control","no-cache");
     _webserver->send(200, "application/json", "{\"status\":\"ok\",\"authentication_lvl\":\"admin\"}");

esp3d/src/modules/http/handles/handle-updatefw.cpp

@@ -38,7 +38,20 @@ void HTTP_Server::handleUpdate ()
         return;
     }
     String jsonfile = "{\"status\":\"" ;
-    jsonfile += String(_upload_status);
+    switch(_upload_status) {
+    case  UPLOAD_STATUS_NONE :
+        jsonfile += "no file";
+        break;
+    case  UPLOAD_STATUS_CANCELLED :
+        jsonfile += "canceled";
+        break;
+    case  UPLOAD_STATUS_SUCCESSFUL :
+        jsonfile += "ok";
+        break;
+    default :
+        jsonfile += "error";
+        break;
+    }
     jsonfile += "\"}";
     _webserver->sendHeader("Cache-Control", "no-cache");
     _webserver->send(200, "application/json", jsonfile);

esp3d/src/modules/network/netservices.cpp

@@ -261,6 +261,10 @@ bool NetServices::begin()
         SSDP.setSerialNumber (stmp.c_str());
         //Any customization could be here
         SSDP.setModelName (ESP_MODEL_NAME);
+#if defined(ESP_MODEL_DESCRIPTION)
+        //this one is optional because windows doesn't care about this field
+        SSDP.setModelDescription(ESP_MODEL_DESCRIPTION);
+#endif //ESP_MODEL_DESCRIPTION
         SSDP.setModelURL (ESP_MODEL_URL);
         SSDP.setModelNumber (ESP_MODEL_NUMBER);
         SSDP.setManufacturer (ESP_MANUFACTURER_NAME);

esp3d/src/modules/network/netservices.h

@@ -34,11 +34,6 @@ class NetServices
     {
         return _started;
     }
-    static void start()
-    {
-        _restart=true;
-        Serial.println("Restarting netservices");
-    }
 private:
     static bool _started;
     static bool _restart;