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. コンソールから望ましいシャドウ状態を更新する。
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 に登録された個別のデバイス識別子です。詳細は 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. 接続後、以下のトピックをサブスクライブします：

   シャドウの差分を受信するためのトピック：

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

   リアルタイムコマンドを受信するためのトピック：

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

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

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

ステップ 4: 望ましいシャドウ状態を更新する

Device Shadow を使うと、デバイスがオンラインでなくても、目標とする状態を宣言できます。詳細は Device Shadow を参照してください。

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

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

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

   {
     "targetTemperature": 22
   }

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

   

Fleets は現在の報告状態と新しい望ましい状態の差分を計算し、以下のトピックにパブリッシュします：

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

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

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

デバイスは差分を読み取り、変更を適用し、新しい報告状態を以下のようにパブリッシュします。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 を使った 実デバイスの統合
• 複数デバイスへの一括操作を行う ジョブの作成