# EMQX Fleets の始め方

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

## 前提条件

- 有効なプロジェクトを持つ EMQX Cloud アカウント。
- **Running** 状態の EMQX Fleets デプロイメント。EMQX Fleets は現在アーリーアクセス段階です。[EMQX Fleets デプロイメントの作成](./deployment/emqx_fleets_create_deployment.md)を参照してアクセスをリクエストしてください。
- Fleets デプロイメントと同じプロジェクト内にある **Running** 状態の EMQX ブローカーのデプロイメント。Fleets はすべてのデバイス通信を関連付けられたブローカー経由でルーティングします。
- （任意）テレメトリイベントやシャドウ履歴などの時系列データを保存したい場合は、同じプロジェクト内に EMQX Tables のデプロイメント。ガイドの完了には必須ではありません。
- MQTT 経由で EMQX ブローカーに接続可能なデバイスまたはアプリケーション。

## 概要

以下のステップを完了します：

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

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

## ステップ 1: Thing Type の作成

Thing Type は、デバイスのカテゴリに対するスキーマを定義し、報告するプロパティや受け付けるコマンドを含みます。詳細は [Thing Types](./device_management/thing_types.md) を参照してください。

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](./device_management/things.md) を参照してください。

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** 設定で構成済み

   ![broker_connection_info](./_assets/broker_connection_info.png)

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

   Desired 状態の変更を受け取るためのシャドウデルタトピック：
   ```text
   $emqx/things/thermostat-001/shadow/update/delta
   ```

   リアルタイムコマンドを受け取るためのコマンドリクエストトピック：
   ```text
   $emqx/commands/things/thermostat-001/executions/+/request
   ```

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

必要なトピックのサブスクライブやメッセージ形式の詳細は [MQTT Integration](./device_integration/mqtt_integration.md) を参照してください。

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

Device Shadow により、デバイスがオンラインでなくても到達してほしい状態を宣言できます。詳細は [Device Shadow](./device_shadow.md) を参照してください。

1. 左メニューから **Shadow Sync** に移動。

2. Things リストから `thermostat-001` を選択。

3. **Target state (Desired)** パネルに以下を入力：
   ```json
   {
     "targetTemperature": 22
   }
   ```

4. **Update Desired** をクリック。

   ![update_desired_state](./_assets/update_desired_state.png)

Fleets は現在の報告状態と新しい Desired 状態の差分を計算し、デバイスに以下のトピックでパブリッシュします：
```text
$emqx/things/thermostat-001/shadow/update/delta
```

デバイスはデルタトピックでメッセージを受信します：
```json
{
  "version": 1,
  "timestamp": 1780298203,
  "state": {
    "targetTemperature": 22
  },
  "metadata": {
    "targetTemperature": {
      "timestamp": 1780298203
    }
  }
}
```

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

- **Topic**: `$emqx/things/thermostat-001/shadow/update`
- **Payload**:
  ```json
  {"state": {"reported": {"targetTemperature": 22, "temperature": 21.5}}}
  ```

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

![report_current_state](./_assets/report_current_state.png)

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

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

1. 左メニューから **Commands & Jobs** に移動。
2. **+ Send Command** をクリック。
3. 以下を入力：
   - **Thing**: `thermostat-001`
   - **Action**: `setTemperature`
   - **Parameters**: **value** に `24` を設定
4. **Send Command** をクリック。

Fleets は以下のトピックにコマンドをパブリッシュします：
```text
$emqx/commands/things/thermostat-001/executions/{executionId}/request
```

デバイスはリクエストを受け取り、アクションを実行後、以下のトピックにレスポンスをパブリッシュすることが期待されます：
```text
$emqx/commands/things/thermostat-001/executions/{executionId}/response
```

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

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

![command_job_list](./_assets/command_job_list.png)

## 次にできること

これで、登録済みデバイス、シャドウ状態、送信済みコマンドを持つ動作する Fleets デプロイメントが完成しました。次のステップとして：

- [Thing Types を管理](./device_management/thing_types.md) して実際のデバイスをモデリング
- [デバイスをグループに整理](./device_management/thing_groups.md) し、タグで動的メンバーシップを活用
- [Device Query インターフェース](./device_query.md) を使ってデバイスフリートをクエリ
- [MQTT または HTTPS を使った実デバイスの統合](./device_integration/device_integration_overview.md)
- [ジョブを作成](./commands_and_jobs/manage_jobs.md) して複数デバイスへの一括操作を実行