BACnet Connector Configuration

Overview
Configuration modes
General settings
Application
Advanced application settings
Data mapping
- Attributes and Time series
- Usage examples
Requests mapping
EDE files parsing (Advanced configuration mode only)
Advanced configuration
- Application
- Devices
Additional information
- Object identifiers
- Property identifiers
Troubleshooting
- Device discovery issues on Linux with Docker Compose
- Device discovery issues on Windows with Docker Compose
Next steps

Overview

This documentation will help you set up the BACnet connector for the ThingsBoard IoT Gateway. We’ll explain the configuration parameters in simple terms to make it easy for you to understand and follow. The BACnet protocol is widely used in building automation and control systems for applications such as heating, ventilation, air conditioning (HVAC), lighting control, access control, and fire detection systems. Use general configuration to enable this extension.

The BACnet connector allows the ThingsBoard IoT Gateway to communicate with BACnet devices, enabling data exchange and control capabilities. The connector can be configured via the user interface form, which helps you set up a connection to the BACnet devices, collect data and write data to devices. Let’s look at all the available settings and explain each one clearly. This will help you understand how everything works.

Configuration modes

The BACnet connector can be configured in two modes: Basic and Advanced.

Basic mode is designed for users who are new to ThingsBoard IoT Gateway and want to quickly set up the connector with minimal configuration. It provides a simplified interface with essential settings.
Advanced mode is intended for experienced users who need more control over the configuration. It offers additional options and flexibility for advanced use cases.

You can switch between these modes using the toggle button at the top of the configuration page:

General settings

This configuration section contains general connector settings, such as:

Name - connector name used for logs and saving to persistent devices;
Logs configuration - settings for local and remote logging:
- Enable remote logging - enables remote logging for the connector;
- Logging level - logging level for local and remote logs: NONE, ERROR, CRITICAL, WARNING, INFO, DEBUG, TRACE;
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).

Application

Configuration in this section is used to configure the gateway in the BACnet network. The following parameters are used to configure application settings:

Object Name - the gateway object name in the BACnet network.
Host - the gateway host in the BACnet network. Make sure you use the correct network address where your devices are located so that the gateway can find them.
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 application settings

You can configure additional application settings like: APDU length, segmentation, network number and discovering timeout.

Parameter	Default value	Description
APDU Length (in bytes)	1476	Maximal length of the APDU.
Segmentation	Both	Segmentation type for transmitting large BACnet messages. Can be: Both, Transmit, Receive, None.
Network number	3	Identifier of the network segment.
Discovering timeout (in sec)	5	Period of time when the connector will try to discover BACnet devices.

Data mapping

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.

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

Attributes and Time series

This configuration section includes the parameters for handling incoming data. You can specify which data will be treated as device attributes and which as time series. Attributes are used for storing static or infrequently changing data, while time series are used for storing dynamic or frequently changing data.

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

Usage examples

Dynamic device name/profile

Alternative responses addresses

Discovering all device(advanced configuration mode only)

Reading all device objects(advanced configuration mode only)

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.

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.

There are situations when there are many devices with the same list of objects, the values of which need to be read. Copying the configuration for each device is not very convenient, so the BACnet connector allows you to automatically find all devices on the network and connect them with the same configuration. To do this, you need to specify the host and port of the device, as well as set templates for the device name and device profile.

Let’s look at an example of how to properly configure automatic device discovery.

Suppose we have two devices with the same list of objects:

Object Type	Object ID	Property ID	Key
Analog Input	1	Present Value	temperature
Binary Input	1	Present Value	relay
Analog Input	2	Present Value	humidity
Analog Input	3	Present Value	pressure

To configure automatic device discovery, use the following BACnet connector configuration:

