MQTT 接入

FastBee 開源版內建基於 Netty 開發的 MQTT Broker，無需額外部署 EMQX。本文介紹設備如何透過 MQTT 協定接入平台。

接入流程

在產品管理中建立並發佈 MQTT 產品，確認產品 ID、設備編號、MQTT 帳號和密碼
設備或 MQTTX 使用約定的 clientId、userName、password 連線 MQTT 服務
連線成功後先發佈 /info/post，再發佈 /property/post 或 /event/post
平台側透過設備詳情的運行狀態、事件日誌和指令日誌確認鏈路閉環

連線資訊

參數	TCP 連線	WebSocket 連線
位址	伺服器 IP	`ws://伺服器IP:8083/mqtt`
連接埠	1883	8083
協定	MQTT 3.1.1	MQTT over WebSocket

設備認證

提示

認證類型：S = 簡單認證，E = 加密認證
產品啟用設備授權碼後，授權碼不可為空
使用者 ID 是登入使用者的 ID，使用不同使用者 ID 設備歸屬不同使用者
設備編號可以是平台建立的編號，也可以是設備 MAC/IMEI 等唯一編碼（平台會自動註冊設備）

簡單認證（建議測試使用）

clientId = S&設備編號&產品ID&使用者ID
userName = MQTT帳號
password = MQTT密碼
password = MQTT密碼&設備授權碼（產品啟用設備授權時）

範例：

clientId = "S&D68329VL588&2&1"
userName = "fastbee"
password = "PHYFED93WSFF1DAS"

加密認證（建議正式環境使用）

clientId = E&設備編號&產品ID&使用者ID
userName = MQTT帳號
password = AES加密(MQTT密碼&過期時間戳&授權碼(可選))

密碼使用產品金鑰進行 AES-CBC 加密（偏移量 wumei-smart-open，輸出 Base64）
過期時間戳精確到毫秒，建議 24 小時以內

範例：

clientId = "E&D68329VL588&2&1"
userName = "fastbee"
password = "/W2A/4MK+9cEGBhyBDgr2K5c62DAjAK4m0b5pvwxX6FFMzI3h1pUmaDY3BH1P2mI"

AES 加密說明

採用 AES-CBC 加密模式，測試可使用線上加解密工具：

參數	值
加密模式	CBC
填充	pkcs5padding
資料區塊	128 位元
偏移量	`wumei-smart-open`
輸出	Base64
密碼	產品金鑰
加密內容	`MQTT密碼&expireTime&授權碼(可選)`

訂閱主題（平台 → 設備）

主題	描述
`/{productId}/{deviceNum}/function/get`	訂閱平台指令（屬性設定、功能呼叫）
`/{productId}/{deviceNum}/info/get`	訂閱設備資訊請求（收到後發佈設備資訊）
`/{productId}/{deviceNum}/monitor/get`	訂閱即時監測請求（回傳次數和間隔）
`/{productId}/{deviceNum}/ntp/get`	訂閱時鐘同步（可選）
`/{deviceNum}/http/upgrade/set`	HTTPS 方式訂閱 OTA 升級
`/{deviceNum}/fetch/upgrade/set`	二進位套件方式訂閱 OTA 升級

發佈主題（設備 → 平台）

主題	描述
`/{productId}/{deviceNum}/property/post`	發佈屬性/功能資料（即時顯示並儲存）
`/{productId}/{deviceNum}/event/post`	發佈事件
`/{productId}/{deviceNum}/info/post`	發佈設備資訊
`/{productId}/{deviceNum}/monitor/post`	發佈即時監測資料（僅即時圖表，不儲存）
`/{productId}/{deviceNum}/ntp/post`	發佈時鐘同步（可選）
`/{deviceNum}/http/upgrade/reply`	HTTPS 方式回覆 OTA 升級
`/{deviceNum}/fetch/upgrade/reply`	二進位套件方式回覆 OTA 升級

