Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BACnet protocol binding improvements #318

Merged
merged 10 commits into from
Nov 28, 2023
+99 −103
Merged

BACnet protocol binding improvements #318

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
63517c8
fix: remove bacnet:covPeriod
fennibay Nov 16, 2023
fac5e7e
refactor: clean up services and URI variables
fennibay Nov 17, 2023
1b41e4f
fix: cleanup the examples with updated URI variables
fennibay Nov 17, 2023
5db4a5d
update the documentation on URI variables
fennibay Nov 17, 2023
d99ec0d
add remark on expected changes in TD.next
fennibay Nov 17, 2023
d43fdae
fix: correct domain of bacv:usesService
fennibay Nov 17, 2023
7c6e7b7
fix: change logicalVal and protocolVal to has...
fennibay Nov 17, 2023
74ce248
change the reference about Q.8 to "based on"
fennibay Nov 17, 2023
bc8a0aa
extend URI scheme section with URI variables
fennibay Nov 28, 2023
a631eb8
fix: capitalization of TD services
fennibay Nov 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 36 additions & 33 deletions bindings/protocols/bacnet/bacnet-model.ttl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Wherever possible, this model refers to ANSI/ASHRAE Standard 135-2020 for BACnet

hctl:hasTarget rdfs:comment """
Should be of form bacnet://<device>/<objecttypenr>,<objectinsttr>[/<property>[/<index>]]
Additional parameters can be specified via URI variable syntax, e.g. ?bacnetCmdPrio=bacnet:CommandPrio8 for writing priority.
Additional parameters can be specified via URI variable syntax, e.g. ?commandPriority=13 for command priority or ?covIncrement=0.5 for COV increment
"""@en ;
rdfs:seeAlso "ASHRAE 135-2020 BACnet Q.8 BACnet URI Scheme" .

Expand All @@ -53,33 +53,50 @@ Additional parameters can be specified via URI variable syntax, e.g. ?bacnetCmdP

bacnet:usesService rdf:type owl:DatatypeProperty ;
rdfs:domain hctl:Form ;
rdfs:range [owl:oneOf ("ReadProperty"^^xsd:string "WriteProperty"^^xsd:string "SubscribeCOV"^^xsd:string "UnsubscribeCOV"^^xsd:string)] ;
rdfs:range [owl:oneOf ("ReadProperty"^^xsd:string "WriteProperty"^^xsd:string "SubscribeCOV"^^xsd:string)] ;
rdfs:comment """
Default BACnet service by td:OperationType:
- td:readProperty -> ReadProperty
- td:writeProperty -> WriteProperty
- td:observeProperty -> SubscribeCOV, subscribe to object if no property ID is present in target, otherwise subscribe to property
- td:unobserveProperty -> UnsubscribeCOV
- td:unobserveProperty -> SubscribeCOV (will do an unsubscribe instead)

TODO: Can we specify the defaults in a machine-readable, RDF-standard way?

Not mapped yet:
- td:invokeAction
- td:invokeAction, td:queryAction, td:cancelaction
- td:subscribeEvent, td:unsubscribeEvent
- td:readAllProperties, td:writeAllProperties, td:readMultipleProperties, td:writeMultipleProperties, td:observeAllProperties, td:unobserveAllProperties
- td:queryAllActions
- td:subscribeallevents, td:unsubscribeallevents
"""@en .

bacnet:covIncrement rdf:type owl:DatatypeProperty ;
rdfs:domain hctl:Form ;
rdfs:range xsd:float ;
rdfs:comment "Specifies the minimum change in that will cause a COV notification to be issued to subscribers, if missing the default value on the object will be used instead."@en ;
bacnet:CovIncrement rdf:type owl:Class ;
rdfs:subClassOf jsonschema:NumberSchema ;
rdfs:subClassOf [
a owl:Restriction ;
owl:onProperty jsonschema:minimum ;
owl:hasValue 0
] ;
rdfs:comment "Specifies the minimum change for numeric values in that will cause a COV notification to be issued to subscribers. Only applies when SubscribeCOVProperty is used. If missing for the present-value, the default value on the object will be used instead."@en ;
rdfs:seeAlso "ASHRAE 135-2020 BACnet 13.1 Change of Value Reporting" .

