Skip to main content
Version: TAO v2.x

BACnet flow

As of TAO version 2.1.0, a BACnet flow is provided in Node-RED. It allows LoRaWAN sensors to automatically expose data within a built-in BACnet server. This server is by default available on the standard UDP multicast port 47808 (BAC0), but you may change the port as described in BACnet server configuration.

It supports three BACnet object types:

  • Analog Value (noted 'AV') for numeric data
  • Binary Value (noted 'BV') for boolean data
  • Character String Value (noted 'SV') for string data.

The flow requires that all uplinks are published to the internal MQTT topic /uplink-topic. This is the default setup with the 'UPLINK / DOWNLINK' flow provided during the installation.

Loading the BACnet flow​

From the Node-RED flow editor:

  1. Click at the top right corner, then select Import.

  2. Select Actility library -> flows -> BACnet.json.

  3. Click the Import button.

  4. On the incoming warning message, click View nodes....

  5. On the "Import nodes" window, ensure that "BACnet" is checked, then click Import selected.

    -> a new "BACnet" tab has been added in the editor:

  6. Click at the top right to deploy the new flow. To learn more, see Node-RED deploy.

Automatic mapping process​

The mapping of LoRaWAN sensor data into BACnet objects is fully automated, without any manual action from the user, except if custom adaptations are required as explained in Customization.

The following steps are automatically triggered by the built-in BACnet flow:

  • Receive uplink packets from the LoRaWAN sensors and decode the hexadecimal payload with the adequate driver.
  • Process decoded payloads and convert each selected property into a single BACnet object.
  • Expose BACnet objects to an embedded BACnet server.

The flow follows these steps:

The incoming uplink messages are extracted from the /uplink-topic of the internal MQTT server (MQTT input node). All messages are injected in the bacnet-adapter node that parses the uplink frame reports (DevEUI_uplink); then, based on its object mapping configuration, execute the following tasks:

  1. Optionally extract the uplink packet's metadata: RSSI, SNR, FCntUp, SpFact (the spreading factor)
  2. Extract all properties from the payload field (standard decoded payload)
  3. Optionally extracts all properties from the points field (for drivers that support 'ontology'), including the unit of each property.

Then, for each extracted property, the bacnet-adapter node automatically formats a BACnet object and injects it into the embedded BACnet server.

DevEUI_uplink: {
   Time: "2024-09-24T13:51:10.920+00:00"
   DevEUI: "20635F0106000244"
   FPort: 17
   ...
   LrrRSSI: -30.600006
   ...
   payload: {
      messageType: "HEARTBEAT"
      trackingMode: "PERMANENT_TRACKING"
      batteryVoltage: 4.05
      ...
   }
   points: {
      temperature: {
         unitId: "Cel"
         record: 28.3
      },
      batteryVoltage: {
         unitId: "V"
         record: 4.05
      }
   },
   Frequency : 867.7
   DynamicClass: "A"
}
note

When 2 properties have the same name, the value coming from the higher stage overwrites the previous value. In the example above, the 'batteryVoltage' property exists both in the 'payload' and 'points' sections, the 'batteryVoltage' extracted from the points section will be exposed since it has richer information thanks to the ontology feature.

When a new uplink is received and it contains decoded properties, a new BACnet object is automatically created or updated for each of these properties.

  • The first uplink packet that contains a 'numeric' value on its first property will be exposed as a new object with type Analog Value (AV) and instance number 0.
  • The next property containing a 'numeric' value will be assigned the instance number 1, and so on.
  • A similar process applies to 'boolean' values, which are mapped to a BACnet object with type Binary Value (BV), with instance numbers starting at 0.
  • 'String' values follow the same pattern, being assigned to a Character String Value (SV) type of object, also starting with an instance number 0.

You may personalize this default/automatic object mapping in order to fix the instance number of a property. To learn more, see Mapping customization.

Customization​

The bacnet-adapter node has its own configuration, which can be customized by double-clicking on it.

It exposes 2 tabs, one for the BACnet server configuration, and the other one concerns how the object mapping can be modified.

The BACnet server configuration​

From here, you can configure the following BACnet properties:

  • Server port: from 'BAC0' (47808), to 'BACF' (47823).
  • Server broadcast: it is the desired subnet for global messages to be broadcast and received on. This should be as strict as possible. Use 255.255.255.255 if unsure.
  • Device ID: default is 817001.
  • Device Name: default is 'BACnet Adapter'.
  • Vendor ID: default is 0. Use you own Vendor ID if you have one.
  • Vendor Name: default is empty. Use you own Vendor Name if you have one.

The object mapping configuration​

From here, you can configure :

BACnet object name​

Each extracted data from LoRaWAN sensors is exposed as a BACnet object whose object identifier is constructed using the DevEUI (default choice) of the device, followed by colon : then the property name. The property includes the path below payload, points, each part is added using the colon : separator.

You can change the definition of the object identifier to use the sensor's ('Device Name' choice) friendly name (which is the device name set in TAO) rather than the DevEUI.

LoRaWAN metadata​

You may change the configuration to additionally extract the LoRaWAN metadata and expose them as BACnet objects. Metadata is not exposed by default.

The following LoRaWAN fields can be selected:

Ontology​

Ontology processing is supported by specific drivers, which provide uniform standardization of properties so that a specific measure (for instance, temperature) is mapped to a standardized property name (for instance, 'temperature'). An associated unit is provided (for instance, 'celsius') and a transformation is applied to the value to ensure it fits the specified unit.

