Create a BACnet Thing Description

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
}

Element	Importance	Description
keyword bacnet	Mandatory	This is to indicate that device is bacnet device.
device-identifier	Mandatory	Bacnet device instance number (integer value). If no other parameters present driver uses “who is” broadcast call to discover the rest of the parameters, such as IP, etc.
Device IP	Optional	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).
Network number	Optional	Bacnet sub-network number. 0 in this example.
Bacnet address	Optional	00 in this example.
max-apdu-length-accepted	Optional	Value in bytes.
Interface	Optional	Used by bacnet driver. `eth0` in this example, typical would be `eth0`.
Segmentation supported	Optional	True or false.
Bacnet vendor ID	Optional

In this particular example , the minimum required 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.

Element	Importance	Description
Data type	Mandatory	Could be “analog-input”, “analog-value”, “binary-input” etc.
Bacnet instance ID	Mandatory	This is integer value taken from bacnet device discovery report.
Property to report	Mandatory	“present-value” in this case. At least one property is mandatory.
Property to report	Optional	Second (third, etc) property to report. 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.