{
  "application": {
    "objectName": "TB_gateway",
    "host": "YOUR_HOST",
    "port": 47808,
    "objectIdentifier": 599,
    "vendorIdentifier": 15,
    "maxApduLengthAccepted": 1476,
    "segmentationSupported": "segmentedBoth",
    "deviceDiscoveryTimeoutInSec": 5
  },
  "devices": [
    {
      "altResponsesAddresses": [],
      "host": "*",
      "port": "*",
      "deviceInfo": {
        "deviceNameExpression": "${objectName}",
        "deviceProfileExpression": "default",
        "deviceNameExpressionSource": "expression",
        "deviceProfileExpressionSource": "constant"
      },
      "pollPeriod": 10000,
      "timeseries": [
        {
          "key": "temperature",
          "objectType": "analogInput",
          "objectId": 1,
          "propertyId": "presentValue"
        },
        {
          "key": "relay",
          "objectType": "binaryInput",
          "objectId": 1,
          "propertyId": "presentValue"
        },
        {
          "key": "humidity",
          "objectType": "analogInput",
          "objectId": 2,
          "propertyId": "presentValue"
        },
        {
          "key": "pressure",
          "objectType": "analogInput",
          "objectId": 3,
          "propertyId": "presentValue"
        }
      ],
      "attributes": [],
      "attributeUpdates": [],
      "serverSideRpc": []
    }
  ]
}

Below are the main parameters that you can use to properly configure automatic device detection. Let’s take a closer look at them:

host - you need to specify *, this is done so that the connector accepts all IAm messages from all devices on the network.
port - you need to specify *, this is done so that the connector accepts all IAm messages from all devices on the network.
deviceNameExpression - This is a template for the device name. ${objectName} is used to match the device name to the object name in the BACnet network.
deviceProfileExpression - This is a template for a device profile. In our case, we use default because all devices have the same type.

After saving the changes and starting the connector, it will send a WhoIs query to the network and start receiving IAm messages from all devices. After receiving the IAm message, the connector will automatically create a device for each device found with the specified templates and start reading data from the objects. The screenshot below shows what the device list looks like after automatic discovery:

There are situations when a BACnet device has a lot of objects, and you want to read all the objects of the device without having to manually add each object to the connector configuration. Or maybe you don’t know what objects are in the device and want to read all the objects automatically. The BACnet connector supports this functionality and allows you to read all the objects of the device by easily configuring just one parameter.

Let’s look at an example of how to properly configure reading all device objects.

In order to read all the device objects, you need to decide where exactly the values of these objects will be stored: in telemetry or attributes. Depending on this, you need to put * in the corresponding section.

In our case, we will store all objects in time series, so the device configuration will look like this:

{
  "application": {
    "objectName": "TB_gateway",
    "host": "YOUR_HOST",
    "port": 47808,
    "objectIdentifier": 599,
    "vendorIdentifier": 15,
    "maxApduLengthAccepted": 1476,
    "segmentationSupported": "segmentedBoth",
    "deviceDiscoveryTimeoutInSec": 5
  },
  "devices": [
    {
      "altResponsesAddresses": [],
      "host": "YOUR_DEVICE_HOST",
      "port": 47808,
      "deviceInfo": {
        "deviceNameExpression": "${objectName}",
        "deviceProfileExpression": "default",
        "deviceNameExpressionSource": "expression",
        "deviceProfileExpressionSource": "constant"
      },
      "pollPeriod": 10000,
      "timeseries": "*",
      "attributes": [],
      "attributeUpdates": [],
      "serverSideRpc": []
    }
  ]
}

As you can see from the configuration above, we have put * in the timeseries section, which means that all device objects will be saved in the telemetry. In the attributes section, we have not put *, so the attributes will not be read.

After saving the changes and starting the connector, you can see that the corresponding device has been added to the platform, and its telemetry has started to fill with all the device objects:

Requests mapping

The Requests mapping section allows you to configure how the ThingsBoard platform instance will interact with the devices. That is, how the platform will request data from the devices, how it will update device attributes, and how it will send RPC commands to the devices.

BACnet connector supports the following requests mapping:

