Attributes

The MQTT Attributes API covers three operations: publishing client-side attributes to ThingsBoard, requesting current attribute values from the server, and subscribing to server-pushed attribute updates. See Attributes for the difference between client-side, server-side, and shared attributes, and Getting Connected for connection parameters and credential types.

Publish Client-Side Attributes

Report device state (serial number, firmware version, hardware config) to ThingsBoard.

Format	Topic
Short	`v2/a`
Standard	`v1/devices/me/attributes`

{"firmwareVersion": "2.1.0", "serialNumber": "SN-4A21F", "hardwareRevision": "B"}

mosquitto_pub -d -q 1 -h "mqtt.thingsboard.cloud" -p 1883 -t "v2/a" -u "$ACCESS_TOKEN" -m '{"firmwareVersion": "2.1.0", "serialNumber": "SN-4A21F"}'

Request Attribute Values from Server

Ask ThingsBoard for the current values of client-side or shared attributes. Useful on device boot to read back configuration stored in ThingsBoard.

Format	Subscribe to responses	Publish request to
Short	`v2/a/res/+`	`v2/a/req/$request_id`
Standard	`v1/devices/me/attributes/response/+`	`v1/devices/me/attributes/request/$request_id`

$request_id is any integer you choose; ThingsBoard echoes it in the response topic so you can match replies to requests.

Request and response payloads:

JSON
Protobuf

Request — specify which keys you want:

Field	Description
`clientKeys`	Comma-separated client-side attribute keys to return; `""` returns all client attributes; omit to exclude the client scope
`sharedKeys`	Comma-separated shared attribute keys to return; `""` returns all shared attributes; omit to exclude the shared scope

An empty request body ({}) returns all client and all shared attributes.

Request:

{"clientKeys": "firmwareVersion,serialNumber", "sharedKeys": "targetTemperature,enabled"}

Response:

{"client": {"firmwareVersion": "2.1.0", "serialNumber": "SN-4A21F"}, "shared": {"targetTemperature": 24, "enabled": true}}

Request:

{"clientKeys": ""}

Response:

{"client": {"firmwareVersion": "2.1.0", "serialNumber": "SN-4A21F"}}

Request:

{"sharedKeys": ""}

Response:

{"shared": {"targetTemperature": 24, "enabled": true}}

Request:

{}

Response:

{"client": {"firmwareVersion": "2.1.0", "serialNumber": "SN-4A21F"}, "shared": {"targetTemperature": 24, "enabled": true}}

The response includes a scope only if that scope returned at least one attribute.

Example

The following example is written in JavaScript and is based on mqtt.js. A pure command-line example is not available: ThingsBoard only accepts a subscription to v1/devices/me/attributes/response/+, and the command-line MQTT clients cannot use a wildcard topic to receive a response.

Save the mqtt-js-attributes-request.js file to your PC.

The content of the mqtt-js-attributes-request.js file:

var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://localhost', {
    username: process.env.TOKEN
});
var requestId = 1;

client.on('connect', function () {
    console.log('connected');
    client.subscribe('v1/devices/me/attributes/response/+');
    // clientKeys/sharedKeys are comma-separated strings. An empty value returns
    // ALL keys in that scope, e.g. sharedKeys: "". Omit a field to exclude that scope.
    var request = { clientKeys: 'firmwareVersion,serialNumber', sharedKeys: 'targetTemperature,enabled' };
    client.publish('v1/devices/me/attributes/request/' + requestId, JSON.stringify(request));
});

client.on('message', function (topic, message) {
    console.log('response.topic: ' + topic);
    console.log('response.body: ' + message.toString());
    client.end();
});

Now, follow these steps:

Replace $ACCESS_TOKEN with your device’s access token.

Install the mqtt package and run the example:
Terminal window
```
npm install mqtt --save
export TOKEN=$ACCESS_TOKEN
node mqtt-js-attributes-request.js
```

When the device profile payload type is set to Protobuf, or when using the short Protobuf topics, the following fixed schemas apply. These schemas cannot be customized in the device profile.

Request — short Protobuf topic: v2/a/req/$request_id/p

syntax = "proto3";

message AttributesRequest {
  string clientKeys = 1;
  string sharedKeys = 2;
}

Response — the device receives a GetAttributeResponseMsg message. Short Protobuf topic: v2/a/res/+/p

syntax = "proto3";

enum KeyValueType {
  BOOLEAN_V = 0;
  LONG_V = 1;
  DOUBLE_V = 2;
  STRING_V = 3;
  JSON_V = 4;
}

message KeyValueProto {
  string key = 1;
  KeyValueType type = 2;
  bool bool_v = 3;
  int64 long_v = 4;
  double double_v = 5;
  string string_v = 6;
  string json_v = 7;
}

message TsKvProto {
  int64 ts = 1;
  KeyValueProto kv = 2;
  optional int64 version = 3;
}

message GetAttributeResponseMsg {
  int32 requestId = 1;
  repeated TsKvProto clientAttributeList = 2;
  repeated TsKvProto sharedAttributeList = 3;
  string error = 5;
}

Receive pushed notifications whenever a shared attribute is changed from the ThingsBoard side (e.g. an operator changes a setpoint in the dashboard).

Format	Subscribe to
Short	`v2/a`
Standard	`v1/devices/me/attributes`

ThingsBoard publishes only the changed keys, request:

mosquitto_sub -d -q 1 -h "mqtt.thingsboard.cloud" -p 1883 -t "v2/a" -u "$ACCESS_TOKEN"

Response:

JSON
Protobuf

{"targetTemperature": 26}

When the device profile payload type is set to Protobuf, or when subscribing to the short Protobuf topic (v2/a/p), the device receives an AttributeUpdateNotificationMsg message. This schema is fixed and cannot be customized in the device profile.

syntax = "proto3";

enum KeyValueType {
  BOOLEAN_V = 0;
  LONG_V = 1;
  DOUBLE_V = 2;
  STRING_V = 3;
  JSON_V = 4;
}

message KeyValueProto {
  string key = 1;
  KeyValueType type = 2;
  bool bool_v = 3;
  int64 long_v = 4;
  double double_v = 5;
  string string_v = 6;
  string json_v = 7;
}

message TsKvProto {
  int64 ts = 1;
  KeyValueProto kv = 2;
  optional int64 version = 3;
}

message AttributeUpdateNotificationMsg {
  repeated TsKvProto sharedUpdated = 1;
  repeated string sharedDeleted = 2;
}

Was this helpful?

Attributes

Publish Client-Side Attributes

Request Attribute Values from Server

Subscribe to Shared Attribute Updates