Generate BACnet Discovery Reports

See the Reports section of the API documentation.

There are two types of reports that can be generated by the BACnet discovery:
  • bacnet-addresses
  • bacnet-devices

The first type discovers address details and related info for the BACnet IP or MSTP (IP connected) physical devices on the network the edge cluster is on. The report can be finetuned by specifying certain input parameters.

The second type discovers data point instances and their parameters (values, properties, etc) related to BACnet device specified in the request body. The request body must match one obtained in stage (1). The report can be fine-tuned by specifying certain input parameters.

Discovery Type: bacnet-addresses

The following API request is used to request the “bacnet-addresses” report generation:

POST /reports/discovery/bacnet-addresses

with request body (fill in the correct values)

{
  "bacnet-addresses": {
    "input": {
      "bacnet": {
        "bacnet_discovery": {
          "bacnet_mac_adress": "<hexidecial like 0A:26:00:4B:BA:C0",
          "bacnet_destination_address": "<hexidecimal like 0A:26:00:4B:BA:C0",
          "bacnet_destination_network": <>,
          "bacnet_discovery_ID": <>,
          "bacnet_maximum_ID": <>,
          "bacnet_minimin_ID": <>,
          "timestamp": <>
        },
        "bacnet_environment": {
          "BACNET_IFACE": "eth0"
        }
      }
    }
  }
}

Here, the bacnet_discovery object uses the same parameters as the bacwi utility. See the bacnet documentation for more information.

The bacnet_environment object uses the same environment variables as used by the bacnet-stack, in particular interface (eth0 in this example).

The bacnet-addresses discovery request input can be simplified to blank JSON object (i.e., {}). In this case bacnet will use device eth0.

The whole request body can be as simple as this, using default parameters:

{
  "bacnet-addresses": {
    "input": {
    }
  }
}

The API response will include an “href” parameter that can be used to retrieve report details. It is structured as follows:

/reports/discovery/{discovery_type}/{report_id}

The report details returned include the status of the report.

