Mqtt プロトコルデバイス接続

ページガイド

対象シーンMQTT で直接接続デバイスやゲートウェイデバイスを接続する場合、または固定フォーマットのデバイスメッセージを FastBee プラットフォームに転送する場合に適しています。

前提条件製品が作成・公開済みで、デバイス番号、製品番号、MQTT アカウント、パスワード、デバイス認証コードを用意していること。

認証の推奨本番環境では暗号化認証を優先してください。簡易認証は連携テスト、デモ、問題切り分けに適しています。

受け入れ条件デバイスが接続に成功し、認証に合格し、トピックのサブスクライブが正常で、モノモデルの送信と指令受信を完了できること。

接続の入口と最小フロー

1. 製品管理で MQTT 製品を作成・公開し、製品 ID、デバイス番号、MQTT アカウント、パスワード、デバイス認証コードを確認します。
2. デバイスまたは MQTTX が、約束された clientId、userName、password で MQTT サービスに接続します。
3. 接続成功後、まず /info/post をパブリッシュし、次に /property/post または /event/post をパブリッシュします。
4. プラットフォーム側でデバイス詳細の稼働状態、イベントログ、指令ログ、ルールシーンを通じてリンクのクローズドループを確認します。

1. 接続手順

提示

• 参考となる ESP8266 ハードウェア SDK ソースコード FastBee Arduino SDK
• デバイスの Mqtt メッセージフォーマットが固定の場合は、ルールエンジンで転送してプラットフォームに適応させることができます
  • システム内蔵 netty-mqtt： トピックと内容の転送をサポート
  • emqx ミドルウェアを使用： 内容の転送をサポート。トピックは emqx 内蔵のルールエンジンで転送可能

1. デバイス認証

• 暗号化認証（推奨）
• 簡易認証

2. デバイス通信

• モノモデル、デバイス情報、時刻同期関連の Mqtt トピックをパブリッシュ
• モノモデル、デバイスアップグレード、時刻同期関連の Mqtt トピックをサブスクライブ

3. デバイス AP ネットワーク設定（オプション、Wifi 系デバイスのみ）

• デバイス検出インターフェース
• デバイス設定インターフェース

2. デバイス認証

提示

• 認証タイプ：S=簡易認証、E=暗号化認証
• 製品でデバイス認証コードを有効にした場合、認証コードは空にできません
• ユーザー ID はログインユーザーの ID で、異なるユーザー ID を使用するとデバイスは異なるユーザーに帰属します。admin アカウント 1 を統一使用し、後でネットワーク設定または QR コードスキャンによるデバイス関連付けで異なるユーザーに割り当てることもできます。
• デバイス番号の取得には 2 つの方法があります：1.システムでデバイスを新規作成したときに生成されたデバイス番号を使用。2.システムでデバイスを新規作成せず、ハードウェア側で一意の番号を生成してデバイス番号とする。認証後にシステムが自動的にデバイスエンティティを登録します（デバイスが多い場合はこの方式を推奨）

1. 暗号化認証

製品詳細で製品番号、Mqtt アカウント、Mqtt パスワード、製品シークレットを取得します。パスワードは製品シークレットで AES 暗号化してバックエンドに渡し、バックエンドは製品シークレットで復号して認証します。Mqtt メッセージサーバーへの接続には一意のクライアント ID、ユーザー名、パスワードが必要で、具体的な形式は以下のとおりです：

# クライアント ID = 認証タイプ + デバイス番号 + 製品番号 + ユーザー ID
clientId = E & deviceNumber & productId & userId

# ユーザー名
userName = fastbee

# パスワード
password = mqttパスワード & 有効期限
password = mqttパスワード & 有効期限 & デバイス認証コード (製品でデバイス認証を有効にした場合の形式)

• クライアント ID = 認証タイプ + デバイス番号 + 製品番号 + ユーザー ID を & 記号で接続し、間にスペースは入れません。
• ユーザー名は Mqtt アカウントをそのまま入力します
  
• パスワードは Mqtt パスワード + パスワード有効期限 + デバイス認証コード(オプション) を AES 暗号化したものです。セキュリティのため、パスワード有効期限は 24 時間以内とし、ミリ秒精度のタイムスタンプ形式を使用してください。

