NightMare Networkv1.0.0-alpha.1

Search every page of the documentation. Or start with:

Docs / Protocols / MQTT topics

MQTT topics

NightMare Network uses MQTT topics as a small wire protocol. Topic names are case-sensitive.

The current protocol is device-rooted:

<device>/...

Namespace is not yet encoded into the topic address.

Device-name rules#

A NightMare device name is one MQTT topic segment.

It must:

  • contain 1 to 64 characters,
  • not be all,
  • not contain /, +, or #,
  • not contain control characters below 0x20.

all is reserved for broadcast command input.

Topic map#

The current standard topic families are:

<device>/status

<device>/info
<device>/hardware/msgpack
<device>/hardware/json
<device>/telemetry/system
<device>/telemetry/network
<device>/telemetry/heartbeat

<device>/manifest/msgpack
<device>/manifest/json
<device>/manifest/consume/msgpack
<device>/manifest/consume/json
<device>/resource/<name>/state
<device>/resource/<name>/set
<device>/resource/<name>/invoke

<device>/console/in
<device>/console/out
<device>/console/controlled/<id>/in
<device>/console/controlled/<id>/out

all/console/in

Control/request
Control/time

Not every device subscribes to every topic. Subscriptions are installed according to enabled features and bound Resources.

Retained topics#

NightMare uses retained messages for current state and current description.

Topic Retained Purpose
<device>/status yes name, hardware signature, timezone + online/offline presence
<device>/info yes boot-scoped/static device information
<device>/hardware/msgpack yes canonical positional hardware configuration
<device>/hardware/json yes optional readable hardware sibling
<device>/telemetry/system yes last published runtime system telemetry
<device>/telemetry/network yes last published network bookkeeping
<device>/manifest/msgpack yes compact positional Resource manifest
<device>/manifest/json yes optional readable Resource manifest
<device>/manifest/consume/msgpack yes compact consume manifest
<device>/manifest/consume/json yes optional readable consume manifest
<device>/resource/<name>/state yes authoritative Value state

An empty retained payload is used as a tombstone where NightMare needs to remove retained state.

For Resource Value state specifically, an empty retained /state means the state has been withdrawn. A bound Remote Value becomes unavailable; withdrawal does not redefine freshness as STALE. Its last decoded value remains stored as last-known data.

Transient topics#

Requests, commands, and command responses are not retained.

Topic Retained Purpose
<device>/resource/<name>/set no request a writable Value change
<device>/resource/<name>/invoke no invoke an Action
<device>/console/in no ordinary command request
<device>/telemetry/heartbeat no runtime-configurable device heartbeat
<device>/console/out no ordinary command response/status
<device>/console/controlled/<id>/in no correlated command request
<device>/console/controlled/<id>/out no correlated command response
all/console/in no broadcast command request
Control/request no global control request, currently time sync
Control/time no global time-sync response

Resource topics#

Manifest#

<device>/manifest/msgpack
<device>/manifest/json

The MessagePack manifest is canonical and retained. The JSON sibling is published only when NM_ENABLE_JSON_WIRE=1. The bare manifest path is a namespace, not a payload topic.

It is descriptive metadata. It does not make Value state fresh and does not gate /state, /set, or /invoke.

Consume manifest#

<device>/manifest/consume/msgpack
<device>/manifest/consume/json

The canonical retained document represents every declared Remote Resource once. An entry with bound: true derives an active consume edge; an unbound entry is still discoverable and configurable. JSON is optional, and the bare consume root is a namespace.

Value state#

<device>/resource/<name>/state

Retained owner state for a Value.

The payload is the Value's codec representation, not a generic JSON envelope.

Examples:

true
23
23.5
cool

Value write request#

<device>/resource/<name>/set

Transient request to a Managed READ_WRITE Value.

The payload uses the same Value codec representation as /state.

Action invocation#

<device>/resource/<name>/invoke

Transient Action request.

The payload is passed to the Action as its canonical payload std::string. Schema-based Actions normally use a JSON object payload, but payload validation is optional at compile time.

There is no Resource result topic.

See Resource protocol for the complete Resource wire contract.

Resource subscriptions#

NightMare subscribes only where a bound Resource needs ingress.

Bound Resource Automatic ingress subscription
ManagedSensor<T> none
ManagedState<T> its own /set
RemoteSensor<T> owner's /state
RemoteState<T> owner's /state
ManagedAction its own /invoke
RemoteAction none

When NM_ENABLE_REMOTE_RESOURCE_VERIFICATION is enabled, the manager also subscribes once to:

<remote-device>/manifest/msgpack

per remote owner. The compact manifest is decoded for compatibility diagnostics against the local Remote-resource declarations. This verification subscription is separate from optional JSON +/manifest/json discovery/handler subscriptions.

These subscriptions are rebuilt after the active transport reconnects.

Ordinary console#

A device with Console + MQTT enabled subscribes to:

<device>/console/in
all/console/in

A command received on either path is executed by the normal NightMare command handler.

The response is published to:

<device>/console/out

For all/console/in, every receiving device replies on its own <device>/console/out; broadcast input is therefore not a single correlated request/response channel.

On MQTT connection, NightMare also publishes a transient message on <device>/console/out:

Booted

for the first connection in the boot, and:

Connected

on later MQTT connections.

Controlled console / MQTTP#

A device also subscribes to:

<device>/console/controlled/+/in

A request at:

<device>/console/controlled/<id>/in

is answered at:

<device>/console/controlled/<id>/out

The <id> is supplied by the caller and creates the correlation.

See MQTTP for the exact ID rules and request/response behavior.

Time synchronization topics#

Automatic time synchronization now uses ESP32 SNTP. The MQTT control topics remain as an auxiliary timestamp path.

When time synchronization is enabled, NightMare subscribes to:

Control/time

If MQTT connects while NightMare's wall clock is not valid, the device publishes:

topic:   Control/request
payload: time

The request is transient and is not prefixed with the device name.

A Control/time payload must be a JSON object containing both:

{
  "timestamp": 1790000000,
  "offset": -10800
}

timestamp is consumed by the current implementation. A value larger than the 32-bit Unix-seconds range is treated as milliseconds and divided by 1000.

offset is currently required for the message to be accepted but is not otherwise used by the router.

Project transport subscriptions#

Applications may register additional topic filters with:

void subscribeProjectTopics()
{
    NightMare::Subscribe("project/topic");
}

void setup()
{
    NightMare::OnConnect(subscribeProjectTopics);
    startNightMareESP();
}

Subscribe() and Unsubscribe() act immediately on the active transport and store no reconnect state. Firmware therefore owns its filter list and installs it again from OnConnect(). Framework owners follow the same event-driven pattern internally. Messages not consumed by a framework route are delivered to the handler registered with NightMare::OnMessage(). Another device's manifest, /state and /event are delivered there too, also when the Resource Manager read them for a Remote Resource.

The connection boundary validates:

topic filter length: 192 characters

NightMare validates MQTT wildcard placement for + and #.

Last updated · Edit this page on GitHub