EMQX Fleetsの始め方

このガイドでは、デバイスモデルの定義、デバイスの登録、Device Shadowを使った状態の同期、リアルタイムコマンドの送信までの一連のワークフローを説明します。最後まで進めることで、動作するFleetsのデプロイメントが完成し、コアコンセプトを明確に理解できます。

前提条件

• 有効なプロジェクトを持つEMQX Cloudアカウント
• Running状態のEMQX Fleetsデプロイメント。EMQX Fleetsは現在パブリックベータ版として提供されています。EMQX Fleetsデプロイメントの作成を参照してください。
• Fleetsデプロイメントと同じプロジェクト内にあるRunning状態のEMQX ブローカーのデプロイメント。EMQX Fleetsはすべてのデバイス通信を関連付けられたブローカー経由でルーティングします。
• Fleetsデプロイメントと同じプロジェクト内にあるRunning状態のEMQX Tablesのデプロイメント。EMQX Fleetsはテレメトリイベントやシャドウ履歴などの時系列データを関連付けられたTablesに保存します。
• MQTT経由でEMQX ブローカーに接続できるデバイスまたはアプリケーション

概要

以下の手順を完了します：

1. Thing Typeを作成してデバイススキーマを定義する。
2. Thing（デバイスインスタンス）を登録する。
3. デバイスをEMQX ブローカーに接続する。
4. コンソールからDesiredシャドウ状態を更新する。
5. リアルタイムコマンドを送信し、結果を確認する。

このガイド全体で使用する例のデバイスは、温度を報告し、setTemperatureコマンドを受け付けるスマートサーモスタットです。

ステップ1: Thing Typeの作成

Thing Typeは、デバイスのカテゴリごとに報告するプロパティや受け付けるコマンドを含むスキーマを定義します。詳細はThing Typesを参照してください。

1. EMQX CloudコンソールでFleetsデプロイメントを開きます。
2. 左メニューのDevice Management > Thing Typesに移動します。
3. + New Typeをクリックします。
4. 名前を入力します：com.example.thermostat
5. （任意）説明を入力します：Thermostat device type for quick start
6. Confirmをクリックします。

新しいThing Typeがリストに表示されます。com.example.thermostat (default)という名前のデフォルトThing Groupが自動的に作成されます。

次に、ステップ5でコマンド送信時にsetTemperatureが使えるようにコマンド定義を追加します：

1. com.example.thermostatをクリックして開き、Edit Typeをクリックします。
2. Commandsセクションで**+ Add**をクリックします。
3. Add Commandダイアログで以下を入力します：
   • Name：setTemperature
   • Type：sync
   • Input：+ Addをクリックし、名前value、タイプfloatのパラメータを追加
4. Confirmをクリックしてダイアログを閉じ、Saveをクリックします。

ステップ2: Thingの登録

ThingはFleetsに登録された個々のデバイスIDです。詳細はThingsを参照してください。

1. 左メニューのDevice Management > Thingsに移動します。
2. + Register Thingをクリックします。
3. 以下の項目を入力します：
   • Name：thermostat-001
   • MQTT Client ID：thermostat-001
   • Thing Type：com.example.thermostat
4. Confirmをクリックします。

デバイスは現在offline状態で登録されます。上記のMQTT Client IDを使ってデバイスが接続するとonlineに変わります。

ステップ3: デバイスの接続

Fleetsデプロイメントと同じプロジェクト内のEMQX ブローカーにデバイスを接続します。物理デバイスがない場合はクライアントツールでシミュレーション可能です。

1. EMQX ブローカーのOverviewページに移動し、Connection Informationセクションで接続情報（ホスト、ポート、認証情報）を確認します。

2. 以下のパラメータでデバイスを接続します：

   • Client ID：Thing登録時に設定した値（このガイドではthermostat-001）
   • Host / Port：ブローカーのMQTT Connection Informationから取得
   • Username / Password：ブローカーのAccess Control -> Authentication設定で構成されたもの

   

