Docs / Modules / Telemetry and INFO
Telemetry and INFO
NightMare's telemetry service exposes device-wide information that is not application Resource state.
The public singleton is:
Telemetry
The data is split by lifecycle:
INFO
identity, hardware, build, boot
HARDWARE CONFIGURATION
assemblies, definitions, devices, connectors and physical connections
SYSTEM
changing runtime system health
NETWORK
changing network bookkeeping
HEARTBEAT
transient liveness cadence configured at runtime
INFO, SYSTEM, NETWORK, and HEARTBEAT keep their existing JSON MQTT topics. Hardware configuration is MessagePack-first; its JSON sibling is optional.
InfoType#
enum class InfoType : uint8_t
{
INVALID,
INFO,
IDENTITY,
HARDWARE,
BUILD,
BOOT,
SYSTEM,
NETWORK,
HEARTBEAT
};
The subsection types are useful for queries even though they do not each have a retained MQTT topic.
std::string lookup#
InfoType getInfoType(const std::string &type);
Recognized names are case-insensitive:
INFO
IDENTITY
HARDWARE
BUILD
BOOT
SYSTEM
NETWORK
HEARTBEAT
An empty std::string means:
INFO
Unknown text maps to:
InfoType::INVALID
TelemetryResult#
Queries return:
struct TelemetryResult
{
bool valid = false;
std::string data;
};
data contains serialized JSON when valid.
Query aggregate INFO#
TelemetryResult result =
Telemetry.getInfo();
or:
Telemetry.getInfo(InfoType::INFO);
The result contains:
identity
hardware
build
boot
Query one section#
Telemetry.getInfo(InfoType::SYSTEM);
or:
Telemetry.getInfo("SYSTEM");
Section queries return the section value directly rather than wrapping it under its aggregate key.
INFO section contents#
Identity#
name
hardware
id
timezone
timezone is the active persisted POSIX timezone. A successful timezone command refreshes the retained INFO document when MQTT is connected.
Hardware#
board
chip
cores
revision
flash_bytes
heap_bytes
psram_bytes
Build#
firmware_version
date
time
compiler
esp_idf_version
features
Boot#
Current boot information is intentionally minimal:
reset_reason
Changing facts do not belong in the boot/static aggregate.
SYSTEM contents#
Current fields:
uptime_ms
cpu_mhz
free_heap_bytes
min_free_heap_bytes
free_psram_bytes
NETWORK contents#
The document has five independent objects:
transport.preferred / active / state
wifi_radio.supported / enabled / state
wifi_ip.supported / enabled / state
esp_now.supported / enabled / state
mqtt.supported / enabled / state / profile
Connected WiFiIP additionally reports ssid, ip, rssi, channel, and
tx_power_dbm. ESP-NOW reports already-available gateway/session facts without
starting discovery. Unsupported services remain explicit with
supported=false.
Readable transport names are:
AUTO
MQTT
ESP_NOW
Preference and active transport are separate so a disabled/unavailable preferred service can coexist with a connected fallback.
gateway_candidate reports already-known retained gateway readiness: known,
id, probable, esp_now_ready, remote_mqtt_ready, local_mqtt_ready,
ssid, bssid, and channel. Producing telemetry does not scan or discover.
HEARTBEAT contents#
{
"uptime_ms": 123456,
"heartbeat": 42
}
The counter advances only after MQTT accepts a heartbeat publication. The
heartbeat is transient and does not replace retained /status plus Last Will
as the authoritative presence mechanism.
Publish one document#
Telemetry.publishInfo(InfoType::INFO);
Telemetry.publishInfo(InfoType::SYSTEM);
Telemetry.publishInfo(InfoType::NETWORK);
Telemetry.publishInfo(InfoType::HEARTBEAT);
std::string forms are also available:
Telemetry.publishInfo("SYSTEM");
Publication is device-prefixed. INFO, SYSTEM, and NETWORK are retained; HEARTBEAT is not retained.
The topics are:
<device>/info
<device>/telemetry/system
<device>/telemetry/network
<device>/telemetry/heartbeat
Query-only sections cannot be published independently#
These are queryable:
IDENTITY
HARDWARE
BUILD
BOOT
but do not have individual MQTT topics.
Therefore:
Telemetry.publishInfo(InfoType::HARDWARE);
returns false.
Publish all documents#
Telemetry.publishAll();
attempts INFO, hardware configuration, system, network, and heartbeat when it is enabled:
INFO
HARDWARE
SYSTEM
NETWORK
HEARTBEAT
even if an earlier publication fails.
The return value is true only if all enabled publications succeed.
Automatic startup#
Telemetry.start();
installs the system and network Scheduler callback jobs plus heartbeat when it is enabled:
nm.telemetry.system
nm.telemetry.network
nm.telemetry.heartbeat
All installed telemetry jobs are MANAGED jobs.
The startup operation is all-or-nothing. Any failure removes jobs installed by that attempt so a later retry does not collide with a half-installed telemetry configuration.
Heartbeat configuration#
Heartbeat is enabled by default with a 15-second period. It is controlled by two persistent Configs:
heartbeat:enable boolean, default true
heartbeat:period integer seconds, default 15, range 15..86400
For example:
CONFIG SET heartbeat:enable false
CONFIG SET heartbeat:period 60
CONFIG SET heartbeat:enable true
The Configs use typed per-Config onWrite callbacks. Changing the period while
enabled immediately replaces the MANAGED heartbeat job. Disabling removes the
job; enabling installs it with the current period. An out-of-range period is
rejected without changing the Config or current schedule.
System interval#
System telemetry uses:
NM_TELEMETRY_INTERVAL_MS
Default:
60000 ms
The job is recurring monotonic runtime work.
It does not persist across reboot.
Network interval#
Network telemetry uses:
NM_NETWORK_TELEMETRY_INTERVAL_MS
Default:
300000 ms
The slower cadence is deliberate because network telemetry is bookkeeping.
Active-transport reconnect and state-change publication#
Every MQTT connection requests cooperative publication of:
Telemetry.publishInfo(InfoType::INFO);
Telemetry.publishHardware();
when telemetry is enabled.
tickNightMareESP() processes one request per call, so the two
allocation-heavy static documents are not built during the MQTT/TLS connection
callback. Meaningful connectivity-service, preferred-transport, and
active-transport changes request a coalesced NETWORK refresh. SYSTEM and
NETWORK also continue on their periodic schedules. HEARTBEAT continues on its
runtime-configured schedule when enabled.
Why network telemetry can look stale after disconnect#
Network telemetry is retained.
If a device disappears unexpectedly, the retained document may still contain:
"mqtt": {"state": "CONNECTED"}
because the device is no longer available to rewrite it.
This is expected.
Presence belongs to:
<device>/status
Network telemetry is last-known bookkeeping.
Resource state is not telemetry#
NightMare deliberately does not copy application Values into a generic telemetry blob.
For example:
temperature
power
target_temperature
door_open
belong to Resources.
Resources already define:
- ownership,
- type,
- access,
- retained state,
- freshness,
- subscriptions.
Duplicating those fields into telemetry would create a second source of application truth.
Hardware configuration#
Hardware configuration uses:
NMHardware::getProfile();
If no project NightMareHardware.h exists, the profile defaults to:
host_assembly: main
roots: [{ id: main, kind: generic }]
definitions: none
connections: none
The canonical retained topic is:
<device>/hardware/msgpack
The readable JSON form is available on demand through:
Telemetry.getHardware();
Publication uses:
Telemetry.publishHardware();
It publishes MessagePack canonically and, only when NM_ENABLE_JSON_WIRE=1,
also publishes <device>/hardware/json. Failure of that optional sibling does
not make canonical publication fail. The bare hardware root carries no payload.
Version 2 stores assemblies, devices, connectors, contacts, terminals, reusable
definitions, and physical connections. It does not store normal nets. The
firmware validates the expanded configuration and infers connected components
with buildTopologyGraph() and inferNets(). Invalid or over-capacity
configuration fails publication rather than producing a partial retained
document. See Hardware configuration v2.