アカウント設定情報の例：

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

2. 簡易認証

製品詳細で Mqtt アカウントと Mqtt パスワードを取得します。テスト環境での使用を推奨します。Mqtt クライアント ID の形式は暗号化認証と同様で、E を S に変更します。

# クライアント ID = 認証タイプ + デバイス番号 + 製品番号 + ユーザー ID
clientId = S & deviceNumber & productId & userId

# ユーザー名
userName = fastbee

# パスワード
password = mqttパスワード
password = mqttパスワード & デバイス認証コード (製品でデバイス認証を有効にした場合の形式)

アカウント設定情報の例：

# クライアント ID = 認証タイプ + デバイス番号 + 製品番号 + ユーザー ID
clientId = "S&D68329VL588&2&1"
userName = "fastbee"
password = "PHYFED93WSFF1DAS"
password = "PHYFED93WSFF1DAS&ADBFCC8934864B26B55658C66F562AC5" (製品でデバイス認証を有効にした場合の形式)

3. デバイスが現在時刻を取得

現在時刻の取得には、システムの NTP 時刻インターフェースを呼び出せます。インターフェースへのリクエスト時にデバイスの現在稼働ミリ秒数を送信すると、デバイス送信時刻、サーバー受信時刻、サーバー送信時刻が返されます。次にデバイスの現在稼働ミリ秒数をデバイス受信時刻として取得します。最後に公式でデバイスの現在時刻を計算します。時刻はミリ秒単位である必要があります。オンラインタイムスタンプツール

# deviceSendTime の値はデバイスの現在稼働ミリ秒数
http://localhost:8080/iot/tool/ntp?deviceSendTime=35768

# 時刻の計算
デバイス現在時刻 = (サーバー受信時刻 + サーバー送信時刻 + デバイス受信時刻 - デバイス送信時刻) / 2

4. AES 暗号化の説明

AES の CBC 暗号化モードを採用し、オフセットは wumei-smart-open の 16 桁固定、出力は Base64、暗号化に使用するパスワードは製品キーです。テストには以下を使用できます：オンライン暗号化・復号ツール

暗号化モード：  CBC
パディング  ：  pkcs5padding
データブロック：  128 ビット
オフセット  ：  wumei-smart-open
出力        ：  base64

パスワード  ：  対応するシステムの製品シークレット
暗号化内容  ：  mqttパスワード & expireTime & 認証コード(オプション)

3. デバイス通信

{productId} は製品 ID、{deviceNum} はデバイス番号を表します。製品 ID とデバイス番号は Web 端末で取得します。デバイスの自動追加を使用する場合、デバイス番号には一意のコードまたはデバイスの MAC アドレスを使用でき、デバイス認証成功後にバックエンドで対応するデバイスエンティティが自動的に追加されます。

1. サブスクライブトピック

トピック	説明
/{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}/ota/get	デバイスアップグレードをサブスクライブ(旧)
/{productId}/{deviceNum}/property/get	2.x 廃止 属性をサブスクライブ（サーバーがパブリッシュ、デバイスがサブスクライブ）
/{productId}/{deviceNum}/property-online/get	2.x 廃止 属性をサブスクライブ（オンラインモード、ユーザー端がパブリッシュ、デバイスがサブスクライブ）
/{productId}/{deviceNum}/function-online/get	2.x 廃止 機能をサブスクライブ（オンラインモード、ユーザー端がパブリッシュ、デバイスがサブスクライブ）

2. パブリッシュトピック

トピック	説明
/{productId}/{deviceNum}/property/post	データをパブリッシュ (リアルタイム表示、属性/機能と監視データ、監視データの定期送信可能)
/{productId}/{deviceNum}/info/post	デバイス情報をパブリッシュ
/{productId}/{deviceNum}/event/post	イベントをパブリッシュ
/{productId}/{deviceNum}/monitor/post	リアルタイム監視データをパブリッシュ（リアルタイム監視チャートの表示のみに使用、保存されません）
/{productId}/{deviceNum}/ntp/post	時刻同期をパブリッシュ(オプション)
/{deviceNum}/http/upgrade/reply	HTTPS 方式で OTA アップグレードに応答(新)
/{deviceNum}/fetch/upgrade/reply	バイナリパッケージ方式で OTA アップグレードに応答(新)
/{productId}/{deviceNum}/upgrade/reply	OTA アップグレードに応答(旧)
/{productId}/{deviceNum}/function/post	2.x 廃止 機能をパブリッシュ (リアルタイム表示)

