Docs / Protocols / Status, info, and telemetry
Status, info, and telemetry
NightMare separates device-level information according to lifecycle:
/status
presence
/info
boot-scoped / effectively static description
/hardware/msgpack
canonical reconstructable hardware configuration
/hardware/json
optional readable hardware configuration
/telemetry/system
changing runtime system health
/telemetry/network
changing network bookkeeping
/telemetry/heartbeat
transient heartbeat when enabled
Application sensor and actuator state is not duplicated here. It belongs to Resources.
Status#
Topic:
<device>/status
Status is retained.
Its JSON shape is always:
{
"name": "bedroom-ac",
"hardware": "Esp32-nm-6ca172e0",
"timezone": "<-03>3",
"online": true
}
Fields:
name
logical/adoptable device name represented by this status topic
hardware
stable hardware signature of the physical board
timezone
persisted POSIX timezone used for local-time presentation
online
current presence state represented by this publication
The same JSON shape is used for:
- normal online publication,
- graceful offline publication,
- MQTT Last Will,
- cleanup of a previous adopted identity.
Observers therefore do not need separate status parsers for graceful and ungraceful disconnects.
Status and Last Will#
The MQTT client installs an offline Last Will for the current device's status topic.
When the connection becomes active, NightMare publishes the same document with:
"online": true
On graceful stop it publishes:
"online": false
before ending the client.
The status document is the presence signal. It does not assert freshness of every Resource.
Hardware signature#
The hardware field is not the logical MQTT identity.
A device may be adopted from:
Esp32-nm-6ca172e0
to:
bedroom-ac
while status still reports:
{
"name": "bedroom-ac",
"hardware": "Esp32-nm-6ca172e0",
"timezone": "<-03>3",
"online": true
}
This allows network identity and physical-board identity to remain distinguishable.
Info#
Topic:
<device>/info
/info is retained.
It is an aggregate of facts that are static or boot-scoped enough that they do not need periodic refresh during one boot:
identity
hardware
build
boot
A representative structure is:
{
"identity": {
"name": "bedroom-ac",
"hardware": "Esp32-nm-6ca172e0",
"id": "0011223344556677",
"timezone": "<-03>3"
},
"hardware": {
"board": "ESP32-C3 SuperMini rev1",
"chip": "ESP32-C3",
"cores": 1,
"revision": 4,
"flash_bytes": 4194304,
"heap_bytes": 327680,
"psram_bytes": 0
},
"build": {},
"boot": {
"reset_reason": 1
}
}
Exact values depend on the board and build.
Identity section#
identity contains:
name
hardware
id
timezone
name is the current logical identity.
hardware is the stable hardware signature.
id is the raw machine-oriented device ID.
timezone is the persisted POSIX TZ string. Changing it refreshes /status and /info while MQTT is connected.
Hardware section#
hardware contains:
board
chip
cores
revision
flash_bytes
heap_bytes
psram_bytes
board is the effective model of host_assembly in the active NightMare hardware profile.
The remaining hardware fields come from the ESP runtime.
Hardware configuration#
Hardware configuration is not embedded in /info. It is retained canonically
as positional MessagePack at <device>/hardware/msgpack. The readable
<device>/hardware/json sibling is optional; the bare root is a namespace.
The top-level shape is:
{
"version": 2,
"host_assembly": "controller/esp32",
"definitions": [],
"roots": [],
"connections": []
}
Assemblies model physical composition. Boards are assembly kinds rather than a
universal container. Devices expose terminals and connectors expose contacts.
Connections contain a and b endpoint references plus optional wire
metadata. Endpoint references use assembly, kind, owner, and endpoint.
The graph is authoritative: normal electrical nets are inferred from connected
components and are not stored. Endpoint canonical identities may be GND,
VCC, +3V3, +5V, AC_PHASE, AC_NEUTRAL, or PE. Conflicting identities
make the document invalid.
These identities are exact. VCC is a specifically named VCC rail, not an
unknown-voltage positive-supply wildcard; omit canonical_net when the rail is
not known.
The exact field contract, containment rules, relative/absolute path behavior, and definition semantics are normative in Hardware configuration v2.
Build section#
build contains:
firmware_version
date
time
compiler
esp_idf_version
features
firmware_version comes from:
NM_FIRMWARE_VERSION
The features object reports the compile-time state of:
settings
network
wifi
mqtt
console
resources
scheduler
jobs
telemetry
time_sync
ota
http
websocket
lvgl
Example:
{
"firmware_version": "1.1.141",
"date": "Sep 21 2026",
"time": "21:17:38",
"compiler": "...",
"esp_idf_version": "...",
"features": {
"settings": true,
"network": true,
"wifi": true,
"mqtt": true,
"console": true,
"resources": true,
"scheduler": true,
"jobs": true,
"telemetry": true,
"time_sync": true,
"ota": false,
"http": false,
"websocket": false,
"lvgl": false
}
}
Boot section#
The current boot document contains:
reset_reason
reset_reason is the numeric esp_reset_reason() value.
Changing information such as uptime is intentionally not placed in /info.
System telemetry#
Topic:
<device>/telemetry/system
The document is retained.
Current fields are:
{
"uptime_ms": 123456,
"cpu_mhz": 160,
"free_heap_bytes": 210000,
"min_free_heap_bytes": 198000,
"free_psram_bytes": 0
}
Fields:
uptime_ms
cpu_mhz
free_heap_bytes
min_free_heap_bytes
free_psram_bytes
System telemetry is normally refreshed every:
NM_TELEMETRY_INTERVAL_MS
whose default is:
60000 ms
Network telemetry#
Topic:
<device>/telemetry/network
The document is retained.
The document represents every connectivity service independently:
{
"transport": {
"preferred": "ESP_NOW",
"active": "ESP_NOW",
"state": "CONNECTED"
},
"wifi_radio": {"supported": true, "enabled": true, "state": "READY"},
"wifi_ip": {
"supported": true,
"enabled": true,
"state": "CONNECTED",
"ssid": "example",
"ip": "192.168.1.50",
"rssi": -55,
"channel": 6,
"tx_power_dbm": 20.0
},
"esp_now": {
"supported": true,
"enabled": true,
"state": "CONNECTED",
"gateway_connected": true,
"channel": 6,
"rtt_ms": 12,
"session_id": 41
},
"mqtt": {
"supported": true,
"enabled": true,
"state": "CONNECTED",
"profile": "REMOTE"
},
"gateway_candidate": {
"known": true,
"id": "nmnw-gateway-a1b2c3",
"probable": true,
"esp_now_ready": true,
"remote_mqtt_ready": true,
"local_mqtt_ready": false,
"ssid": "example",
"bssid": "aa:bb:cc:dd:ee:ff",
"channel": 6
}
}
The schema can also represent an unavailable preference without contradiction:
{
"transport": {"preferred": "MQTT", "active": "ESP_NOW", "state": "CONNECTED"},
"wifi_radio": {"supported": true, "enabled": true, "state": "READY"},
"wifi_ip": {"supported": true, "enabled": false, "state": "STOPPED"},
"esp_now": {"supported": true, "enabled": true, "state": "CONNECTED"},
"mqtt": {"supported": true, "enabled": false, "state": "STOPPED", "profile": "REMOTE"}
}
wifi_ip.ssid, ip, rssi, channel, and tx_power_dbm are present only
while WiFiIP is connected. ESP-NOW session details are included from already
available state; telemetry does not initiate discovery. Unsupported services
remain present with supported=false, enabled=false, and state=STOPPED.
Network telemetry is normally refreshed every:
NM_NETWORK_TELEMETRY_INTERVAL_MS
whose default is:
300000 ms
Last-known network bookkeeping#
Network telemetry is retained, but it is not the authoritative presence signal.
If a device disappears unexpectedly, its last retained network telemetry may still say:
"mqtt": {"state": "CONNECTED"}
because the device cannot rewrite telemetry after it has disappeared.
Use:
<device>/status
for presence.
Use network telemetry as last-known bookkeeping.
Publication on active transport and state changes#
Every active NMNW transport connection requests a refresh of the static retained information documents:
<device>/info
<device>/hardware/msgpack
tickNightMareESP() publishes at most one ready document per call. A failed
publication moves behind other ready work and retries with exponential backoff
capped at five minutes. A fresh request resets its backoff. This spreads
allocations across cooperative ticks instead of the connection callback.
Each document is attempted even if publication of another document fails.
Meaningful WiFiIP, MQTT, ESP-NOW, preferred-transport, and active-transport changes also request a network telemetry refresh. Duplicate requests are coalesced; publication failure never changes connectivity state.
SYSTEM and NETWORK telemetry are additionally refreshed by periodic Scheduler jobs. HEARTBEAT is published by its runtime-configured Scheduler job when enabled.
Periodic publication#
Telemetry.start() installs MANAGED monotonic callback jobs:
nm.telemetry.system
nm.telemetry.network
nm.telemetry.heartbeat when heartbeat:enable is true
They publish at the configured system and network intervals and at the current
heartbeat:period when heartbeat is enabled.
These are framework jobs, not USER jobs, so operator JOB DELETE and JOB CLEAR cannot remove them.
INFO query interface#
The same data can be queried without MQTT publication.
Supported sections are:
INFO
IDENTITY
HARDWARE
BUILD
BOOT
SYSTEM
NETWORK
HEARTBEAT
INFO means the aggregate retained /info shape.
The others return only the requested section.
For example:
INFO HARDWARE
returns an object containing only hardware fields.
Hardware connections use the separate command:
HW [PUBLISH]
HW returns JSON directly. HW PUBLISH republishes the retained MQTT document.
Publishable documents#
Four InfoType values map to MQTT topics:
INFO
SYSTEM
NETWORK
HEARTBEAT
Therefore:
INFO PUBLISH
INFO PUBLISH SYSTEM
INFO PUBLISH NETWORK
INFO PUBLISH HEARTBEAT
are valid publication requests.
Section-only types such as HARDWARE or BOOT are queryable but are not independent MQTT documents. INFO, SYSTEM, and NETWORK are retained; HEARTBEAT is transient.
Heartbeat#
Topic:
<device>/telemetry/heartbeat
The heartbeat is not retained. Its payload is:
{
"uptime_ms": 123456,
"heartbeat": 42
}
Runtime Configs control publication:
heartbeat:enable boolean, default true
heartbeat:period integer seconds, default 15, accepted range 15..86400
Changing either through CONFIG SET immediately updates the MANAGED heartbeat
job. Presence is still represented by retained status plus MQTT Last Will;
application state freshness remains represented by Resource /state.