Skip to main content
Version: TAO v2.x

BACnet flow example

As of TAO version 2.1.0, a sample BACnet flow is provided in Node-Red. It allows LoRaWAN sensors to automatically expose data inside an built-in BACnet server. This server is available on the standard UDP multicast port 47808.

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

Loading the bacnet-sample flow​

From the Node-RED flow editor:

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

  2. Select Actility library -> flows -> bacnet-sample.js.

  3. Click the Import button.

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

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

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

  6. 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 sample:

  • 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 sample 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 'UplinkAdapter' function that parses the uplink frame reports (DevEUI_uplink), then extracts:

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

Then, for each extracted property, the 'UplinkAdapter' function automatically formats a BACnet object and injects it into the embedded BACnet server (Bitpool BACnet gateway node).

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 phase overwrites the previous value. In the example above, the property batteryVoltage 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.

For more information about device drivers, see Supported drivers/ontologies.

Customization​

Gateway node​

The BACnet node has its own configuration, which may be customized by clicking the gateway node on the sample flow.

note

Any configuration change to the Gateway node currently requires a Node-Red restart or a reboot of the TAO server.

note

TAO authorized ports are UDP 47808 (BAC0) to 47823 (BACF).

Extraction function​

You may change the UplinkAdapter function to only extract the properties you are interested in. The default function currently extracts:

  • RSSI
  • SNR
  • ESP
  • FCntUp
  • SpFact
  • All properties from the payload field
  • All properties from the points field

BACnet object identifier​

Each extracted data from LoRaWAN sensors is exposed as a BACnet object whose object identifier is constructed using the DevEUI 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 friendly name (which is the device name set in TAO) rather than the DevEUI. To do this, run the following steps:

  1. Open the BACnet configuration node:

  2. Select the On Start tab:

  3. Comment flow.set('BACNET_OBJECT_NAME', 'DEVEUI_BASED');

  4. Uncomment flow.set('BACNET_OBJECT_NAME', 'DEVICE_NAME_BASED');

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: 3.23
      ackToken: 0
      ...
   }
   points: {
      temperature: {
         unitId: "Cel"
         record: 28.8
      },
      batteryVoltage: {
         unitId: "V"
         record: 3.23
      }
   },
   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 sample follows these steps:

All outgoing message from the BACnet gateway are passed to the 'DownlinkAdapter' function. This function is called whenever a write event occurs on the BACnet serve, 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​

note

Any configuration change to the Gateway node currently requires a Node-Red restart or a reboot of the TAO server.

Use the 'Create downlink 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 downlink 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.