BACnet Connector Configuration

Connector configuration
Section “General”
Section “Application”
Section “Devices”
- Subsection “Device”
(Examples) Device name expression and device profile expression
(Examples) Alternative responses addresses
Object identifiers
Property identifiers
Next steps

The BACnet connector is a way to read and write some basic objects and properties in BACnet IP device. Use general configuration to enable this connector.
We will describe the connector configuration below.

Connector configuration

Connector configuration is a UI form that contains information on how to connect to the BACnet device, how to process the data and other service features. 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, TRACE;
Send data only on change - sends data only if 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 or report period - sends data to ThingsBoard when the value changes or after the report period;
  - On received - sends data to ThingsBoard after receiving data from the device (default strategy).

Section “Application”

Configuration in this section is used to configure the gateway in the BACnet network.

Basic

Advanced

This configuration section contains application settings, such as:

Object Name - the gateway object name in the BACnet network;
Host - the gateway host in the BACnet network;
Port - the gateway port in the BACnet network;
Network mask - the gateway mask in the BACnet network;
Object ID - the gateway object identifier in the BACnet network;
Vendor ID - the gateway vendor identifier in the BACnet network;
Advanced settings:
- Max APDU Length - maximal length of the APDU;
- Segmentation - the type of segmentation:
  - Both - supports both sending and receiving segmented messages;
  - Transmit - supports only sending segmented messages;
  - Receive - supports only receiving segmented messages;
  - None - doesn’t support segmented messages;

Parameter	Default value	Description
objectName	TB_gateway	The gateway object name in the BACnet network.
host	0.0.0.0	The gateway host in the BACnet network.
port	47808	The gateway port in the BACnet network.
mask		The gateway mask in the BACnet network.
objectIdentifier	599	The gateway object identifier in the BACnet network.
maxApduLengthAccepted	1476	Maximal length of the APDU.
segmentationSupported	segmentedBoth	The type of segmentation, can be (detailed description below): segmentedBoth, segmentedTransmit, segmentedReceive, noSegmentation.
vendorIdentifier	15	The gateway vendor identifier in the BACnet network.
networkNumber	3	Identifier of the network segment.
deviceDiscoveryTimeoutInSec	5	Period of time when the connector will try to discover BACnet devices.

segmentationSupported can be one of the following values:

segmentedBoth - supports both sending and receiving segmented messages;
segmentedTransmit - supports only sending segmented messages;
segmentedReceive - supports only receiving segmented messages;
noSegmentation - doesn’t support segmented messages.

Example:

"application": {
    "objectName": "TB_gateway",
    "host": "0.0.0.0",
    "port": "47808",
    "objectIdentifier": 599,
    "maxApduLengthAccepted": 1476,
    "segmentationSupported": "segmentedBoth",
    "vendorIdentifier": 15
},

Section “Devices”

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

Subsection “Device”

Basic

Advanced

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

Provide the following fields in the opened model window:

Host - the host of the device;
Port - the port of the device;
Device name source - the source of the device name, can be:
- Constant - the device name is static;
- Expression - the device name is an expression;
Device name value / expression - the device name (you can find detail examples here);
Device profile source - the source of the device profile, can be the same as the device name source;
Device profile value / expression - the device profile name (you can find detail examples here);
Poll period - the period of time when the connector will try to poll BACnet device;
Advanced configuration settings:
- Alternative responses addresses - the alternative address for responses from the device (you can find detail examples here).

Parameter	Description
host	The host of the device.
port	The port of the device.
pollPeriod	The period of time when the connector will try to poll the BACnet device.
altResponsesAddresses	Array of alternative addresses for device responses (you can find detail examples here).
deviceInfo
… deviceNameExpressionSource	The source of the device name: constant, expression.
… deviceNameExpression	The device name (you can find detail examples here).
… deviceProfileExpressionSource	The source of the device profile: constant, expression.
… deviceProfileExpression	The device profile name (you can find detail examples here).

Example:

{
  "host": "192.168.2.110",
  "port": "47808",
  "pollPeriod": 10000,
  "altResponsesAddresses": [
    "192.168.2.110"
  ],
  "deviceInfo": {
    "deviceNameExpression": "BACnet Device ${objectName}",
    "deviceProfileExpression": "default",
    "deviceNameExpressionSource": "expression",
    "deviceProfileExpressionSource": "constant"
  },
  ...

Subsection “Time series” and “Attributes”

This configuration section includes the parameters for handling incoming data.

Basic

Advanced

Configuration in this subsection provides settings for processing data from BACnet device as timeseries and attributes on the platform instance.

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

Click “pencil” icon of the “Attributes” section to add new attribute key;
Click “Add attribute” in the opened window;
Enter the key name, select “Object ID” and “Property ID” from the dropdown list. Click “Apply”;
Now click on the “pencil” icon of the “Time series” section to add new time series key;
Click “Add time series” in the opened window;
Enter the key name, select “Object ID” and “Property ID” from the dropdown list. 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 “Add attribute” in the opened window; — Click “**Add attribute**” in the opened window;

Enter the key name, select "Object ID" and "Property ID" from the dropdown list. Click “Apply”; — Enter the **key name**, select “Object ID” and “Property ID” from the dropdown list. 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 "Add time series" in the opened window; — Click “**Add time series**” in the opened window;

For each time series or attribute, you can enable specific report strategy. This strategy defines how often the data will be 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 after the report period;
On received - sends data to ThingsBoard after receiving data from the device (default strategy).

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

Parameter	Description
timeseries	This subsection contains parameters of the device data, that will be interpreted as timeseries for the device.
… key	Name for timeseries in the platform.
… objectType	Object type in the BACnet device.
… objectId	Object id in the BACnet device.
… propertyId	Property id in the BACnet device.
attributes	This subsection contains parameters of the device data, that will be interpreted as attributes for the device.
… key	Name for attribute in the platform.
… objectType	Object type in the BACnet device.
… objectId	Object id in the BACnet device.
… propertyId	Property id in the BACnet device.

Example:

"timeseries": [
  {
    "key": "temperature",
    "objectType": "analogInput",
    "objectId": 2,
    "propertyId": "presentValue"
  }
],
"attributes": [
  {
    "key": "voltage",
    "objectType": "analogInput",
    "objectId": 1,
    "propertyId": "presentValue"
  }
],

Subsection “Attribute updates”

This configuration subsection 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” subsection to add new attribute update;
Click “Add attribute update” in the opened window;
Fill in “Key” field, select “Object ID” and “Property ID” from the dropdown list. Click “Apply” button.

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

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

Fill in "Key" field, select "Object ID" and "Property ID" from the dropdown list. Click “Apply” button. — Fill in “**Key**” field, select “**Object ID**” and “**Property ID**” from the dropdown list. Click “**Apply**” button.

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

Parameter	Description
key	Name of the shared attribute on platform instance.
objectType	Object type in the BACnet device.
objectId	Object id in the BACnet device.
propertyId	Property id in the BACnet device.

This subsection in configuration file looks like:

"attributeUpdates": [
  {
    "key": "brightness",
    "objectType": "analogOutput",
    "objectId": 1,
    "propertyId": "presentValue"
  }
],

Subsection “RPC methods”

This configuration subsection 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;
In the opened window click “Add method”;
Fill in “Method” field, select “Request Type”, “Object ID”, “Property ID” from the dropdown list. Click “Apply” button.

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

In the opened window click “Add method”; — In the opened window click “**Add method**”;

Fill in "Method" field, select "Request Type", "Object ID", "Property ID" from the dropdown list. Click “Apply” button. — Fill in “**Method**” field, select “**Request Type**”, “**Object ID**”, “**Property ID**” from the dropdown list. Click “**Apply**” button.

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

Parameter	Description
method	RPC method name.
requestType	“writeProperty” to write data and “readProperty” to read data.
requestTimeout	Timeout to wait for a response from the BACnet device, in milliseconds.
objectType	Object type in the BACnet device.
objectId	Object id in the BACnet device.
propertyId	Property id in the BACnet device.
priority	Priority of the value to write (optional, should be an integer from 1 to 16).

If value is None, BACnet connector will send relinquish command with Null value. Also, writing RPC should contain value or priority, or both.

This subsection in configuration file looks like this:

"serverSideRpc": [
  {
    "method": "set_state",
    "requestType": "writeProperty",
    "requestTimeout": 10000,
    "objectType": "binaryOutput",
    "objectId": 1,
    "propertyId": "presentValue"
  },
],

Additionally, every telemetry and attribute parameter comes with 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 (for the BACnet Connector, these include: objectType, objectId, propertyId, and value – only if RPC method name is “set”). See the guide.

(Examples) Device name expression and device profile expression

Let’s review more examples of device name expression and device profile expression fields.

These fields allow for the dynamic construction of a formatted device name/profile using values extracted from a JSON object. You can specify variables to access the relevant fields in the JSON.

You can use the following variables to extract specific device information:

objectName - extracts the device’s object name (e.g., “Main Controller”);
vendorId - extracts the device’s vendor ID, typically a numeric identifier representing the manufacturer (e.g., “1234”);
objectId - extracts the device’s unique object identifier (e.g., “999”);
address - extracts the device’s network address (e.g., “192.168.1.1”).

Examples:

“Device ${objectName}” If the objectName variable exists and contains “objectName”: “Main Controller”, the device on platform will have the following name: Device Main Controller;
“Vendor: ${vendorId}” If the vendorId variable exists and contains “vendorId”: 1234, the device on platform will have the following name: Vendor: 1234;
“Device ID: ${objectId} at ${address}” If the objectId variable exists and contains “vendorId”: 999 and address variable exists and contains “address”: “192.168.1.1”, the device on platform will have the following name: Device ID: 999 at 192.168.1.1.

(Examples) Alternative responses addresses

Let’s review more examples of alternative responses addresses.

This field allows you to specify an alternative address for responses from the device. It is useful when the gateway and BACnet device are located in different networks.

For example, if gateway running via the docker container and the BACnet device is located in the local network under 192.168.1.200:45606, you can specify the IP address of the BACnet device in the alternative responses addresses field.

"altResponsesAddresses": ["192.168.1.200"]

This is important because bacpypes provide APDU to the gateway without port number, so the connector can’t determine if
it is an allowed device. In this case, the connector will use the alternative address to determine that it is an allowed device.

Object identifiers

The BACnet connector Object identifiers consist of two parts separated by a colon (“:”) symbol:
the name of object and the number of this object on the device.

Tested and supported objects:

BACnet object id	ThingsBoard object id
Binary input	binaryInput
Binary output	binaryOutput
Binary value	binaryValue
Analog Input	analogInput
Analog output	analogOutput
Analog value	analogValue

Objects in testing:

accumulatorObject
averagingObject
calendarObject
commandObject
fileObject
lifeSafetyPointObject
lifeSafetyZoneObject
loopObject
multiStateInputObject
multiStateOutputObject
multiStateValueObject
notificationClassObject
programObject
pulseConverterObject
scheduleObject
structuredViewObject
trendLogObject

Property identifiers

Property identifiers depend on type of the BACnet object, provided in camelCase, e.g. presentValue objectName objectDescription etc.

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.