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

feat: introduce cov:confirmable vocabulary term #392

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat: introduce cov:confirmable vocabulary term #392

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
450449c
feat: introduce cov:confirmable vocabulary term
JKRhb Dec 19, 2024
e24a1e6
chore: regenerate binding documents
JKRhb Dec 19, 2024
3df9138
fixup! feat: introduce cov:confirmable vocabulary term
JKRhb Dec 19, 2024
7c34960
fixup! chore: regenerate binding documents
JKRhb Dec 19, 2024
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
68 changes: 64 additions & 4 deletions bindings/protocols/coap/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,56 @@ <h3>Requests/Responses</h3>
}
}
</pre>
<p>
In CoAP over UDP or DTLS [[RFC7252]], requests and responses can either be confirmable (CON) or non-confirmable (NON).
In contrast to non-confirmable messages, confirmable messages are required to be acknowledged by the receiving endpoint and are otherwise retransmitted until an acknowledgement has been received.
Using non-confirmable requests can be useful for sensor data (that gets sent repeatedly and therefore does not need to be transmitted reliably), while confirmable requests provide a certain reliability that is useful for retrieving values or invoking actions that should not fail.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In a TD we want to tell the TD consumer how to interact with the Thing, so this is about CoAP requests that the consumer sends to the Thing, right?

I would assume that if a TD consumer knows what it is doing (e.g. transmitting sensor data, retrieving a value, or invoking an action) it also knows whether it is best to do it with a CON or NON. Maybe the consumer just needs to give the CoAP driver a hint as to what it is doing?

Or what are the cases where a TD consumer is doing something and also knows what it is doing, but does not know whether to use CON or NON, and so the TD should tell it (or overrule what it would normally do)?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, yeah, these are good points. Maybe a better example could be sleepy devices that were also discussed in the context of #389? Although I am still not completely sure how to model that. Perhaps another use case could be resource constraints in general, where using NON could be slightly more efficient (although not that much when piggybacked acknowledgments are being used).