提示

{productId} 為產品 ID（非產品編號），在平台產品詳情中取得
{deviceNum} 為設備編號，與平台設備完全一致

資料格式

設備和平台互動使用 JSON 格式。

發佈屬性/功能/事件 — `/property/post`、`/event/post`

json

[{
    "id": "temperature",
    "value": "27.43",
    "remark": "溫度正常"
}, {
    "id": "switch",
    "value": "1",
    "remark": "開關已開啟"
}]

id：物模型識別碼，產品詳情中查看，產品下唯一
value：值以字串傳遞；布林型別用 "0"/"1"；列舉型別對應列舉鍵值；陣列型別以逗號分隔
remark：備註資訊，設備日誌中可查看

訂閱平台指令 — `/function/get`

json

[{
    "id": "gear",
    "value": "1",
    "remark": "場景聯動觸發"
}, {
    "id": "switch",
    "value": "0",
    "remark": "定時關閉"
}]

發佈設備資訊 — `/info/post`

json

{
    "rssi": -43,
    "firmwareVersion": 1.2,
    "status": 3,
    "userId": 1,
    "longitude": 0,
    "latitude": 0,
    "summary": {
        "name": "FastBee",
        "chip": "ESP32"
    }
}

欄位	說明
rssi	訊號強度（極佳 [-55~0]，佳 [-70~-55]，普通 [-85~-70]，差 [-100~-85]）
firmwareVersion	韌體版本號
status	設備狀態，固定為 3（線上）
userId	使用者 ID
longitude/latitude	可選，設備定位
summary	可選，設備摘要資訊

即時監測 — `/monitor/get`、`/monitor/post`

平台下發監測請求：

json

{
    "count": 60,
    "interval": 1000
}

設備按指定次數和間隔上報資料：

json

[{
    "id": "temperature",
    "value": "27.43",
    "remark": ""
}]

時鐘同步 — `/ntp/post`、`/ntp/get`

設備發佈：

json

{
    "deviceSendTime": "1592361428000"
}

平台回覆：

json

{
    "deviceSendTime": "1592361428000",
    "serverRecvTime": "1592366463548",
    "serverSendTime": "1592366463548"
}

設備目前時間 = (serverRecvTime + serverSendTime + deviceRecvTime - deviceSendTime) / 2

物模型識別碼規則

所有識別碼在產品下唯一，以字母和數字為主，避免特殊字元
物件型別子模型 ID 格式：parentId_childId
陣列型別識別碼以 array_索引 開頭（索引為兩位數，如 array_00_power_switch），陣列長度不超過 100

設備 AP 配網（可選，僅限 WiFi 設備）

設備開啟熱點（位址 192.168.4.1），行動端透過設備 Web 服務傳遞設定資訊。

偵測設備

GET http://192.168.4.1/api/wifi/status

HTTP 200 表示偵測到設備，回應包含設備資訊與目前網路狀態。

設定介面

POST http://192.168.4.1/api/wifi/config?SSID=WiFi名稱&password=WiFi密碼&userId=使用者ID

參數	說明
SSID	WiFi 名稱（必傳，相容小寫 ssid）
password	WiFi 密碼（必傳，相容別名 pwd）
userId	使用者 ID（必傳）
deviceNum	設備編號（可選）
extra	產品編號（可選）

HTTP 200 表示配網成功（設備隨後自動切換 STA 模式），400 表示必傳參數缺失，500 表示儲存失敗。介面詳細說明見《網路設定 · 手機/行動端 AP 配網 API》。

使用 MQTTX 測試

下載 MQTTX 用戶端
新建連線：
- Host: mqtt://伺服器IP，Port: 1883
- Client ID: S&設備編號&產品ID&1
- Username: MQTT 帳號
- Password: MQTT 密碼
訂閱 /{productId}/{deviceNum}/function/get
向 /{productId}/{deviceNum}/info/post 發佈設備資訊
向 /{productId}/{deviceNum}/property/post 發佈屬性資料
觀察平台控制台設備線上狀態和運行資料

