Socket Connector Configuration

Connector configuration
Section “General”
Section “Socket”
Section “Devices”
- Subsection “Device”
Next steps

This guide will help you get familiar with Socket Connector configuration for ThingsBoard IoT Gateway. Use the general configuration guide to enable this Connector. It’s purpose
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

Connector configuration is a UI form that contains information on 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. Let’s take a comprehensive look at all the available settings. We will go through each option in detail to ensure that we thoroughly understand their functions and implications. By doing so, we can make well-informed decisions about which settings will best suit our needs and preferences.

Section “General”

This configuration section contains general connector settings, such as:

Name - connector name used for logs and saving to persistent devices;
Logs configuration:
- Enable remote logging - enables remote logging for the connector;
- Logging level - logging level for local and remote logs: INFO, DEBUG, WARNING, ERROR, CRITICAL, NONE;
Send data only on change - sends data only it has changed since the last check, otherwise – data will be sent after every check;
Report strategy - strategy for sending data to ThingsBoard:
- Report period - period for sending data to ThingsBoard in milliseconds;
- Type - type of the report strategy:
  - On report period - sends data to ThingsBoard after the report period;
  - On value change - sends data to ThingsBoard when the value changes;
  - On value change and report period - sends data to ThingsBoard when the value changes or report period;
  - On received - sends data to ThingsBoard after receiving data from the device (default strategy).

Section “Socket”

The “Socket” section is used for configuring socket connection settings.

Basic

Advanced

This configuration section contains settings of the socket, such as:

Connection type - socket type, can either be TCP or UDP;
Address - connector bound address;
Port - connector bound port;
Buffer size - size of received data block buffer.

This configuration section contains settings of the socket, such as:

Parameter	Default value	Description
name	TCP Connector Example	Connector name
type	TCP	Socket type, can either be TCP or UDP
address	127.0.0.1	Connector bound address
port	50000	Connector bound port
bufferSize	1024	Size of received data block buffer

Configuration section will look like this:

{
  "type": "TCP",
  "address": "127.0.0.1",
  "port": 50000,
  "bufferSize": 1024,
  ...
}

Section “Devices”

This configuration section contains an array of objects that contains clients that can be connected to the connector and send the data. Any connection not included in this array will be rejected by the connector.

Subsection “Device”

Basic

Advanced

To add a new device, click the “plus” icon:

In the opened modal window provide the following fields:

Address filter - used to filter the allowed IP addresses to connect to the connector.
Device name - name for the device in ThingsBoard.
Device profile - device profile for ThingsBoard, by default this parameter is absent, but you can add it.
Encoding - encoding used when writing string data to storage.

Parameter	Default value	Description
addressFilter	.	Used to filter the allowed IP addresses to connect to the connector.
deviceName	Device Example	Name for the device in ThingsBoard.
deviceType	default	Device type for ThingsBoard, by default this parameter is absent, but you can add it.
encoding	utf-8	Encoding used when writing string data to storage.

Example:

{
  "address": "127.0.0.1:50001",
  "deviceName": "Device Example",
  "deviceType": "default",
  "encoding": "utf-8",
  ...

Let’s review more examples of IP addresses filtering:

For example, we have a device that has the following IP address: 192.168.0.120:5001. Now, let’s look at configuration examples of the field to allow connections with different IP address variants:

Only one device with a specified IP address and port can connect:

Address filter: 192.168.0.120:5001
Allow any devices with any IP address, but only port 5001:

Address filter: *:5001
Allow all devices that have the IP address 192.168.0.120 with any port:

Address filter: 192.168.0.120:*
Allow all devices with any IP address and any port:

Address filter: :

Subsection “Time series” and “Attributes”

This configuration section includes the parameters for handling incoming data.

Basic

Advanced

This converter is designed for binary payloads. It directly interprets binary data to retrieve attributes and time series, using specific byte positions for data extraction.

To add new time series or attribute key, follow these steps:

Click “pencil” icon of the “Attributes” section to add new attribute key;
Click on “Add attribute” in the opened window;
Enter the key name and fill in the byte positions. Click “Apply”;
Now click on the “pencil” icon of the “Time series” section to add new time series key;
Click on “Add time series” in the opened window;
Enter the key name, fill in the byte positions and click “Apply”.

Click “pencil” icon of the “Attributes” section to add new attribute key; — Click “**pencil**” icon of the “**Attributes**” section to add new attribute key;

Click on "Add attribute" in the opened window; — Click on “**Add attribute**” in the opened window;

Enter the key name and fill in the byte positions. Click “Apply”; — Enter the **key name** and fill in the **byte positions**. Click “**Apply**”;

Now click on the “pencil” icon of the “Time series” section to add new time series key; — Now click on the “**pencil**” icon of the “**Time series**” section to add new time series key;

Click on "Add time series" in the opened window; — Click on “**Add time series**” in the opened window;

Enter the key name, fill in the byte positions and click “Apply”. — Enter the **key name**, fill in the **byte positions** and click “**Apply**”.

You can enable a specific report strategy for each time series or attribute. This strategy defines how often
data is sent to the ThingsBoard server. The following strategies are available:

On report period - sends data to ThingsBoard after the report period;
On value change - sends data to ThingsBoard when the value changes;
On value change and report period - sends data to ThingsBoard when the value changes or report period;
On received - sends data to ThingsBoard after receiving data from the device (default strategy).

This converter is designed for binary payloads. It directly interprets binary data to retrieve attributes and time series, using specific byte positions for data extraction.

Parameter	Default value	Description
telemetry		This subsection contains parameters of the incoming message, that will be interpreted as telemetry for the device.
… key	temp	Name for telemetry in ThingsBoard.
… byteFrom	0	Used to slice received data from the specific index.
… byteTo	-1	Used to slice received data to the specific index.
attributes		This subsection contains parameters of the incoming requests, that will be interpreted as attributes for the device.
… key	hum	Name for attribute in ThingsBoard.
… byteFrom	2	Used to slice received data from the specific index.
… byteTo	4	Used to slice received data to the specific index.

The attributes section uses the same parameters as the telemetry section.

Example:

{
  "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
    }
  ]
}

