API
- Web Handlers
Web handlers description and parameters
- Web Sockets
Web Sockets description, messages and parameters
Web handlers description and parameters
Web Sockets description, messages and parameters
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
it will serve any file from SD card if there is one, it is only a wrapper to read SD card, no upload
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 thempath=...
define the path to the fileaction=...
define the action to execute which can be:filename=...
it will also use path=...
to do full pathfilename=...
it will also use path=...
to do full path filename=...
it will also use path=...
to do full pathcreatePath=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 name, need to be set before file is set in upload, POST onlythe output is a json file:
```json
{
"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
}
```
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 thempath=...
define the path to the fileaction=...
define the action to execute which can be:filename=...
it will also use path=...
to do full pathfilename=...
it will also use path=...
to do full path filename=...
it will also use path=...
to do full pathcreatePath=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 name, need to be set before file is set in upload, POST onlythe output is a json file:
```json
{
"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
}
```
this handler is for MKS boards using MKS communication protocol if enabled, it handle only upload on SD
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
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:
{"status":"Identified","authentication_lvl":"admin"}
and code 200{"status":"Wrong authentication!","authentication_lvl":"guest"}
and code 401this handler is a shortcut to [ESP420] command in text mode, to get output in json add json=yes
this handler is for FW upload and update
Answer output is :
{"status":"..."}
if upload is successful the ESP will restart
this handler is on esp32cam with camera enabled to capture a Frame it answer by sending a jpg image
this handler is for SSDP if enabled to present device informations
<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>
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
there are 2
terminal websocket used to stream data to webUI and exchange internal data
data websocket used to exchange data with external client (not used by WebUI)
use subprotocol webui-v3
and port is web port +1 (e.g: 80+1=>81)
Reserved
messages between webui / ESP
Format: <label>:<message>
from ESP to WebUI
currentID:<id>
Sent when client is connecting, it is the last ID used and become the active ID
activeID:<id>
Broadcast current active ID, when new client is connecting, client without this is should close, ESP WS Server close all open WS connections but this one also
PING:<time left>:<time out>
It is a response to PING from client to inform the time left if no activity (see below)
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
NOTIFICATION:<message>
Forward the message sent by [ESP600] to webUI toast system
SENSOR: <value>[<unit>] <value2>[<unit2>] ...
The sensor connected to ESP like DHT22
from WebUI to ESP
PING:<current cookiesessionID / none >
if any, or “none” if noneReserved
from ESP to WebUI stream data from ESP to WebUI
from WEBUI to ESP
[-> File transfert from WebUI to ESP : not implemented yet]
use sub protocol arduino
and port is any defined port (e.g: 8282)
This mode is used to transfert all GCODE commands and their answers from printer/cnc
This mode is used to transfert files to / from esp board
it use frame of 1024 bytes, can be increased after test
the frame format is : 2 bytes: for frame type 2 bytes: for frame size to check some integrity, currently as already part of frame no checksume is used x bytes : extra data according frame type
type: client -> esp Status Request
S |
R |
0 | 0 |
---|
with hexadecimal values:
0x53 | 0x52 | 0 | 0 |
---|
Response frame use inverted header: Response Status
R |
S |
0 | 1 | A |
---|
with hexadecimal values:
0x52 | 0x53 | 0 | 1 | 0x41 |
---|
the first byte of answer is the state
Code | Hexa | Meaning |
---|---|---|
B |
0x42 | busy |
O |
0x4F | idle/ok |
E |
0x45 | error |
A |
0x41 | abort |
D |
0x44 | download ongoing |
U |
0x55 | upload ongoing |
extra data may be added :
error code and string, 1 byte : error code: 0->255 1 byte : string size 0->255 XX bytes for the string
R |
S |
x | x | C |
4 | X | .. | .. |
---|
Upload informations: 1 byte : path size 0->255 XX bytes : the path string 1 byte : the filename size 0->255 xx bytes : filename string 4 bytes : total file size 4 bytes : currently processed bytes 4 bytes : last packet id processed
R |
S |
x | x | U |
X | .. | .. | X | .. | .. | S1 | S1 | S1 | S1 | S2 | S2 | S2 | S2 |
---|
Download informations: 1 byte : path size 0->255 XX bytes : the path string 1 byte : the filename size 0->255 xx bytes : filename string 4 bytes : total file size 4 bytes : currently processed bytes 4 bytes : last packet id processed
R |
S |
x | x | D |
X | .. | .. | X | .. | .. | S1 | S1 | S1 | S1 | S2 | S2 | S2 | S2 |
---|
header is :
S |
U |
0 | 0 |
---|
the content is: 1 byte : path size 0->255 XX bytes : the path string 1 byte : the filename size 0->255 xx bytes : filename string 4 bytes : total file size
S |
U |
x | x | D |
X | .. | .. | X | .. | .. | S1 | S1 | S1 | S1 |
---|
if answer is :
U |
S |
0 | 1 | O |
---|
it means transfert can start
header is :
U |
P |
x | x | ID | ID | ID | ID | .. | .. |
---|
4 bytes is packet id XXXX bytes is data
if packet is received the answer is
P |
U |
0 | 5 | O |
ID | ID | ID | ID |
---|
header is :
S |
D |
0 | 0 |
---|
the content is: 1 byte : path size 0->255 XX bytes : the path string 1 byte : the filename size 0->255 xx bytes : filename string 4 bytes : total file size
S |
D |
x | x | D |
X | .. | .. | X | .. | .. | S1 | S1 | S1 | S1 |
---|
if answer is :
D |
S |
0 | 1 | O |
---|
it means transfert can start
header is :
D |
P |
x | x | ID | ID | ID | ID | .. | .. |
---|
4 bytes is packet id XXXX bytes is data
if packet is received the answer is
P |
D |
0 | 5 | O |
ID | ID | ID | ID |
---|
header is :
C |
M |
0 | 1 | X |
---|
Commands:
Code | Hexa | Meaning |
---|---|---|
A |
0x41 | abort |
Abort command frame
C |
M |
0 | 1 | A |
---|