BACnet Discovery

BACnet discovery provides the ability to automatically scan the network, identify what devices are running, automatically create and register device profiles for those devices, and finally, automatically onboard the devices to the Edge Xpert platform.

This automatic discovery process greatly reduces the effort in creating the device profiles and allows BACnet devices to be onboarded quickly and easily.

Discovery Properties

There are specific environment variables that can be used to control how the devices are discovered and onboarded to the platform. Find these listed under BACnet Environment Variables.

The name, description, and labels variables can be static values or can contain properties that are set during the discovery process. The discovered values are noted with the double braces notation. For example:

XRTCONTROL_DISCOVERY_DEVICEDESCRIPTION: 'MyDescription'

XRTCONTROL_DISCOVERY_DEVICEDESCRIPTION: '{{ModelName}}, DeviceInstance {{DeviceInstance}}'

Properties that can be used in the variables, including sample values, are listed below:

  "ApplicationSoftware":"2.0",
  "Contactable":true,
  "DeviceType":"BACnet-IP",
  "DeviceInstance":1234
  "Firmware":"1.0.2",
  "IP":"172.17.0.2",
  "InstanceID":1234,
  "ModelName":"IOTech BACnet Simulator",
  "ObjectName":"bacnet-ip-sim",
  "Port":47808,
  "VendorID":1313,
  "VendorName":"IOTech"

Create a local docker-compose file

Create a local docker-compose file to override the default Edge Xpert image and its settings.

This example uses two bacnet-sim simulator instances: the default bacnet-sim, which runs with Device Instance 123; and a second one with Device Instance 200.

The configuration shown below will automatically discover and onboard all BACnet IP devices to the platform. These devices are given names relating to the Vendor Name and Device Instance so they can be easily recognized.

In this example, we only want a specific set of attributes to be turned into device resources in the profile. To do this, we use the BACNET_DISCOVERY_PROPERTIES and BACNET_DISCOVERY_OBJECTS variables. 85 is the enum for the property present value, while 0 and 1 are the analog input and analog output values. This means we will expect to create device resources for only analog input and output present values.

version: '3.7'

services:
  device-bacnet-ip:
    environment:
      BACNET_BBMD_ADDRESS: bacnet-sim
      DEVICE_DISCOVERY_ENABLED: 'true'
      XRTCONTROL_DISCOVERY_IDENTIFIER: 'DeviceInstance'
      XRTCONTROL_DISCOVERY_DEVICENAMETEMPLATE: 'BACnet-IP-{{VendorName}}-{{DeviceInstance}}'
      XRTCONTROL_DISCOVERY_DEVICEADMINSTATE: 'LOCKED'
      XRTCONTROL_DISCOVERY_DEVICELABELS: 'Auto-Discovered,instance-{{InstanceID}},{{DeviceType}},{{VendorName}}'
      XRTCONTROL_DISCOVERY_DEVICEDESCRIPTION: '{{ModelName}}, DeviceInstance {{DeviceInstance}}'
      XRTCONTROL_DISCOVERY_PROFILENAMETEMPLATE: 'BACnet-IP-{{ModelName}}'
      XRTCONTROL_DISCOVERY_PROFILELABELS: 'Auto-Discovered,{{DeviceType}},{{VendorName}}'
      XRTCONTROL_DISCOVERY_PROFILEDESCRIPTION: '{{DeviceType}} profile for {{ModelName}}'
      BACNET_DISCOVERY_PROPERTIES: '[85]'
      BACNET_DISCOVERY_OBJECTS: '[0,1]'

  bacnet-sim2:
    image: iotechsys/bacnet-sim:2.0
    command: "--script /example-scripts/device-service-example.lua --instance 200 --name SimpleServer"
    networks:
      - edgex-network
    restart: always
    environment:
      RUN_MODE: "IP"

Deploy Edge Xpert with the BACnet Device Service and simulators

Use the following command to deploy the required services and two BACnet simulators:

edgexpert up xpert-manager device-bacnet-ip bacnet-sim bacnet-sim2

Query the discovered devices

The BACnet device service will trigger discovery when the service starts up and the two devices should be discovered. The default is that the discovery process runs every 30 seconds.

This can be controlled, as below:

DEVICE_DISCOVERY_ENABLED: 'true'