3. データフォーマット

デバイスとシステム間の通信には JSON 形式を使用します

• デバイス情報のサブスクライブ、対応トピック：/info/get

# 説明：デバイス情報を受信したらデバイス情報をパブリッシュし、デバイス状態の同期問題を解決
# デバイスメッセージの内容は空

• デバイス情報のパブリッシュ、対応トピック：/info/post

# 説明：1.デバイスは電源投入後にデバイス情報をパブリッシュ； 2.デバイスはデバイス情報指令を受信後にデバイス情報をパブリッシュ
# rssi             デバイス信号（非常に良い[-55— 0]、良い[-70— -55]、普通[-85— -70]、悪い[-100— -85]）
# status           デバイス状態、3 固定でオンラインを示す
# firmwareVersion  ファームウェアバージョン
# userId           ユーザーの ID。ユーザー ID 1（管理者）に設定可能。ネットワーク設定時にデバイスが具体的なユーザーに割り当てられる。
# longitude        オプション、経度。デバイス位置情報を使用する場合にアップロード
# latitude         オプション、緯度。デバイス位置情報を使用する場合にアップロード
# iccid            オプション、IoT SIM カードの ICCID 番号。デバイスが IoT SIM カードを使用する場合にアップロード
# cardPlatformId   オプション、IoT SIM カード管理のカードプラットフォーム番号に対応。デバイスが ICCID 番号をアップロードする場合にアップロード。アップロードしない場合はすべてのカードプラットフォームを巡回して検索
# summary          オプション、概要。デバイスの設定情報など、json 形式、オブジェクトはカスタム可能

{
     "rssi": -43,
     "firmwareVersion": 1.2,
     "status": 3,
     "userId": 2, 
     "longitude": 0,
     "latitude": 0,
     "iccid": 898604293620C0000970,
     "cardPlatformId": 0,
     "summary": {
 	    "name": "FastBee",
 	    "chip": "ESP8266",
 	    "author": "fastbee",
 	    "deliveryTime": "2023-06-06",
 	    "activeTime": "2022-10-01"
     }
 }

• リアルタイム監視のサブスクライブ、対応トピック：/monitor/get

# 説明：リアルタイム監視メッセージを受信し、回数と間隔に基づいてリアルタイム監視データをパブリッシュ
# count      回数
# interval   間隔、ミリ秒単位

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

• リアルタイム監視のパブリッシュ、対応トピック：/monitor/post

# 説明：受信したリアルタイム監視メッセージに基づき、指定された回数と間隔で監視データをパブリッシュ
# id       識別子。リアルタイム監視はモノモデルの属性。製品詳細で識別子を確認し、id 値に対応
# value    デバイスが収集した値。整数または小数のみ、文字列型で渡す
# remark   空またはデバイスの現在時刻を使用可能

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

• プラットフォーム指令のサブスクライブ、対応トピック：/function/get

# 説明：属性、機能、イベントはいずれもモノモデルに属し、Json 定義は同じ。例えばいずれもスイッチオンのメッセージを受信した場合、デバイスの処理はいずれもスイッチをオンにすること。   
# id      識別子。製品詳細でモノモデルを確認し、モノモデルの識別子に対応
# value   値。モノモデルの定義に対応し、文字列型で渡す
# remark  プラットフォームのアラーム、シーン連携、タイマー送信の指令には備考情報がある

[{
    "id": "gear",
    "value": "1",
    "remark": "デバイスタイマー"
},{
    "id": "switch",
    "value": "0",
    "remark": "シーン連携トリガー"
}]

• データとイベントのパブリッシュ、対応トピック：/property/post 、 /event/post

# 説明：属性、機能、イベントはいずれもモノモデルに属し、Json 定義は同じ。`value` の値がブール型の場合、値は "0" または "1" でオン/オフを表す；列挙型は列挙項目のキー値に対応（例えば "1" は中速ギアを表す）；配列型は半角カンマ区切りの文字列。
# id      識別子。製品詳細でモノモデルを確認し、モノモデルの識別子に対応
# value   値。モノモデルの定義に対応し、文字列型で渡す
# remark  受信した備考情報をそのまま使用可能。デバイスログ情報でこの備考を確認できる

