Reading BACnet Data with ControlCom Edge Server

A BACnet client connects the Edge Server to a BACnet controller over BACnet/IP (Ethernet) or BACnet MS/TP (RS-485 serial) and reads object properties into platform variables. You configure it from the platform in the device's SDK Configuration editor; the Edge Server picks the configuration up on its next restart.

Prerequisites

The Edge Server must already be onboarded as a ControlCom Gateway. The Edge Server getting started guide covers deployment and onboarding.

Each object you read needs a variable on the gateway to receive it. Create those first (see Creating a Variable); you select each variable by its Topic Property Path when you add an object below. The object editor also has a Create New Variable button if you prefer to create them as you go.

Creating a BACnet Client

1. Open Devices under System in the sidebar and select the onboarded gateway.
2. Open the Edge Server tab. The SDK Configuration editor opens on its Clients tab.
3. Click Add Client and choose BACnet IP or BACnet MSTP in the Add New Client dialog. This guide uses BACnet IP.

The new client opens in a side panel and also appears as a card on the Clients tab; click the card to reopen it later. New clients start disabled.

BACnet MS/TP talks to the controller over a serial port, so the Edge Server container needs a volume mount for that serial device. This guide does not cover that setup.

The client panel has three tabs: Connection, Settings and Objects.

Connection

Enter a Client Name, then fill in the transport-specific fields.

For BACnet IP, enter the Device Address (the IP address of the controller, such as 192.168.1.100) and the Port (defaults to 47808, the BACnet/IP standard). Routed network and Routed MAC (hex) are only needed when the controller sits behind a BACnet router.

For BACnet MSTP, enter the Serial Port path (such as /dev/ttyUSB0) and the Baud Rate (defaults to 9600). MAC Address is the address the Edge Server claims on the MS/TP bus (0 to 127), and Target MAC Address is the controller's address on the bus; set it explicitly, because leaving it empty falls back to the Edge Server's own MAC Address, which only works when the two happen to match. Max Master (defaults to 127), Max Info Frames (1), Data Bits (8), Stop Bits (1) and Parity (none, even or odd) can usually stay at their defaults.

The remaining fields apply to both transports:

1. Enter the Device Instance, the BACnet device instance ID of the controller.
2. Set the Poll Interval (ms), how often each object is read. Defaults to 1000.
3. Set the Timeout (seconds), how long to wait for a response before the request is treated as failed. Defaults to 15.
4. Turn on Enabled.

Settings

The Settings tab holds maintenance actions: Remove Client deletes the client from this configuration, Export Variables downloads the object list as a CSV for bulk editing, and Import Client Variables loads an object list from a CSV.

Objects

An object is one BACnet property read from the controller. Click Add Object, then select the new entry in the list on the left. Sort by Instance Number keeps the list in order.

On the General tab:

1. Select the Object Type: AnalogInput, AnalogOutput, AnalogValue, BinaryInput, BinaryOutput, BinaryValue, MultiStateInput, MultiStateOutput or MultiStateValue.
2. Enter the Instance Number of the object on the controller (0 to 4194302).
3. Enter the Property Identifier. It defaults to 85, Present Value, which is what you want in nearly every case. Other common identifiers are 77 (Object Name), 28 (Description), 36 (Event State), 103 (Reliability) and 111 (Status Flags).
4. Optionally enter a Write Priority (1 to 16) used when the platform writes to this object. BACnet keeps a priority array where lower numbers win: 1 is Manual Life Safety, 2 Automatic Life Safety, 5 Critical Equipment, 8 Manual Operator and 16 the lowest priority. When left empty, writes use 16.
5. Select the Topic Property Path, which is the variable that receives the value. The object's data type (number, boolean or string) follows the selected variable.
6. Optionally select a Write Variable to let the platform write to this object when a matching command is sent. The default is No Write Allowed.

On the Scaling tab (number objects only), Scale (defaults to 1) multiplies the raw value, Offset (defaults to 0) is added after scaling, and Decimals (defaults to 2) rounds the result.

On the Misc tab, Send if Stale After Milliseconds forces a publish when the value has not changed in that time (defaults to 600000, ten minutes), and Deadband Percentage (defaults to 5, number objects only) suppresses changes smaller than that share of the previous value.

On the Transforms tab you can add Value Transforms that rewrite the value before it is published.

Saving

Click Save Configuration in the editor header, then confirm with Save Configuration in the Save SDK configuration? dialog. The configuration is stored on the platform; the gateway applies it on its next restart.

Deployment

The Edge Server reads its configuration when it starts, so a restart is what puts the new client into service. There are two ways to trigger one.

From the platform, open the gateway's Details tab and click Restart in the Send command panel. The Edge Server restarts and reconnects with the new configuration. Edge Server Management describes the full set of SDK commands.

On the gateway itself, restart the container as described in the Edge Server getting started guide.