BACnet

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.

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:

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

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.

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

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 in the usage examples section);
• 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 in the usage examples section);
• 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 in the usage examples section).
• 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).

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:

1. Click “pencil” icon of the “Attributes” section to add new attribute key;

   

2. Click “Add attribute” in the opened window;

   

3. Enter the key name, select “Object ID” and “Property ID” from the dropdown list. Click “Apply”;

   

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

   

5. Click “Add time series” in the opened window;

   

6. Enter the key name, select “Object ID” and “Property ID” from the dropdown list. Click “Apply”.

   

You can set up filtering for time series and attributes based on Object Type, Object ID and Property ID. This allows you to specify which data should be collected and sent to the platform. Let’s review each filtering option:

Object Type Filtering

This filter allows you to specify the type of BACnet objects from which data should be collected. For example, you can choose to collect data only from “Analog Input” or “Binary Output” object types or both:

• "objectType": "*" - will collect data from all supported object types;
• "objectType": "analogValue" - will collect data only from Analog Value objects;
• "objectType": ["analogValue", "binaryInput"] - will collect data from both “Analog Value” and “Binary Input” objects.

Object ID Filtering

This filter allows you to specify particular Object IDs for data collection. You can define a single Object ID or a list of Object IDs:

• "objectId": 1234 - will collect data only from the object with ID 1234;
• "objectId": "*" - will collect data from all Object IDs;
• "objectId": "0-10" - will collect data from Object IDs in the range 0 to 10 (inclusive);
• "objectId": ["0-10", "12-15"] - will collect data from Object IDs in the ranges 0 to 10 and 12 to 15 (inclusive).

Property ID Filtering

This filter allows you to specify particular Property IDs for data collection. You can define a single Property ID or a list of Property IDs:

• "propertyId": "presentValue" - will read only the “presentValue” property;
• "propertyId": "*" - will read all supported properties;
• "propertyId": ["presentValue", "location"] - will read both “presentValue” and “location” properties.

Example of filtering configuration:

{
  "timeseries": [
    {
      "key": "${objectName} - ${objectType} | ${units}",
      "objectType": "analogInput",
      "objectId": "*",
      "propertyId": ["presentValue", "statusFlags"]
    }
  ]
}

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

• Dynamic device name/profile
• Alternative responses addresses
• Discovering all devices
• Reading all device objects
• Filtering objects and properties

BACnet connector allows you to set dynamic device names and profiles using expressions. This is especially useful when you have multiple devices with similar configurations and want to differentiate them based on their properties. In this example, we will configure a BACnet device to have a dynamic device name based on its objectName and address properties and a dynamic device profile based on its vendorId property.

Here is an example configuration snippet for a BACnet device with dynamic device name and profile:

{
  "application": {
    "objectName": "TB_gateway",
    "host": "YOUR_HOST",
    "port": 47808,
    "mask": 24,
    "objectIdentifier": 599,
    "maxApduLengthAccepted": 1476,
    "segmentationSupported": "segmentedBoth",
    "vendorIdentifier": 15,
    "deviceDiscoveryTimeoutInSec": 5,
    "devicesDiscoverPeriodSeconds": 30
  },
  "devices": [
    {
      "host": "*",
      "port": "*",
      "pollPeriod": 10000,
      "deviceInfo": {
        "deviceNameExpressionSource": "expression",
        "deviceNameExpression": "${objectName} at ${address}",
        "deviceProfileExpressionSource": "expression",
        "deviceProfileExpression": "${vendorId}_profile"
      },
      "attributes": [],
      "timeseries": "*",
      "attributeUpdates": [],
      "serverSideRpc": []
    }
  ]
}

In this configuration:

• The deviceNameExpression is set to ${objectName} at ${address}, which will create a device name that includes the device’s object name and address.
• The deviceProfileExpression is set to ${vendorId}_profile, which will create a device profile name based on the vendor ID of the device.

After applying this configuration, the device will be created with a name and profile that reflect its specific properties. The screenshot below shows how the device appears in ThingsBoard with the dynamic name and profile:

As you can see, the device name is generated based on the objectName and address, and the device profile is based on the vendorId.

Device name/profile dynamic expressions provide flexibility in managing multiple BACnet devices with varying configurations and can help in organizing devices effectively within ThingsBoard.

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.

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:

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

   

2. Click “Add attribute update” in the opened window;

   

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

   

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:

1. Click “pencil” icon of the “RPC methods” section to add new RPC;

   

2. In the opened window click “Add method”;

   

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

   

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

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

   

2. Click on the “Connectors configuration” button on the right side menu.

   

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

   

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

   

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

   

6. 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": []
    }
  ]
}

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:

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

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

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
  }
}

The foreign device configuration parameters are used to configure the gateway as a foreign device in the BACnet network. It is useful when the gateway is behind a NAT and needs to register with a BACnet Broadcast Management Device (BBMD).

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.

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": []
    }
  ]
}

You can use the following parameters for forming device name and profile:

• ${objectName} - the device object name of the BACnet device.
• ${objectId} - the device object identifier of the BACnet device.
• ${vendorId} - the device vendor identifier of the BACnet device.
• ${address} - the device host address.
• ${routerId} - the device router identifier.
• ${routerName} - the device router name.
• ${routerAddress} - the device router address.
• ${routerVendorId} - the device router vendor identifier.

You can find detail examples in the usage examples section.

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

Example of the device attribute updates configuration:

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

Example of the device RPC methods configuration:

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

The BACnet connector support the following BACnet object types:

Property identifiers depend on type of the BACnet object, provided in camelCase, e.g:

• presentValue
• objectName
• objectDescription
• units
• eventState
• outOfService
• priorityArray
• relinquishDefault
• currentCommandPriority
• eventMessageTexts
• eventMessageTextsConfig
• eventAlgorithmInhibitReference
• timeDelayNormal
• weeklySchedule
• listOfObjectPropertyReferences
• location

Add the following lines to the tb-gateway service in your docker-compose.yml:

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

BACnet device discovery is not supported on Windows due to Docker networking limitations. Use a direct installation (not Docker) when running the gateway on Windows.