Create BACnet Thing Description

Introduction

See Things documentation on how to manage Things in Altair IoT Studio.

A Thing for this device driver uses a schema as described on this page.

Once it exists in Studio it can be synced to the Cluster (Asset) as shown on the Sync Things page.

The following is an example of a Thing description to be instantiated by the BACnet driver:

{
    "@type": [
      "BACnet", 
      "Meter", 
      "bacnet,777,AC:11:00:02:BA:C0,0,00,1476,eth0,true,260"
    ],
    "id": "<leave blank when creating a thing>",
    "title": "BACnetMeter",
    "description": "My BACnet Meter",
    "properties": {
        "analog-input,7,present-value": {
            "title": "inputType 0 inputIndex 7",
            "description": "Return Temperature",
            "type": "number",
            "@type": "TemperatureProperty",
            "unit": "Celsius",
            "maximum": 200,
            "readOnly": true
        }
    }
}
There are two important items to note here:
  • the "bacnet,777,..." string in the "@type" array
  • the "analog-input,7,present-value" property key

The first item is essential for the BACnet driver to recognise this Thing description as a BACnet device. Details on how to construct this string can be found in the next section.

The second item is essential for the BACnet driver to recognise the object it needs to manage. Details on how to construct property keys and the rest of the property object can be found in a subsequent section.

Construct the "bacnet,.." "@type"

The following element in the "@type"` array is required to specify bacnet device. It is comma-separated string of parameters.

"bacnet,777,AC:11:00:02:BA:C0,0,00,1476,eth0,true,260"

It is entirely taken from bacnet address discovery report (also found in the bacnet devices report as the "address" section). These also can be seen with bacnet-stack bacwi utility. Example below:

"777": {
  "device-identifier": 777,
  "ipaddress": "AC:11:00:02:BA:C0",
  "max-apdu-length-accepted": 1476,
  "network-number": 0,
  "saddress": "",
  "segmentation-supported": true,
  "updated": "1587667968",
  "vendor-identifier": 260
}
keyword bacnet
This is to indicate that device is bacnet device. Mandatory.
device-identifier
Bacnet device instance number (integer value). Mandatory. If no other parameters present driver uses "who is" broadcast call to discover the rest of the parameters, such as IP etc.
Device IP
Device IP and port in hex notation, such as AC:11:00:02:BA:C0 (ip 172.17.0.2) and port number (0xBAC0 == 47808). Optional.
Network number
Bacnet sub-network number. 0 in this example. Optional.
Bacnet saddress
00 in this example. Optional.
max-apdu-length-accepted
In bytes. Optional.
Interface
Used by bacnet driver. eth0 in this example, typical would be eth0. Optional.
Segmentation supported
True or false. Optional.
Bacnet vendor ID
Optional

In this particular example, the minimum requirement would be:

bacnet,777

In this case the driver will issue broadcast request "who is" and find the BACnet IP on its own.

If the BACnet IP is already known, it can be included as follows:

bacnet,777,AC:11:00:02:BA:C0

In this case the driver will use IP without issuing broadcast request to find it first. It means that bacnet device may not be on the local network at all.

Construct a Property

The data instances to report are specified as keys in "properties" section. Example below:

"analog-input,5,present-value": {
    "title": "inputType 0 inputIndex 7",
    "description": "COV",
    "type": "number",
    "@type": "cov",
    "maximum": 200,
    "readOnly": true
}

The corresponding section of device discovery report is the following:

"objects": {
    "777:0:5": {
        "COV-increment": "1.000000",
        "description": "ANALOG INPUT 5",
        "object-identifier": "(analog-input, 0)",
        "object-name": "ANALOG INPUT 5",
        "object-type": "analog-input",
        "present-value": "0.000000",
        "rawtime_us": 1587669499279057,
        "units": "percent",
        "updated": "PDT 2020-04-23 12:18:19.279"
    },
Here is only key, which is comma-separated list, is used. In this example analog-input,5,present-value. Note that it uses textual names for data types and properties, the same as in the discovery report. These are defined in bacnet-stack library:
Data type
Could be "analog-input", "analog-value", "binary-input" etc. Mandatory.
Bacnet instance ID
This is integer value taken from bacnet device discovery report. Mandatory.
Property to report
"Present-value" in this case. At least one property is mandatory.
Property to report
Second (third, etc) property to report. Optional. For instance string could look like "analog-input,5,present-value,units"
Note: If only one property to report is specified then the telemetry will return just the value of that property. If multiple properties to report are specified then the telemetry will consist of an object with the properties as the keys and the return values as the object values.