Connectors are Gateway components that connect to external system or directly to devices. Gateway has many built-in connectors (e.g. MQTT, OPC-UA server, Modbus, BLE, etc).
Once connected, connector is either poll data from those systems or subscribe to updates. Poll vs subscribe depends on the protocol capabilities.
Main goal of the custom connector is opportunity to connect to any device with any protocol. Connectors are written in Python language.
We will demonstrate how to create custom connector by example. Let’s assume we want our connector to connect to serial port on your device and read the data.
Connector will be able to push data to device over serial. We will call this connector SerialConnector.
Please see step-by-step guide how we have added SerialConnector to the Gateway.
You can create your custom connector, based on this example.
Notate: The gateway already contains this connector, you can find it in the extensions folder
Let’s assume our serial devices push UTF-8 encoded strings like this:
48\r2430947595\n
where 48 is humidity, \r is delimiter between values 2430947595 is device serial number and messages are separated by \n symbol.
Step 1. Define SerialConnector configuration
At first, we need create configuration file for our serial connector. Let’s create file in the config folder (In the folder with tb_gateway.yaml file.)
touch custom_serial.json
After this we need add some configuration for this connector in file.
Example of custom connector configuration file. Press to expand.
In this file we write the configuration that we will use in the connector code.
Parameters in the configuration:
“name” - connector name, it should be like a connector name in the tb_gateway.yaml file. Uses by the gateway to find correct connector for saved devices.
“devices” - array with devices configuration (We can provide more that one device.)
In the “devices” array configuration file has devices json objects with configuration parameters for this device.
Parameters in device object:
“name” - name of the device for ThingsBoard instance.
“port” - port for the device.
“baudrate” - port baudrate for connection to device. Notate: You can also use parameters from a configuration for serial port such as parity, stop bits, etc.
You can read more about serial port parameters here.
“converter” - class name of converter that we will use for the serial connector.
“telemetry” - objects array, with a configuration for processing data from device, data processed with configuration in this section will be interpreted as device telemetries.
“attributes” - objects array, with a configuration for processing data from device, data processed with configuration in this section will be interpreted as device attributes.
“attributesUpdates” - objects array with a configuration for processing attribute update request from ThingsBoard.
Step 2. Locate extensions folder
Connector file should being placed in extensions folder that depends on type of installation:
We need create a folder and file for our connector class.
We have a folder “serial” in extensions folder and file “custom_serial_connector.py”.
After this, we write connector class in the connector file and override some methods of parent class. List of methods.
Example of custom connector file. Press to expand.
Step 4. Define Converter Implementation
The purpose of the converter is to convert data from devices to the ThingsBoard format.
Converters written in Python language.
We should create a custom converter file “custom_serial_converter.py” in the extension folder, you can find extension folder location in Step 2
Example of custom converter file. Press to expand.
After processing 48\r2430947595\n we receive following dictionary:
This dictionary will be converted into json and gateway will send it to ThingsBoard instance.
Step 5. Include Connector into main Gateway configuration file
To add the serial connector to the gateway, we need add following lines into section connectors tb_gateway.yaml file.
-name:Custom Serial Connectortype:serialconfiguration:custom_serial.jsonclass:CustomSerialConnector
where:
name - connector name
type - folder name in extensions, with connector file
configuration - connector configuration file in folder with tb_gateway.yaml file
class - connector class name in connector file in extensions
Step 6. Run the IoT gateway
To run the gateway you should execute following command, it depends on type of installation:
If you install the IoT gateway as daemon, you should restart it with following command to apply changes to the configuration:
sudo systemctl restart thingsboard-gateway
If you install the IoT gateway as Python module, you should run it from the folder with tb_gateway.yaml (or change path to the tb_gateway.yaml file) with the following command to apply changes to the configuration:
You can check a status of the IoT Gateway by watch the logs in a folder that you provide in logs.conf file.
Default location of logs folder for the daemon - “/var/log/thingsboard-gateway/”
Default location of logs folder for Python module - “./logs/”
Step 6. Check a result in the ThingsBoard instance
To check the result, you should connect device, and go to the ThingsBoard UI into “Devices” tab.
If device connected correctly and has sent some data, you will see device with a name - “CustomSerialDevice1”.
To check the data - open device and go to the telemetry tab.
You should see the telemetry from config (humidity) with some value 48 (Value from example, your value can be different).
Custom connector methods reference
You should implement following methods: __init__ – called on creating object (In example used for loading converters, saving data from configs to object variables and creating serial ports objects). open – called on start connection to device with connector. get_name – called to recieve name of connector. is_connected – called to check the connection to devices. run – Main method of thread, must contain an infinite loop and all calls to data receiving/processing functions. close – method, that has being called when gateway stops and should contain processing of closing connection/ports etc. on_attributes_update – gateway call it when receives AttributeUpdates request from ThingsBoard server to device with this connector. server_side_rpc – gateway call it when receives ServerRpcRequest from ThingsBoard server.
__init__ method
Parameters:
def__init__(self,gateway,config,connector_type):
self – current object gateway – gateway object (will being used for saving data) config – dictionary with data from connector configuration file connector_type – type of connector(Need for load converters for this connector type, from tb_gateway.yaml)
In example above, we used this method to initialize data with which we will work.
__connect_to_devices method
def__connect_to_devices(self):
self – current object
Service method, used for connection to devices.
get_name method
defget_name(self):# Function used for logging, sending data and statistic
self – current object
Method to get connector name.
is_connected method
defis_connected(self):# Function for checking connection state
self – current object
Method for check current connection state.
load_converters method
defload_converters(self):# Function for search a converter and save it.
self – current object
Method for loading converters for devices.
run method
Method from threading module, that being called after initializing of gateway.
Parameters:
defrun(self):
self – current object.
In example above we use this method for connection to devices, read data from them and run converter
close method
Method is being called when gateway stopping or catch a fatal exception in a main loop of gateway.
defclose(self):
self – current object.
on_attributes_update method
Method is being called when gateway receive AttributeUpdates request from ThingsBoard.
defon_attributes_update_method(self,content):
self – current object. content – dictionary with data from ThingsBoard server.
Where: device - String with device name. req_id - Id of RPC request from ThingsBoard content - depends on type of rpc:
If without response:
content={"success":True}
If with response in content should be any dictionary with content that you want send to ThingsBoard as response.
Custom converter methods reference
You should implement following methods: __init__ – called on creating object. convert – Method for conversion data from device format to ThingsBoard data format.
__init__ method
Parameters:
def__init__(self,config):
self – current object. config – dictionary with data from connector configuration file.
In the example used to save the converter configuration and create a template for the result’s dictionary with ThingsBoard data format
convert method
Method for conversion data from device format to ThingsBoard data format.
Parameters:
defconvert(self,config,data):
self – current object. config – configuration section for this device from connector configuration file. data – data from a device.
This function should return dictionary in format like following: