مرجع MQTT Topicهای Gateway

این صفحه مرجع Public Topicهای Gateway v1 است. Direct Device Topicها در معماری Gateway استفاده نمی‌شوند.

Namespace اصلی

تمام Gateway Cloud Topicهای فعال از این الگو استفاده می‌کنند:

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

• up: Gateway → Server
• dn: Server → Gateway
• تمام Topicهای gateway-cloud به /AES ختم می‌شوند.
• retain=false است مگر جایی که صریحاً خلاف آن نوشته شده باشد.

Gateway → Server

Topic	QoS	Retain	کاربرد
{projectCode}/v1/gw/{gatewaySerial}/up/status/AES	1	true	Online/Offline و 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
{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	ACK عمومی غیر Command
{projectCode}/v1/gw/{gatewaySerial}/up/cmd/ack/{mid}/AES	1	false	نتیجه واقعی اجرای Command
{projectCode}/v1/gw/{gatewaySerial}/up/telemetry/{deviceSerial}/AES	0 یا 1	false	Telemetry/State واقعی
{projectCode}/v1/gw/{gatewaySerial}/up/event/{type}/AES	1	false	Event مهم
{projectCode}/v1/gw/{gatewaySerial}/up/onboard/req/AES	1	false	درخواست Onboarding
{projectCode}/v1/gw/{gatewaySerial}/up/onboard/log/AES	1	false	گزارش Onboarding
{projectCode}/v1/gw/{gatewaySerial}/up/auth/token/request/AES	1	false	درخواست API Token

Server → Gateway

Topic	QoS	Retain	کاربرد
{projectCode}/v1/gw/{gatewaySerial}/dn/sync/manifest/AES	1	false	Manifest و ترتیب Sync
{projectCode}/v1/gw/{gatewaySerial}/dn/cmd/AES	1	false	Command برای 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
{projectCode}/v1/gw/{gatewaySerial}/dn/auth/token/response/AES	1	false	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 قبل از AES:

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

deviceSerial در این payload مربوط به Child است، اما deviceSerial داخل AES envelope مربوط به 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 یکی از success | failed | unknown است. MQTT PUBACK هرگز جای این ACK را نمی‌گیرد.

Telemetry

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

QoS Telemetry می‌تواند برای داده پرتکرار 0 و برای State مهم 1 باشد.

Child Shadow

Topic با retain=true:

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

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

Offline شدن Child retained Shadow را حذف نمی‌کند. Shadow فقط وقتی حذف می‌شود که Child واقعاً از Gateway Unbind شود.

HTML Live Topicها

این چهار Topic Gateway Cloud Topic نیستند و /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

هر چهار مورد: QoS 1، Retain false، WSS/TLS + Temporary Credential.

Legacy / Future

• up/register / up/announce: Legacy/Cancelled؛ استفاده نکنید.
• Full snapshot sync از MQTT: Legacy؛ Sync فعلی Hybrid HTTP+MQTT است.
• OTA/Coredump و Scenario Gateway: Future/Deferred تا Contract مستقل فعال شود.

نکته امنیتی

Topic path فقط Routing است. Authoritative identity و authorization از Credential/AES/Association معتبر می‌آید؛ هیچ payload یا path ساختگی نباید بتواند Child دیگری را جعل کند.