Skip to content
ESP3D Logo ESP3D Ecosystem

Web Handlers

/ (GET)

Section titled “/ (GET)”

The root is the default handler where all files are served. If no file is defined, it looks for index.html or index.html.gz (compressed). If you call a specific file, it looks for filename and filename.gz (compressed). If no file is defined and there is no index.html(.gz), it displays the embedded page. Another way to show the embedded page is /?forcefallback=yes.

/sd/ (GET)

Section titled “/sd/ (GET)”

It serves any file from the SD card if present. It is only a wrapper for SD card reading; no upload.

/files (GET/POST)

Section titled “/files (GET/POST)”

This handler processes all commands for the file system (FS), including uploads.
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 uploading, if the path does not exist, it is created (POST only)
  • &lt;filename&gt;S=... give the size of uploaded file with <filename> name, must be set before the file is uploaded, POST only

The output is a JSON object:

{
    "files":[ //the file list
        {
            "name":"index.html.gz", //the name of the file
            "size":"83.46 KB", //the formatted size of the file
            "time":"2022-09-04 11:56:05" //the last modification time, this one is optional and depends 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, depends on (FILESYSTEM_TIMESTAMP_FEATURE)
        }
    ],
    "path":"/", //current path
    "occupation":"52", //occupation in %
    "status":"subdir created", //status
    "total":"192.00 KB", //Formatted total filesystem space
    "used":"100.00 KB" //Formatted used filesystem space
}

/sdfiles (GET/POST) )

Section titled “/sdfiles (GET/POST) )”

This handler processes all commands for SD, including uploads to SD (shared and direct SD only).
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 Refreshes file statistics
    • 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 uploading, if the path does not exist, it is created (POST only)
  • &lt;filename&gt;S=... give the size of uploaded file with <filename> name, must be set before the file is uploaded, POST only

The output is a JSON object:

{
    "files":[ //the file list
        {
            "name":"3Oc-pika2.gco",//the name of the file
            "shortname":"3Oc-pika2.gco", //the 8.3 short name if available; otherwise the file name
            "size":"83.46 KB", //the formatted size of the file
            "time":"2022-09-04 11:56:05" //the last modification time, this one is optional and depends 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, depends on (SD_TIMESTAMP_FEATURE)
        }
    ],
    "path":"/", //current path
    "occupation":"52", //occupation in %
    "status":"subdir created", //status
    "total":"192.00 KB", //Formatted total filesystem space
    "used":"100.00 KB" //Formatted used filesystem space
}

/upload (POST)

Section titled “/upload (POST)”

This handler is for MKS boards (when the MKS protocol is enabled). It handles SD uploads only.

/command (GET)

Section titled “/command (GET)”

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 (GET/POST)

Section titled “/login (GET/POST)”

This handler manages authentication when 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:

  • if authenticated 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

/config (GET)

Section titled “/config (GET)”

this handler is a shortcut to [ESP420] command in text mode, to get output in json add json=yes

/updatefw (GET/POST)

Section titled “/updatefw (GET/POST)”

This handler is for firmware upload and update. Response output is: \{"status":"..."\} if upload is successful the ESP will restart

/snap (GET)

Section titled “/snap (GET)”

This handler is for ESP32-CAM with camera enabled to capture a frame. It responds by sending a JPG image.

/description.xml (GET)

Section titled “/description.xml (GET)”

This handler is for SSDP (if enabled) to present device information.

<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

Section titled “Captive portal bypass handlers”

To avoid redirecting to index.html (and therefore refreshing the page), some classic handlers have been added; they all point to /.

  • /generate_204
  • /gconnectivitycheck.gstatic.com
  • /fwlink/