Mappings
This section describes the strategies and default values to use protocol-specific concepts within the WoT Interaction model.
Default Operation Mappings
| Operation | Default Binding | Variables and parameters |
|---|---|---|
readproperty |
"bacv:usesService": "ReadProperty" |
|
writeproperty |
"bacv:usesService": "WriteProperty" |
CommandPriority |
observeproperty |
"bacv:usesService": "SubscribeCOV" |
covIncrement |
unobserveproperty |
"bacv:usesService": "SubscribeCOV" |
|
observeproperty |
"bacv:usesService": "SubscribeCOV" |
Note: BACnet driver must handle Status Flags |
unobserveproperty |
"bacv:usesService": "SubscribeCOV" |
WoT Data Schema and BACnet Types
BACnet has its own data model, which cannot always be derived from the data schema of the interaction affordances. Hence the type information is amended in the Form (column 3) of the protocol binding while staying conceptually conformant to the WoT Data Schema (column 2). The goal here is to abstract BACnet's data model into a Web-like JSON-based data model, by still keeping the wire compatibility on the protocol. The table below shows how the mappings are done, comprehensively for all BACnet types.
| BACnet Type | WoT Data Schema | BACnet Type Description under the Form |
|---|---|---|
bacv:SequenceOf |
{ "type": "array" } |
{
"bacv:hasDataType": {
"@type": "bacv:SequenceOf",
"bacv:hasMember": {
"$comment": "Data type of the element",
"@type": "bacv:..."
}
}
}
|
bacv:Sequence |
{ "type": "object" }
For the special case where a DateTime object is modeled as a Sequence "bacv:isISO8601": true:
{
"type": "string",
"pattern": "^((([1-9][0-9]*)?[0-9]{4})|\\*)-((1[0-2]|0[1-9])|O|E|\\*)-((3[01]|0[1-9]|[12][0-9])|O|E|\\*)(\\s*\\([1-7\\*]\\))?T((2[0-3]|[01][0-9])|\\*):([0-5][0-9]|\\*):([0-5][0-9]|\\*)(\\.[0-9]+)?(Z|[+-]\\d\\d:\\d\\d)?$",
"$comment": "A recurrence rule format based on ISO8601, specifies repeating dates and times using year, month, day, hour, minute, second, and optionally day of week (1: Mon, 7: Sun). Supports wildcards: 'O' for odd values, 'E' for even values, and '*' for any valid value in each component."
}
Please see bacv:Date and bacv:Time about the details of wildcards.
|
{
"bacv:hasDataType": {
"@type": "bacv:Sequence",
"bacv:isISO8601": true,
"bacv:hasNamedMember": [
{
"bacv:hasFieldName": "date",
"bacv:hasDataType": {
"@type": "bacv:Date"
}
},
{
"bacv:hasFieldName": "time",
"bacv:hasDataType": {
"@type": "bacv:Time"
}
}
]
}
}
|
bacv:List |
{ "type": "array", "uniqueItems": true } |
{
"bacv:hasDataType": {
"@type": "bacv:List",
"bacv:hasMember": {
"@type": "bacv:..."
}
}
}
|
bacv:Choice |
{ "oneOf": [
{ "type": "..." },
{ "type": "..." },
{ "...": "..." },
]}
|
{
"bacv:hasDataType": {
"@type": "bacv:Choice",
"bacv:hasNamedMember": [
{
"bacv:hasFieldName": "...",
"bacv:hasContextTag": 1,
"bacv:hasDataType": {
"@type": "bacv:..."
}
},
{
"bacv:hasFieldName": "...",
"bacv:hasContextTag": 2,
"bacv:hasDataType": {
"@type": "bacv:..."
}
}
]
}
}
|
bacv:Date |
{
"type": "string",
"pattern": "^((([1-9][0-9]*)?[0-9]{4})|\\*)-((1[0-2]|0[1-9])|O|E|\\*)-((3[01]|0[1-9]|[12][0-9])|O|E|\\*)(\\s*\\([1-7\\*]\\))?$",
"$comment": "A recurrence rule format based on ISO8601, specifies repeating dates using year, month, day, and optionally day of week (1: Mon, 7: Sun). Supports wildcards: 'O' for odd days, 'E' for even days, and '*' for any valid value in each component."
}
|
{
"bacv:hasDataType": {
"@type": "bacv:Date"
}
}
|
bacv:Time |
{
"type": "string",
"pattern": "^((2[0-3]|[01][0-9])|\\*):([0-5][0-9]|\\*):([0-5][0-9]|\\*)(\\.[0-9]+)?(Z|[+-]\\d\\d:\\d\\d)?$",
"$comment": "A recurrence rule format based on ISO8601, specifies repeating times using hour, minute, and second. Supports the '*' wildcard for any valid value in each component."
}
Examples:
|
{
"bacv:hasDataType": {
"@type": "bacv:Time"
}
}
|
bacv:WeekNDay |
{
"type": "string",
"pattern": "^((1[0-2]|0[1-9])|O|E|\\*)-(01|08|15|22|29|L7|B7|B14|B21|\\*)-([1-7]|\\*)$",
"$comment": "Custom WeekNDay string: first part month 01-12, O for odd, E for even, * for any; second part week of month: beginning on 01st, 08th, the last 7 days, they days before last 7 days, last 14 days.., or any; third part day of week: 1-7 (Mon-Sun) or any"
}
|
{
"bacv:hasDataType": {
"@type": "bacv:WeekNDay"
}
}
|
bacv:Unsigned |
{ "type": "integer", "minimum": 0 } |
{
"bacv:hasDataType": {
"@type": "bacv:Unsigned"
}
}
|
bacv:Signed |
{ "type": "integer" } |
{
"bacv:hasDataType": {
"@type": "bacv:Signed"
}
}
|
bacv:Real |
{ "type": "number" } |
{
"bacv:hasDataType": {
"@type": "bacv:Real"
}
}
|
bacv:Double |
{ "type": "number" } |
{
"bacv:hasDataType": {
"@type": "bacv:Double"
}
}
|
bacv:Boolean |
{ "type": "boolean" } |
{
"bacv:hasDataType": {
"@type": "bacv:Boolean"
}
}
|
bacv:Enumerated |
{
"$comment": "Contains the possible enum members, as strings or integers",
"enum": []
}
|
{
"bacv:hasDataType": {
"@type": "bacv:Enumerated"
}
}
|
bacv:String |
{ "type": "string" } |
{
"bacv:hasDataType": {
"@type": "bacv:String"
}
}
|
bacv:OctetString |
{
"type": "string",
"pattern": "^(([0-9A-F]{2}-?)+|(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})|(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{4}|[A-Za-z0-9+\/]{3}=|[A-Za-z0-9+\/]{2}={2}))$",
"$comment": "Binary data encoded in hex, dotted decimal (e.g., IPv4 address) or base64"
}
|
{
"bacv:hasDataType": {
"@type": "bacv:OctetString",
"bacv:hasBinaryRepresentation": "..."
}
}
|
bacv:BitString |
{
"type": "array",
"items": {
"$comment": "Contains the possible bit numbers",
"enum": []
}
"uniqueItems": true
}
|
{
"bacv:hasDataType": {
"@type": "bacv:BitString"
}
}
|
bacv:Any |
The type field should be left out completely. This is allowed according to WoT Data Schema Vocabulary Definitions.
|
{
"bacv:hasDataType": {
"@type": "bacv:Any"
}
}
|
bacv:Null |
{ "type": "null" } |
"bacv:hasDataType": {
"@type": "bacv:Null"
}
|
bacv:ObjectIdentifier |
{
"type": "string"
"format": "iri-reference",
"$comment": "BACnet Object Identifier is to be converted to an IRI, using the href schema of this protocol binding"
}
|
{
"bacv:hasDataType": {
"@type": "bacv:ObjectIdentifier"
}
}
|
BACnet contentType
BACnet has only one encoding format based on ASN.1
for transporting data. Since there is no other option and to avoid falling back to the
default
of application/json, contentType shall always be set to application/octet-stream.
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:
- 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.
- Objects can monitor themselves for event states (intrinsic reporting), or dedicated other objects can monitor other objects (algorithmic reporting)
- 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.
- 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 key aspects of the mapping to WoT are:
- Each Notification Class is mapped to an EventAffordance. This maps directly to the subscription granularity.
- Event Enrollment objects used for algorithmic reporting are not explicitly mapped; they are not relevant to the WoT consumer, per se.
-
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:
-
GetCurrentEventsaction 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. -
AcknowledgeEventaction can be used for all events (including the ones received viaGetCurrentEvents), where theackReqfield is true. Here thesourcefield of the event should match theeventSourcefield ofAcknowledgeEvent.input.
Future work on Manageable Affordances will improve this by modelling the relations between InteractionAffordances.
-
- 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:
-
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. - 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.
- 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 |
|
The simplifications below allow to omit the WoT Data Model.
|
| EventAffordance.cancellation | Not modeled; cancellation is implicit | Same as EventAffordance.subscription | Same as EventAffordance.subscription |
| EventAffordance.data |
|
|
We focus only on ConfirmedEventNotification; unconfirmed event notifications are currently not supported. |
| GetCurrentEvents: ActionAffordance.input |
|
|
|
| GetCurrentEvents: ActionAffordance.output |
|
|
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 |
|
|
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.