BACnet to Tandem Data Synchronization
Introduction
The solution below describes integration between the BACnet (Building Automation and Control Networks) devices and Autodesk Tandem by reading device property values from BACnet network of devices and sending the data as streams to Tandem.
The scope of this document is to give user a guide to deploy the integration with a basic configuration and also detail other advanced options available.
Features
Below is a short list of features the solution offers when reading or writing to different systems.
| Feature | Description |
|---|---|
| Automatic Device Discovery | The solution provides ways to auto discover devices in a BACnet network by connecting to either a BACnet router or gateway which is configurable. Users can also do a manual lookup of devices by providing additional device details. |
| Read multiple object types | The solution allows users to configure and read different object types and the PRESENT VALUE property of these object types. The Object types can be configured to read a subset or all of them. |
| Create Timeseries Data in Tandem | The solution allows users to read bacnet data and send it to Tandem as timeseries data. |
Pre-requisites
The BACnet to Tandem solution currently only supports deployment to the Tandem Connect outpost. This section provides the prerequisite to deploy the solution to an outpost instance.
For more information on deployment to outpost, please refer to the outpost documentation.
Basic Setup
The solution by default is configured to run in Auto Device Discovery mode reading all Object types of the devices discovered from the BACnet network. The PRESENT_VALUE of each of these object types are then used to create time series data using device as connection name and the object types as the streams. Below is the configuration needed for the basic setup.
| Plugin Type | Parameter Name | Description |
|---|---|---|
| BACnet Stream | Bacnet Router IP Address | The ip address for the bacnet router which the plugin needs to connect to. |
| Autodesk Tandem Connector | Client ID | The api client id to connect to the tandem facility. |
| Autodesk Tandem Connector | Client Secret | The api client secret to connect to the tandem facility. |
| Autodesk Tandem Connector | Tandem Facility | The facility id to which the data must be sent in Tandem. |
Advanced Setup
Solution Overview
The solution also known as a tandem connect pipeline contains different plugins each providing a unique functionality. These plugins are highly configurable but also have out of the box default configurations. Each plugin can be configured to achieve the use cases highlighted above. The below sections explains each of these plugins and its configurations available.
The solution provides prompts for each plugin which represents the mandatory configuration needed. Apart from these the plugins can also be modified to achieve alternate use cases.
Solution Diagram
The diagram below shows how the Tandem Connect pipeline makes a connection to the BACnet gateway / router to discover and read devices and them transform the data to create streams in Tandem.
Pipeline
Plugins
BACnet Stream
The bacnet stream plugin is an ingest plugin which connects to the BACnet router to perform different tasks like discovering devices and its object types, reading PRESENT_VALUE property for each object type and passing it to the next plugin. The plugin is configurable to achieve different use cases as detailed below. Please refer to the HELP tab of the plugin on the platform console to get a detailed documentation on the plugin.
By default, the plugin runs in auto discovery mode and require just the BACnet router's IP Address to be provided. The remaining parameters of the plugin are all optional and have default values. Also by default, the plugin reads all object types for the devices discovered. Below are the alternate use cases and the configuration needed for each.
| Typical Customisation Options | Configuration Needed |
|---|---|
| Reading different subnets | If a user would like to probe a certain subnets only, then the plugin parameter "NETWORKS TO PROBE", can be configured with a comma seperated list of subnet numbers and the plugin will run the auto discovery only on those subnets. |
| Reading a set of Object Types | By default the plugin reads all available object types for the devices discovered. This for some networks be overwhelming as it returns a large set of data. To restrict the plugin to read certain object types, the plugin parameter "OBJECT TYPES TO QUERY" can be configured with a comma seperated list of object types to be read. The complete list of object types supported can be found on the plugin HELP section. |
| Specifying a network interface to connect from | By default the plugin always connect to the primary network interface of the device where the pipeline is deployed. This can be changed by providing the "PRIMARY INTERFACE", "BROADCAST ADDRESS" parameters with values of the interface the user would like to communicate with the BACnet network. |
| Manual Discovery Mode | The plugin can be configured to run in a manual discovery mode where the plugin expects users to provide device configuration under the "DEVICE CONFIGURATION" parameter. The format and the details as to how to provide device configuration is mentioned in detail under the plugin HELP section. |
| Prefix Device Id | The plugin parameter "Device Prefix" can be configured with a string value that will be prefixed to all device ids send to the convertor plugin. |
Convertor Plugin
The convertor is a source code plugin that allows users to write custom javascript code to achieve certain funtionality. As part of the solution, the convertor plugin transforms the data received from the BACnet stream plugin and prepares the data as needed for the Tandem Connector plugin. This code is a simple transformation javascript code. For more advanced users this convertor can be used to do a lot more as needed when sending data to the Tandem system.
Tandem Connector Plugin
The tandem connector plugin is an egress plugin which sends data to the Tandem system and creates streams as needed. The data from the convertor plugin is already prepared to be consumed by the tandem connector plugin. This plugin uses the device id from the convertor plugin to create a stream and the object types being the properties of the stream which represents the time series data. A timestamp is attached along with the values from the bacnet devices to create historical timeseries data for each device. The tandem system can then show heat maps and charts to display the timeseries data.
By default, the plugin will use the device id from the incoming data to create a stream id. The stream id is a generated 20-byte hash using the device id.
| Typical Customisation Options | Configuration Needed |
|---|---|
| Use custom stream Id | The plugin can be configured to use the stream id from the incoming data by providing the field name under the parameter "Stream ID Key/Field". This will enable the plugin to use the value from this field to generate the 20-byte hash. |
| Attach timestamp for stream data | By default, the plugin does not add any timestamp data and if the user wishes to add the plugin offers two options. 1. Attach the timestamp to the timeseries data. 2. Use a field from the incoming data to read timestamp. |
| Create Streams | By default the plugin will not create a stream if it does not exists. The parameter "Create Stream" can be turned on to create stream if it does not exists. |
| Ignore Devices | The plugin parameter "Ignore Device List" can be configured with a comma seperated list of device ids, which will be ignored from creating time series data. |
| Use custom classification | A custom classification can be specified while creating streams using the parameter "Classification". |
Troubleshooting
All errors or exceptions are logged under the outpost logs directory. These can be easily retrieved from the outpost machine and analysed. Please refer to the outpost documentation for more details.
The other alternative is outpost supports logs shipping to an external HTTP end point. The end point can be specified as environment variable while setting up outpost. All these details are available in the documentation for outpost.