# Device Integration Overview

This section is for device and firmware developers integrating hardware with EMQX Fleets. It covers how devices connect, authenticate, and exchange data with the Fleets backend.

## Two Integration Paths

Devices can communicate with Fleets over MQTT or HTTPS (or both).

| | MQTT | HTTPS |
|---|---|---|
| **Connection type** | Long-lived, bidirectional | Per-request, request-response only |
| **Receive cloud-to-device messages** | Yes (subscribe to topics) | No push; poll using GET requests |
| **Offline message queue** | Yes (with persistent MQTT session) | No |
| **Shadow updates** | Received via delta topic subscription | Poll via GET `/api/v1/thing-datas/{thingName}/shadow` |
| **Commands** | Received via command topic subscription | Not supported for inbound commands |
| **Jobs notifications** | Received via jobs/notify topic | Poll using POST `/api/v1/thing-datas/jobs/get` |
| **Reporting state / events** | Publish to MQTT topics | POST to ThingDatas API endpoints |
| **Protocol overhead** | Low | Higher (TLS handshake per request) |
| **SDK required** | MQTT client library | Standard HTTP client |

**Use MQTT** if the device needs to receive commands, shadow desired state, or job notifications pushed from the cloud. This is the recommended path for most IoT devices.

**Use HTTPS** if the device only needs to report data (events, shadow state) and can poll for desired state changes. Suitable for constrained devices or environments where persistent TCP connections are impractical.

## Device Identity

Before a device can communicate with Fleets, it must be registered as a Thing. Two identity fields are relevant for device communication:

| Field | Used for |
|---|---|
| **Thing name** | `{thingName}` in all MQTT system topics and in ThingDatas API request bodies |
| **MQTT Client ID** | The MQTT `CONNECT` packet Client ID; used for lifecycle event tracking |

These values may be the same or different. Use the Thing name consistently in topic paths and API payloads.

## Authentication

### MQTT Connection to EMQX Broker

Devices connect to the EMQX Broker associated with your Fleets deployment using standard MQTT authentication. Refer to your deployment's connection settings for the host, port, and credentials.

### HTTPS (ThingDatas API)

All `/api/v1/thing-datas/*` endpoints require authentication. Use a Deployment API Key with Basic Auth:

```text
Authorization: Basic <base64(apiKey:apiSecret)>
```

See [Manage API Keys](../deployment/emqx_fleets_manage_deployment.md#deployment-api-keys) to create an API key for device use.

## MQTT System Topics

All Fleets system topics use the `$emqx/` prefix. Custom telemetry topics (if configured) use application-defined paths.

| Topic pattern | Direction | Purpose |
|---|---|---|
| `$emqx/things/{name}/shadow/update` | Bidirectional | Shadow state (desired from cloud; reported from device) |
| `$emqx/things/{name}/shadow/update/delta` | Cloud → Device | Delta notification |
| `$emqx/things/{name}/events/{type}` | Device → Cloud | Events (QoS 1) |
| `$emqx/commands/things/{name}/executions/{id}/request` | Cloud → Device | Command request |
| `$emqx/commands/things/{name}/executions/{id}/response` | Device → Cloud | Command response |
| `$emqx/things/{name}/jobs/notify` | Cloud → Device | Pending jobs changed |
| `$emqx/things/{name}/jobs/notify-next` | Cloud → Device | Next pending job changed |
| `$emqx/things/{name}/jobs/get` | Device → Cloud | Request pending jobs list |
| `$emqx/things/{name}/jobs/start-next` | Device → Cloud | Start next pending job |
| `$emqx/things/{name}/jobs/{jobId}/get` | Device → Cloud | Get a specific job execution |
| `$emqx/things/{name}/jobs/{jobId}/update` | Device → Cloud | Report job execution status |

## Next Steps

- [MQTT Integration](./mqtt_integration.md): Full MQTT setup, subscriptions, publish formats, and flow diagrams for shadow, commands, and jobs
- [HTTPS Integration](./https_integration.md): ThingDatas API reference for devices using HTTPS only
- [Device Shadow Sync](./device_shadow_sync.md): Step-by-step shadow synchronization flow from the device perspective