DEVICE_DISCOVERY_INTERVAL: '1h'

You can use seconds (s), minutes (m), hours (h), and so forth.

The discovery and onboarding of the devices can be easily verified by using the Edge Xpert Manager UI at http://localhost:9090:

You can inspect the detail of the devices, including their discovered BACnet properties. Click on the expanding icon and select “View Detail”.

Alternatively, you can use the REST API in the command line as follows:

curl localhost:59882/api/v2/device/all

The above configuration specifies that discovered devices are onboarded with their admin state locked by default. This allows you to confirm that expected devices have been found. When locked the devices cannot send data into the platform. Once unlocked, (by clicking on the lock icon in the UI or by using the REST API) the devices will issue operations as normal. Select the Control button on a device to make requests.

Inspect the device properties

The properties or operations (device resources) are also controlled by the discovery process and are listed as Device Profiles. Since the two devices are of the same type, only one profile is listed. Both devices will refer to this profile.

Note that with the above configuration, a specific reduced set of properties will be created in the device profiles.

The screenshot shows that only the present-values for the analog input and analog output objects are discovered with this configuration. The user has complete flexibility to list the specific properties or objects they would like to be discovered.

BACNET_DISCOVERY_PROPERTIES: '[85]'
BACNET_DISCOVERY_OBJECTS: '[0,1]'

Note also that the user does not have to automatically onboard the devices that are discovered. If desired, the BACnet discovery process can just be used to automatically create the device profiles, i.e., they are able to download the created device profiles then manually onboard devices as normal either using the Edge Xpert Manager UI Device Management capability or by using the REST APIs.

Observe the default provision watcher

Since we set up the XRTCONTROL_DISCOVERY_IDENTIFIER: 'DeviceInstance', the device service will create a default provision watcher which can filter devices and provide the default admin state or labels for the device:

curl http://localhost:59881/api/v2/provisionwatcher/all | json_pp
...
{
   "apiVersion" : "v2",
   "provisionWatchers" : [
      {
         "adminState" : "LOCKED",
         "created" : 1657629431288,
         "deviceDescription" : "{{ModelName}}, DeviceInstance {{DeviceInstance}}",
         "deviceLabels" : [
            "Auto-Discovered",
            "instance-{{InstanceID}}",
            "{{DeviceType}}",
            "{{VendorName}}"
         ],
         "deviceNameTemplate" : "BACnet-IP-{{ModelName}}",
         "id" : "2dae612c-677f-4d3b-8a3f-e4efe72efd8d",
         "identifiers" : {
            "DeviceInstance" : "."
         },
         "modified" : 1657629431288,
         "name" : "device-bacnet-ip-provisionWatcher",
         "profileDescription" : "{{DeviceType}} profile for {{ModelName}}",
         "profileLabels" : [
            "Auto-Discovered",
            "{{DeviceType}}",
            "{{VendorName}}"
         ],
         "profileName" : "",
         "profileNameTemplate" : "BACnet-IP-{{ModelName}}",
         "protocolName" : "bacnet-ip",
         "serviceName" : "device-bacnet-ip"
      }
   ],
   "statusCode" : 200,
   "totalCount" : 1
}

Create your own provision watchers

To provide more control of the discovery process, users can disable the default provision watcher for the BACnet device service and create their own provision watchers with specific filters and settings.

Disable the default provision watcher by commenting out the environment variable:

services:
  device-bacnet-ip:
    environment:
      ...
      # XRTCONTROL_DISCOVERY_IDENTIFIER: 'DeviceInstance'

Stop and restart Edge Xpert:

edgexpert clean

The default provision watcher can also be deleted from a running system if necessary:

curl --request DELETE 'http://localhost:59881/api/v2/provisionwatcher/name/device-bacnet-ip-provisionWatcher'

Create provision watchers with specific identifiers

We can use the identifier to filter the devices and assign the different labels to specific devices.

It is not currently possible to edit provision watchers using the Edge Xpert Manager UI. For now these can be controlled via the REST APIs.

In the below example, we create two different provision watchers. One relating to BACnet Device Instances 0-199, and another for BACnet Device Instances 200-399. We are able to assign different adminStates, labels, and descriptions as below:

