Generate BACnet Discovery Reports
Introduction
See the Reports section of the API documentation.
- 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 fine-tuned 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-addresseswith 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}/uploadsThe 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-deviceswith 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-deviceswith 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}/uploadsThe 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"
},