ESP3D API

Web Handlers

/ (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.

/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
<filename>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 formatted size of the file
            "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
}

/upload_serial (POST)

this handler is for uploading files to printer SD using M28/M29 protocol

/command (GET)

This handler is for all commands. The parameter is commandText=... 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

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

/config (GET)

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

/updatefw (POST)

This handler is for firmware upload and update.

/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

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/

Web Socket

Only for WebUI not for bridge data

use subprotocol arduino and web port +1 (e.g: 80+1=>81)

text mode

Reserved Messages between WebUI / ESP Format: <label>:<message>

from ESP to WebUI
- CURRENT_ID:<id> Sent when client is connecting, it is the last ID used and become the active ID
- ACTIVE_ID:<id> Broadcast current active ID, when new client is connecting, client without this is <id> should close, ESP WS Server close all open WS connections but this one also
- ERROR:<code>:<message> If an error raise when doing upload, it informs client it must stop uploading because sometimes the http answer is not possible, or cannot cancel the upload, this is a workaround as there is no API in current webserver to cancel active upload
- DHT: <value>C The DHT sensor connected to ESP like DHT22

binary mode

Reserved

from ESP to WebUI serial stream data from ESP to WebUI
from WEBUI to ESP
[Not used]