In the context of the Web of Things (WoT), a Binding is a blueprint that gives guidance on how to implement a specific IoT protocol, data format, or IoT platform. The WoT Thing Description specification explains the overall mechanism and the WoT Binding Registry provides the formal requirements for any binding to follow. This document is a binding for BACnet [[BACnet]], a building automation and control networking protocol.

More specifically, this document defines a set of vocabulary terms that can be used inside a Thing Description document, and associated rules that allow to describe WoT operations using BACnet over the network. Additionally, relevant examples are provided to showcase different vocabulary terms and the associated behavior.

This document is a work in progress

BACnet® is a registered trademark of ASHRAE. This document has not been reviewed for publication by ASHRAE, and no endorsement by ASHRAE is implied.

Introduction

BACnet [[BACnet]] is a building automation and control networking protocol for applications such as heating, ventilating, and air conditioning control, lighting control, access control, and fire detection systems.

This document describes how the Web of Things Thing Description [[WOT-THING-DESCRIPTION]] (TD) can be used to represent devices that use BACnet. In particular, the document explains how to create valid TD Forms for the different operations that BACnet can perform.

Forms of a Thing Description instance with BACnet Binding complies with this specification if it follows the normative statements in [[[#vocabulary]]] and [[[#mappings]]].

A JSON Schema [[?JSON-SCHEMA]] to validate Thing Description instances containing BACnet Binding is provided in the GitHub repository.

Binding Scope

It is assumed the reader of this document is familiar with the basic principles and mechanisms of the BACnet standard [[BACnet]].

The following subset of BACnet features is supported by this binding:

• Services: ReadProperty, WriteProperty, SubscribeCOV
• Data Model: Device, Object, Property, Index

This protocol binding is intended to be used to enable web applications to interact with data and control affordances exposed by BACnet devices. It is not intended that this binding be used for device commissioning, onboarding, or device management.

WoT Interaction Affordances are mapped to BACnet Properties. If the BACnet property-identifier is not present in the URI element of the form, the object-identifier is used to interact with the BACnet Object, exposing the present-value Property.

When it is necessary to expose properties other than the present-value property, the property-identifier must be included in the URI element of the form.

Selected BACnet Service parameters are exposed as URI Variables to enable WoT consumers access to BACnet features, for example, Command Priority.

URI Scheme

In cases where a URI is needed to refer to data that is accessible using BACnet services, the 'bacnet' URI scheme provides a means to identify a property of an object in the scope of a BACnet device. The 'bacnet' URI scheme does not provide means to identify the BACnet network on which a device resides, or the network access method, physical media, or protocol service to use.

The 'bacnet' URI Scheme used herein is based on the definition in Annex Q.8 of the BACnet Specification [[BACnet]]. The additions to Q.8 are as follows:

1. object-type and property-identifier are restricted to their numeric versions and not the registered alphanumeric identifiers, in order to reduce the maintenance overhead when new object-types and property-identifiers are introduced in the BACnet standard.
2. Query components (as per RFC 3986 Section 3.4) are added to cover specific needs not covered in Annex Q.8. Current examples are command priority and COV increment.

bacnet-URI = scheme ":" scheme-specific-part [uri-variable-part]
scheme = "bacnet"
scheme-specific-part = "//" device-identifier "/" object-identifier [ "/" property-identifier [ "/" property-array-index ] ]
device-identifier = number / ".this"
object-identifier = object-type "," object-instance
object-type = number / identifier
object-instance = number
property-identifier = number / identifier
property-array-index = number
uri-variable-part = ?(key1=value1) *( "&" keyN=valueN )
number = "0" / non-zero-digit *decimal-digit
non-zero-digit = %x31-39  ; "1" to "9"
decimal-digit = %x30-39  ; "0" to "9"
identifier = lowercase *alphanumeric *( "-" 1*alphanumeric )
alphanumeric = uppercase / lowercase / decimal-digit
uppercase = %x41-5A  ; "A" to "Z"
lowercase = %x61-7A  ; "a" to "z"

device-identifier = number / ".this"

object-identifier = object-type "," object-instance
object-type = number / identifier
object-instance = number

property-identifier = number / identifier

property-array-index = number

uri-variable-part = ?(key1=value1) *( "&" keyN=valueN )

number = "0" / non-zero-digit *decimal-digit
non-zero-digit = %x31-39  ; "1" to "9"
decimal-digit = %x30-39  ; "0" to "9"

identifier = lowercase *alphanumeric *( "-" 1*alphanumeric )
alphanumeric = uppercase / lowercase / decimal-digit
uppercase = %x41-5A  ; "A" to "Z"
lowercase = %x61-7A  ; "a" to "z"
                

BACnet Vocabulary

This section describes the vocabulary used in BACnet. A protocol binding implementation should use the vocabulary defined in this section to describe the different configurations that can be used to exchange data between Web of Things clients, devices, and services.

This vocabulary is fully defined in the BACnet ontology published together with this document.

Until the JSON-LD context is published, this document will use the example URI "https://example.org/bacnet"for the context with the prefix "bacv".

{
    "@context": ["https://www.w3.org/2022/wot/td/v1.1",
    {
        "bacv": "https://example.org/bacnet"
    }],
    "uriVariables": {
        "commandPriority": {
            "@type": "bacv:CommandPriority",
            "type": "integer",
            "enum": [1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
            "default": 16
        },
        "covIncrement": {
            "@type": "bacv:CovIncrement",
            "type": "number",
            "minimum": 0
        },
        "relinquish": {
            "@type": "bacv:Relinquish",
            "type": "boolean",
            "default": false
        }
    }  
}
            

Mappings

This section describes the strategies and default values to use protocol-specific concepts within the WoT Interaction model.

Mappings related to events

BACnet has an extensive alarm model; see [[BACnet]] Chapter 13. Alarm and Event Services for a complete description. The fundamental aspects are as follows:

1. There are three event states: Normal (no event); OffNormal (e.g., operating temperature outside of the normal range); and Fault (e.g., defective sensor). Events are sent for transitions, including self-transitions and toNormal transitions.
2. Objects can monitor themselves for event states (intrinsic reporting), or dedicated other objects can monitor other objects (algorithmic reporting)
3. Alarms are always sent via Notification Class objects, which keep lists of alarm recipients, i.e., alarm subscriptions are always of the Notification Classes; it is not possible to receive alarms only from some of the objects linked to a given Notification Class. In the typical case, a client will register to all Notification Classes of a BACnet Device.
4. Some alarms can be configured as "acknowledgement required". Acknowledgement is defined by BACnet as a manual action performed by a human operator, and is separate from the confirmation of the successful reception of the event notification.

The picture below demonstrates these key aspects and how they are mapped to the WoT concepts.

The key aspects of the mapping to WoT are:

1. Each Notification Class is mapped to an EventAffordance. This maps directly to the subscription granularity.
2. Event Enrollment objects used for algorithmic reporting are not explicitly mapped; they are not relevant to the WoT consumer, per se.
3. Special event-related actions (getting current events and acknowledging events) are mapped to ActionAffordances.

   The WoT consumer does not need to know the details of BACnet alarming; it can simply interact with the InteractionAffordances of the Thing, according to their data schemata. However, the consumer does need to have an understanding of the relations between the InteractionAffordances:

   1. GetCurrentEvents action can be used to fetch all current events of the thing, which would not be received just by subscribing to events. This action delivers the same payload as the EventAffordance's data.
   2. AcknowledgeEvent action can be used for all events (including the ones received via GetCurrentEvents), where the ackReq field is true. Here the source field of the event should match the eventSource field of AcknowledgeEvent.input.

   Future work on Manageable Affordances will improve this by modelling the relations between InteractionAffordances.

4. Thing is assumed to be mapped to the BACnet device. While this is simple, it is not a mandatory decision. In specific cases, one BACnet device can correspond to multiple things, and even vice-versa.

In contrast to PropertyAffordances, which are generically mapped to BACnet, interactions related to events come with a specific payload specified by the BACnet standard. The flexibility that would be possible, for example, for an HTTP longpoll-based event notification with a custom HTTP body, is not possible in BACnet context. Thus, it is necessary for the WoT consumer to work with a given logical data schema that is influenced by the BACnet standard. Still, this binding takes an approach to define the data schemata of the InteractionAffordances as independently as possible from BACnet, in order to avoid a direct dependency of WoT consumers on a specific protocol.

With this background, this binding takes some simplifying design decisions:

1. When the BACnet payload is fixed by the BACnet standard for a given service — e.g., event subscription, or data or alarm acknowledgement — the binding doesn't model the BACnet data with bacv:hasDataType.
2. Some features of the BACnet alarm model are abstracted away: filtering alarms based on day of week, time of day, and event state; and using unconfirmed event notifications. If these become necessary, they can be added in a future version.
3. Payloads containing three event states (Normal, OffNormal, Fault) are split into simpler payloads for each event state. For instance, GetEventInformation sends one array item for each BACnet object containing three flags, three timestamps, three acknowledge flags, etc., for each possible event state. This binding splits that payload in the ActionAffordance's output into multiple payloads for each active event, with one timestamp, acknowledge flag, etc. This approach makes the output similar to the EventAffordance data payload and removes the three-event state-based BACnet design from the WoT Consumer's view.

The resulting data payloads look like this:

Data	WoT Model	BACnet Model	Remarks
EventAffordance.subscription	Not modeled; subscription is implicit	valid-days from-time to-time recipient process-identifier issue-confirmed transitions	The simplifications below allow to omit the WoT Data Model. valid-days ← all days from-time ← all time to-time ← all time recipient ← BACnet address of the WoT Consumer process-identifier ← BACnet process ID of the WoT consumer issue-confirmed-notifications ← always true transitions ← all transitions
EventAffordance.cancellation	Not modeled; cancellation is implicit	Same as EventAffordance.subscription	Same as EventAffordance.subscription
EventAffordance.data	source: IRI of the BACnet object sending the event time: Timestamp of the event prio: Priority of the event ackReq (optional): Flag indicating whether acknowledgement is required. Default is false. toState: The target state of the event transition origSource (optional): In case of algorithmic reporting, the IRI of the object monitored by the event-sending object. eventType (optional): If the event is a regular event transition, an acknowledgement notification or a general sync-required event. Default is regular. values (optional): Additional values associated with the event, e.g., high-limit if the value exceeded an OffNormal limit. message (optional): The message associated with the event. inactive (optional): Flag whether the event is not active anymore. Default is false. This is needed for inactive, but not yet acknowledged events; they are there for symmetry with GetCurrentEvents action.	process-identifier initiating-device-identifier event-object-identifier time-stamp notification-class priority event-type message-text notify-type ack-required from-state to-state event-values	We focus only on ConfirmedEventNotification; unconfirmed event notifications are currently not supported.
GetCurrentEvents: ActionAffordance.input	lastReceivedSource (optional): IRI of the last received object with event	Last Received Object Identifier
GetCurrentEvents: ActionAffordance.output	currentEvents: Array. Each array item is modeled exactly the same as EventAffordance.data: source time prio ackReq (optional) toState origSource (optional) eventType (optional) values (optional) message (optional) inactive (optional) moreEvents: Flag indicating whether more events should be queried	List of Event Summaries: Object Identifier Event State Acknowledged Transitions Event Timestamps Notify Type Event Enable Event Priorities More Events	As indicated above, the BACnet payload and the ActionAffordance output differ, especially around how events are grouped. In the BACnet payload, one list item represents one object with its three possible events, which is reflected in Event State, Acknowledged Transitions, Event Timestamps, and Priorities. This is to be processed and split into one standalone event for every current event, or past unacknowledged event, of this object, with corresponding timestamp, priority, etc.
AcknowledgeEvent: ActionAffordance.input	eventSource: Source of the event to be acknowledged eventState: To-state of the event to be acknowledged eventTime: Timestamp of the event to be acknowledged eventTime: Timestamp of the event to be acknowledged ackSource: String describing the acknowledgement source ackTime: Timestamp of the acknowledge operation	Process Identifier Object Identifier Event State Event Timestamp Acknowledgement Source Time of Acknowledgement	Process Identifier is to be set by WoT Consumer corresponding to what it has entered at subscription time.

Detailed schemata of these payloads can be found in the JSON Schema linked in this file's header. Examples below will be helpful in understanding the details.

Examples

This section will present a set of examples of how the terms defined in this document can be used to describe and configure a Form.

[[[#example-readproperty]]] shows a property with the object type analog-input, object instance 1, and property identifier present-value in the scope of a BACnet device with device instance number 5.

{
    "@context": ["https://www.w3.org/2022/wot/td/v1.1",
    {
        "bacv": "https://example.org/bacnet"
    }],
    ...
    "properties": {
        "analog1": {
            "type": "number",
            "readOnly": true,
            "forms": [{
                "op": [ "readproperty" ],
                "href": "bacnet://5/0,1/85",
                "contentType": "application/octet-stream",
                "bacv:usesService": "ReadProperty",
                "bacv:hasDataType": {
                    "@type": "bacv:Real"
                }
            }]
        }
    }
}

[[[#example-uri-variables-with-forms]]] demonstrates how the uriVariables in the affordance-level can be used and how they need to be represented in a forms element. The "bacv:covIncrement" indicates that the URI variable set by the Consumer application will be used to notify the Consumer only if the property value changes more than the set amount by the URI variable.

{
    "@context": ["https://www.w3.org/2022/wot/td/v1.1",
    {
        "bacv": "https://example.org/bacnet"
    }],
    ...
    "properties": {
        "analog1": {
            "type": "number",
            "readOnly": true,
            "uriVariables": {
                "observeIncrement": {
                    "@type": "bacv:covIncrement",
                    "type": "number",
                    "minimum": 0
                }
            },
            "forms": [{
                "op": [ "observeproperty" ],
                "href": "bacnet://5/0,1/85?covIncrement={observeIncrement}",
                "contentType": "application/octet-stream",
                "bacv:usesService": "SubscribeCOV",
                "bacv:hasDataType": {
                    "@type": "bacv:Real"
                }
            }]
        }
    }
}

[[[#example-uri-variable-for-writing]]] demonstrates how the uriVariable in the affordance-level can be used to model a writing priority in a forms element. The "bacv:CommandPriority" indicates that the URI variable set by the Consumer application will be relayed as the priority argument in the WriteProperty request. "bacv:Relinquish" indicates whether the user wants to relinquish the property value at the given command priority. For other operations (e.g., readproperty, observeproperty, unobserveproperty) these URI variables are irrelevant, so the corresponding forms do not use them. If the URI variables are also irrelevant for the writeproperty operation (e.g., when the BACnet object doesn't have a priority array), they can also be left out of the writeproperty form, and the URI variables can be omitted completely. The URI variables come with defaults, so if the Consumer doesn't provide them, the defaults of writePriority=16 and relinquish=false will be used. Another possibility is to fix the writing priority in the TD by giving a fixed commandPriority in the href of the form, and not exposing its value via a URI variable. These decisions belong to the TD author.

            {
                "@context": ["https://www.w3.org/2022/wot/td/v1.1",
                {
                    "bacv": "https://example.org/bacnet"
                }],
                ...
                "properties": {
                    "analog1": {
                        "type": "number",
                        "readOnly": false,
                        "writeOnly": false,
                        "observable": true,
                        "uriVariables": {
                            "writePriority": {
                                "@type": "bacv:CommandPriority",
                                "type": "integer",
                                "enum": [1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
                                "default": 16
                            },
                            "relinquish": {
                                "@type": "bacv:Relinquish",
                                "type": "boolean",
                                "default": false
                            }
                        },
                        "forms": [
                            {
                                "op": [ "readproperty", "observeproperty", "unobserveproperty" ],
                                "href": "bacnet://5/2,1",
                                "contentType": "application/octet-stream",
                                "bacv:hasDataType": {
                                    "@type": "bacv:Real"
                                }
                            },
                            {
                                "op": [ "writeproperty" ],
                                "href": "bacnet://5/2,1?commandPriority={writePriority}{&relinquish}",
                                "contentType": "application/octet-stream",
                                "bacv:usesService": "WriteProperty",
                                "bacv:hasDataType": {
                                    "@type": "bacv:Real"
                                }
                            }
                        ]
                    }
                }
            }

[[[#example-enum-mapping]]] shows how an enum in the Data Schema is extended in the forms to make it understandable by BACnet drivers.

{
    "@context": ["https://www.w3.org/2022/wot/td/v1.1",
    {
        "bacv": "https://example.org/bacnet"
    }],
    ...
    "properties": {
        "multistate1": {
            "type": "string",
            "enum": ["on", "off", "auto", "manual"],
            "readOnly": true,
            "forms": [{
                "op": [ "readproperty" ],
                "href": "bacnet://5/14,1/85",
                "contentType": "application/octet-stream",
                "bacv:usesService": "ReadProperty",
                "bacv:hasDataType": {
                    "@type": "bacv:Enumerated",
                    "bacv:hasValueMap": [
                        {
                            "bacv:hasProtocolVal": 1,
                            "bacv:hasLogicalVal": "on"
                        },
                        {
                            "bacv:hasProtocolVal": 2,
                            "bacv:hasLogicalVal": "off"
                        },
                        {
                            "bacv:hasProtocolVal": 3,
                            "bacv:hasLogicalVal": "auto"
                        },
                        {
                            "bacv:hasProtocolVal": 4,
                            "bacv:hasLogicalVal": "normal"
                        }
                    ]
                }
            }]
        }
    }
}

[[[#example-event]]] shows the InteractionAffordances for using BACnet events:

1. One ActionAffordance for the Device Object for GetEventInfo, named as GetCurrentEvents
2. One ActionAffordance for the Device Object for AcknowledgeAlarm, named as AcknowledgeEvent
3. One EventAffordance for every Notification Class object

        {
        "@context": ["https://www.w3.org/2022/wot/td/v1.1",
        {
        "bacv": "https://example.org/bacnet"
        }],
        ...
        "actions": {
            "GetCurrentEvents": {
                "input": {
                  "type": "object",
                  "properties": {
                    "lastReceivedSource": {
                      "type": "string",
                      "format": "iri-reference"
                    }
                  }
                },
                "output": {
                  "type": "object",
                  "properties": {
                    "currentEvents": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "source": {
                            "type": "string",
                            "format": "iri-reference"
                          },
                          "time": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "prio": {
                            "type": "integer"
                          },
                          "ackReq": {
                            "type": "integer",
                            "enum": [
                              0,
                              1
                            ],
                            "default": 0
                          },
                          "toState": {
                            "type": "string",
                            "enum": [
                              "fault",
                              "offnormal",
                              "normal"
                            ]
                          },
                          "eventType": {
                            "type": "string",
                            "enum": [
                              "regular",
                              "ack",
                              "syncrequired"
                            ],
                            "default": "regular"
                          },
                          "origSource": {
                            "type": "string",
                            "format": "iri-reference"
                          },
                          "message": {
                            "type": "string"
                          },
                          "values": {
                            "type": "object"
                          },
                          "inactive": {
                            "type": "integer",
                            "enum": [
                              0,
                              1
                            ],
                            "default": 0
                          }
                        },
                        "required": [
                          "source",
                          "time",
                          "prio",
                          "toState"
                        ]
                      }
                    }
                  },
                  "moreEvents": {
                    "type": "boolean"
                  },
                  "required": [
                    "currentEvents",
                    "moreEvents"
                  ]
                },
                "forms": [
                  {
                    "href": "bacnet://1/8,1",
                    "contentType": "application/octet-stream",
                    "op": [
                      "invokeaction"
                    ],
                    "bacv:usesService": "GetEventInfo"
                    ]
                  }
                ]
            },
            "AcknowledgeEvent": {
                "input": {
                    "type": "object",
                    "properties": {
                        "source": {
                            "type": "string",
                            "format": "iri-reference"
                          },
                          "toState": {
                            "type": "string",
                            "enum": [
                              "fault",
                              "offnormal",
                              "normal"
                            ]
                          },
                          "eventTime": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "ackSource": {
                            "type": "string"
                          },
                          "ackTime": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "required": ["source", "ackState", "eventTime", "ackSource", "ackTime"]
                    }
                },
                "forms": [
                  {
                    "href": "bacnet://1/8,1",
                    "contentType": "application/octet-stream",
                    "op": [
                      "invokeaction"
                    ],
                    "bacv:usesService": "AcknowledgeAlarm"
                  }
                ]
            }
        },
        "events": {
            "NotifCl2": {
                "title": "Highest priority notification with acknowledge",
                "data": {
                    "type": "object",
                    "properties": {
                      "source": {
                        "type": "string",
                        "format": "iri-reference"
                      },
                      "time": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "prio": {
                        "type": "integer"
                      },
                      "message": {
                        "type": "string"
                      },
                      "ackReq": {
                        "type": "integer",
                        "enum": [0, 1],
                        "default": 0
                      },
                      "toState": {
                        "type": "string",
                        "enum": [
                          "fault",
                          "offnormal",
                          "normal"
                        ]
                      },
                      "eventType": {
                        "type": "string",
                        "enum": ["regular", "ack", "syncrequired"],
                        "default": "regular"
                      },
                      "origSource": {
                        "type": "string",
                        "format": "iri-reference"
                      },
                      "values": {
                        "type": "object"
                      },
                      "inactive": {
                        "type": "integer",
                        "enum": [0, 1],
                        "default": 0
                      }
                    },
                    "required": [
                      "source",
                      "time",
                      "prio",
                      "toState"
                    ]
                },
                "forms": [
                    {
                        "href": "bacnet://2/15,2/102",
                        "contentType": "application/octet-stream",
                        "op": [
                            "subscribeevent",
                            "unsubscribeevent"
                        ]
                    }
                ],
              },
            }
        }
        

The resulting example payloads are available below.

            {
                "source": "bacnet://5/0,20",
                "time": "2024-07-30T12:33:00+00:00",
                "prio": 150,
                "message": "Equipment overheat",
                "ackReq": 1,
                "toState": "offnormal",
                "values": {
                    "deadband": 0.5,
                    "exceedLim": 50,
                    "exceedValue": 55,
                    "statusFlags": [0, 0, 0, 0]
                }
            }
        

[[[#example-event-data]]] shows an event notification because of an overheating piece of equipment. Event message gives this as a useful hint; prio is set accordingly. values object gives additional details about the event — that the current value is 55, and the exceeded limit was 50. The unit of these values can be found at the source object that triggered this event. Because overheating events are important for the operator to notice, ackReq is set, so the operator definitely will see the event, even after the overheating condition is over.

            {
                "source": "bacnet://5/0,20",
                "toState": "offnormal",
                "eventTime": "2024-07-30T12:33:00+00:00",
                "ackSource": "Management Station Operator Acknowledge",
                "ackTime": "2024-07-30T13:15:00+00:00"
            }
        

When the operator sees this event and decides to acnowledge it, management station will send the payload shown in [[[#example-acknowledgeevent-input]]]. This can happen before or after the event is over.

            {
                "currentEvents": [
                    {
                        "source": "bacnet://5/0,12",
                        "time": "2024-07-21T20:14:00+00:00",
                        "prio": 200,
                        "ackReq": 0,
                        "toState": "fault"
                    },
                    {
                        "source": "bacnet://5/0,20",
                        "time": "2024-07-30T12:33:00+00:00",
                        "prio": 150,
                        "message": "Equipment overheat",
                        "ackReq": 0,
                        "toState": "offnormal",
                        "values": {
                            "deadband": 0.5,
                            "exceedLim": 50,
                            "exceedValue": 55,
                            "statusFlags": [0, 0, 0, 0]
                        }
                    }
                ],
                "moreEvents": false
            }
        

If the event client wants to get a list of all events of the device, it will invoke the GetCurrentEvents action, and will receive te payload shown in [[[#example-getcurrentevents-output]]]. Here the event notification about the overheating and a past fault event can be seen. This is useful for synchronizing the events known on the client to the events that are on the device, in case of temporary disconnection, reboot of client or device, etc. Please note that in the second alarm, the ackReq value turned to 0, because this event was acknowledged by the operator in the meantime.