The esp3d_commands module is the central command dispatch engine of the ESP3D firmware. It implements the ESP3DCommands class, which detects, parses, authenticates, routes, and responds to all [ESPxxx] control commands received from any transport channel.
Every communication path — Serial UART, Bluetooth SPP/BLE, USB Serial, TCP Socket, WebSocket — funnels incoming text through this module. When an [ESPxxx] command token is detected inside a message, the module takes ownership: it extracts parameters, enforces the caller’s authentication level, executes the corresponding handler method, then dispatches the response back to the originating client in either plain text or JSON format.
The module is also responsible for forwarding non-command messages to the CNC firmware via the active transport and for managing multi-part response streaming (head / core / tail message types).
The universal message container that flows through every transport and through this module.
structESP3DMessage {
uint8_t*data; // Raw payload bytes
size_t size; // Payload size
ESP3DClientType origin; // Sending client type
ESP3DClientType target; // Receiving client type
ESP3DAuthenticationLevel authentication_level; // guest / user / admin
ESP3DRequest request_id; // Response routing key
ESP3DMessageType type; // head | core | tail
ESP3DMessagePriority priority; // normal (back) | high (front)
};
ESP3DMessageType drives multi-part streaming: a single logical response is split into a head (opening segment), zero or more core segments (body entries), and a tail (closing segment with summary). This avoids large heap allocations for directory listings or settings dumps.
Every handler respects an optional json tag in the command parameters. Without it the output is human-readable text; with json it is structured JSON compatible with the WebUI.
All commands check msg->authentication_level before executing. The model has three levels:
Level
Symbol
Access
No authentication
guest
Read-only public commands only
Normal user
user
Most read + limited write commands
Administrator
admin
All commands including settings write
When access is denied, dispatchAuthenticationError() sends a structured error without revealing system state. The standard guard pattern used in every handler:
#ifESP3D_AUTHENTICATION_FEATURE
if (msg->authentication_level==ESP3DAuthenticationLevel::guest) {
How the level is assigned per transport: connection_management.md, authentication_lifecycle.md. On the command channels (telnet, /wsdata, USB CDC device, UART0 console) the level is checked on every line: a guest line is refused unless it is an ESP command, a wrong password demotes to guest. Telnet and /wsdata sessions expire after the STREAM= inactivity timeout of [ESP510] (0 = none, the default); the USB CDC device and UART0 console have no session record and keep their own level through checkCommandChannelLine(). DISABLE_SERIAL_AUTHENTICATION (ON by default) gives admin to every serial-class line and turns authentication off on the USB CDC device channel too (physical access trusted). [ESP500]LOGOUT closes the session. See esp3d_x_stream_authentication.md.
Commands are grouped by functional area. Each group is compiled in or out via CMake feature flags defined in CMakeLists.txt and converted to C preprocessor defines by cmake/features.cmake. Mutual exclusions are enforced in cmake/sanity_check.cmake.
Descriptions and guards below come from each handler’s header comment (main/core/commands/espNNN.cpp) and from the #if blocks around its case in ESP3DCommands::execute_internal_command(). Feature names drop the ESP3D_ prefix and _FEATURE suffix.
Get / set STA SSID, or BT device name (WIFI= / BTSERIAL= / BTBLE=)
[ESP101]
WIFI or BT
Set STA password, or BT password (WIFI= / BTSERIAL= / BTBLE=)
[ESP102]
WIFI
STA IP mode (DHCP / STATIC)
[ESP103]
WIFI
STA static IP / mask / gateway / DNS
[ESP104]
WIFI
STA fallback mode at boot: BT, WIFI-SETUP (was CONFIG), OFF, STA
[ESP105] / [ESP106]
WIFI
AP SSID / AP password
[ESP107] / [ESP108]
WIFI
AP IP / AP channel
[ESP109]
WIFI
STA rejoin from the setup fallback (ON / OFF): the network task looks for the STA SSID every 2 minutes while no station uses the setup AP
[ESP110]
—
Radio mode at boot: BT, WIFI-SETUP (was CONFIG), STA, AP, OFF. Saved to NVS and applied asynchronously by the network task: ok means accepted, check with [ESP111] or the connection status screen
[ESP111]
WIFI
Current IP (ALL for details)
[ESP112]
—
Hostname
[ESP114]
—
Radio state at boot (ON / OFF)
[ESP115]
—
Immediate network state (ON / OFF), applied asynchronously like [ESP110]
The module keeps _lastESP3DCmdOrigin (an ESP3DClientType) to track which transport sent the most recent [ESPxxx] command. This prevents a trailing newline arriving on one transport (e.g., Serial) from being swallowed because a different transport (e.g., BT) had just completed a command.
Each transport’s RX handler runs in a single dedicated task, so origin-keyed state eliminates cross-transport interleave. The enum is byte-sized, so reads and writes do not tear without an explicit lock.
Commands injected by the pendant UI (LVGL task) use ESP3DMessagePriority::high and are placed at the front of the TX queue via addFrontTxData(). Commands arriving from a remote terminal use normal priority and are appended to the back with addTxData().
ESP500, ESP510, ESP550, ESP555; auth guard in all handlers
ESP3D_NOTIFICATIONS_FEATURE
ESP600, ESP610
ESP3D_USB_SERIAL_FEATURE
ESP902, ESP950
ESP3D_USB_CDC_DEVICE_FEATURE
ESP935; USB-CDC value of ESP950
ESP3D_SERIAL_FEATURE
ESP900
ESP3D_UPDATE_FEATURE + ESP3D_SD_CARD_FEATURE
ESP402
ESP3D_MDNS_FEATURE
ESP450
ESP3D_IP_CNC_CLIENT_FEATURE + ESP3D_MDNS_FEATURE
ESP455
ESP3D_LUA_INTERPRETER_FEATURE
ESP300, ESP301
ESP3D_FACTORY_FEATURE
FACTORY value of ESP444 (rebootToFactory())
SD_INTERFACE_TYPE == 0
ESP202
ESP3D_UART_EXT_FEATURE
ESP950
Build constraint rules are enforced in cmake/sanity_check.cmake — for example, SOCKET_CLIENT_SERVICE and WEBUI_SERVER are mutually exclusive. See docs/features/feature_resource_matrix.md and docs/features/features.md for the full SKU × feature matrix.