bacnet:covPeriod rdf:type owl:DatatypeProperty ;
rdfs:domain hctl:Form ;
rdfs:range xsd:nonNegativeInteger ;
rdfs:comment "Indicates the number of seconds to issue a COV notification periodically, even if there was no change. If 0 or missing, periodic COV notifications should be deactivated."@en ;
rdfs:seeAlso "ASHRAE 135-2020 BACnet 13.1 Change of Value Reporting" .
bacnet:CommandPriority rdf:type owl:Class ;
rdfs:subClassOf jsonschema:IntegerSchema ;
rdfs:subClassOf [
a owl:Restriction ;
owl:onProperty jsonschema:enum ;
# Prio 6 is reserved for minimum on off by BACnet, see clause 19.2.3 Minimum_On_Time and Minimum_Off_Time
owl:hasValue 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
] ;
rdfs:subClassOf [
a owl:Restriction ;
owl:onProperty jsonschema:default ;
# Default priority for writing is 16, ref. ASHRAE 135-2020 BACnet 15.9.1.1.5 Priority
owl:hasValue 16
] ;
rdfs:comment "Specifies the writing priority for BACnet objects with commanding, i.e. priority array."@en ;
rdfs:seeAlso "ASHRAE 135-2020 BACnet 19.2 Command Prioritization" .

#################################################################
# Type information properties
Expand Down Expand Up @@ -168,29 +185,15 @@ bacnet:hasMapEntry rdf:type owl:ObjectProperty ;
rdfs:domain bacnet:ValueMap ;
rdfs:range bacnet:ValueMapEntry .

bacnet:logicalVal rdf:type owl:DatatypeProperty ;
rdfs:domain bacnet:ValueMapEntry ;
rdfs:range [owl:unionOf (xsd:integer xsd:string xsd:boolean)] .
bacnet:hasLogicalVal rdf:type owl:DatatypeProperty ;
rdfs:domain bacnet:ValueMapEntry ;
rdfs:range [owl:unionOf (xsd:integer xsd:string xsd:boolean)] .

bacnet:protocolVal rdf:type rdf:type owl:DatatypeProperty ;
rdfs:domain bacnet:ValueMapEntry ;
rdfs:range xsd:integer .
bacnet:hasProtocolVal rdf:type rdf:type owl:DatatypeProperty ;
rdfs:domain bacnet:ValueMapEntry ;
rdfs:range xsd:integer .


bacnet:hasValueMap rdf:type owl:ObjectProperty ;
rdfs:domain [owl:unionOf (bacnet:Boolean bacnet:Enumerated bacnet:Unsigned bacnet:BitString)] ;
rdfs:range bacnet:ValueMap .

#################################################################
# Commanding (Priority array) properties definitions
# Based on ASHRAE 135-2020 BACnet 19.2 Command Prioritization
# This can be used for instance for a URI Variable for writeproperty
#################################################################