[{
    "id": "gear",
    "value": "1",
    "remark": "ギア設定成功"
}, {
    "id": "switch",
    "value": "0",
    "remark": "スイッチオフ"
}]

関連モノモデルの説明

• すべてのモノモデルの Id（識別子）は一意で、特殊文字はできるだけ使用せず、英数字を主体にしてください。
• オブジェクト型モノモデル配下のサブモデル Id（識別子）の形式：parentId_childId。オブジェクト配列型も同様で、サブモデル Id に親の Id をアンダースコアで区切って追加します。例：

# 親モノモデル Id：power
# 子モノモデル Id：power_light

• 配列型（オブジェクト配列型を含む）のモノモデル Id（識別子）は 1 つだけで、モノモデル値は配列（半角カンマ区切りの文字列で保存）です。例えば 98,100,50 という文字列。そのため配列型の属性/機能/イベントの送信は比較的特殊で、Id(識別子) は array_インデックス で始まる必要があります。インデックスは 2 桁です。例：

  # 通常の配列形式 `array_00_RGB`
  # オブジェクト配列形式 `array_00_power_switch`
  # インデックス 00 は配列の最初の要素を表し、02 / 03 ... 98 / 99 も同様。配列の長さは 100 を超えてはならない
  [{
     "id": "array_01_power_switch",   // array_01 をプレフィックスとし、配列の 2 番目の要素を表す
     "value": "1",
     "remark": ""
  }]

• 時刻同期のパブリッシュ、対応トピック：/ntp/post

# 説明：オプション。時刻同期メッセージをパブリッシュし、サーバーが受信後に時刻同期メッセージを送信
# deviceSendTime デバイス送信時刻

{
    "deviceSendTime": "1592361428000"
}

• 時刻同期のサブスクライブ、対応トピック：/ntp/get

# 説明：オプション。時刻同期メッセージを受信し、現在時刻を計算 = (サーバー受信時刻 + サーバー送信時刻 + デバイス受信時刻 - デバイス送信時刻) / 2
# deviceSendTime  デバイス送信時刻
# serverRecvTime  サーバー受信時刻
# serverSendTime  サーバー送信時刻

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

• OTA アップグレードのサブスクライブ、対応トピック：/http/upgrade/set または /fetch/upgrade/set

新バージョンの OTA アップグレードは詳細ドキュメント（中国語）を参照

# 説明：デバイスアップグレードメッセージを受信後、ファームウェアのダウンロードアドレスに基づき、Http リクエストでファームウェアをダウンロードしてアップグレード
# version       バージョン番号。ファームウェアバージョンの照合に使用可能
# downloadUrl   ファームウェアのダウンロードアドレス

  {
    "taskId": 26,
    "url": "/profile/iot/1/2024-0824-001954.bin",
    "version": 1.2,
    "status": 1
  }

4. デバイスのネットワーク設定（オプション、Wifi 系デバイスのみ）

提示

• デバイスは AP ネットワーク設定を採用します。ネットワーク設定時、デバイスがホットスポットを起動し、Web サービスを提供します。モバイル端末はデバイスが提供する Web サービスを通じて設定情報を渡します。
• デバイス端ホットスポットのアドレスは 192.168.4.1 に設定されています
• プロジェクト SDK を参照できます

1. デバイス検出インターフェース

デバイス端は検出インターフェースを提供し、モバイル端末はこのインターフェースでデバイス発見機能を実現します。単一デバイスのネットワーク設定に適しています。

# リクエストメソッド：Get
# インターフェースアドレス：http://192.168.4.1/status
# パラメータ：なし
# 返信情報：HTTP ステータスコード 200 はデバイスが検出されたことを示す

2. 設定インターフェース

デバイス端は情報取得用の設定インターフェースを提供し、モバイル端末が設定情報を送信します。パラメータは Url 方式で渡し、SSID、password、userId は必須パラメータです。

