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 which 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 explain 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]].

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 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 about how the terms defined in this document can be used to describe and configure a Form.

[[[#example-readproperty]]] shows the property with 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-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"
                        }
                    ]
                }
            }]
        }
    }
}