NightMare Networkv1.0.0-alpha.1

Search every page of the documentation. Or start with:

Docs / Protocols / MQTTP

MQTTP

MQTTP is NightMare's correlated command request/response pattern over MQTT.

In the current implementation it is the controlled console topic family:

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

It reuses the normal NightMare command parser and command handler. It is not a second command language.

Purpose#

Ordinary MQTT console uses:

<device>/console/in
<device>/console/out

That is convenient for interactive/operator use, but several requests can share the same output topic.

MQTTP gives a caller a request-specific topic pair by supplying an ID.

Example:

request:
bedroom-ac/console/controlled/req-42/in

response:
bedroom-ac/console/controlled/req-42/out

The caller can subscribe to the response topic before publishing the request and correlate that response with its own ID.

Device subscription#

With MQTT + Console enabled, every device subscribes to:

<device>/console/controlled/+/in

The + wildcard represents exactly one request ID segment.

Request#

Publish a normal NightMare command std::string to:

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

Example:

topic:
bedroom-ac/console/controlled/req-42/in

payload:
INFO SYSTEM

The payload is parsed by the same handleNightMareCommand() implementation used by the other command sources.

All normal command grammar rules therefore apply:

  • 512-character maximum command line,
  • command and subcommand are case-insensitive through uppercasing,
  • up to five arguments after the command word,
  • quoted arguments,
  • backtick literal arguments,
  • normal built-in and project-resolver behavior.

See Commands.

Response#

The result std::string is published to:

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

Example:

topic:
bedroom-ac/console/controlled/req-42/out

payload:
{"uptime_ms":123456,"cpu_mhz":160,...}

The response is transient:

retained: false

MQTTP does not define a second JSON response envelope around command output. The response payload is the command handler's result.response std::string.

That means the payload format depends on the command:

PING
    PONG

INFO SYSTEM
    JSON object

JOB LIST
    JSON object

CONFIG GET <name>
    the Config's NetCodec text value

CONFIG MANIFEST
    Base64 of the versioned Config MessagePack manifest

The caller must know the command's response contract.

Request ID rules#

The <id> must:

  • contain at least 1 character,
  • contain at most 64 characters,
  • not contain /,
  • not contain +,
  • not contain #,
  • not contain control characters below 0x20.

The ID is a topic segment supplied by the caller.

NightMare does not generate IDs for the caller.

ID uniqueness#

The device does not maintain an ID registry.

It simply derives the response topic from the incoming request topic.

Therefore uniqueness is the caller's responsibility.

Two clients using the same:

<device>
<id>

at the same time will share the same response topic.

A practical ID should therefore be unique enough for the client/session issuing the request.

Request lifecycle#

The minimal caller flow is:

1. choose id
2. subscribe to <device>/console/controlled/<id>/out
3. publish command to <device>/console/controlled/<id>/in
4. wait for one response
5. correlate it by id
6. unsubscribe when appropriate

The device itself does not create client-side timeout or retry policy.

No retention#

Neither request nor response is retained.

MQTTP is for command transactions, not state.

A late subscriber should not receive an old response from the broker as if it belonged to a new request.

No device-side retry contract#

The current protocol defines no device-side:

retry
acknowledgement-of-acknowledgement
request persistence
duplicate suppression
idempotency registry
transaction log

If a client times out and retries a command, whether that command is safe to repeat depends on the command itself.

Clients should treat non-idempotent commands accordingly.

Error responses#

Parser errors and command failures still produce normal response payloads.

Examples include:

Parse error: ...
Unknown INFO section.
Job not found.
Command 'X' unrecognized.

There is no generic MQTTP status-code envelope around those strings.

Where a command returns JSON containing its own error shape, that is the command's contract rather than an MQTTP-level contract.

Ordinary console vs MQTTP#

Property Ordinary console MQTTP / controlled console
Request <device>/console/in <device>/console/controlled/<id>/in
Response <device>/console/out <device>/console/controlled/<id>/out
Correlation shared output caller-provided ID
Request retained no no
Response retained no no
Command grammar NightMare command grammar same
Built-ins same same

Broadcast console is not MQTTP#

NightMare also accepts:

all/console/in

Every subscribed device executes that command and responds at its own:

<device>/console/out

There is no controlled ID in that path.

Broadcast console is therefore useful for fan-out commands, but it is not one correlated request/response transaction.

Relationship to Resource Actions#

Raw Resource Action MQTT still uses:

<device>/resource/<action>/invoke

and remains fire-and-forget.

The > Resource-command adapter gives command sources a correlated path around local Resource execution. An MQTTP request such as:

> identify invoke {"mode":"blink"}

executes a ManagedAction on the receiving device and returns its ActionResult.result on the matching controlled-console response topic.

This does not add a Resource result topic.

If the bound Action is Remote, the command publishes the normal /invoke request and can only report whether that publication was accepted. It still cannot report remote execution success. RemoteState writes have the same transport-acceptance limitation.

Context on the device#

Controlled-console requests are executed with MQTT command source context.

Internally, the source identifier is the derived response topic:

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

This allows the MQTT command runner to publish the command result to the correct correlated topic.

The project command resolver itself currently receives NightMareMessage, not the full input NightmareContext, so applications should not depend on reading the controlled ID from the resolver API.

What MQTTP guarantees#

For the current implementation, MQTTP guarantees only the protocol mapping:

valid controlled request topic
    -> run one NightMare command
    -> publish its response on the matching controlled output topic

It does not guarantee:

  • remote business-operation success beyond what the command reports,
  • exactly-once execution,
  • retry,
  • durable requests,
  • durable responses,
  • cross-device transactions.

Those behaviors must not be inferred from the presence of a request ID.

Last updated · Edit this page on GitHub