Do you see a better motivation here? (Also pinging @mkovatsc as we discussed this potential addition to the vocabulary during WoT week.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sleepy devices are interesting because a TD consumer may spend a lot of time trying to reach a device that is unreachable, draining the resources of the network infrastructure, which may also be resource constrained. It would therefore be very desirable if a TD could give a consumer hints on how best to reach the sleepy device. Is the choice between CON and NON enough? Is the sleepy device awake at regular intervals so that the TD consumer only has to synchronize its schedule once and can then communicate at the fixed interval that is specified in the TD? This would then no longer be CoAP-specific but would go in the direction of the generic terms mentioned by @danielpeintner.

</p>
<p>
To provide a hint whether CON or NON requests should be used for accessing a CoAP resource associated with a form, the vocabulary term `cov:confirmable` can be used.
A value of `true` indicates that a CON request SHOULD be used by the Consumer, while a value of `false` indicates that a NON request SHOULD be used instead (for potential usages of the vocabulary term see [[[#example-request-con-non]]]).
However, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.
When `cov:confirmable` is absent from a CoAP form, the consumer can choose freely between CON and NON requests as there is no default value defined.
Comment on lines +219 to +222
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A "hint" seems rather less powerful than the SHOULD (which looks like RFC2119, to me).

Suggested change
To provide a hint whether CON or NON requests should be used for accessing a CoAP resource associated with a form, the vocabulary term `cov:confirmable` can be used.
A value of `true` indicates that a CON request SHOULD be used by the Consumer, while a value of `false` indicates that a NON request SHOULD be used instead (for potential usages of the vocabulary term see [[[#example-request-con-non]]]).
However, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.
When `cov:confirmable` is absent from a CoAP form, the consumer can choose freely between CON and NON requests as there is no default value defined.
The vocabulary term `cov:confirmable` can be used to provide a hint whether CON or NON requests are expected to be better for accessing a CoAP resource associated with a form.
A value of `true` encourages the Consumer to use CON requests, while a value of `false` encourages the Consumer to use NON requests. (For potential uses of the vocabulary term, see [[[#example-request-con-non]]].)
Note that, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.
When `cov:confirmable` is absent from a CoAP form, the consumer can choose freely between CON and NON requests as there is no default value defined.

</p>
<p>
When using reliable transport protocols (such as TCP) that ensure that messages are delivered, the distinction between confirmable and non-confirmable messages is not being made at the protocol level.
Therefore, when using one of these CoAP variants, the vocabulary term `cov:confirmable` is simply ignored by a WoT consumer.
</p>
<pre id="example-request-con-non" class="example" title="A Thing Description containing CoAP forms with hints for confirmable and non-confirmable requests.">
{
"@context": "https://www.w3.org/2022/wot/td/v1.1",
...
"properties": {
"currentTemperature": {
"title": "Latest temperature value",
"description": "Returns the latest temperature value recorded.",
"type": "number",
"forms": [
{
"href": "coap://[2001:DB8::1]/currentTemperature",
"cov:confirmable": true,
"op": "readproperty"
}
]
}
},
"action": {
"recordTemperature": {
"title": "Record temperature value",
"description": "Record a temperature value (e.g., from a sensor node).",
"input": {
"type": "number"
},
"forms": [
{
"href": "coap://[2001:DB8::1]/recordTemperature",
"cov:confirmable": false
}
]
}
}
}
</pre>
<p>
The <code>contentType</code> and <code>contentCoding</code> members of a form specify the CoAP content format of the request and/or response.
In <abbr title="Constrained Application Protocol">CoAP</abbr>, combinations of content type and content coding are encoded using standardized values listed in the <a href="https://www.iana.org/assignments/core-parameters/#content-formats">IANA CoAP Content-Formats registry</a>.
Expand Down Expand Up @@ -563,6 +613,16 @@ <h3>Form terms</h3>
<a href="http://www.w3.org/2001/XMLSchema#string">string</a> (e.g., <code>GET</code>, <code>PUT</code>, <code>POST</code>, <code>DELETE</code>, <code>FETCH</code>, <code>iPATCH</code>, or <code>PATCH</code>)<p>(See the <a href="https://www.iana.org/assignments/core-parameters/#method-codes">CoAP Method Codes</a> registry for the set of possible values.)</p>
</td>
</tr>
<tr>
<td><code>cov:confirmable</code></td>
<td>
Provides a hint for Consumers to use confirmable (`true`) or non-confirmable (`false`) requests with a particular resource. Only applicable to CoAP over UDP/DTLS [[RFC7252]].
</td>
<td>optional</td>
<td>
<a href="http://www.w3.org/2001/XMLSchema#boolean">boolean</a>
</td>
</tr>
<tr>
<td><code>cov:minPollingInterval</code></td>
<td>
Expand Down Expand Up @@ -670,10 +730,10 @@ <h3>BlockWiseTransferParameters</h3>
<!-- Blockwise terms from the ontology-->
<tr>
<td>
<code>cov:block2Size</code>
<code>cov:block1Size</code>
</td>
<td>
Indicates the largest block size that may be used in a Block2 or Q-Block2 Option
Indicates the largest block size that may be used in a Block1 or Q-Block1 Option
</td>
<td>optional</td>
<td>
Expand All @@ -682,10 +742,10 @@ <h3>BlockWiseTransferParameters</h3>
</tr>
<tr>
<td>
<code>cov:block1Size</code>
<code>cov:block2Size</code>
</td>
<td>
Indicates the largest block size that may be used in a Block1 or Q-Block1 Option
Indicates the largest block size that may be used in a Block2 or Q-Block2 Option
</td>
<td>optional</td>
<td>
Expand Down
50 changes: 50 additions & 0 deletions bindings/protocols/coap/index.template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,56 @@ <h3>Requests/Responses</h3>
}
}
</pre>
<p>
In CoAP over UDP or DTLS [[RFC7252]], requests and responses can either be confirmable (CON) or non-confirmable (NON).
In contrast to non-confirmable messages, confirmable messages are required to be acknowledged by the receiving endpoint and are otherwise retransmitted until an acknowledgement has been received.
Using non-confirmable requests can be useful for sensor data (that gets sent repeatedly and therefore does not need to be transmitted reliably), while confirmable requests provide a certain reliability that is useful for retrieving values or invoking actions that should not fail.
</p>
<p>
To provide a hint whether CON or NON requests should be used for accessing a CoAP resource associated with a form, the vocabulary term `cov:confirmable` can be used.
A value of `true` indicates that a CON request SHOULD be used by the Consumer, while a value of `false` indicates that a NON request SHOULD be used instead (for potential usages of the vocabulary term see [[[#example-request-con-non]]]).
However, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.
Comment on lines +215 to +221
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestions made against this content in index.html also apply to this content in index.template.html. But I don't understand why these files contain so much duplication.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI: the duplication comes from the fact that based on index.template.html and additional resources like ontologies etc. the final index.html is generated. Hence, it is sufficient to fix index.template.html and tooling will do the rest.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hence, it is sufficient to fix index.template.html and tooling will do the rest.

That would be true only if index.html contains nothing in addition to what is in index.template.html. Rather, "it is sufficient to fix index.template.html where it is duplicated in index.html, and fix index.html where it is not duplicated from index.template.html, and then tooling will do the rest".

Lacking anything highlighting the differences between index.template.html and index.html, reviewing these is thereby made a much larger effort.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a render script in place that uses index.template.html and adds additional parts to it (based on other resources like ontologies). The result will be stored in index.html. Hence, changing index.html only does not have any effect, since a subsequent render task will override it again. See https://github.com/w3c/wot-binding-templates?tab=readme-ov-file#tooling

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So index.template.heml is not a template, and index.html is an output artifact, which means it shouldn't be under git management, unless it is stored to a different folder of the repo, which clearly indicates that its contents are such artifacts.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In contrast to non-confirmable messages, confirmable messages are required to be acknowledged by the receiving endpoint and are otherwise retransmitted until an acknowledgement has been received.
Using non-confirmable requests can be useful for sensor data (that gets sent repeatedly and therefore does not need to be transmitted reliably), while confirmable requests provide a certain reliability that is useful for retrieving values or invoking actions that should not fail.
</p>
<p>
To provide a hint whether CON or NON requests should be used for accessing a CoAP resource associated with a form, the vocabulary term `cov:confirmable` can be used.
A value of `true` indicates that a CON request SHOULD be used by the Consumer, while a value of `false` indicates that a NON request SHOULD be used instead (for potential usages of the vocabulary term see [[[#example-request-con-non]]]).
However, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.
In contrast to non-confirmable messages, confirmable messages are required to be acknowledged by the receiving endpoint and are otherwise retransmitted until an acknowledgement has been received.
Using non-confirmable requests can be useful for sensor data (that gets sent repeatedly and therefore does not need to be transmitted reliably), while confirmable requests provide a certain reliability that is useful for retrieving values or invoking actions that should not fail.
</p>
<p>
The vocabulary term `cov:confirmable` can be used to provide a hint whether CON or NON requests are expected to be better for accessing a CoAP resource associated with a form.
A value of `true` encourages the Consumer to use CON requests, while a value of `false` encourages the Consumer to use NON requests. (For potential uses of the vocabulary term, see [[[#example-request-con-non]]].)
Note that, as the vocabulary term is just a hint, the consumer is not bound to this recommendation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So index.template.heml is not a template, and index.html is an output artifact, which means it shouldn't be under git management, unless it is stored to a different folder of the repo, which clearly indicates that its contents are such artifacts.

We are slowly getting there as that was also what @lu-zero suggested :) Btw, this is the same in wot-thing-description repository. Sorry for the confusion and thank you for reviewing!

When `cov:confirmable` is absent from a CoAP form, the consumer can choose freely between CON and NON requests as there is no default value defined.
</p>
<p>
When using reliable transport protocols (such as TCP) that ensure that messages are delivered, the distinction between confirmable and non-confirmable messages is not being made at the protocol level.
Therefore, when using one of these CoAP variants, the vocabulary term `cov:confirmable` is simply ignored by a WoT consumer.
</p>
<pre id="example-request-con-non" class="example" title="A Thing Description containing CoAP forms with hints for confirmable and non-confirmable requests.">
{
"@context": "https://www.w3.org/2022/wot/td/v1.1",
...
"properties": {
"currentTemperature": {
"title": "Latest temperature value",
"description": "Returns the latest temperature value recorded.",
"type": "number",
"forms": [
{
"href": "coap://[2001:DB8::1]/currentTemperature",
"cov:confirmable": true,
"op": "readproperty"
}
]
}
},
"action": {
"recordTemperature": {
"title": "Record temperature value",
"description": "Record a temperature value (e.g., from a sensor node).",
"input": {
"type": "number"
},
"forms": [
{
"href": "coap://[2001:DB8::1]/recordTemperature",
"cov:confirmable": false
}
]
}
}
}
</pre>
<p>
The <code>contentType</code> and <code>contentCoding</code> members of a form specify the CoAP content format of the request and/or response.
In <abbr title="Constrained Application Protocol">CoAP</abbr>, combinations of content type and content coding are encoded using standardized values listed in the <a href="https://www.iana.org/assignments/core-parameters/#content-formats">IANA CoAP Content-Formats registry</a>.
Expand Down
16 changes: 11 additions & 5 deletions bindings/protocols/coap/mapping.ttl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,36 +47,42 @@
] ;
sh:property [
sh:order 2 ;
sh:path cov:confirmable ;
sh:datatype xsd:boolean ;
sh:maxCount 1 ;
] ;
sh:property [
sh:order 3 ;
sh:path cov:minPollingInterval ;
sh:datatype xsd:unsignedInt ;
sh:maxCount 1 ;
] ;
sh:property [
sh:order 3 ;
sh:order 4 ;
sh:path cov:blockwise ;
sh:class cov:BlockWiseTransferParameters ;
sh:maxCount 1 ;
] ;
sh:property [
sh:order 4 ;
sh:order 5 ;
sh:path cov:qblockwise ;
sh:class cov:BlockWiseTransferParameters ;
sh:maxCount 1 ;
] ;
sh:property [
sh:order 5 ;
sh:order 6 ;
sh:path cov:hopLimit ;
sh:datatype xsd:unsignedByte ;
sh:maxCount 1 ;
] ;
sh:property [
sh:order 6 ;
sh:order 7 ;
sh:path cov:contentFormat ;
sh:datatype xsd:unsignedShort ;
sh:maxCount 1 ;
] ;
sh:property [
sh:order 7 ;
sh:order 8 ;
sh:path cov:accept ;
sh:datatype xsd:unsignedShort ;
sh:maxCount 1 ;
Expand Down
1 change: 1 addition & 0 deletions bindings/protocols/coap/ontology.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ <h2>Introduction</h2>
<section><h4>qblockwise</h4><p>IRI: <code>https://www.w3.org/2019/wot/coap#qblockwise</code></p><span>Indicates that quick block-wise transfer [[RFC9177]] is supported.</span><table class="def"><tbody><tr><td>Range</td><td><code><a href="#blockwisetransferparameters">BlockWiseTransferParameters</a></code></td></tr></tbody></table></section></section><section><h3>Datatype Properties</h3><section><h4>accept</h4><p>IRI: <code>https://www.w3.org/2019/wot/coap#accept</code></p><span>Indicates that a Consumer must include an Accept option [[RFC7252]] with the given value when requesting the resource associated with this Form.</span><table class="def"><tbody><tr><td>Range</td><td><code><a href="http://www.w3.org/2001/XMLSchema#unsignedShort">unsignedShort</a></code></td></tr></tbody></table></section>
<section><h4>block1Size</h4><p>IRI: <code>https://www.w3.org/2019/wot/coap#block1Size</code></p><span>Indicates the largest block size that may be used in a Block1 or Q-Block1 Option</span><table class="def"><tbody><tr><td>Domain includes</td><td><code><a href="#blockwisetransferparameters">BlockWiseTransferParameters</a></code></td></tr><tr><td>Domain</td><td><code><a href="#blockwisetransferparameters">BlockWiseTransferParameters</a></code></td></tr><tr><td>Range</td><td><code><a href="http://www.w3.org/2001/XMLSchema#unsignedShort">unsignedShort</a></code></td></tr></tbody></table></section>
<section><h4>block2Size</h4><p>IRI: <code>https://www.w3.org/2019/wot/coap#block2Size</code></p><span>Indicates the largest block size that may be used in a Block2 or Q-Block2 Option</span><table class="def"><tbody><tr><td>Domain includes</td><td><code><a href="#blockwisetransferparameters">BlockWiseTransferParameters</a></code></td></tr><tr><td>Domain</td><td><code><a href="#blockwisetransferparameters">BlockWiseTransferParameters</a></code></td></tr><tr><td>Range</td><td><code><a href="http://www.w3.org/2001/XMLSchema#unsignedShort">unsignedShort</a></code></td></tr></tbody></table></section>
<section><h4>confirmable</h4><p>IRI: <code>https://www.w3.org/2019/wot/coap#confirmable</code></p><span>Provides a hint for Consumers to use confirmable (`true`) or non-confirmable (`false`) requests with a particular resource. Only applicable to CoAP over UDP/DTLS [[RFC7252]].</span><table class="def"><tbody><tr><td>Range</td><td><code><a href="http://www.w3.org/2001/XMLSchema#boolean">boolean</a></code></td></tr></tbody></table></section>
<section><h4>contentFormat</h4><p>IRI: <code>https://www.w3.org/2019/wot/coap#contentFormat</code></p><span>Specifies the Content-Format to be used by a client for input data and the Content-Format to be used by a server for output data (where applicable). The value must be the numeric Content-Format ID registered with IANA for the combination of the <code>contentType</code> and <code>contentCoding</code> specified in the same form.</span><table class="def"><tbody><tr><td>Range</td><td><code><a href="http://www.w3.org/2001/XMLSchema#unsignedShort">unsignedShort</a></code></td></tr></tbody></table></section>
<section><h4>hopLimit</h4><p>IRI: <code>https://www.w3.org/2019/wot/coap#hopLimit</code></p><span>Indicates that a CoAP Hop-Limit option [[RFC8768]] should be included in the request.</span><table class="def"><tbody><tr><td>Range</td><td><code><a href="http://www.w3.org/2001/XMLSchema#unsignedByte">unsignedByte</a></code></td></tr></tbody></table></section>
<section><h4>method</h4><p>IRI: <code>https://www.w3.org/2019/wot/coap#method</code></p><span>Indicates the CoAP method to be used in the request.</span><table class="def"><tbody><tr><td>Range</td><td><code><a href="http://www.w3.org/2001/XMLSchema#string">string</a></code></td></tr></tbody></table></section>
Expand Down
6 changes: 6 additions & 0 deletions bindings/protocols/coap/ontology.ttl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,12 @@ cov:minPollingInterval a rdf:Property, owl:DatatypeProperty ;
rdfs:isDefinedBy <> ;
rdfs:label "minPollingInterval"@en .

cov:confirmable a rdf:Property, owl:DatatypeProperty ;
rdfs:range xsd:boolean ;
rdfs:comment "Provides a hint for Consumers to use confirmable (`true`) or non-confirmable (`false`) requests with a particular resource. Only applicable to CoAP over UDP/DTLS [[RFC7252]]."@en ;
rdfs:isDefinedBy <> ;
rdfs:label "confirmable"@en .

cov:blockwise a rdf:Property, owl:ObjectProperty ;
rdfs:range cov:BlockWiseTransferParameters ;
rdfs:comment "Indicates that block-wise transfer [[RFC7959]] is supported."@en ;
Expand Down