Skip to content

BACnet Event Registration Extension Component

The BACnet Event Registration Extension Component can both register and deregister the XRT BACnet device service from all recipient lists of all BACnet devices provisioned in XRT. Once registered, any events that occur on these devices will be communicated to the XRT device service.

For further information on BACnet Events see BACnet Events.

Note

This extension component will only work with the BACnet/IP device service.


Configuring the Component

A json file bacnet_event_registration.json is required to configure this component. The following table describes the fields used within this file.

Field Description Example Usage
Library Shared library component name libxrt-bacnet-event-registration.so
Factory Factory name bacnet_event_registration_factory
DeviceService The name of the BACnet/IP device service as indicated by its name in main.json bacnet_ip
Timeout The timeout on a confirmed request in milliseconds 1000

An example bacnet_event_registration.json file is provided:

{
  "Library": "libxrt-bacnet-event-registration.so",
  "Factory": "bacnet_event_registration_factory",
  "DeviceService": "bacnet_ip",
  "Timeout": 1000
}

This component will also need referenced in the XRT main.json file:

{
  ...
  "bacnet_ip":"XRT::BACnetIPDeviceService",
  "bacnet_event_registration": "XRT::BACnetEventRegistration"
}

Registering Events

To trigger this component to register events, a request must be made on the RequestTopic of the BACnet device service. The payload of this request follows standard format of any request, but the operation field op will be event:register.

There is one extra field that will be required in this payload which is recipient_list_entry. The following table provides the settings that are required to be set:

Field Type Description Mandatory
process_identifier Uint32 The handle of a process within the recipient device that is to receive the event Mandatory
confirmed_notify Bool true if confirmed notifications are to be sent

false if unconfirmed notifications are to be sent
Mandatory
recipient String The type of address to register to recipient lists

ID - Use the BACnet device identifier of the BACnet device service

IP - Use the IP address of the host running the BACnet device service
Not Mandatory

Default:

ID

Some example payloads are provided:

  • Will register the device service IP address to all recipient lists
{
  "client": "IOTech",
  "request_id": "1010",
  "op": "event:register",
  "recipient_list_entry": {
    "recipient": "IP",
    "process_identifier": 1234,
    "confirmed_notify" : false
  }
}
  • Will register the device service BACnet device ID to all recipient lists
{
  "client": "IOTech",
  "request_id": "2020",
  "op": "event:register",
  "recipient_list_entry": {
    "recipient": "ID",
    "process_identifier": 4321,
    "confirmed_notify" : true
  }
}
  • Missing recipient means default to register the device service BACnet device ID to all recipient lists
{
  "client": "IOTech",
  "request_id": "3030",
  "op": "event:register",
  "recipient_list_entry": {
    "process_identifier": 4821,
    "confirmed_notify" : false
  }
}

Once triggered, the component will read every recipient list resource of every device provisioned looking for matches to the IP or BACnet device ID of all the recipients already registered in the list. If it doesn't find a match, it will add a new entry at the end of the list and write it back to the device.

If a match is found, the component will check whether the process_identifier and confirmed_notify values of the recipient list entry match what was provided by the user and if not they will be updated and written back to the device.

Deregistering Events

To trigger this component to deregister events, a request must be made on the RequestTopic of the BACnet device service. The payload of this request follows standard format of any request, but the operation field op will be event:deregister. No other content is required in this request.

An example payload is provided:

{
  "client": "IOTech",
  "request_id": "9090",
  "op": "event:deregister"
}

Once triggered, the component will read every recipient list resource of every device provisioned looking for matches in both the IP address and BACnet device ID. If matches are found for either of them, these matching recipient entries will be removed from the lists and the recipient lists written back to the devices.

Response from Component

General Error Responses

Whilst the BACnet event registration component is running, it cannot be triggered again. The user will just receive this message:

{
   "client":"IOTech",
   "request_id":"1010",
   "result":{
      "error":"BACnetEventRegistration: Extension already active",
      "status":11
   }
}

If the component fails to retrieve the device list we will receive this response:

{
   "client":"IOTech",
   "request_id":"1010",
   "result":{
      "error":"BACnetEventRegistration: Could not retrieve device list",
      "status":5
   }
}

Action Responses

After the component has completed, within the result field of the response a devices field is included. This field contains a list of the names of all the devices that were interacted with by the component. These device names are used as keys to provide further information on what operations were performed on each device. If a device has recipient list resources, these will be included and a status given on what action was taken against each of these resources. The following table provides information on these statuses.

Status When Applicable Description
FAILED
  • Event Registration
  • Event Deregistration
Against Device Name

Error when reading profile of device

Against Device Resource

Error when reading or writing recipient list
EMPTY
  • Event Registration
  • Event Deregistration
Against Device Name

No recipient list resources found in profile of device
INSERTED
  • Event Registration
Against Device Resource

Could not match IP or device identifier to any in recipient list so successfully added new entry to the list
UPDATED
  • Event Registration
Against Device Resource

Matched IP or device identifier to recipient list entry but process_identifier or confirmed_notify did not match and so successfully updated entry
EXISTING
  • Event Registration
Against Device Resource

Matched IP or device identifier to recipient list entry where process_identifier and confirmed_notify also matched and so did not need to do anything
REMOVED
  • Event Deregistration
Against Device Resource

Found match with IP or device identifier and removed the entry from the list
NOT_PRESENT
  • Event Deregistration
Against Device Resource

Could not find match IP or device identifier in recipient list
  • An example response is provided for multiple devices on an operation event:register:
{
  "client":"IOTech",
  "request_id":"1030",
  "result":
  {
    "devices":
    [
      {
        "BacnetDevice1":[
        { "NOTIFICATION CLASS 0:recipient-list":"INSERTED" },
        { "NOTIFICATION CLASS 1:recipient-list":"INSERTED" },
        { "NOTIFICATION CLASS 2:recipient-list":"FAILED" }]
      },
      {
        "BacnetDevice2":[
        { "NOTIFICATION CLASS 0:recipient-list":"UPDATED" },
        { "NOTIFICATION CLASS 1:recipient-list":"EXISTING" }]
      },
      { "BacnetDevice3":"EMPTY" },
      { "BacnetDevice4":"FAILED" }
    ],
    "status": 0
  }
}
  • An example response is provided for multiple devices on operation event:deregister:
{
  "client":"IOTech",
  "request_id":"1040",
  "result":
  {
    "devices":
    [
      {
        "BacnetDevice1":[
        { "NOTIFICATION CLASS 0:recipient-list":"REMOVED" },
        { "NOTIFICATION CLASS 1:recipient-list":"REMOVED" },
        { "NOTIFICATION CLASS 2:recipient-list":"NOT_PRESENT" }]
      },
      {
        "BacnetDevice2":[
        { "NOTIFICATION CLASS 0:recipient-list":"REMOVED" },
        { "NOTIFICATION CLASS 1:recipient-list":"REMOVED" }]
      },
      { "BacnetDevice3":"EMPTY" },
      { "BacnetDevice4":"EMPTY" }
    ],
    "status": 0
  }
}
Back to top