• "^[01]?[0-9][0-9]?$" match 0~199, see the regular expression online example.

  curl --request POST 'http://localhost:59881/api/v2/provisionwatcher' \
  --header 'Content-Type: application/json' \
  --data-raw '[
     {
        "provisionwatcher":{
           "apiVersion":"v2",
           "name":"Provision-Watcher-0-199",
           "description":"Filter 0~199",
           "adminState":"UNLOCKED",
           "identifiers":{
              "DeviceInstance":"^[01]?[0-9][0-9]?$"
           },
           "serviceName":"device-bacnet-ip",
           "protocolName":"bacnet-ip",
           "deviceLabels":[
              "Group-A", "BACnet-IP", "0-199"
           ],
           "deviceDescription":"Group-A, DeviceInstance {{DeviceInstance}}"
        },
        "apiVersion":"v2"
     }
  ]'
  

• "^[23]?[0-9][0-9]?$" match 200~399, see the regular expression online example

  curl --request POST 'http://localhost:59881/api/v2/provisionwatcher' \
  --header 'Content-Type: application/json' \
  --data-raw '[
     {
        "provisionwatcher":{
           "apiVersion":"v2",
           "name":"Provision-Watcher-200-399",
           "description":"Filter 200~399",
           "adminState":"UNLOCKED",
           "deviceLabels":[
              "Group-B", "BACnet-IP", "200~399"
           ],
           "identifiers":{
              "DeviceInstance":"^[23]?[0-9][0-9]?$"
           },
           "serviceName":"device-bacnet-ip",
           "protocolName":"bacnet-ip",
           "deviceDescription":"Group-B, DeviceInstance {{DeviceInstance}}"
        },
        "apiVersion":"v2"
     }
  ]'
  

Below we can see that the different descriptions, labels, and adminStates are applied:

Likewise, you could use other properties as the selector for the different provision watchers. For example, you could specify that devices from a specific manufacturer should be onboarded in a certain way:

curl --request POST 'http://localhost:59881/api/v2/provisionwatcher' \
--header 'Content-Type: application/json' \
--data-raw '[
   {
      "provisionwatcher":{
         "apiVersion":"v2",
         "name":"Provision-Watcher-IOTech",
         "description":"IOTech provision watcher",
         "adminState":"UNLOCKED",
         "identifiers":{
            "VendorName":"IOTech"
         },
         "serviceName":"device-bacnet-ip",
         "protocolName":"bacnet-ip",
         "deviceDescription":"Manufactured by IOTech"
      },
      "apiVersion":"v2"
   }
]'

The resulting description is specific to the manufacturer of the discovered devices:

Query devices or device profiles by labels

To retrieve a subset of the devices based on their properties, you can query the devices or device profiles by the labels parameter:

curl http://localhost:59881/api/v2/device/all?labels=BACnet-IP
curl http://localhost:59881/api/v2/device/all?labels=Group-A
curl http://localhost:59881/api/v2/deviceprofile/all?labels=BACnet-IP

Control the Auto Discovery Duration

You can use XRTCONTROL_DISCOVERY_DURATION to control the time to wait for a response from the broadcast. In the following case, the device service sends a broadcast and waits 3000 ms to receive the response, and adds it as the discovered device.

[xrt:1658194751809737:console:Debug] bacnet_discovery_call: Broadcasting global who-is
[xrt:1658194751810679:console:Debug] bacnet_discovery_call: Waiting 3000 ms for i-am responses
[xrt:1658194751811290:console:Debug] bacnet_i_am_handler: Received I-Am Request from device_id 111
[xrt:1658194751811399:console:Debug] bacnet_i_am_handler: Added device 111 to the discovered devices map
[xrt:1658194751811502:console:Debug] bacnet_i_am_handler: Received I-Am Request from device_id 120
[xrt:1658194751811651:console:Debug] bacnet_i_am_handler: Added device 120 to the discovered devices map
[xrt:1658194751811722:console:Debug] bacnet_i_am_handler: Received I-Am Request from device_id 108
[xrt:1658194751811832:console:Debug] bacnet_i_am_handler: Added device 108 to the discovered devices map
[xrt:1658194751812116:console:Debug] bacnet_i_am_handler: Received I-Am Request from device_id 103
[xrt:1658194751812185:console:Debug] bacnet_i_am_handler: Added device 103 to the discovered devices map
...