bacnet:CommandPriority rdf:type jsonschema:IntegerSchema ;
td:name "bacnetCmdPrio" ;
# Prio 6 is reserved for minimum on off by BACnet, see clause 19.2.3 Minimum_On_Time and Minimum_Off_Time
jsonschema:enum 1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ;
# Default priority for writing is 16, ref. ASHRAE 135-2020 BACnet 15.9.1.1.5 Priority
jsonschema:default 16 ;
rdfs:seeAlso "ASHRAE 135-2020 BACnet 19.2 Command Prioritization" .
20 changes: 8 additions & 12 deletions bindings/protocols/bacnet/bacnet.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,11 @@
"enum": [
"ReadProperty",
"WriteProperty",
"SubscribeCOVproperty"
"SubscribeCOV"
]
},
"bacv:hasDataType": {
"$ref": "#/definitions/bacnetDataType"
},
"bacv:covIncrement": {
"type": "number",
"minimum": 0
},
"bacv:covPeriod": {
"type": "integer",
"minimum": 0
}
},
"required": ["bacv:hasDataType"]
Expand Down Expand Up @@ -229,21 +221,25 @@
"items": {
"type": "object",
"properties": {
"bacv:logicalVal": {
"bacv:hasLogicalVal": {
"oneOf": [
{"type": "integer"},
{"type": "string"},
{"type": "boolean"}
]
},
"bacv:protocolVal": {
"bacv:hasProtocolVal": {
"type": "integer"
}
}
},
"minItems": 1
},
"bacnetCommandPriority": {
"covIncrement": {
"type": "number",
"minimum": 0
},
"commandPriority": {
"type": "integer",
"enum": [1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
"default": 16
Expand Down
97 changes: 40 additions & 57 deletions bindings/protocols/bacnet/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ <h2>Binding Scope</h2>
The following subset of BACnet features is supported by this binding:
<ul>
<li>
Services: ReadProperty, WriteProperty, SubscribeCOV, SubscribeCOVproperty
Services: ReadProperty, WriteProperty, SubscribeCOV
</li>
<li>
Data Model: Device, Object, Property, Index
Expand Down Expand Up @@ -169,7 +169,7 @@ <h2>URI Scheme</h2>
method, physical media, or protocol service to use.
</p>
<p>
The 'bacnet' URI Scheme used herein is defined in Annex Q.8 of
The 'bacnet' URI Scheme used herein is based on the definition in Annex Q.8 of
the BACnet Specification [[BACnet]].
</p>
<section>
Expand Down Expand Up @@ -324,42 +324,51 @@ <h3>URI Variables</h3>
<table class="def">
<thead>
<tr>
<th>Vocabulary term</th>
<th>URI variable</th>
<th>Description</th>
<th>Assignment</th>
<th>Type</th>
<th>Range</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>CommandPriority</code></td>
<td>Sets CmdPrio for Writes</td>
<td><code>commandPriority</code></td>
<td>Sets priority for WriteProperty</td>
<td>optional</td>
<td>
<a href="https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#nonNegativeInteger"><code>integer</code></a>
<a href="https://www.w3.org/2019/wot/json-schema#IntegerSchema"><code>integer</code></a>
</td>
</tr>
<tr>
<td><code>covIncrement</code></td>
<td>Sets minimum change for reporting</td>
<td>Sets COV increment change for reporting via SubscribeCOVProperty (SubscribeCOV with a property ID)</td>
<td>optional</td>
<td>
<a href="https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#decimal"><code>decimal</code></a>
<a href="https://www.w3.org/2019/wot/json-schema#NumberSchema"><code>number</code></a>
</td>
</tr>
</tbody>
</table>
<p>
URI Variables are not included in the 'bacnet' URI Scheme, and are included in the Protocol Binding to communicate PDU option settings for the BACnet driver to use when sending requests.
URI Variables are included in the 'bacnet' URI Scheme, and are included in the Protocol Binding to communicate PDU option settings for the BACnet driver to use when sending requests.
</p>
<p>
The following JSON example shows usage of the BACnet vocabulary for URI Variables, specifically CommandPriority and covIncrement. The semantic annotation is optional.
The following JSON example shows usage of the BACnet vocabulary for URI Variables, specifically CommandPriority and CovIncrement. The semantic annotation is optional.
</p>
<p>
This template could be used to construct the uriVariables element for TD interaction afffordances, to enable the application to communicate URI variables to the BACnet driver, using a consistent format according to the schema constraints below.
</p>
<p>
These variables may be also used in a form element to provide a constant value for the BACnet driver to use for PDU option values. If the variable is set in the forms element, and the application appends a URI variable to the URI in the request to the BACnet driver, the BACnet driver MUST use the value provided by the application in the URI variable when constructing the BACnet PDU for the request.
These variables may be also fixed in the href and not exposed via URI variables, causing the BACnet driver to use constant value for this parameter.
</p>
<p>
Some aspects were identified as improvement candidates in TD.next, which may result in breaking changes regarding URI variables:
<ol>
<li>Showing the link of URI variables to exactly which operations they are applicable to.</li>
<li>Exposing protocol-related parameters from Form-level instead of InteractionAffordance-level.</li>
<li>Providing a standardized set of parameters.</li>
<li>Having the ability to use parameters also in other places than the href</li>
</ol>
</p>
<pre id="uri-variables" class="json" title="URI Variables">
{
Expand All @@ -368,14 +377,14 @@ <h3>URI Variables</h3>
"bacv": "https://example.org/bacnet"
}],
"uriVariables": {
"CommandPriority": {
"commandPriority": {
"@type": "bacv:CommandPriority",
"type": "integer",
"minimum": 1,
"maximum": 16
"enum": [1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
"default": 16
},
"covIncrement": {
"@type": "bacv:covIncrement",
"@type": "bacv:CovIncrement",
"type": "number",
"minimum": 0
}
Expand All @@ -400,9 +409,9 @@ <h3>Form terms</h3>
<td>Indicates the BACnet service to use</td>
<td>
<a href="https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#string"><code>string</code></a>
<p>(one of <code>"ReadProperty"</code>, <code>"WriteProperty"</code>, <code>"SubscribeCOVproperty"</code>)</p>
<p>(one of <code>"ReadProperty"</code>, <code>"WriteProperty"</code>, <code>"SubscribeCOV"</code>)</p>
</td>
<td>td:forms</td>
<td>hctl:Form</td>
</tr>
<tr>
<td><code>bacv:isISO8601</code></td>
Expand All @@ -411,7 +420,6 @@ <h3>Form terms</h3>
<a href="https://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/#boolean"><code>boolean</code></a>
</td>
<td>bacv:Sequence</td>

</tr>
<tr>
<td><code>bacv:hasBinaryRepresentation</code></td>
Expand Down Expand Up @@ -527,12 +535,12 @@ <h3>Default Operation Mappings</h3>
</tr>
<tr>
<td><code>observeproperty</code></td>
<td><code>"bacv:usesService": "SubscribeCOVproperty"</code></td>
<td><code>"bacv:usesService": "SubscribeCOV"</code></td>
<td>covIncrement</td>
</tr>
<tr>
<td><code>unobserveproperty</code></td>
<td><code>"bacv:usesService": "SubscribeCOVproperty"</code></td>
<td><code>"bacv:usesService": "SubscribeCOV"</code></td>
<td></td>
</tr>
<tr>
Expand Down Expand Up @@ -998,41 +1006,16 @@ <h2>Examples</h2>
"type": "number",
"readOnly": true,
"uriVariables": {
"covIncrement": {
"observeIncrement": {
"@type": "bacv:covIncrement",
"type": "number",
"minimum": 0
}
},
"forms": [{
"op": [ "observeproperty" ],
"href": "bacnet://5/0,1/85",
"bacv:usesService": "subscribeCOVproperty",
"bacv:hasDataType": {
"@type": "bacv:Real"
}
}]
}
}
}
</pre>

<pre id="example-form-variables" class="example" title="uriVariables in the forms element">
{
"@context": ["https://www.w3.org/2022/wot/td/v1.1",
{
"bacv": "https://example.org/bacnet"
}],
...
"properties": {
"analog1": {
"type": "number",
"readOnly": true,
"forms": [{
"op": [ "observeproperty" ],
"href": "bacnet://5/0,1/85",
"bacv:usesService": "subscribeCOVproperty",
"bacv:covIncrement": 0.2,
"href": "bacnet://5/0,1/85?covIncrement={observeIncrement}",
"bacv:usesService": "SubscribeCOV",
"bacv:hasDataType": {
"@type": "bacv:Real"
}
Expand Down Expand Up @@ -1062,20 +1045,20 @@ <h2>Examples</h2>
"@type": "bacv:Enumerated",
"bacv:hasValueMap": [
{
"bacv:protocolVal": 1,
"bacv:logicalVal": "on"
"bacv:hasProtocolVal": 1,
"bacv:hasLogicalVal": "on"
},
{
"bacv:protocolVal": 2,
"bacv:logicalVal": "off"
"bacv:hasProtocolVal": 2,
"bacv:hasLogicalVal": "off"
},
{
"bacv:protocolVal": 3,
"bacv:logicalVal": "auto"
"bacv:hasProtocolVal": 3,
"bacv:hasLogicalVal": "auto"
},
{
"bacv:protocolVal": 4,
"bacv:logicalVal": "normal"
"bacv:hasProtocolVal": 4,
"bacv:hasLogicalVal": "normal"
}
]
}
Expand Down