Subsection “Attribute request”

This configuration section is optional.

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

Basic

Advanced

In order to add new attribute request, use the following steps:

Click “pencil” icon of the “Attribute requests” section to add new attribute request;
Click on “Add attribute request” in the opened window;
Select the request type, enter request expression, and attribute name expression. Click “Apply”.

Click “pencil” icon of the “Attribute requests” section to add new attribute request; — Click “**pencil**” icon of the “**Attribute requests**” section to add new attribute request;

Click on "Add attribute request" in the opened window; — Click on “**Add attribute request**” in the opened window;

Select the request type, enter request expression, and attribute name expression. Click “Apply”. — Select the request type, enter request expression, and attribute name expression. Click “**Apply**”.

Parameter	Default value	Description
type	shared	The type of requested attribute, can be either “shared” or “client”.
requestExpression	${[0:3]==atr}	The expression that is used to determine if the request from the device is “Attribute Request” or not.
attributeNameExpression	[3:]	The expression that is used to get the name of the requested attribute from the received data.

Configuration of this subsection looks like this:

"attributeRequests": [
  {
    "type": "shared",
    "requestExpression": "${[0:3]==atr}",
    "attributeNameExpression": "[3:]"
  }
]

Additionally, you can request multiple attributes at once. Simply add one more slice expression to attributeNameExpression parameter. For example, if we want to request two shared attributes in a single request, our config will look like this:

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

This means that we have to send the following message to request two shared attributes: atr sharedAttribute sharedAttribute1

Subsection “Attribute update”

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.

Basic

Advanced

In order to add new attribute update, follow these steps:

Click “pencil” icon of the “Attribute updates” section to add new attribute update;
Click on “Add attribute update” in the opened window;
Select encoding and fill in “Attribute on platform” field. Click “Apply”.

Click “pencil” icon of the “Attribute updates” section to add new attribute update; — Click “**pencil**” icon of the “**Attribute updates**” section to add new attribute update;

Click on "Add attribute update" in the opened window; — Click on “**Add attribute update**” in the opened window;

Select encoding and fill in "Attribute on platform" field. Click “Apply”. — Select encoding and fill in “**Attribute on platform**” field. Click “**Apply**”.

The “attributeUpdates” configuration allows you to set up the format of the corresponding attribute data that will be sent to the server.

Parameter	Default value	Description
encoding	utf-16	Encoding used when writing received string data to storage.
attributeOnThingsBoard	sharedName	Shared attribute name

This subsection in configuration file looks like this:

"attributeUpdates": [
  {
    "encoding": "utf-16",
    "attributeOnThingsBoard": "sharedName"
  }
]

Subsection “RPC methods”

This configuration section is optional.

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

Basic

Advanced

In order to add new RPC method, follow these steps:

Click “pencil” icon of the “RPC methods” section to add new RPC;
Click on “Add method” in the opened window;
Fill in “Method name” field, select encoding and check/uncheck “With Response” field. Click “Apply”.

Click “pencil” icon of the “RPC methods” section to add new RPC; — Click “**pencil**” icon of the “**RPC methods**” section to add new RPC;

Click on "Add method" in the opened window; — Click on “**Add method**” in the opened window;

Fill in "Method name" field, select encoding and check/uncheck "With Response" field. Click “Apply”. — Fill in “**Method name**” field, select **encoding** and check/uncheck “**With Response**” field. Click “**Apply**”.

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

Parameter	Default value	Description
methodRPC	rpcMethod1	RPC method name.
withResponse	true	Boolean value that determines whether to send response back to ThingsBoard.
methodProcessing	write	Type of operation.
encoding	utf-8	Encoding used when writing received string data to storage.

This subsection in configuration file looks like this:

"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.