聯調驗收清單

步驟	驗收內容	成功表現
1	產品已發佈	產品狀態為已發佈
2	MQTTX 連線	設備詳情顯示線上
3	`/info/post`	設備資訊、訊號、版本欄位更新
4	`/property/post`	運行狀態顯示物模型屬性值
5	`/event/post`	事件日誌出現上報事件
6	`/function/get`	平台下發後設備收到指令
7	回傳結果	設備按下發結果回傳，平台狀態重新整理
8	規則/場景	相關規則、場景、告警能被觸發

常見錯誤

連線被拒絕

伺服器 1883 連接埠是否開放
內建 MQTT Broker 是否啟動
clientId 格式是否正確（S&設備編號&產品ID&使用者ID）
產品是否啟用設備授權碼
設備是否被停用

設備線上但屬性不更新

發佈主題是否為 /{productId}/{deviceNum}/property/post
productId 是否使用產品 ID（非產品編號）
deviceNum 是否與設備編號完全一致
訊息內容是否為 JSON 陣列格式
id 是否與物模型識別碼完全一致
value 是否符合資料型別

平台下發設備收不到

設備是否訂閱 /{productId}/{deviceNum}/function/get
設備是否仍在線上
物模型是否為可寫功能或可下發屬性
使用者是否有設備詳情和指令下發權限

規則或告警沒有觸發

設備資料是否進入平台運行狀態
場景或規則綁定的產品、設備、變數是否正確
條件表達式是否與上報值型別一致
告警設定是否啟用

規則指令碼轉換

如果設備使用自訂資料格式，可在 規則指令碼 中編寫轉換邏輯，將原始資料轉為平台標準格式。詳見規則指令碼（简体中文）。

關聯文件

產品管理（简体中文）
設備管理（简体中文）
物模型（简体中文）
場景聯動（简体中文）

MQTT 接入 ​

接入流程 ​

連線資訊 ​

設備認證 ​

簡單認證（建議測試使用） ​

加密認證（建議正式環境使用） ​

AES 加密說明 ​

訂閱主題（平台 → 設備） ​

發佈主題（設備 → 平台） ​

資料格式 ​

發佈屬性/功能/事件 — /property/post、/event/post ​

訂閱平台指令 — /function/get ​

發佈設備資訊 — /info/post ​

即時監測 — /monitor/get、/monitor/post ​

時鐘同步 — /ntp/post、/ntp/get ​

物模型識別碼規則 ​

設備 AP 配網（可選，僅限 WiFi 設備） ​

偵測設備 ​

設定介面 ​

使用 MQTTX 測試 ​

聯調驗收清單 ​

常見錯誤 ​

連線被拒絕 ​

設備線上但屬性不更新 ​

平台下發設備收不到 ​

規則或告警沒有觸發 ​

規則指令碼轉換 ​

關聯文件 ​

MQTT 接入

接入流程

連線資訊

設備認證

簡單認證（建議測試使用）

加密認證（建議正式環境使用）

AES 加密說明

訂閱主題（平台 → 設備）

發佈主題（設備 → 平台）

資料格式

發佈屬性/功能/事件 — `/property/post`、`/event/post`

訂閱平台指令 — `/function/get`

發佈設備資訊 — `/info/post`

即時監測 — `/monitor/get`、`/monitor/post`

時鐘同步 — `/ntp/post`、`/ntp/get`

物模型識別碼規則

設備 AP 配網（可選，僅限 WiFi 設備）

偵測設備

設定介面

使用 MQTTX 測試

聯調驗收清單

常見錯誤

連線被拒絕

設備線上但屬性不更新

平台下發設備收不到

規則或告警沒有觸發

規則指令碼轉換

關聯文件