Web Sockets

There are two WebSocket servers:

• Terminal websocket — streams data to WebUI and exchanges internal messages
• Data websocket — exchanges data with an external client (not used by WebUI)

---

Terminal WebSocket

Uses subprotocol webui-v3. Port is web port + 1 (e.g. 80 → 81).

Text mode

Reserved messages between WebUI and ESP. Format: <label>:<message>

ESP → WebUI:

• currentID:<id> Sent when client connects. It is the last used ID and becomes the active ID.

• activeID:<id> Broadcast when a new client connects. Clients without this ID should close. The ESP WS server closes all open WS connections except this one.

• PING:<time left>:<time out> Response to a PING from client, informing the time remaining before inactivity timeout.

• ERROR:<code>:<message> Raised during upload when the HTTP answer cannot cancel it. This is a workaround: there is no API in the current webserver to cancel an active upload.

• NOTIFICATION:<message> Forwards the message sent by [ESP600] to the WebUI toast system.

• SENSOR: <value>[<unit>] <value2>[<unit2>] ... Sensor data (e.g. DHT22 temperature/humidity).

WebUI → ESP:

• PING:<cookieSessionID | none> Keepalive ping. Sends the current session cookie ID, or none if not authenticated.

Binary mode

ESP → WebUI: stream data from ESP to WebUI. WebUI → ESP: file transfer — not implemented yet.

---

Data WebSocket

Uses subprotocol arduino. Port is configurable (e.g. 8282).

Text mode

Used to transfer all G-code commands and their responses from the CNC/printer.

Binary mode

Used to transfer files to/from the ESP board.

Frame format

Every binary frame uses the same fixed 4-byte header:

Byte 0	Byte 1	Byte 2–3	Byte 4+
Opcode MSB	Opcode LSB	Payload length (uint16_t LE)	Payload

• Opcode: 2 ASCII bytes identifying the frame type (e.g. SR, UP).
• Payload length: number of bytes that follow the header, little-endian uint16_t.
• All multi-byte integer fields in the payload are little-endian.
• Maximum data payload per packet: 1024 bytes (may be increased after testing).

---

Frame types

Query status — SR / RS

Client → ESP (no payload):

S	R	0x00	0x00

ESP → Client (1-byte payload: status code):

R	S	0x00	0x01	STATUS

Status codes:

Code	Hex	Meaning
O	0x4F	Idle / OK
B	0x42	Busy
E	0x45	Error
A	0x41	Abort
U	0x55	Upload ongoing
D	0x44	Download ongoing

Additional payload for E (Error):

After the status byte: 1 byte error code, 1 byte string length, then the string.

R	S	PL_LO	PL_HI	E	ERR_CODE	STR_LEN	STR…

Additional payload for U (Upload ongoing):

After the status byte: path size (1 byte), path, filename size (1 byte), filename, total file size (uint32_t LE), processed bytes (uint32_t LE), last packet ID (uint32_t LE).

R	S	PL_LO	PL_HI	U	PATH_SZ	PATH…	NAME_SZ	NAME…	TOTAL(4)	DONE(4)	LAST_ID(4)

Additional payload for D (Download ongoing):

Same layout as Upload ongoing, with D status byte.

R	S	PL_LO	PL_HI	D	PATH_SZ	PATH…	NAME_SZ	NAME…	TOTAL(4)	DONE(4)	LAST_ID(4)

---

Start upload — SU / US

Client → ESP:

Payload: path size (1 byte), path, filename size (1 byte), filename, total file size (uint32_t LE).

S	U	PL_LO	PL_HI	PATH_SZ	PATH…	NAME_SZ	NAME…	FILE_SIZE(4)

ESP → Client (OK — transfer can start):

U	S	0x01	0x00	O

ESP → Client (Error — transfer rejected):

U	S	0x01	0x00	E

---

Upload packet — UP / PU

Client → ESP:

Payload: packet ID (uint32_t LE), then data bytes.

U	P	PL_LO	PL_HI	ID(4)	DATA…

ESP → Client (ACK):

P	U	0x05	0x00	O	ID(4)

---

End upload — EU / UE

Sent by the client after the last upload packet.

Client → ESP (no payload):

E	U	0x00	0x00

ESP → Client (OK):

U	E	0x01	0x00	O

ESP → Client (Error):

U	E	0x01	0x00	E

---

Start download — SD / DS

Client → ESP:

Payload: path size (1 byte), path, filename size (1 byte), filename.

S	D	PL_LO	PL_HI	PATH_SZ	PATH…	NAME_SZ	NAME…

ESP → Client (OK — transfer can start):

Payload: status O, then total file size (uint32_t LE).

D	S	0x05	0x00	O	FILE_SIZE(4)

ESP → Client (Error):

D	S	0x01	0x00	E

---

Download packet — DP / PD

ESP → Client:

Payload: packet ID (uint32_t LE), then data bytes.

D	P	PL_LO	PL_HI	ID(4)	DATA…

Client → ESP (ACK):

P	D	0x05	0x00	O	ID(4)

---

End download — ED / DE

Sent by the ESP after the last download packet.

ESP → Client (no payload):

E	D	0x00	0x00

Client → ESP (ACK):

D	E	0x01	0x00	O

---

NAK — retransmit request — NK

Sent by either side when a packet is missing or corrupted. The sender must retransmit starting from the requested packet ID.

N	K	0x04	0x00	ID(4)

---

Command — CM

Client → ESP (1-byte payload: command code):

C	M	0x01	0x00	CMD

Command codes:

Code	Hex	Meaning
A	0x41	Abort current transfer

Abort frame:

C	M	0x01	0x00	A

---

Transfer flow summary

Upload

Client                        ESP
  |--- SU (path, name, size) --->|
  |<-- US (O) -------------------|
  |--- UP (id=0, data) --------->|
  |<-- PU (O, id=0) -------------|
  |--- UP (id=1, data) --------->|
  |<-- PU (O, id=1) -------------|
  |         ...                  |
  |--- EU ---------------------->|
  |<-- UE (O) -------------------|

Download

Client                        ESP
  |--- SD (path, name) -------->|
  |<-- DS (O, file_size) -------|
  |<-- DP (id=0, data) ---------|
  |--- PD (O, id=0) ----------->|
  |<-- DP (id=1, data) ---------|
  |--- PD (O, id=1) ----------->|
  |         ...                 |
  |<-- ED ----------------------|
  |--- DE (O) ----------------->|

Abort (at any point during transfer)

Client                        ESP
  |--- CM (A) ----------------->|