Attribute updates - allows update device objects values from ThingsBoard platform instance.
RPC methods - allows sending RPC commands to devices. Using RPC methods, you can get or set values of the BACnet device objects values. BACnet connector supports different types of RPC methods, such as:
- Reserved GET/SET methods - these methods are automatically created for each attribute and time series parameter. You can use them to get or set values of the BACnet device objects values.
- Configurable RPC to device - these methods allow you to configure custom RPC commands in connector configuration that can be sent to the devices.

Attribute updates

This subsection contains configuration for attribute updates request from ThingsBoard platform instance.

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 following parameters are used to configure attribute updates:

Key - the key of the shared attribute in ThingsBoard. It can be specified as a static value.
Object ID - the object id in the BACnet device.
Object Type - the object type in the BACnet device.
Property ID - the property id in the BACnet device.

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.

RPC methods

ThingsBoard allows sending RPC commands to devices connected directly to ThingsBoard or via Gateway. The following parameters are used to configure RPC methods:

Method - the RPC method name.
Request Type - “writeProperty” to write data and “readProperty” to read data.
Object ID - the object id in the BACnet device.
Object Type - the object type in the BACnet device.
Property ID - the property id in the BACnet device.
Request Timeout - timeout in milliseconds for the RPC method execution.

In order to add a 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.

Usage examples

Attribute Updates

RPC to Device

Reserved RPCs

Attribute updates allow you to update objects values on the BACnet device. You can add new attribute updates in the “Attribute updates” section of the device configuration page.

As an example, we will use a BACnet controller to which a relay is connected. We also know that the relay has the following object ID: Binary Input:1. We added this Object ID as a telemetry parameter with the key relay. We used telemetry so that later it would be convenient for us to see if the value we changed using the attribute update has changed. You, also, can add this telemetry datapoint to the device configuration or use the reserved get method to check the value of the node.

Let’s add an attribute update to our configuration. For this purpose, follow these steps:

Go to “Entities” → “Gateways” in the left sidebar and select your gateway.
Click on the “Connectors configuration” button on the right side menu.
Select the created BACnet connector and click on the “Devices” tab. Make sure you have configured and connected device (if you don’t know how to do it, see Application settings and Data mapping sections of this guide). Click on the “Pencil” icon on a device you want to configure attribute updates for.
Scroll down to the “Attribute updates” section and click on the “Pencil” icon to edit the attribute updates.
Click on the “Add attribute update” button. In our case, we will add relay attribute update, so the “Key” field, enter relay, select the “Object ID” as Analog Input and “1”, “Property ID” as “Present Value”.
Remember to save your changes by clicking the “Apply” button and click save connector configuration button.

Go to "Entities" → "Gateways" in the left sidebar and select your gateway. — Go to “**Entities**” → “**Gateways**” in the left sidebar and select your gateway.

Click on the "Connectors configuration" button on the right side menu. — Click on the “**Connectors configuration**” button on the right side menu.