3. 接続後、以下のトピックをサブスクライブします：

   シャドウのデルタトピック（デバイスがDesired状態の変更を受信するため）：

   $emqx/things/thermostat-001/shadow/update/delta

   コマンドリクエストトピック（デバイスがリアルタイムコマンドを受信するため）：

   $emqx/commands/things/thermostat-001/executions/+/request

接続してサブスクライブが完了すると、Thingsリストのデバイス状態がonlineに変わります。

必要なトピックのサブスクライブやメッセージフォーマットの詳細はMQTT Integrationを参照してください。

ステップ4: Desiredシャドウ状態の更新

Device Shadowは、デバイスがオンラインでなくても到達してほしい状態を宣言できます。詳細はDevice Shadowを参照してください。

1. 左メニューのShadow Syncに移動します。

2. Thingsリストからthermostat-001を選択します。

3. **Target state (Desired)**パネルに以下を入力します：

   {
     "targetTemperature": 22
   }

4. Update Desiredをクリックします。

   

Fleetsは現在のReported状態と新しいDesired状態のデルタを計算し、以下のトピックでデバイスにパブリッシュします：

$emqx/things/thermostat-001/shadow/update/delta

デバイスはデルタトピックでメッセージを受信します：

{
  "version": 1,
  "timestamp": 1780298203,
  "state": {
    "targetTemperature": 22
  },
  "metadata": {
    "targetTemperature": {
      "timestamp": 1780298203
    }
  }
}

デバイスはデルタを読み取り、変更を適用し、新しいReported状態を以下のトピックにパブリッシュします。MQTTクライアントを使って次の内容をパブリッシュしてください：

• Topic：$emqx/things/thermostat-001/shadow/update
• Payload：

  {"state": {"reported": {"targetTemperature": 22, "temperature": 21.5}}}

パブリッシュ後、FleetsデプロイメントのShadow Syncに戻り、ページを更新すると**Current state (Reported)**が更新されていることが確認できます。

ステップ5: リアルタイムコマンドの送信

コマンドは接続されたデバイスに直接送信されるリクエスト・レスポンスのやり取りです。詳細はCommands & Jobsを参照してください。

1. 左メニューのCommands & Jobsに移動します。
2. + Send Commandをクリックします。
3. 以下の項目を入力します：
   • Thing：thermostat-001
   • Action：setTemperature
   • Parameters：valueを24に設定
4. Send Commandをクリックします。

Fleetsは以下のトピックにコマンドをパブリッシュします：

$emqx/commands/things/thermostat-001/executions/{executionId}/request

デバイスはリクエストを受信し、アクションを実行後、以下のトピックにレスポンスをパブリッシュすることが期待されます：

$emqx/commands/things/thermostat-001/executions/{executionId}/response

このガイドではMQTTクライアントでデバイスをシミュレートしているため、自動的にレスポンスは送信されません。レスポンスがパブリッシュされるまで実行ステータスはSENTのままです。実際のデバイス統合では、デバイスコードがレスポンスをパブリッシュし、ステータスはSUCCEEDEDまたはFAILEDに更新されます。

コマンドが送信されたことを確認するには、Commands & Jobs > Commandsタブに移動し、thermostat-001の実行レコードがあるか確認してください。実行IDをクリックすると詳細を表示できます。

次にやること

これで、登録済みデバイス、シャドウ状態、送信済みコマンドを持つ動作するFleetsデプロイメントが完成しました。ここからは以下を行えます：

• Thing Typesの管理で実際のデバイスをモデリング
• デバイスをグループに整理し、タグで動的メンバーシップを活用
• Device Queryインターフェースを使ったデバイスフリートのクエリ
• MQTTまたはHTTPSを使った実デバイスの統合
• ジョブの作成で複数デバイスへの一括操作を実行