Stop the war

Stand with Ukraine flag

Support Ukraine
Try it now Pricing
Community Edition
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Getting Started Documentation Devices Library Guides Installation Architecture API FAQ

Device Messaging Plugin

Doc info icon
Important note

Please note that this guide is for ThingsBoard versions prior v2.0.

Old rules and plugins functionality is replaced by new rule engine components (rule chains and rule nodes).

Please review new rule engine documentation to learn how to adopt new functionality.

We are doing our best to modify this guide to v2.0 components. Contributions are welcome.

Overview

This RPC plugin enables communication between various IoT devices through the ThingsBoard cluster. The plugin introduces basic security features: devices are able to exchange messages only if they belong to the same customer. The plugin implementation can be customized to cover more complex security features.

Configuration

You can specify following configuration parameters:

  • Maximum amount of devices per customer
  • Default request timeout
  • Maximum request timeout

Device RPC API

The plugin handles two rpc methods: getDevices and sendMsg. The examples listed below will be based on demo account and MQTT protocol. Please note that you are able to use other protocols - CoAP and HTTP.

Get Device List API

In order to send a message to other devices, you will need to know their identifiers. A device can request a list of other devices that belong to the same customer using getDevices RPC call.

1
2

export TOKEN=A1_TEST_TOKEN
node mqtt-get-device-list.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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

client.on('connect', function () {
    console.log('connected');
    client.subscribe('v1/devices/me/rpc/response/+');
    var requestId = 1;
    var request = {
        "method": "getDevices",
        "params": {}
    };
    client.publish('v1/devices/me/rpc/request/' + requestId, JSON.stringify(request));
});

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

1
2
3
4
5
6
7
8
9
10

[
  {
    "id": "aa435e80-9fce-11e6-8080-808080808080",
    "name": "Test Device A2"
  },
  {
    "id": "86801880-9fce-11e6-8080-808080808080",
    "name": "Test Device A3"
  }
]
Send Message API

A device can send a message to other device that belongs to the same customer using sendMsg RPC call.

The example below will attempt to send a message from device “Test Device A1” to device “Test Device A2”.

1
2

export TOKEN=A1_TEST_TOKEN
node mqtt-send-msg.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

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

client.on('connect', function () {
    console.log('connected');
    client.subscribe('v1/devices/me/rpc/response/+');
    var requestId = 1;
    var request = {
        method: "sendMsg",
        params: {
            deviceId: "aa435e80-9fce-11e6-8080-808080808080",
            timeout: 2000,
            oneway: false,
            body: {
                param1: "value1"
            }
        }
    };
    client.publish('v1/devices/me/rpc/request/' + requestId, JSON.stringify(request));
});

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

As a result, you should receive the following error:

1

{"error":"No active connection to the remote device!"}

Let’s launch emulator of target device and send message again:

1
2

export TOKEN=A2_TEST_TOKEN
node mqtt-receive-msg.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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

client.on('connect', function () {
    console.log('connected');
    client.subscribe('v1/devices/me/rpc/request/+');
});

client.on('message', function (topic, message) {
    console.log('response.topic: ' + topic);
    console.log('response.body: ' + message.toString());
    client.publish(topic.replace('request', 'response'), '{"status":"ok"}');
});

As a result, you should receive following response from device:

1

{"status":"ok"}

Note that target device id, access tokens, request and response bodies are hardcoded into scripts and correspond to the demo devices.

Example

As a tenant administrator, you are able to review plugin example inside Plugins->Demo Device Messaging RPC Plugin.