Gateway MQTT Topic Reference

This is the public Gateway v1 topic reference. Direct Device topics are not used for Gateway-mediated Children.

Main namespace

All active Gateway-cloud topics follow:

{projectCode}/v1/gw/{gatewaySerial}/{up|dn}/{action}/AES

• up: Gateway → Server
• dn: Server → Gateway
• every active gateway-cloud topic ends in /AES
• retain=false unless explicitly stated otherwise

Gateway → Server

Topic	QoS	Retain	Purpose
{projectCode}/v1/gw/{gatewaySerial}/up/status/AES	1	true	Online/offline and LWT
{projectCode}/v1/gw/{gatewaySerial}/up/sync/status/AES	1	true	Revision/sync status
{projectCode}/v1/gw/{gatewaySerial}/up/sync/check/AES	1	false	Sync coordination request
{projectCode}/v1/gw/{gatewaySerial}/up/heartbeat/AES	0	false	Health/liveness
{projectCode}/v1/gw/{gatewaySerial}/up/device/{deviceSerial}/AES	1	true	Child Shadow
{projectCode}/v1/gw/{gatewaySerial}/up/ack/{mid}/AES	1	false	General non-command ACK
{projectCode}/v1/gw/{gatewaySerial}/up/cmd/ack/{mid}/AES	1	false	Real command execution result
{projectCode}/v1/gw/{gatewaySerial}/up/telemetry/{deviceSerial}/AES	0 or 1	false	Actual telemetry/state
{projectCode}/v1/gw/{gatewaySerial}/up/event/{type}/AES	1	false	Significant event
{projectCode}/v1/gw/{gatewaySerial}/up/onboard/req/AES	1	false	Onboarding request
{projectCode}/v1/gw/{gatewaySerial}/up/onboard/log/AES	1	false	Onboarding report
{projectCode}/v1/gw/{gatewaySerial}/up/auth/token/request/AES	1	false	Request API token

Server → Gateway

Topic	QoS	Retain	Purpose
{projectCode}/v1/gw/{gatewaySerial}/dn/sync/manifest/AES	1	false	Sync manifest/order
{projectCode}/v1/gw/{gatewaySerial}/dn/cmd/AES	1	false	Command to a Child
{projectCode}/v1/gw/{gatewaySerial}/dn/discover/start/AES	1	false	Trigger discovery
{projectCode}/v1/gw/{gatewaySerial}/dn/onboard/rsp/{reqId}/AES	1	false	Onboarding response
{projectCode}/v1/gw/{gatewaySerial}/dn/auth/token/response/AES	1	false	Short-lived API token
{projectCode}/v1/gw/{gatewaySerial}/dn/sys/reboot/AES	1	false	Reboot Gateway

Command payload

Topic:

{projectCode}/v1/gw/{gatewaySerial}/dn/cmd/AES

Plaintext business payload before AES:

{
  "mid": "cmd-0001",
  "deviceSerial": "AIRN0987654321",
  "groupKey": "rgb",
  "operationKey": "on_off",
  "commandKey": "on",
  "params": {}
}

The business deviceSerial is the Child. The deviceSerial inside the AES envelope is the Physical Gateway.

Command execution ACK

Topic:

{projectCode}/v1/gw/{gatewaySerial}/up/cmd/ack/{mid}/AES

{
  "mid": "cmd-0001",
  "deviceSerial": "AIRN0987654321",
  "status": "success",
  "code": "success",
  "retry": "none",
  "completedAtUtc": "2026-09-14T08:12:03Z",
  "diagnostic": {"message": null, "nativeCode": null}
}

status is success | failed | unknown. MQTT PUBACK never replaces this application result.

Telemetry

{
  "deviceSerial": "AIRN0987654321",
  "values": [
    {"groupKey":"rgb","operationKey":"on_off","value":true,"ts":1813000001}
  ]
}

Telemetry may use QoS 0 for frequent/noisy data or QoS 1 for important state.

Child Shadow

Retained topic:

{projectCode}/v1/gw/{gatewaySerial}/up/device/{deviceSerial}/AES

{
  "deviceSerial": "AIRN0987654322",
  "deviceId": "device-template-rgb-v1",
  "online": false,
  "enabled": true,
  "reason": "poll_timeout",
  "lastSeenAt": 1812999000
}

A Child going offline does not delete its retained Shadow. The retained entry is removed only when the Child is actually unbound.

HTML Live topics

These four topics are not Gateway-cloud AES topics and do not carry /AES:

{projectCode}/v1/gw/{gatewaySerial}/html/{sessionId}/request
{projectCode}/v1/gw/{gatewaySerial}/html/{sessionId}/response
{projectCode}/v1/gw/{gatewaySerial}/html/{sessionId}/event
{projectCode}/v1/gw/{gatewaySerial}/html/{sessionId}/control

All four use QoS 1, retain=false, WSS/TLS, and temporary session credentials.

Legacy / future

• up/register / up/announce: legacy/cancelled; do not implement.
• Full snapshot sync over MQTT: legacy; current sync is hybrid HTTP+MQTT.
• Gateway OTA/coredump/scenario topics: future/deferred until explicitly activated by their own contract.

Security note

A topic path is routing context, not authorization by itself. Credentials, AES validation, and current association authority determine whether traffic is trusted.