sky121113
32fa28dc0f
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 1m12s
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) 以符合新架構。
101 lines
3.7 KiB
Markdown
101 lines
3.7 KiB
Markdown
---
|
||
name: MQTT 即時通訊與 Topic 規範
|
||
description: 定義 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 開銷。
|
||
|
||
```json
|
||
{
|
||
"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 邏輯。
|
||
|
||
```json
|
||
{
|
||
"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 的輪詢等待。
|
||
|
||
```json
|
||
{
|
||
"command": "dispense",
|
||
"payload": {
|
||
"slot_no": 5,
|
||
"transaction_id": "T202604140001"
|
||
},
|
||
"message_id": "MSG_123456789"
|
||
}
|
||
```
|
||
**常用指令集：**
|
||
- `reboot`: 機台重啟。
|
||
- `reload_config`: 重新下載參數 (B014)。
|
||
- `reload_products`: 重新同步商品 (B012)。
|
||
- `dispense`: 遠端出貨指令 (B055)。
|
||
|
||
---
|
||
|
||
## 4. 安全與 QOS 規範
|
||
|
||
1. **存取控制 (ACL)**：EMQX Broker 必須設定 ACL，禁止機台 A 訂閱機台 B 的 Topic。機台僅能訂閱與發布包含自身 `serial_no` 的路徑。
|
||
2. **QoS 策略**：
|
||
- **QoS 0**：適用於高頻率心跳，即使掉一兩次包也不影響系統判斷。
|
||
- **QoS 1**：適用於交易與指令，確保「至少送達一次」。App 端收到指令後應回覆回執。
|
||
3. **遺囑訊息 (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 輪詢模式以維持基礎通訊。
|