Select the created BACnet connector and click on the "Devices" tab. Make sure you have configured and connected device (if you don’t know how to do it, see [Application settings](/docs/iot-gateway/config/bacnet/#application) and [Data mapping](/docs/iot-gateway/config/bacnet/#data-mapping) sections of this guide). Click on the “Pencil” icon on a device you want to configure attribute updates for. — Select the created BACnet connector and click on the “**Devices**” tab. Make sure you have configured and connected device (if you don’t know how to do it, see Application settings and Data mapping sections of this guide). Click on the “**Pencil**” icon on a device you want to configure attribute updates for.

Scroll down to the “Attribute updates” section and click on the “Pencil” icon to edit the attribute updates. — Scroll down to the “**Attribute updates**” section and click on the “**Pencil**” icon to edit the attribute updates.

Click on the “Add attribute update” button. In our case, we will add `relay` attribute update, so the “Key” field, enter `relay`, select the “Object ID” as Analog Input and "1", "Property ID" as "Present Value". — Click on the “**Add attribute update**” button. In our case, we will add `relay` attribute update, so the “**Key**” field, enter `relay`, select the “**Object ID**” as **Analog Input** and “1”, “**Property ID**” as “**Present Value**”.

Remember to save your changes by clicking the “Apply” button and click save connector configuration button. — Remember to save your changes by clicking the “**Apply**” button and click save connector configuration button.

Now we can check if the attribute update works. Go to “Entities” → “Devices” → select a created device → “Attributes” tab → select “Shared attributes” → click on the “+” icon and add relay attribute with type “Boolean” set it to “True”.

Now, let’s check the value of the relay Object ID. In the selected device, go to the “Last telemetry” tab and check the value of the relay telemetry. It should be true since we set the shared attribute to true.

Try to change the value of the relay shared attribute to false. After a few seconds, you should see that the relay telemetry value has changed to false, which means that the attribute update worked correctly.

Full configuration for BACnet connector for the examples above will look like this (make sure to use the right device host and port):

{
  "application": {
    "objectName": "TB_gateway",
    "host": "YOUR_HOST",
    "port": 47808,
    "objectIdentifier": 599,
    "vendorIdentifier": 15,
    "maxApduLengthAccepted": 1476,
    "segmentationSupported": "segmentedBoth",
    "networkNumber": 3,
    "deviceDiscoveryTimeoutInSec": 5
  },
  "devices": [
    {
      "altResponsesAddresses": [],
      "host": "YOUR_DEVICE_HOST",
      "port": 47808,
      "networkMask": "",
      "deviceInfo": {
        "deviceNameExpression": "${objectName}",
        "deviceProfileExpression": "default",
        "deviceNameExpressionSource": "expression",
        "deviceProfileExpressionSource": "constant"
      },
      "pollPeriod": 10000,
      "timeseries": [
        {
          "key": "relay",
          "objectType": "binaryInput",
          "objectId": 1,
          "propertyId": "presentValue"
        }
      ],
      "attributes": [],
      "attributeUpdates": [
        {
          "key": "relay",
          "objectType": "binaryInput",
          "objectId": 1,
          "propertyId": "presentValue"
        }
      ],
      "serverSideRpc": []
    }
  ]
}

RPC to Device allows sending RPC commands to the device that is connected to ThingsBoard directly or via Gateway.

As an example, we will use a BACnet controller with temperature sensor. We also know that the temperature sensor has the following object ID: Analog Value:1, so we will read this value using RPC to Device. To call this method, first, we need to configure the BACnet connector to support RPC calls. For this purpose, follow these steps:

Go to “Entities” → “Gateways” in the left sidebar and select your gateway.
Click on the “Connectors configuration” button on the right side menu.
Select the created BACnet connector and click on the “Devices” tab. Make sure you have configured and connected device (if you don’t know how to do it, see Application settings and Data mapping sections of this guide). Click on the “Pencil” icon on a device you want to configure attribute updates for.
Scroll down to the “RPC methods” section and click on the “Pencil” icon to edit the RPC methods.
Click on the “Add method” button. Fill in the “Method” field with getTemperature, select the “Request Type” as “Read Property”, “Object ID” as “Analog Value” and “1”, and “Property ID” as “Present Value”.
Remember to save your changes by clicking the “Apply” button and click save connector configuration button.

Scroll down to the "RPC methods" section and click on the "Pencil" icon to edit the RPC methods. — Scroll down to the “**RPC methods**” section and click on the “**Pencil**” icon to edit the RPC methods.

Click on the "Add method" button. Fill in the "Method" field with `getTemperature`, select the "Request Type" as "Read Property", "Object ID" as "Analog Value" and "1", and "Property ID" as "Present Value". — Click on the “**Add method**” button. Fill in the “**Method**” field with `getTemperature`, select the “**Request Type**” as “**Read Property**”, “**Object ID**” as “**Analog Value**” and “1”, and “**Property ID**” as “**Present Value**”.

We are done with configuration, so let’s check how to call the method. In the RPC Debug Terminal widget, run the following command:

getTemperature

Response:

Full configuration for BACnet connector for the example above will look like this (make sure to use the right device host and port):

{
  "application": {
    "objectName": "TB_gateway",
    "host": "YOUR_HOST",
    "port": 47808,
    "objectIdentifier": 599,
    "vendorIdentifier": 15,
    "maxApduLengthAccepted": 1476,
    "segmentationSupported": "segmentedBoth",
    "deviceDiscoveryTimeoutInSec": 5
  },
  "devices": [
    {
      "altResponsesAddresses": [],
      "host": "YOUR_DEVICE_HOST",
      "port": 47808,
      "deviceInfo": {
        "deviceNameExpression": "${objectName}",
        "deviceProfileExpression": "default",
        "deviceNameExpressionSource": "expression",
        "deviceProfileExpressionSource": "constant"
      },
      "pollPeriod": 10000,
      "timeseries": [
        {
          "key": "some-key",
          "objectType": "binaryInput",
          "objectId": 1,
          "propertyId": "presentValue"
        }
      ],
      "attributes": [],
      "attributeUpdates": [],
      "serverSideRpc": [
        {
          "method": "getTemperature",
          "objectType": "analogValue",
          "objectId": 1,
          "propertyId": "presentValue",
          "timeout": 5000,
          "requestType": "readProperty"
        }
      ]
    }
  ]
}

Every telemetry and attribute parameter has GET and SET RPC methods out of the box, so you don’t need to configure them manually.

As an example, we will use a BACnet controller to which a relay is connected. We also know that the relay has the following object ID: Binary Input:1.

We will use this object ID to read the value of the relay using the GET RPC method and to set the value of the relay using the SET RPC method. The configuration for this telemetry will look like this:

{
  "key": "relay",
  "objectType": "binaryInput",
  "objectId": 1,
  "propertyId": "presentValue"
}

Let’s check the value of the relay using the reserved GET method. To get the current value of the relay, run the query in the RPC debug terminal:

get objectType=binaryInput;objectId=1;propertyId=presentValue;

Response:

{"result": {"value":  "inactive"}}

So, the GET method returns the current value of the relay, and we can see that the relay is off.

To set the value of the relay and turn it on, run the query:

set objectType=binaryInput;objectId=1;propertyId=presentValue;value=1;

Response:

{"result": {"value": 1}}

And as you can see, from the screenshot below, the relay telemetry value has changed to 1:

Also, let’s check the value of the relay telemetry again:

get objectType=binaryInput;objectId=1;propertyId=presentValue;

Response:

{"result": {"value":  "active"}}

Full configuration for BACnet connector for the examples above will look like this (make sure to use the right device host and port):

{
  "application": {
    "objectName": "TB_gateway",
    "host": "YOUR_HOST",
    "port": 47808,
    "objectIdentifier": 599,
    "vendorIdentifier": 15,
    "maxApduLengthAccepted": 1476,
    "segmentationSupported": "segmentedBoth",
    "deviceDiscoveryTimeoutInSec": 5
  },
  "devices": [
    {
      "altResponsesAddresses": [],
      "host": "YOUR_DEVICE_HOST",
      "port": 47808,
      "deviceInfo": {
        "deviceNameExpression": "${objectName}",
        "deviceProfileExpression": "default",
        "deviceNameExpressionSource": "expression",
        "deviceProfileExpressionSource": "constant"
      },
      "pollPeriod": 10000,
      "timeseries": [
        {
          "key": "relay",
          "objectType": "binaryInput",
          "objectId": 1,
          "propertyId": "presentValue"
        }
      ],
      "attributes": [],
      "attributeUpdates": [],
      "serverSideRpc": []
    }
  ]
}

EDE files parsing (Advanced configuration mode only)

The BACnet connector supports EDE files parsing. EDE (Engineering Data Exchange) files are used to describe the structure and properties of BACnet devices. By parsing EDE files, the BACnet connector can automatically configure itself to interact with the devices described in the files.

To use EDE files parsing, you need to provide the path to the EDE file in the connector configuration. The connector will then read the file and extract the necessary information to communicate with the BACnet devices. The EDE file should be in CSV format and follow the BACnet EDE schema.

Let’s look at the example of the EDE file parsing configuration.

We will use an EDE file exported from YABE (Yet Another BACnet Explorer) application. The file contains the description of a BACnet device with several objects. The file looks like this:

Now let’s configure the BACnet connector to use this EDE file. In the advanced configuration mode, paste the following connector configuration (make sure to use the correct path to your EDE file):

{
  "application": {
    "objectName": "TB_gateway",
    "host": "YOUR_HOST",
    "port": 47808,
    "objectIdentifier": 599,
    "vendorIdentifier": 15,
    "maxApduLengthAccepted": 1476,
    "segmentationSupported": "segmentedBoth",
    "deviceDiscoveryTimeoutInSec": 5
  },
  "edeFilePath": "/path/to/your/file.ede"
}

After applying the configuration, the BACnet connector will parse the EDE file and automatically configure itself to interact with the BACnet device described in the file. You can then use the connector to read data from the device, update device attributes, and send RPC commands to the device. As you can see on the screenshot below, the connector has automatically created the device with the name and profile from the EDE file, as well as all the attributes and time series from the file:

Advanced configuration

The advanced configuration section provides a detailed overview of all available parameters for the BACnet connector.

Application

The application configuration parameters are used to configure the gateway in the BACnet network.

Parameter	Default value	Description
application.objectName	ThingsBoard Gateway	The gateway object name in the BACnet network.
application.host		The gateway host in the BACnet network
application.port	47808	The gateway port in the BACnet network.
application.mask		The gateway mask in the BACnet network.
application.networkNumber		Identifier of the network segment.
application.objectIdentifier	599	The gateway object identifier in the BACnet network.
application.vendorIdentifier	15	The gateway vendor identifier in the BACnet network.
application.maxApduLengthAccepted	1476	Maximal length of the APDU.
application.segmentationSupported	segmentedBoth	The type of segmentation, can be: segmentedBoth, segmentedTransmit, segmentedReceive, noSegmentation.
application.deviceDiscoveryTimeoutInSec (in sec)	5	Timeout for discovering devices.
application.devicesDiscoverPeriodSeconds (in sec)	30	Period of time when the connector will try to discover BACnet devices.
application.devicesRescanObjectsPeriodSeconds (in sec)	60	The period of time when the connector will try to reread device objects that it failed to read last time.

Example of the application configuration:

{
  "application": {
    "objectName": "TB_gateway",
    "host": "192.168.1.168",
    "port": 47808,
    "objectIdentifier": 599,
    "vendorIdentifier": 15,
    "maxApduLengthAccepted": 1476,
    "segmentationSupported": "segmentedBoth",
    "networkNumber": 3,
    "deviceDiscoveryTimeoutInSec": 5
  }
}

Devices

The device list contains an array of BACnet devices that can be connected to the connector and interact with them. Any BACnet device not included in this array will be rejected by the connector.

Parameter	Description
devices[].host	The host of the device.
devices[].port	The port of the device.
devices[].mask	The mask of the device.
devices[].networkMask	The identifier of the device network segment.
devices[].pollPeriod	The period of time when the connector will try to poll the BACnet device.
devices[].altResponsesAddresses[]	Array of alternative addresses for device responses (you can find detail examples here).
devices[].reportStrategy	Report strategy object using for configuring report strategy for device.
devices[].deviceInfo	Device info object using for configuring device name and profile.
devices[].deviceInfo.deviceNameExpressionSource	The source of the device name: constant, expression.
devices[].deviceInfo.deviceNameExpression	The device name (you can find detail examples here).
devices[].deviceInfo.deviceProfileExpressionSource	The source of the device profile: constant, expression.
devices[].deviceInfo.deviceProfileExpression	The device profile name (you can find detail examples here).

Example of the device mapping configuration:

{
  "devices": [
    {
      "deviceInfo": {
        "deviceNameExpression": "BACnet Device ${objectName}",
        "deviceProfileExpression": "default",
        "deviceNameExpressionSource": "expression",
        "deviceProfileExpressionSource": "constant"
      },
      "host": "192.168.2.110",
      "port": "47808",
      "pollPeriod": 10000,
      "attributes": [],
      "timeseries": [],
      "attributeUpdates": [],
      "serverSideRpc": []
    }
  ]
}

Device attributes and time series

Parameter	Description
devices[].attributes[]	This subsection contains parameters of the device data, that will be interpreted as attributes for the device.
devices[].attributes[].key	The name for time series on the platform.
devices[].attributes[].objectType	The object type in the BACnet device.
devices[].attributes[].objectId	The object id in the BACnet device.
devices[].attributes[].propertyId	The property id in the BACnet device.
devices[].attributes[].reportStrategy	Report strategy object using for configuring report strategy for device attribute.
devices[].timeseries[]	This subsection contains parameters of the device data, that will be interpreted as time series for the device.
devices[].timeseries[].key	The name for time series on the platform.
devices[].timeseries[].objectType	The object type in the BACnet device.
devices[].timeseries[].objectId	The object id in the BACnet device.
devices[].timeseries[].propertyId	The property id in the BACnet device.
devices[].timeseries[].reportStrategy	Report strategy object using for configuring report strategy for device time series.

Example of the device attributes and time series configuration:

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

Device attribute updates

Parameter	Default value	Description
devices[].attributeUpdates[]		List of attributes that will be updated on the device.
devices[].attributeUpdates[].key		The name of the shared attribute on platform instance.
devices[].attributeUpdates[].objectType		The object type in the BACnet device.
devices[].attributeUpdates[].objectId		The object id in the BACnet device.
devices[].attributeUpdates[].propertyId		The property id in the BACnet device.
devices[].attributeUpdates[].timeout (in ms)	5000	Timeout in milliseconds for the attribute update request.

Example of the device attribute updates configuration:

{
  "attributeUpdates": [
    {
      "key": "setpoint",
      "objectType": "analogValue",
      "objectId": 3,
      "propertyId": "presentValue",
      "timeout": 5000
    }
  ]
}

Device RPC methods

Parameter	Default value	Description
devices[].serverSideRpc[]		List of RPC methods that will be sent to the device.
devices[].serverSideRpc[].method		RPC method name.
devices[].serverSideRpc[].requestType		“writeProperty” to write data and “readProperty” to read data.
devices[].serverSideRpc[].objectType		The object type in the BACnet device.
devices[].serverSideRpc[].objectId		The object id in the BACnet device.
devices[].serverSideRpc[].propertyId		The property id in the BACnet device.
devices[].serverSideRpc[].priority		Priority of the value to write (optional, should be an integer from 1 to 16).
devices[].serverSideRpc[].timeout (in ms)	5000	Timeout in milliseconds for the RPC method execution.

Example of the device RPC methods configuration:

{
  "serverSideRpc": [
    {
      "method": "set_state",
      "requestType": "writeProperty",
      "objectType": "analogValue",
      "objectId": 3,
      "propertyId": "presentValue",
      "timeout": 5000
    }
  ]
}

Additional information

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.

Troubleshooting

Device discovery issues on Linux with Docker Compose

If you are running Gateway via docker compose on Linux, and you have issues with device discovery, make sure that you have set the correct network mode in the docker compose file. So you should add the following line to tb-gateway service in your docker compose file:

network_mode: "host"
extra_hosts:
    - "host.docker.internal:host-gateway"

Device discovery issues on Windows with Docker Compose

BACnet connector doesn’t support device discovery on Windows OS due to the limitations of the Docker networking stack on Windows. Please use installation from source or other installation methods to run Gateway on Windows OS.

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.