Stand with Ukraine flag
Try it now Pricing
IoT Gateway
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation > Configuration guides > BACnet Connector
Getting Started
Installation
On this page

BACnet Connector Configuration

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.

Doc info icon

Please note: If you are new to IoT Gateway, use the “Basic” configuration mode. If you are familiar with configuring IoT Gateway, you can use the “Advanced” configuration mode.

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;
  • 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 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).
Doc info icon

Additional information about the report strategy can be found here.

image

Doc info icon

The settings are the same for both the basic and advanced configurations.

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 Accepted - maximal length of the APDU;
    • Segmentation Supported - 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;

image

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:

1
2
3
4
5
6
7
8
9

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

image

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:

image

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

image

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:

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

{
  "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"
  },
  ...

image

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;

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

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

image

Doc info icon

Additional information about the report strategy can be found here.

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:

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

"attributes": [
    {
      "key": "temperature",
      "objectType": "analogOutput",
      "objectId": "1",
      "propertyId": "presentValue"
    }
],
"timeseries": [
    {
      "key": "state",
      "objectType": "binaryValue",
      "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:

1
2
3
4
5
6
7
8

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

image

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 seconds.
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 this:

1
2
3
4
5
6
7
8
9
10

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

image

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.

1

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