Files

star-cloud-deploy-demo / deploy-demo (push) Successful in 1m12s

Details

1. 新增 MQTT 即時通訊與 Topic 規範文件 (.agents/skills/mqtt-communication-specs/SKILL.md)。
2. 建立 MQTT 基礎架構實作計畫文件 (docs/mqtt-implementation-plan.md)。
3. 更新全域開發框架規範 (framework.md)，納入 Go Gateway 與 EMQX 架構說明。
4. 重構 IoT 通訊處理規範 (iot-communication/SKILL.md)，支援 HTTP 與 MQTT 雙軌管線。
5. 更新背景 API 規範 (api-rules.md) 與技能觸發規則 (skill-trigger.md) 以符合新架構。

2026-04-14 13:02:08 +08:00

3.7 KiB

Raw Blame History

name, description

name	description
MQTT 即時通訊與 Topic 規範	定義 Star Cloud 與終端機台 (IoT) 之間的 MQTT 全域通訊拓撲、主題 (Topic) 結構、資料載體 (Payload) 格式與安全性認證機制。

MQTT 即時通訊與 Topic 規範 (MQTT Protocol Specs)

本文件定義機台與 Star Cloud 之間的高併發即時通訊標準。MQTT 主要用於處理高頻率且對即時性要求高的訊息（如心跳、遠端指令），與 HTTP REST API 形成雙軌互補架構。

1. 連線基礎設定 (Connection Basics)

1.1 Broker 資訊

協議版本：MQTT v3.1.1 (相容性最高)
預設埠號：1883 (TCP / 測試用), 8883 (SSL/TLS / 正式用)
Keep-Alive：建議設定為 30 ~ 60 秒。

1.2 身份認證 (Authentication)

機台連線時必須提供以下憑據：

Username：機台編號 (serial_no)，例如 M-001。
Password：機台正式 Token (api_token)，由 B014 API 取得。
Client ID：建議格式為 SC_{serial_no}_{random_suffix}，確保唯一性。

2. 主題架構 (Topic Topology)

我們採用目錄式的層級結構，方便未來進行萬台設備的管理與 ACL 權限切分。

主題名稱 (Topic)	方向	QoS	用途說明
`machine/{serial_no}/heartbeat`	設備 ➜ 雲端	0	每 10 秒上報心跳、溫度、目前的頁面碼。
`machine/{serial_no}/error`	設備 ➜ 雲端	1	發生硬體故障、卡貨或門未關時立即上報。
`machine/{serial_no}/transaction`	設備 ➜ 雲端	1	交易完成、出貨結果的回報。
`machine/{serial_no}/command`	雲端 ➜ 設備	1	雲端下發的即時指令（出貨、更新、重啟）。

3. 資料載體規範 (Payload Definitions)

所有 Payload 統一採用 JSON 格式，字母一律為 snake_case。

3.1 心跳上報 (Heartbeat) - `machine/{id}/heartbeat`

比照原 B010 邏輯，但去除不必要的 HTTP Header 開銷。

{
  "current_page": 1,
  "firmware_version": "1.0.5",
  "temperature": 25.5,
  "door_status": 0,
  "timestamp": "2026-04-14T09:00:00+08:00"
}

3.2 異常上報 (Error/Event) - `machine/{id}/error`

比照原 B013 邏輯。

{
  "tid": 12,
  "error_code": "0403",
  "log": "Slot jammed at slot 12",
  "timestamp": "2026-04-14T09:05:00+08:00"
}

3.3 雲端指令 (Downstream Commands) - `machine/{id}/command`

這是雲端主動下發給機台的訊息，取代原本 B010 Response 的輪詢等待。

{
  "command": "dispense",
  "payload": {
    "slot_no": 5,
    "transaction_id": "T202604140001"
  },
  "message_id": "MSG_123456789"
}

常用指令集：

reboot: 機台重啟。
reload_config: 重新下載參數 (B014)。
reload_products: 重新同步商品 (B012)。
dispense: 遠端出貨指令 (B055)。

4. 安全與 QOS 規範

存取控制 (ACL)：EMQX Broker 必須設定 ACL，禁止機台 A 訂閱機台 B 的 Topic。機台僅能訂閱與發布包含自身 serial_no 的路徑。
QoS 策略：
- QoS 0：適用於高頻率心跳，即使掉一兩次包也不影響系統判斷。
- QoS 1：適用於交易與指令，確保「至少送達一次」。App 端收到指令後應回覆回執。
遺囑訊息 (Last Will and Testament)：機台 Connect 時應設定 Last Will 於 machine/{serial_no}/heartbeat，Payload 為 {"status": "offline"}。當連線異常中斷時，雲端能立刻得知。

5. 與 REST API 的同步關係

當 MQTT 通訊正常時，機台應停止定時呼叫 B010 HTTP API。若 MQTT 斷線超過 3 分鐘，則退回 (Fallback) 使用 HTTP 輪詢模式以維持基礎通訊。

3.7 KiB Raw Blame History Unescape Escape