Docs / Protocols / Commands
Commands
NightMare has one text command grammar that can be executed from different sources.
The parser and built-in command handler are shared. A command behaves as the same command whether it came from serial, MQTT console, controlled MQTT request/response, an HTTP endpoint, or a Scheduler std::string job.
Config commands#
The built-in command path routes the complete text after CONFIG directly to
configManager().handle(...). The manager grammar is:
list
get <name>
set <name> <payload>
manifest
set decodes before calling the optional global change handler and the typed
per-Config onWrite handler, then commits only when every stage succeeds.
manifest returns Base64 of the canonical MessagePack
Config declaration manifest; it does not publish it. That manifest is
explicitly versioned: encoding version is position 0 and declaration-manifest
version is position 1.
Unlike ordinary commands, CONFIG bypasses generic argument tokenization.
Everything after set <name> is one opaque payload, so its spaces and quotes
are preserved exactly.
Resource command expressions#
When Resources are enabled, any command whose first non-whitespace character is > is handled by ResourcesManager before the generic command parser.
The character immediately after > selects one of two grammars.
ResourceManager operations#
No space after > selects an internal ResourceManager operation:
>list
>manifest [publish] [json|msgpack]
>raw <topic> [payload]
>list returns the manager's currently bound Resources as a text table
(KIND, NAME, TYPE, OWNER, VALUE).
>manifest json returns the readable manifest. >manifest msgpack republishes
the retained compact manifest and returns Republished. because raw
MessagePack is not useful on a text command response. publish explicitly
requests MQTT publication; with no format it republishes canonical MessagePack
and the optional JSON sibling only when NM_ENABLE_JSON_WIRE=1.
Bare >manifest selects MessagePack and republishes only that manifest.
>raw sends the supplied MQTT-shaped topic and opaque payload through ResourcesManager::handleIngressMessage().
Examples:
>list
>raw bedroom-ac/resource/power/set true
>raw weather-node/resource/temperature/state 23.5
Bound Resource operations#
A space after > selects a Resource by unique short name:
> <name>
> <name> get
> <name> set <payload>
> <name> invoke [payload]
> <name> source [OWNER/RESOURCE|CLEAR]
> <name> advertise [signed-ms]
> <name> poll [signed-ms|RESET]
A bare Value defaults to get.
A bare Action defaults to invoke with an empty payload.
get accepts no payload and returns the encoded effective current Value.
set requires a Value and a payload. A Managed Value goes through its normal managed write path; a Remote writable Value goes through its normal typed request path, preserving RemoteState optimism.
invoke requires an Action. A ManagedAction returns its local ActionResult; a RemoteAction can only report whether publication was accepted.
source requires a Remote Resource. With no payload it returns the current
source. OWNER/RESOURCE changes and persists the source; CLEAR removes it.
It also accepts {"source":"OWNER/RESOURCE"} or
{"owner":"OWNER","resource":"RESOURCE"}.
advertise requires a Managed Value. With no payload it queries the signed
millisecond policy. Positive values periodically reaffirm state, 0 is
event-driven, and negative values suppress publication (-1 is canonical).
Changing from negative to non-negative immediately advertises current available
state; changing to negative tombstones retained transport state without changing
Resource availability.
poll requires an opted-in Managed Value hardware policy. With no payload it
queries the effective interval. Writes require CONFIGURABLE_POLL; negative
writes additionally require CAN_DISABLE. RESET removes the persisted
override and restores the firmware-declared default. Hardware connection state
is firmware-reported and cannot be written remotely.
ResourcesManager::executeCommand() returns an unformatted ActionResult.
At the external command-response boundary, unsuccessful Resource commands are
rendered as ERROR: <message>. The shell protocol remains plain text; success
responses remain specific to the command.
ERROR: ADVERTISE expects signed milliseconds
ERROR: POLL is not configurable
ERROR: Resource not found
ERROR: Could not persist advertisement setting
The implementation also accepts action as an alias for invoke, but invoke is the canonical spelling.
A short name must identify exactly one bound Resource. Ambiguous names are rejected.
Everything after set or invoke is kept as one opaque Resource payload rather than being parsed as command arguments.
Resource-command size limits#
Normal commands remain limited to:
512 characters
Resource-command expressions use:
NetResourceMaxCommandLength
= NetResourceMaxManifestLength + 256
= 16640 bytes
Individual Value/Action payloads are still limited to:
2048 bytes
The larger expression envelope exists so >raw can carry Resource ingress such as a manifest-sized payload.
Grammar#
The parser accepts:
COMMAND [ARG0 [ARG1 [ARG2 [ARG3 [ARG4]]]]]
The conventional interpretation is:
COMMAND SUBCOMMAND ARG1 ARG2 ARG3 ARG4
because args[0] is also exposed as subcommand.
Current limits:
maximum command-line length: 512 characters
maximum arguments after command: 5
The command word and subcommand are converted to uppercase.
Remaining arguments preserve their case.
Whitespace#
Runs of whitespace outside quoted/literal regions are treated as separators.
For example:
JOB LIST
parses like:
JOB LIST
Double quotes#
Double quotes group whitespace into one argument and are removed.
Example:
JOB AFTER once 1000 "PING"
An explicitly empty argument is preserved:
""
The parser reports an unterminated quote as an error instead of guessing.
Backtick literals#
Backticks create a verbatim argument region.
Example:
JOB AFTER once 1000 `CONFIG SET message hello world`
The content inside the backtick fence is kept verbatim, including whitespace and quote characters.
A run of N opening backticks is closed only by a run of exactly N backticks. This permits literal backticks inside a fenced argument by choosing a longer fence.
Backslash behavior#
Backslash only escapes:
"
`
before those delimiters.
Otherwise the backslash is preserved.
This lets filesystem-style text such as:
C:\tmp
/a\b.json
round-trip without requiring every backslash to be doubled.
Parse errors#
Malformed commands return explicit parser errors for cases such as:
empty command
too many arguments
unterminated quote
unterminated ` literal
message too long
They do not silently fall through as unknown commands.
Command sources#
The same command handler is used by several sources.
Serial#
When:
NM_CONSOLE_SERIAL
is enabled, tickNightMareESP() services the serial resolver. It reads
standard input without blocking and resolves each line ending in CR or LF,
printing the answer to standard output.
On ESP-IDF with a UART console, the first call installs that UART's driver,
with an NM_SERIAL_RX_BUFFER-byte receive buffer (default 512), unless the
application already installed one. It then routes standard input through the
driver, so input waits in the driver's buffer between ticks instead of
overrunning the 128-byte hardware FIFO. An application that installs the
console UART driver itself keeps it. Arduino builds leave the port to Serial.
MQTT console#
Request:
<device>/console/in
Response:
<device>/console/out
Broadcast request:
all/console/in
Each receiving device responds on its own <device>/console/out.
Controlled MQTT / MQTTP#
Request:
<device>/console/controlled/<id>/in
Response:
<device>/console/controlled/<id>/out
See MQTTP.
Scheduler#
A std::string command job runs through the same handleNightMareCommand() path with command source JOB.
Built-in precedence#
When built-ins are enabled, built-in commands are handled before the project resolver.
An application command resolver registered with:
setCommandResolver(...)
receives commands that the built-in preprocessor does not recognize.
Applications therefore extend the command set; they do not override an enabled built-in with the same name.
Feature-dependent commands#
Not every command exists in every build.
JOB
requires NM_ENABLE_JOBS
INFO
requires NM_ENABLE_TELEMETRY
HW
requires NM_ENABLE_TELEMETRY
MQTT
requires NM_ENABLE_MQTT
NETWORK
requires NM_ENABLE_NETWORK or NM_ENABLE_WIFI
HTTPSERVER
requires NM_ENABLE_HTTP
WS
requires NM_ENABLE_WEBSOCKET
GATEWAY
requires NM_ENABLE_GATEWAY
general built-ins
require NM_CONSOLE_BUILTINS
PING#
PING
Response:
PONG
STATUS#
STATUS
A human-readable list, one fact per row, returned as the single text response of the command (so it reads the same on the serial console and over any text channel). Rows for a layer that is not compiled in are omitted.
STATUS VALUE
name adler
firmware 1.4.2
uptime 0h12m05s
free heap 182340 bytes
wifi radio READY
wifi ip CONNECTED 192.168.1.40 (Home, -52 dBm)
mqtt CONNECTED (REMOTE)
esp-now CONNECTED
active ESP_NOW (CONNECTED)
preferred ESP_NOW
The layer rows show the same ConnectivityState names that OnNetworkStatus() reports.
For the JSON forms use INFO and NETWORK GET.
REBOOT#
REBOOT
Calls:
ESP.restart();
This is an immediate device restart operation.
ADOPT and CHANGE NAME#
ADOPT <device-name>
CHANGE NAME <device-name>
These are equivalent spellings for identity adoption. They call DeviceIdentity::beginAdoption() rather than editing settings directly, so validation, address locking, reboot behavior, and old-identity cleanup all remain in force.
A successful response is JSON:
{
"name": "bedroom-ac",
"active_name": "Esp32-nm-6ca172e0",
"reboot_required": true
}
active_name is the name still in use by the current boot. When the address was already locked, reboot_required is true and the adopted name becomes active after reboot.
A second adoption is rejected while cleanup from the previous identity remains pending.
TIMEZONE and CHANGE TIMEZONE#
Query the active timezone:
TIMEZONE
Persist and immediately apply a POSIX timezone:
TIMEZONE SET <posix-tz>
CHANGE TIMEZONE <posix-tz>
The two mutation forms are equivalent. Timezones must be non-empty printable strings no longer than 128 characters. Quote an argument when needed by the general command grammar.
The response is:
{
"timezone": "EST5EDT,M3.2.0,M11.1.0"
}
When MQTT is connected, a successful change refreshes retained /status and /info identity data. Epoch timestamps remain UTC-based.
INFO#
Query the complete aggregate:
INFO
Query one section:
INFO IDENTITY
INFO HARDWARE
INFO BUILD
INFO BOOT
INFO SYSTEM
INFO NETWORK
Publication:
INFO PUBLISH
INFO PUBLISH SYSTEM
INFO PUBLISH NETWORK
INFO PUBLISH with no document argument defaults to the aggregate /info document.
Only:
INFO
SYSTEM
NETWORK
are MQTT documents. The other section names are query-only.
See Status, info, and telemetry.
HW#
HW [PUBLISH]
HW (and the accepted explicit alias HW JSON) returns the readable hardware
configuration. HW PUBLISH republishes <device>/hardware/msgpack (plus the
optional /hardware/json sibling when enabled) and returns
Republished to MQTT..
TIME#
TIME
TIME STATUS
Both forms return the same JSON clock-status document with:
synced
valid
epoch
local
timezone
uptime_ms
valid reports whether the wall clock is usable. synced additionally requires NightMare's synchronization state to be set. local is formatted in the process timezone.
See Time.
JOB#
All JOB commands operate on Scheduler scope:
USER
They cannot list, delete, or clear MANAGED framework/application jobs.
List#
JOB LIST
Returns Scheduler JSON containing only USER jobs.
Delete by label#
JOB DELETE night
Delete by ID#
JOB DELETE #12
The numeric ID form requires the # prefix.
Clear#
JOB CLEAR
Clears all USER jobs.
It does not clear MANAGED jobs.
Run once at wall time#
JOB AT <label> <epoch_s> "<command>"
Example:
JOB AT lights-off 1790000000 "CONFIG SET mode sleep"
epoch_s is a 32-bit unsigned Unix-seconds value.
Run once after a monotonic delay#
JOB AFTER <label> <delay_ms> "<command>"
Example:
JOB AFTER prefer_mqtt 5000 "NETWORK TRANSPORT SET MQTT"
Repeat#
JOB EVERY <label> <WALL|MONO> <interval> "<command>"
For:
WALL
the interval unit is seconds.
For:
MONO
the interval unit is milliseconds.
Examples:
JOB EVERY hourly WALL 3600 "INFO PUBLISH"
JOB EVERY poll MONO 5000 "PING"
The interval must be greater than zero.
USER label namespace#
USER job labels are unique within USER scope.
A USER job and MANAGED job may use the same label without blocking each other.
Scheduler persistence through JOB#
Only wall-clock std::string command jobs persist.
Therefore:
JOB AT ...
JOB EVERY ... WALL ...
are persistence-capable.
JOB AFTER ...
JOB EVERY ... MONO ...
are runtime-only.
See the Scheduler module documentation for the full job model.
NETWORK#
Connectivity lifecycle and NMNW routing use explicit namespaces:
NETWORK GET
NETWORK WIFI GET
NETWORK WIFI ENABLE
NETWORK WIFI DISABLE
NETWORK WIFI IP
NETWORK WIFI SCAN
NETWORK WIFI CHANGE <ssid> <password> [dBm|AUTO]
NETWORK WIFI TXPOWER [dBm|AUTO]
NETWORK ESPNOW GET
NETWORK ESPNOW ENABLE
NETWORK ESPNOW DISABLE
NETWORK MQTT GET
NETWORK MQTT ENABLE [REMOTE|LOCAL]
NETWORK MQTT DISABLE
NETWORK TRANSPORT GET
NETWORK TRANSPORT SET <MQTT|ESP_NOW|AUTO>
NETWORK GET returns readable named states for transport, wifi_radio,
wifi_ip, esp_now, mqtt, and gateway_candidate. supported, enabled, and state are
independent fields. Transport reports both preferred and active.
Lifecycle commands affect only their named service. MQTT enable is rejected when WiFiIP is disabled, and WiFiIP disable is rejected while MQTT is enabled:
{"ok":false,"reason":"wifi_ip_disabled","state":"STOPPED"}
{"ok":false,"reason":"mqtt_enabled","state":"CONNECTED"}
Successful lifecycle requests include the resulting requested/runtime state,
for example {"ok":true,"state":"CONNECTING"}. ESP-NOW does not block WiFiIP
disable. MQTT disable leaves WiFiIP unchanged, and ESP-NOW enable/disable leaves
WiFiIP and MQTT unchanged.
NETWORK TRANSPORT SET changes only the persisted NMNW routing preference. It
does not enable, disable, connect, or disconnect a service. An unavailable but
compiled transport may still be preferred; the current usable active transport
remains until routing policy can use the preference.
LOCAL_MQTT is not a transport or command alias. Local versus remote broker
selection belongs to the single MQTT service profile.
NETWORK WIFI SCAN starts an asynchronous scan when no results are present,
reports SCANNING while active, and returns DONE plus networks afterward.
Each entry contains ssid, rssi, mac, channel, and encryptionType.
When ESP-NOW is enabled, it is temporarily suspended and is resumed after scan
completion, failure, abort, or timeout without changing its enable state or the
transport preference.
The ambiguous pre-decoupling forms NETWORK SET, NETWORK STATE, NETWORK IP,
NETWORK SCAN, NETWORK CHANGE, NETWORK TXPOWER, and NETWORK RECONNECT are
not aliases and return unknown_network_command.
GATEWAY#
Operator control of the NightMare Gateway. Answers
are JSON; a refused or unknown request is {"ok":false,"reason":...}, with a
usage field when the form was wrong.
GATEWAY GET
GATEWAY ENABLE
GATEWAY DISABLE
GATEWAY CLIENTS
GATEWAY ESPNOW GET
GATEWAY ESPNOW PAUSE
GATEWAY ESPNOW RESUME
GATEWAY TRACE GET
GATEWAY TRACE ENABLE
GATEWAY TRACE DISABLE
GATEWAY MQTT GET
GATEWAY MQTT TEST [bytes [count]]
GATEWAY MQTT LINKDEBUG GET
GATEWAY MQTT LINKDEBUG ENABLE
GATEWAY MQTT LINKDEBUG DISABLE
GATEWAY alone is GATEWAY GET: enabled, state, link
(NONE/LOCAL/REMOTE/BRIDGED), id, generation, and espnow, mqtt,
vault and trace sections. A side that is not compiled in reports
{"supported":false}, and its commands return unsupported.
ENABLE/DISABLE stop or restart the whole gateway (ESP-NOW sessions are
dropped; devices reconnect). ESPNOW PAUSE/RESUME tear the ESP-NOW side down
and bring it back while MQTT keeps running, to separate a radio problem from an
uplink one; DISABLE clears a pause. These requests are applied by the next
gateway tick, so the answer is {"ok":true} for the request and GATEWAY GET
shows when it took effect.
CLIENTS lists ESP-NOW sessions: mac, name (learned from the device's
/status), cid, state, suspended, subscriptions, rssi, rtt_ms,
last_seen_s, last_will and disconnect_candidate.
TRACE switches the per-hop log of <device>/hardware documents at runtime.
MQTT TEST publishes count QoS 1 messages of bytes (defaults 1024 x 10,
at most 32768 x 200) to <gateway-id>/diag one at a time and logs each PUBACK
latency on the mqtttest log module; the answer only confirms the start.
MQTT LINKDEBUG dumps the Wi-Fi driver statistics at every MQTT disconnect.
CONFIG#
CONFIG addresses firmware-declared values registered with configManager(). It no
longer exposes the generic PersistentSettings store.
List declarations#
CONFIG LIST
CONFIG LIST JSON
CONFIG LIST returns a text table (TYPE, NAME, REBOOT, VALUE), one
Config per row. CONFIG LIST JSON returns compact JSON containing each Config's name, wire type,
require_reboot metadata, and current canonical std::string value:
[{"name":"heartbeat:period","type":"integer","require_reboot":false,"value":"15"}]
The versioned Config manifest remains declaration-only and does not contain current values.
Read one Config#
CONFIG GET <name>
Returns the current NetCodec<T> text encoding.
Set one Config#
CONFIG SET <name> <payload>
The payload is opaque command text. It is decoded according to the declared
Config<T> type, offered to the optional global change handler and then the
Config's typed onWrite handler, persisted in canonical form, and committed
to the runtime value only when every stage succeeds. Rejection or persistence
failure leaves the runtime value unchanged. An accepted value survives reboot.
Manifest#
CONFIG MANIFEST
Returns Base64 of the canonical versioned MessagePack manifest. The decoded
shape is [encodingVersion, manifestVersion, configs[]]; each declaration is
[name, NetValueType, requireReboot].
FS#
Filesystem commands are part of the general built-in command set.
List#
FS LIST
Returns JSON:
{
"files": [
{
"name": "/configs.json",
"size": 123
}
]
}
SPIFFS exposes a flat file list. The serialized JSON response is limited to 4096 bytes.
Read#
FS READ <filename>
Status#
FS STATUS
Returns fields:
totalBytes
usedBytes
usedPercentage
initialized
Delete#
FS DELETE <filename>
Format#
The current implementation authorizes formatting when the second argument is:
-p
so the accepted form is:
FS FORMAT -p
One failure string in the current implementation still says FS FORMAT CONFIRM; that message does not match the actual argument check and should be treated as stale text rather than protocol syntax.
Optional HTTPSERVER commands#
Only present when HTTP is compiled in.
HTTPSERVER PRIORITY <high|normal>
HTTPSERVER STATUS
HTTPSERVER RESET
HTTPSERVER ENABLE <1|0>
HTTP is an optional surface that has not received the same architecture pass as the core Resource/network model.
Optional WS commands#
Only present when WebSocket support is compiled in.
WS LIST
WS <message>
WS LIST reports active clients.
Any other subcommand is broadcast to WebSocket clients by the current implementation.
WebSocket command support is peripheral to the current core architecture.
TEST#
TEST "<command text>"
This is a parser/debug command. It runs the older parseNightMareMessage() parser over the supplied first argument and reports the parsed fields.
It should not be treated as part of application protocol design.
Commands vs Resource Actions#
Commands and Resource Actions remain intentionally different.
Use a command for framework/operator control such as:
INFO
TIME
JOB
MQTT
NETWORK
CONFIG
Use a Resource Action for an application capability such as:
learn_ir
pair_remote
run_cycle
A Resource Action remains discoverable through the Resource manifest and belongs to the device's application contract.
The > syntax is a bridge between command sources and already-bound Resources; it does not redefine a Resource Action as a command family.