NightMare Networkv1.0.0-alpha.1

Search every page of the documentation. Or start with:

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.

Last updated · Edit this page on GitHub