Example All devices that expose a temperature measurement with drivers supporting ontology will provide the temperature in the same way (same unit, same property name). For more information about device drivers, see Supported drivers/ontologies.

Ontology is deactivated per default, you can activate it using the checkbox.

Mapping customization​

As mentioned above, the LoRaWAN to BACnet mapping is fully automated by default. You may change this default mapping in order to fix the instance number of a property and ensure that this property is always exposed at a fix instance number.

To do so, follow the steps below:

  1. Export you current object list to a csv file.

  2. Modify the instance number association of the csv file, and save it to your custom list. The following recommendations should be respected:

    • Start the instance numbering from 0 for each type (AV,BV,SV).
    • Do not leave holes in the numbering scheme.
    • Do not change the type for a specific property.
    • Create new entries for future devices properties that are not yet exposed.
    • Leave the header line as is, do not add columns.

  3. Import this custom csv file to the server.

    -> Your new mapping will then be available instantaneously.

Export object list​

  1. Click the Export object list button. If you wan to add the current value of each property in you export file, check the option Include object values.

  2. Check the downloaded export-bacnet.csv file: The first line is the header, it must contain "name","type","instance" or "name","type","instance","value","unit".

    Then each line contains:

    • name : the BACnet object name
    • type : the abbreviated object Type:
      • AV for Analog Value
      • BV for Binary Value
      • SV for Character String Value
    • instance : the BACnet instance Id of the object
"name","type","instance"
"20635F0106000244:batteryVoltage","AV",0
"20635F0106000244:ackToken","AV",1
"20635F0106000244:temperatureMeasure","AV",2
...

For a list with values included:

"name","type","instance","value","unit"
"20635F0106000244:batteryVoltage","AV",0,3.74,
"20635F0106000244:ackToken","AV",1,0,
"20635F0106000244:temperatureMeasure","AV",2,36.9,
"20635F0106000244:sosFlag","AV",3,0,
...
Import custom object list​

The import file format is the same as the export file format (value and unit are not taken into account during import).

  1. Click and select the csv file on your computer.

  2. Press 'OK' on the alert message.

  3. Check the import status

    In case of error, you get the list of points to fix, as illustrated by the following example:

Clear object list​

Follow these steps to clear the entire object list:

  1. Click

  2. Press 'OK' on the alert message

  3. Check the status

Visualization​

Once the flow is running, each extracted data from your LoRaWAN sensors is exposed as BACnet object.

You can use a tool like YABE (Yet Another BACnet Explorer) to visualize and interact with the BACnet objects:

Example of an uplink message extracted by TAO, corresponding to a DevEUI_uplink, with temperature measured at 28.8° celsius.

DevEUI_uplink: {
   Time: "2024-09-24T13:51:10.920+00:00"
   DevEUI: "20635F0106000244"
   FPort: 17
   ...
   LrrRSSI: -30.600006
   ...
   payload: {
      messageType: "POSITION_MESSAGE"
      trackingMode: "PERMANENT_TRACKING"
      batteryVoltage: 4.05
      ackToken: 0
      ...
   }
   points: {
      temperature: {
         unitId: "Cel"
         record: 28.8
      },
      batteryVoltage: {
         unitId: "V"
         record: 4.05
      }
   },
   Frequency : 867.7
   DynamicClass: "A"
}

The corresponding visualization in YABE:

This section describes how to use BACnet to send downlink packets.

tip

Sending downlink packets through BACnet is not a straightforward operation, therefore it is much more convenient to directly send downlink message on the MQTT downlink-topic as explained in MQTT usage.

Process description​

Unlike uplink messages, the processing of downlink messages is not automatic, it requires manual adaptations as described in Usage and adaptations.

The process steps are:

  1. A BACnet object representing the property you want to change in your LoRaWAN sensor must exist in the BACnet server. This step is not automated, it must be done by the user.

  2. When the property is changed on the BACnet side, a function is called to processes the message and automatically create a DevEUI_downlink message.

  3. Then, the downlink message shall be sent by TAO to the LoRaWAN sensor

The flow follows these steps:

All outgoing message from the bacnet-adapter node are passed to the 'DownlinkAdapter' function. This function is called whenever a write event occurs on the BACnet server, it filters endpoint calls, and for the ones that need a downlink, it generates a 'DevEUI_downlink' message and sends it to the MQTT downlink queue.

Usage and Adaptations​

Use the 'Create endpoint' to create an endpoint for the downlink. In the sample, we want to turn on the SOS mode of an Abeeway asset tracker whose devEUI is 20635F0106000244:

Our convention for the object identifier is 'devEUI' + colon (':') + property name. We have chosen 'message' as the property name. We create the endpoint with the initial value of 'STOP_SOS'

  • Object identifier: 20635F0106000244:message
  • PresentValue: STOP_SOS

When the 'Create endpoint' button is pressed, the new object is created / updated on the BACnet server.

When the '20635F0106000244:message' present value is changed on the BACnet server (from 'STOP_SOS' to 'START_SOS'), the 'DownlinkAdapter' function is called. This handleMessage(msg) function must be adapted to prepare the downlink message to your sensor. It requires :

  • Javascript development knowledge (basic level).
  • Knowledge of the downlink format specification for each device model.