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_インデックス で始まります（インデックスは 2 桁、例：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 でのテスト

連携テスト受け入れチェックリスト

よくあるエラー

接続が拒否される

デバイスはオンラインだが属性が更新されない

プラットフォームからの指令をデバイスが受信できない

ルールまたはアラームがトリガーされない

ルールスクリプトによる変換

関連ドキュメント