Device API
Devices connect to ThingsBoard Edge directly on the local network — not to the cloud server. Edge exposes the same device APIs as ThingsBoard CE on the same default ports. The only difference is the target host: devices use the Edge node’s IP address or hostname instead of the cloud server address.
Default ports: 1883 (plain), 8883 (TLS)
Connection parameters
Section titled “Connection parameters”| Parameter | Value |
|---|---|
| Host | Edge node hostname or IP |
| Port | 1883 (plain) or 8883 (TLS) |
| Client ID | any unique string |
| Username | device access token |
| Password | (leave empty) |
Topic reference
Section titled “Topic reference”| Operation | Direction | Topic |
|---|---|---|
| Publish telemetry | Device → Edge | v1/devices/me/telemetry |
| Publish attributes | Device → Edge | v1/devices/me/attributes |
| Subscribe to shared attribute updates | Edge → Device | v1/devices/me/attributes |
| Request attributes | Device → Edge | v1/devices/me/attributes/request/{requestId} |
| Receive attribute response | Edge → Device | v1/devices/me/attributes/response/{requestId} |
| Subscribe to server-side RPC | Edge → Device | v1/devices/me/rpc/request/+ |
| Send server-side RPC response | Device → Edge | v1/devices/me/rpc/response/{requestId} |
| Send client-side RPC | Device → Edge | v1/devices/me/rpc/request/{requestId} |
| Receive client-side RPC response | Edge → Device | v1/devices/me/rpc/response/{requestId} |
| Claim device | Device → Edge | v1/devices/me/claim |
| Provision device | Device → Edge | /provision |
| Receive firmware chunk | Edge → Device | v2/fw/response/+/chunk/+ |
| Receive software chunk | Edge → Device | v2/sw/response/+/chunk/+ |
For full payload schemas, protocol version options, Protobuf encoding, and Sparkplug B support, see the MQTT API reference.
Default ports: 8080 (plain), 443 (HTTPS)
Base URL: http://{EDGE_HOST}:8080/api/v1/{accessToken}
Endpoint reference
Section titled “Endpoint reference”| Operation | Method | Path |
|---|---|---|
| Publish telemetry | POST | /telemetry |
| Publish attributes | POST | /attributes |
| Get attributes | GET | /attributes?clientKeys=…&sharedKeys=… |
| Subscribe to attribute updates (long-poll) | GET | /attributes/updates?timeout={ms} |
| Subscribe to RPC commands (long-poll) | GET | /rpc?timeout={ms} |
| Send RPC response | POST | /rpc/{requestId} |
| Claim device | POST | /claim |
| Provision device | POST | http://{EDGE_HOST}:8080/api/v1/provision |
| Get firmware info | GET | /firmware?title={title}&version={ver} |
For full payload schemas and provisioning flows, see the HTTP API reference.
Default ports: 5683 UDP (plain), 5684 UDP (DTLS)
CoAP uses the same operation paths as the HTTP API with coap://{EDGE_HOST}/ as the base URL. Confirmable (CON) messages are used by default; the observe option is used for subscriptions.
For the full CoAP topic reference and DTLS setup, see the CoAP API reference.
Default ports: 5685 CoAP, 5686 CoAP/DTLS, 5687 TCP, 5688 TCP/TLS
ThingsBoard implements the OMA LwM2M 1.0 and 1.1 specifications. Devices register via the standard LwM2M bootstrap or direct registration flow. Object and resource mappings, OTA update support, and RPC command encoding are described in the LwM2M API reference.
Default port: 161 UDP
Edge acts as an SNMP manager that polls devices on a configurable schedule. Devices do not connect to Edge — Edge polls them. For polling configuration and OID mapping, see the SNMP API reference.
Gateway MQTT API
Section titled “Gateway MQTT API”Gateways connecting multiple devices use a separate MQTT topic namespace. Connect as a regular MQTT device using the access token as the username, then use the gateway topics to manage child devices.
Gateway topic reference
Section titled “Gateway topic reference”| Operation | Direction | Topic |
|---|---|---|
| Connect child device | Gateway → Edge | v1/gateway/connect |
| Disconnect child device | Gateway → Edge | v1/gateway/disconnect |
| Publish telemetry | Gateway → Edge | v1/gateway/telemetry |
| Publish attributes | Gateway → Edge | v1/gateway/attributes |
| Subscribe to attribute updates | Edge → Gateway | v1/gateway/attributes |
| Request attributes | Gateway → Edge | v1/gateway/attributes/request |
| Receive attribute response | Edge → Gateway | v1/gateway/attributes/response |
| Subscribe to RPC commands | Edge → Gateway | v1/gateway/rpc |
| Send RPC response | Gateway → Edge | v1/gateway/rpc |
For the full gateway payload schemas, see the MQTT Gateway API reference and the MQTT Sparkplug B API reference.
The following SDKs implement the ThingsBoard device protocols and work against Edge without modification — set the host to your Edge node:
| SDK | Language | Protocols |
|---|---|---|
| Python Device SDK | Python | MQTT, HTTP |
| MicroPython Client SDK | MicroPython | MQTT |
| CircuitPython Client SDK | CircuitPython | MQTT |
| Arduino Client SDK | C++ (Arduino) | MQTT |
| Python Gateway SDK | Python | MQTT (Gateway API) |
| ThingsBoard IoT Gateway | Java | MQTT, Modbus, OPC-UA, BACnet, and others |