# リクエストメソッド：Post
# インターフェースアドレス：http://192.168.4.1/config
# パラメータは以下のとおり：
    SSID            # Wifi の名前
    password        # Wifi のパスワード
    userId          # ユーザー番号/ID
    deviceNum       # オプション、デバイス番号
    authCode        # オプション、認証コード
    extra           # オプション、補足情報
# 返信情報：HTTP ステータスコード 200 はネットワーク設定成功を示す；HTTP ステータスコード 500 はネットワーク設定失敗を示す；

# リクエスト URL の例。デバイスはこの Url からパラメータを取得し、デバイスに保存
http://192.168.4.1/config?SSID=mywifi&password=mywifipassword&userId=1
http://192.168.4.1/config?SSID=mywifi&password=mywifipassword&userId=1&deviceNum=D68329VL588&authCode=6688&extra=open

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

MQTT デバイス接続は以下の順序で検収することをお勧めします。接続成功だけが見えて業務データがプラットフォームに入っていない状況を避けるためです。

手順	検証内容	成功の目安
1	製品が公開済み	製品ステータスが公開済み
2	MQTTX またはデバイスが接続	EMQX コンソールにクライアント接続が表示
3	デバイス状態	デバイス詳細にオンラインまたは最近のオンライン時刻の更新が表示
4	/info/post	デバイス情報、信号、バージョンなどのフィールドが更新
5	/property/post	稼働状態にモノモデル属性値が表示
6	/event/post	イベントログに送信イベントが表示
7	/function/get	プラットフォーム送信後にデバイス端が指令を受信
8	結果の返送	デバイスが送信結果どおりに返送し、プラットフォームの状態が更新
9	ルール/シーン	関連するルール、シーン、アラームがトリガーされる

6. よくあるエラー

接続が拒否される

優先的に確認：

1. サーバーの 1883 ポートが開放されているか。
2. EMQX または内蔵 MQTT サービスが起動しているか。
3. clientId が S&デバイス番号&製品ID&ユーザーID または暗号化認証の形式に合致しているか。
4. 製品でデバイス認証が有効になっているか、有効な場合パスワードに認証コードが含まれているか。
5. デバイスが無効化されていないか。

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

優先的に確認：

1. パブリッシュ先のトピックが /{productId}/{deviceNum}/property/post か。
2. productId に製品番号ではなく製品 ID を使用しているか。
3. deviceNum がデバイス番号と完全に一致しているか。
4. メッセージ本文が配列か。
5. id がモノモデル識別子と完全に一致しているか。
6. value がデータ型に合致しているか。

プラットフォーム送信後にデバイスが受信できない

優先的に確認：

1. デバイスが /{productId}/{deviceNum}/function/get をサブスクライブしているか。
2. MQTTX またはデバイスの接続がまだオンラインか。
3. モノモデルが書き込み可能な機能または送信可能な属性か。
4. ユーザーにデバイス詳細と指令送信の権限があるか。
5. デバイスシャドウが現在の判断に影響していないか。

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

優先的に確認：

1. デバイスデータがプラットフォームの稼働状態に入っているか。
2. シーンまたはルールにバインドされた製品、デバイス、変数が正しいか。
3. 条件式が送信値の型と一致しているか。
4. アラーム設定が有効になっているか。

7. 二次開発の入口

タイプ	パスまたはインターフェース	説明
MQTT 認証	/iot/tool/mqtt/auth、/iot/tool/mqtt/webhook	EMQX 認証と Webhook の入口
デバイスインターフェース	/iot/device	デバイスのオンライン、状態、詳細
モノモデルインターフェース	/iot/model	モデル定義とマッピング
プロトコルモジュール	springboot/fastbee-protocol	MQTT メッセージの解析と変換
データモジュール	springboot/fastbee-iot-data	属性、イベント、監視データの処理
フロントエンドページ	vue3/src/views/iot/device	デバイス詳細、稼働状態、データデバッグ
フロントエンド API	vue3/src/api/iot	デバイスとモノモデルのリクエストカプセル化

8. 関連ドキュメント

• 製品からデバイスまでの完全なクローズドループ（中国語）
• 製品管理
• デバイス管理（中国語）
• 汎用モノモデル（中国語）
• デバイス接続トラブルシューティングチェックリスト（中国語）