Once the report has been completed details of the uploaded reports (by the BACnet driver to the core driver service) can be retrieved using the following API call:
GET /reports/discovery/{discovery_type}/{report_id}/uploads
The returned uploadId values can be used to retrieve the reports by using the following API call:
GET /reports/discovery/{discovery_type}/{report_id}/uploads/{upload_id}
An example response (truncated) is as follows:
{
  "devices": {
    "999": {
      "device-identifier": 999,
      "ipaddress": "0A:26:00:E9:BA:C0",
      "max-apdu-length-accepted": 1476,
      "network-number": 0,
      "saddress": "",
      "segmentation-supported": false,
      "updated": "1621927158",
      "vendor-identifier": 36,
      "vendor-name": "Tridium Inc."
    },
    "36000": {
      "device-identifier": 36000,
      "ipaddress": "0A:26:00:24:BA:C0",
      "max-apdu-length-accepted": 1476,
      "network-number": 0,
      "saddress": "",
      "segmentation-supported": true,
      "updated": "1621927158",
      "vendor-identifier": 556,
      "vendor-name": "Obvius"
    },

Discovery type: Data point instances for device

The following API request is used to request the “bacnet-devices” report generation:
POST /reports/discovery/bacnet-devices
with request body (fill in the correct values, include an object for each device a report is needed for):
{
  "bacnet-devices": {
    "input": {
      "devices": {
        "999": {
          < address section as returned by bacnet-addresses request >
        },
        "bacnet_environment": {
          "BACNET_IFACE": "eth0"
        },
        "bacnet_requested_properties": {},
        "timestamp": "%Z %F %T"
      }
    }
  }
}

Here, the <address section> for the requested device must be the complete address as returned by the bacnet-addresses discovery report. Include all the devices a discovery report is needed for.

The bacnet_requested_properties input is blank in this example but can contain properties requested for discovery for each data point type, as follows:
{
  "bacnet_requested_properties": {
    "device": [
      "object-name",
      "object-type",
      "description",
      "model-name",
      "system-status",
      "firmware-revision",
      "application-software-version",
      "vendor-name",
      "object-identifier"
    ],
    "analog-input": [
      "units",
      "present-value",
      "object-name",
      "object-type",
      "description",
      "COV-increment",
      "object-identifier"
    ],
    "analog-output": [
      "units",
      "present-value",
      "object-name",
      "object-type",
      "description",
      "COV-increment",
      "object-identifier",
      "priority-array",
      "relinquish-default"
    ],
    "analog-value": [
      "units",
      "object-name",
      "object-type",
      "description",
      "COV-increment",
      "object-identifier"
    ],
    "binary-output": [
      "present-value",
      "object-name",
      "object-type",
      "description",
      "object-identifier",
      "priority-array",
      "relinquish-default"
    ],
    "multi-state-output": [
      "present-value",
      "object-name",
      "object-type",
      "description",
      "object-identifier",
      "priority-array",
      "relinquish-default"
    ]
  }
}

This allows fine-tuning properties requested for discovery.

The bacnet_environment, bacnet_requested_properties and timestamp input parameters can all be omitted, in which case default values will be used (such as eth0).

Using the bacnet-addresses example response from the previous section, a simple example for the bacnet_devices discovery request for device “999” only will look like the following. API endpoint:
POST /reports/discovery/bacnet-devices
with request body:
{
  "bacnet-devices": {
    "input": {
      "devices": {
        "999": {
          "device-identifier": 999,
          "ipaddress": "0A:26:00:E9:BA:C0",
          "max-apdu-length-accepted": 1476,
          "network-number": 0,
          "saddress": "",
          "segmentation-supported": false,
          "updated": "1621927158",
          "vendor-identifier": 36,
          "vendor-name": "Tridium Inc."
        }
      }
    }
  }
}
The API response will include an href parameter that can be used to retrieve report details. It is structured as follows:
/reports/discovery/{discovery_type}/{report_id}

The report details returned include the status of the report.

Once the report has been completed details of the uploaded reports (by the BACnet driver to the core driver service) can be retrieved using the following API call:
GET /reports/discovery/{discovery_type}/{report_id}/uploads
The returned uploadId values can be used to retrieve the reports bu using the following API call:
GET /reports/discovery/{discovery_type}/{report_id}/uploads/{upload_id}
An example response (truncated) is as follows:
{
  "999": {
    "address": {
      "device-identifier": 999,
      "ipaddress": "0A:26:00:E9:BA:C0",
      "max-apdu-length-accepted": 1476,
      "network-number": 0,
      "saddress": "",
      "segmentation-supported": false,
      "updated": "1621927158",
      "vendor-identifier": 36,
      "vendor-name": "Tridium Inc."
    },
    "application-software-version": "Tridium 3.8.38.9",
    "description": "Local BACnet Device object",
    "firmware-revision": "3.8.38.6",
    "max-info-frames": "1",
    "max-master": "127",
    "model-name": "NiagaraAX Station",
    "multiread": true,
    "object-name": "CandiDemo_999",
    "object-type": "device",
    "objects": {
      "999:0:0": {
        "cov-increment": "1.000000",
        "description": "Box Flow",
        "object-identifier": "(analog-input, 0)",
        "object-name": "VAV.BoxFlow",
        "object-type": "analog-input",
        "present-value": "1198.108887",
        "rawtime_us": 1621928308682669,
        "units": "cubic-feet-per-minute",
        "updated": "1621928308"
      },
      "999:0:1": {
        "cov-increment": "1.000000",
        "description": "",
        "object-identifier": "(analog-input, 1)",
        "object-name": "Dummy Points.NumericInput",
        "object-type": "analog-input",
        "present-value": "0.000000",
        "rawtime_us": 1621928308687010,
        "units": "no-units",
        "updated": "1621928308"
      },