# Get Started with EMQX Fleets

This guide walks you through a complete end-to-end workflow: defining a device model, registering a device, synchronizing state using Device Shadow, and sending a real-time command. By the end, you will have a working Fleets deployment and a clear understanding of the core concepts.

## Prerequisites

- An EMQX Cloud account with an active project.
- An EMQX Fleets deployment in the **Running** state. EMQX Fleets is currently in early access. See [Create an EMQX Fleets Deployment](./deployment/emqx_fleets_create_deployment.md) to request access.
- An EMQX Broker deployment in the **Running** state, in the same project as your Fleets deployment. Fleets routes all device communication through the associated Broker.
- (Optional) An EMQX Tables deployment in the same project, if you want to store time-series data such as telemetry events and shadow history. This is not required to complete this guide.
- A device or application that can connect to EMQX Broker via MQTT.

## Overview

You will complete the following steps:

1. Create a Thing Type to define the device schema.
2. Register a Thing (a device instance).
3. Connect your device to EMQX Broker.
4. Update the desired shadow state from the console.
5. Send a real-time command and check the result.

The example device used throughout this guide is a smart thermostat that reports temperature and accepts a `setTemperature` command.

## Step 1: Create a Thing Type

A Thing Type defines the schema for a category of devices, including the properties they report and the commands they accept. For full details, see [Thing Types](./device_management/thing_types.md).

1. Open your Fleets deployment in the EMQX Cloud Console.
2. In the left menu, go to **Device Management** > **Thing Types**.
3. Click **+ New Type**.
4. Enter a name: `com.example.thermostat`
5. (Optional) Enter a description: `Thermostat device type for quick start`
6. Click **Confirm**.

The new Thing Type appears in the list. A default Thing Group named `com.example.thermostat (default)` is automatically created.

Next, add a command definition so that `setTemperature` is available when you send a command in Step 5:

1. Click the `com.example.thermostat` entry to open it, then click **Edit Type**.
2. In the **Commands** section, click **+ Add**.
3. In the **Add Command** dialog, fill in:
   - **Name**: `setTemperature`
   - **Type**: `sync`
   - **Input**: click **+ Add** and add a parameter named `value` with type `float`.
4. Click **Confirm** to close the dialog, then click **Save**.

## Step 2: Register a Thing

A Thing is an individual device identity registered in Fleets. For full details, see [Things](./device_management/things.md).

1. In the left menu, go to **Device Management** > **Things**.
2. Click **+ Register Thing**.
3. Fill in the fields:
   - **Name**: `thermostat-001`
   - **MQTT Client ID**: `thermostat-001`
   - **Thing Type**: `com.example.thermostat`
4. Click **Confirm**.

The device is now registered with an **offline** status. It will show as **online** once the device connects using the MQTT Client ID configured above.

## Step 3: Connect Your Device

Connect your device to the EMQX Broker in the same project as your Fleets deployment. If you do not have a physical device, you can use a client tool to simulate one.

1. Go to the **Overview** page of your EMQX Broker deployment and find the connection details in the **Connection Information** section (host, port, and credentials).

2. Connect your device using the following parameters:
   - **Client ID**: must match the value set when registering the Thing (`thermostat-001` in this guide)
   - **Host / Port**: from the Broker **MQTT Connection Information**
   - **Username / Password**: configured in the Broker's **Access Control** -> **Authentication** settings

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

3. After connecting, subscribe to the following topics:

   Shadow delta topic, so the device can receive desired state changes:
   ```text
   $emqx/things/thermostat-001/shadow/update/delta
   ```

   Command request topic, so the device can receive real-time commands:
   ```text
   $emqx/commands/things/thermostat-001/executions/+/request
   ```

Once connected and subscribed, the device status in the **Things** list changes to **online**.

For details on required topic subscriptions and message formats, see [MQTT Integration](./device_integration/mqtt_integration.md).

## Step 4: Update the Desired Shadow State

Device Shadow lets you declare the state you want the device to reach, without needing the device to be online at the time of the update. For full details, see [Device Shadow](./device_shadow.md).

1. In the left menu, go to **Shadow Sync**.

2. Select `thermostat-001` from the Things list.

3. In the **Target state (Desired)** panel, enter:
   ```json
   {
     "targetTemperature": 22
   }
   ```

4. Click **Update Desired**.

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

Fleets computes the delta between the current reported state and the new desired state, and publishes it to the device on:
```text
$emqx/things/thermostat-001/shadow/update/delta
```

The device receives an incoming message on the delta topic:
```json
{
  "version": 1,
  "timestamp": 1780298203,
  "state": {
    "targetTemperature": 22
  },
  "metadata": {
    "targetTemperature": {
      "timestamp": 1780298203
    }
  }
}
```

The device reads the delta, applies the change, and publishes the new reported state back. Use your MQTT client to publish the following:

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

After publishing, go back to **Shadow Sync** in your Fleets deployment and refresh the page to see the **Current state (Reported)** updated.

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

## Step 5: Send a Real-Time Command

Commands are request-response interactions sent directly to a connected device. For full details, see [Commands & Jobs](./commands_and_jobs/commands_and_jobs_overview.md).

1. In the left menu, go to **Commands & Jobs**.
2. Click **+ Send Command**.
3. Fill in the fields:
   - **Thing**: `thermostat-001`
   - **Action**: `setTemperature`
   - **Parameters**: set **value** to `24`
4. Click **Send Command**.

Fleets publishes the command to the device on:
```text
$emqx/commands/things/thermostat-001/executions/{executionId}/request
```

The device receives the request and is expected to execute the action, then publish a response to:
```text
$emqx/commands/things/thermostat-001/executions/{executionId}/response
```

In this guide, you are simulating the device with an MQTT client, so no response is sent automatically. The execution status remains `SENT` until a response is published. In a real device integration, your device code publishes the response and the status updates to `SUCCEEDED` or `FAILED`.

To verify the command was dispatched, go to **Commands & Jobs** > **Commands** tab and check that an execution record appears for `thermostat-001`. Click the execution ID to view its details.

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

## What's Next

You now have a working Fleets deployment with a registered device, a shadow state, and a dispatched command. From here you can:

- [Manage Thing Types](./device_management/thing_types.md) to model your real devices
- [Organize devices into groups](./device_management/thing_groups.md) and use tags for dynamic membership
- [Query your device fleet](./device_query.md) using the Device Query interface
- [Integrate a real device](./device_integration/device_integration_overview.md) using MQTT or HTTPS
- [Create a Job](./commands_and_jobs/manage_jobs.md) to dispatch a batch operation to multiple devices