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 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.

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.

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

   

3. After connecting, subscribe to the following topics:

   Shadow delta topic, so the device can receive desired state changes:

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

   Command request topic, so the device can receive real-time commands:

   $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.

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.

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:

   {
     "targetTemperature": 22
   }

4. Click Update Desired.

   

Fleets computes the delta between the current reported state and the new desired state, and publishes it to the device on:

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

The device receives an incoming message on the delta topic:

{
  "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:

  {"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.

Step 5: Send a Real-Time Command

Commands are request-response interactions sent directly to a connected device. For full details, see Commands & Jobs.

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:

$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:

$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.

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 to model your real devices
• Organize devices into groups and use tags for dynamic membership
• Query your device fleet using the Device Query interface
• Integrate a real device using MQTT or HTTPS
• Create a Job to dispatch a batch operation to multiple devices