In the context of the Web of Things (WoT), a Binding Template is a blueprint that gives guidance on how to implement a specific IoT protocol, data format, or IoT platform. The Core Binding Templates specification explains the overall mechanism and requirements for any binding to follow. This document gives implementation guidelines regarding 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
        }
    }  
}
            

Mappings

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

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",
                "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}",
                "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. For other operations (readproperty, observeproperty, unobserveproperty) this URI variable is irrelevant, so the corresponding forms do not use the URI variable. If the URI variable is also irrelevant for the writeproperty operation (e.g., when the BACnet object doesn't have a priority array), it can also be left out of the writeproperty form and the URI variable can be omitted completely. The URI variable comes with a default, so if the Consumer doesn't provide this URI variable, the default of 16 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
                            }
                        },
                        "forms": [
                            {
                                "op": [ "readproperty", "observeproperty", "unobserveproperty" ],
                                "href": "bacnet://5/2,1",
                                "bacv:hasDataType": {
                                    "@type": "bacv:Real"
                                }
                            },
                            {
                                "op": [ "writeproperty" ],
                                "href": "bacnet://5/2,1?commandPriority={writePriority}",
                                "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",
                "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"
                        }
                    ]
                }
            }]
        }
    }
}