Getting Connected

ThingsBoard acts as a standard MQTT broker. Any MQTT v3.1, v3.1.1, or v5.0 client can connect — firmware libraries (Paho, MQTT.js, arduino-mqtt), integration tools, or the mosquitto command-line client used in examples throughout this section.

Examples in this section use mosquitto_pub and mosquitto_sub. Install the mosquitto client package for your OS from mosquitto.org/download or your system package manager, then verify with mosquitto_pub --version.

Choose the credential type that fits your device’s security requirements. Configure it per device under Manage credentials — see Devices.

The simplest credential type. The token acts as the MQTT username; no password is required.

Plain MQTT (port 1883):

mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -p 1883 -t "v2/t" -u "$ACCESS_TOKEN" -m '{"temperature": 25}'

MQTT over TLS (port 8883) — one-way SSL:

The client verifies the server’s identity using a CA root certificate. Download ca-root.pem from the Check connectivity dialog on the device page.

mosquitto_pub -d -q 1 --cafile ca-root.pem -h "mqtt.thingsboard.cloud" -p 8883 -t "v2/t" -u "$ACCESS_TOKEN" -m '{"temperature": 25}'

Replaces the access token with a custom clientId, username, and password. All three fields are optional — use whichever combination your firmware supports.

Plain MQTT (port 1883):

mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -p 1883 -t "v2/t" -i "$CLIENT_ID" -u "$USERNAME" -P "$PASSWORD" -m '{"temperature": 25}'

MQTT over TLS (port 8883) — one-way SSL:

mosquitto_pub -d -q 1 --cafile ca-root.pem -h "mqtt.thingsboard.cloud" -p 8883 -t "v2/t" -i "$CLIENT_ID" -u "$USERNAME" -P "$PASSWORD" -m '{"temperature": 25}'

Mutual TLS: both the server and the device authenticate each other with certificates. Always uses port 8883. Two strategies are available.

Each device has its own certificate registered directly on the device record.

1. Generate a certificate and private key:

   # RSA
   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes
   # or EC (smaller, faster)
   openssl ecparam -out key.pem -name prime256v1 -genkey
   openssl req -new -key key.pem -x509 -nodes -days 365 -out cert.pem

2. Register the certificate in ThingsBoard: Entities → Devices → [device] → Manage credentials → X.509 Certificate, paste cert.pem, save.
3. Connect using the certificate and key:

   mosquitto_pub --cafile ca-root.pem -d -q 1 -h "mqtt.thingsboard.cloud" -p 8883 -t "v2/t" --key key.pem --cert cert.pem -m '{"temperature": 25}'

Register one intermediate CA certificate in the device profile instead of one certificate per device. ThingsBoard extracts the device name from the certificate’s Common Name using a configurable regex and can auto-provision new devices when their certificate is first seen.

1. Generate the certificate hierarchy (root → intermediate → device):

   # Root CA
   openssl req -x509 -newkey rsa:4096 -keyout rootKey.pem -out rootCert.pem -sha256 -days 365 -nodes
   
   # Intermediate CA
   openssl req -new -newkey rsa:4096 -keyout intermediateKey.pem -out intermediate.csr -sha256 -nodes
   echo basicConstraints=CA:TRUE > ca-ext.txt
   openssl x509 -req -in intermediate.csr -out intermediateCert.pem -CA rootCert.pem -CAkey rootKey.pem -days 365 -sha256 -CAcreateserial -extfile ca-ext.txt
   
   # Device certificate
   openssl req -new -newkey rsa:4096 -keyout deviceKey.pem -out device.csr -sha256 -nodes
   openssl x509 -req -in device.csr -out deviceCert.pem -CA intermediateCert.pem -CAkey intermediateKey.pem -days 365 -sha256 -CAcreateserial
   
   # Build the chain sent by the device
   cat deviceCert.pem intermediateCert.pem rootCert.pem > chain.pem

2. Register the intermediate certificate in ThingsBoard: Profiles → Device profiles → [profile] → Device Provisioning → X.509 Certificate Chain. Paste intermediateCert.pem, configure the CN regex for device name extraction, and optionally enable auto-provisioning.
3. Connect using the chain and device key:

   mosquitto_pub --cafile ca-root.pem -d -q 1 -h "mqtt.thingsboard.cloud" -p 8883 -t "v2/t" --key deviceKey.pem --cert chain.pem -m '{"temperature": 25}'

ThingsBoard Cloud already has TLS configured with a valid certificate. Connect on port 8883 and pass the system CA bundle (or your OS trust store) — no additional server-side setup is needed.

ThingsBoard supports two MQTT topic formats. Both are equivalent — they accept the same payloads and produce the same result.

Short topics are available since ThingsBoard 3.5. They reduce bandwidth for constrained devices and support an optional serialization suffix: /j for JSON or /p for Protobuf. Without a suffix, the format configured in the device profile is used.

Complete topic mapping:

When you set the transport type to MQTT in a device profile, additional settings become available under Transport configuration. These settings apply to all devices using the profile.

You can override the default topics that ThingsBoard listens on for telemetry and attributes:

MQTT wildcards are supported:

• + matches a single topic level — e.g. v1/devices/+/telemetry or +/devices/+/attributes
• # matches the rest of the topic and must be the last character — e.g. # or v1/devices/me/#

Choose the serialization format for MQTT messages:

Send PUBACK on PUBLISH message validation failure — by default, ThingsBoard closes the MQTT session when it receives a message that fails validation (e.g. malformed JSON). Enable this option to send a PUBACK acknowledgment instead, so the device stays connected. Useful for devices that cannot handle unexpected disconnects gracefully.

When Protobuf is selected, you define four .proto schemas in the device profile — one for each message type:

Telemetry proto schema:

syntax = "proto3";
package telemetry;

message SensorDataReading {
  optional double temperature = 1;
  optional double humidity = 2;
  InnerObject innerObject = 3;

  message InnerObject {
    optional string key1 = 1;
    optional bool key2 = 2;
    optional double key3 = 3;
    optional int32 key4 = 4;
    optional string key5 = 5;
  }
}

Attributes proto schema:

syntax = "proto3";
package attributes;

message SensorConfiguration {
  optional string firmwareVersion = 1;
  optional string serialNumber = 2;
}

RPC request proto schema (server-side RPC commands sent to the device):

syntax = "proto3";
package rpc;

message RpcRequestMsg {
  optional string method = 1;
  optional int32 requestId = 2;
  optional string params = 3;
}

RPC response proto schema (device replies to two-way RPC):

syntax = "proto3";
package rpc;

message RpcResponseMsg {
  optional string payload = 1;
}

Customize these schemas to match your device’s data model. Field names in the telemetry and attributes schemas become the ThingsBoard telemetry keys and attribute keys respectively.

Enable compatibility with other payload formats — when enabled, the platform tries to parse messages as Protobuf first, then falls back to JSON if parsing fails. This is useful during firmware upgrades when older devices still send JSON while newer ones send Protobuf. The compatibility mode introduces slight performance overhead, so disable it once all devices are updated.

Send PUBACK on PUBLISH message validation failure — same behavior as for JSON: sends a PUBACK instead of closing the session on validation failure.

Check MQTT Sparkplug B Edge of Network (EoN) node to treat connected devices as Sparkplug B nodes. See the Sparkplug API reference for details.

MQTT v5.0 clients receive numeric error codes in CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, and DISCONNECT packets. The table below lists every code ThingsBoard may return.