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
        }
    }
}

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"
    },