Socket Connector Configuration

• Connector configuration: socket.json
  • General section
  • General section
    • Device subsection
    • Attribute request subsection
    • Attribute update subsection
    • Server side RPC subsection
• Next steps

This guide will help you to get familiar with Socket Connector configuration for ThingsBoard IoT Gateway. Use general configuration guide to enable this Connector. The purpose of this Connector is to connect to your server using TCP or UDP connection type.

This Connector is useful when you have a local server in your facility or corporate network and want to push data from the server to ThingsBoard.

We will describe the connector configuration file below.

Connector configuration: socket.json

Connector configuration is a JSON file that contains information about how to connect to an external server, how to process the data and other service features. Let’s review the format of the configuration file using the example below.

Example of Socket Connector config file.

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "name": "TCP Connector Example",
  "type": "TCP",
  "address": "127.0.0.1",
  "port": 50000,
  "bufferSize": 1024,
  "devices": [
    {
      "address": "127.0.0.1:50001",
      "deviceName": "Device Example",
      "deviceType": "default",
      "encoding": "utf-8",
      "telemetry": [
        {
          "key": "temp",
          "byteFrom": 0,
          "byteTo": -1
        },
        {
          "key": "hum",
          "byteFrom": 0,
          "byteTo": 2
        }
      ],
      "attributes": [
        {
          "key": "name",
          "byteFrom": 0,
          "byteTo": -1
        },
        {
          "key": "num",
          "byteFrom": 2,
          "byteTo": 4
        }
      ],
      "attributeRequests": [
        {
          "type": "shared",
          "requestExpression": "${[0:3]==atr}",
          "attributeNameExpression": "[3:]"
        }
      ],
      "attributeUpdates": [
        {
          "encoding": "utf-16",
          "attributeOnThingsBoard": "sharedName"
        }
      ],
      "serverSideRpc": [
        {
          "methodRPC": "rpcMethod1",
          "withResponse": true,
          "methodProcessing": "write",
          "encoding": "utf-8"
        }
      ]
    }
  ]
}

General section

Configuration section will look like this:

1
2
3
4
5
6
7
8
{
  "name": "TCP Connector Example",
  "type": "TCP",
  "address": "127.0.0.1",
  "port": 50000,
  "bufferSize": 1024,
  ...
}

General section

This configuration section contains an array of objects that contains clients that can be connected to the connector and send the data. This means that connector rejects all connections not included in this array.

Device subsection

This object configuration section includes the parameters of how to proceed with incoming data.

Example:

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
28
29
30
{
  "address": "127.0.0.1:50001",
  "deviceName": "Device Example",
  "deviceType": "default",
  "encoding": "utf-8",
  "telemetry": [
    {
      "key": "temp",
      "byteFrom": 0,
      "byteTo": -1
    },
    {
      "key": "hum",
      "byteFrom": 0,
      "byteTo": 2
    }
  ],
  "attributes": [
    {
      "key": "name",
      "byteFrom": 0,
      "byteTo": -1
    },
    {
      "key": "num",
      "byteFrom": 2,
      "byteTo": 4
    }
  ]
}

Attribute request subsection

In order to request client-side or shared device attributes from ThingsBoard server node, Gateway allows sending attribute requests.

Configuration of this subsection looks like:

1
2
3
4
5
6
7
"attributeRequests": [
  {
    "type": "shared",
    "requestExpression": "${[0:3]==atr}",
    "attributeNameExpression": "[3:]"
  }
]

Also, you can request multiple attributes at once. Simply add one more JSON-path to attributeNameExpression parameter. For example, we want to request two shared attributes in one request, our config will look like:

1
2
3
4
5
6
7
"attributeRequests": [
  {
    "type": "shared",
    "requestExpression": "${[0:3]==atr}",
    "attributeNameExpression": "[4:19][20:]"
  }
]

That means that we have to send the next message for requesting two shared attributes: atr sharedAttribute sharedAttribite1

Attribute update subsection

This configuration section is optional. ThingsBoard allows the provisioning of device attributes and fetches some of them from the device application. You can treat this as a remote configuration for devices, enabling them to request shared attributes from ThingsBoard. See user guide for more details.

The “attributeRequests” configuration allows you to configure the format of the corresponding attribute data that will be sent to the server.

This subsection in configuration file looks like:

1
2
3
4
5
6
"attributeUpdates": [
  {
    "encoding": "utf-16",
    "attributeOnThingsBoard": "sharedName"
  }
]

Server side RPC subsection

ThingsBoard allows for sending RPC commands to devices connected directly to ThingsBoard or via Gateway.

Configuration, provided in this section is used for sending RPC requests from ThingsBoard to the device.

This subsection in configuration file looks like:

1
2
3
4
5
6
7
8
"serverSideRpc": [
  {
    "methodRPC": "rpcMethod1",
    "withResponse": true,
    "methodProcessing": "write",
    "encoding": "utf-8"
  }
]

Also, every telemetry and attribute parameter has a built-in SET RPC method out of the box, eliminating the need for manual configuration. To use them, make sure you set all the required parameters (in the case of Socket Connector, these are the following: withResponse, methodProcessing, encoding). See the guide.

Next steps

Explore guides related to main ThingsBoard features:

• Data Visualization - how to visualize collected data.
• Device attributes - how to use device attributes.
• Telemetry data collection - how to collect telemetry data.
• Using RPC capabilities - how to send commands to/from devices.
• Rule Engine - how to use rule engine to analyze data from devices.