BACnet Event Registration Extension Component

The BACnet Event Registration Extension Component can both register and deregister the Edge 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 Edge 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 Edge 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
  }
}