---
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 輪詢模式以維持基礎通訊。