Skip to content

Address #230: update first chapters #234

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

Merged
merged 4 commits into from
Aug 19, 2020
Merged

Address #230: update first chapters #234

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8e0d953
Fix ReSpec errors
zolkis Aug 17, 2020
4068953
Address #230: update first chapters
zolkis Aug 17, 2020
ada430c
Make refs to other WoT specs direct links
zolkis Aug 18, 2020
1ec0a9e
Replace void with undefined as WebIDL spec changed
zolkis Aug 18, 2020
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
114 changes: 70 additions & 44 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@
]
},
],
xref: "web-platform",
xref: ["web-platform", "streams", "wot-architecture", "wot-thing-description", "wot-binding-templates"],
localBiblio: {
"WOT-ARCHITECTURE" : {
href:"https://www.w3.org/TR/2019/CR-wot-architecture-20190516/",
Expand Down Expand Up @@ -116,19 +116,24 @@

<section id="abstract">
<p>
The main <a>Web of Things</a> (WoT) concepts are described in the <a href="https://www.w3.org/TR/2019/CR-wot-architecture-20190516/">WoT Architecture</a> document. The Web of Things is made of entities (<a>Thing</a>s) that can describe their capabilities in a machine-interpretable <a>Thing Description</a> (TD) and expose these capabilities through the <a>WoT Interface</a>, that is, network interactions modeled as <a>Properties</a> (for reading and writing values), <a>Action</a>s (to execute remote procedures with or without return values) and <a>Event</a>s (for signaling notifications).
The Web of Things is made of entities (<a>Thing</a>s) that can describe their capabilities in a machine-interpretable <a>Thing Description</a> (TD) and expose these capabilities through the <a>WoT Interface</a>, that is, network interactions modeled as <a>Properties</a> (for reading and writing values), <a>Action</a>s (to execute remote procedures with or without return values) and <a>Event</a>s (for signaling notifications).
</p>
<p>
Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a <a>WoT Runtime</a> and <a href="https://github.com/w3c/wot-scripting-api/tree/master/applications/script-manager">script management</a>, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications such as <a href="https://github.com/w3c/wot-scripting-api/tree/master/applications/thing-directory">Thing Directory</a>.
The main <a>Web of Things</a> (WoT) concepts are described in the [[[WOT-ARCHITECTURE]]] specification.
</p>
<p>
Scripting is an optional building block in WoT and it is typically used in gateways or browsers that are able to run a <a>WoT Runtime</a> and
<a href="https://github.com/w3c/wot-scripting-api/tree/master/applications/script-manager">script management</a>, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications such as <a href="https://github.com/w3c/wot-scripting-api/tree/master/applications/thing-directory">Thing Directory</a>.
Copy link
Contributor

Choose a reason for hiding this comment

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

w.r.t. https://github.com/w3c/wot-scripting-api/tree/master/applications/script-manager
I am not 100% sure how we deal with it but https://github.com/w3c/wot-scripting-api/tree/master/applications/script-manager uses a very out-dated TD form.
Shall I try to propose a PR with an updated form. Is there more we should do?

w.r.t. https://github.com/w3c/wot-scripting-api/tree/master/applications/thing-directory
Also outdated code snippets... mhhh

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes, we discussed in yesterday's call that we need to update the auxiliary documents, including the script manager (or remove the reference from here).

Same for Thing Directory (which got a new definition in the current charter).

</p>
<p>
This specification describes a programming interface representing the <a>WoT Interface</a> that allows scripts to discover, operate <a>Thing</a>s and to expose locally defined <a>Things</a> characterized by <a> WoT Interactions</a> specified by a script.
</p>
<p>
The specification deliberately follows the <a href="https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/">WoT Thing Description specification</a> closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the <a>WoT Interface</a>).
The specification deliberately follows the [[[WOT-TD]]] specification closely. It is possible to implement simpler APIs on top of this API, or implementing directly the WoT network facing interface (i.e. the <a>WoT Interface</a>).
</p>
<p class="ednote">
This specification is implemented at least by the <a href="http://www.thingweb.io/">Thingweb</a> project also known as <a href="https://github.com/eclipse/thingweb.node-wot">node-wot</a>, which is considered the reference open source implementation at the moment. Check its <a href="https://github.com/eclipse/thingweb.node-wot"> source code</a>, including <a href="https://github.com/eclipse/thingweb.node-wot">examples</a>. Other, closed source implementations have been made by WG member companies and tested against <a href="https://github.com/eclipse/thingweb.node-wot">node-wot</a> in plug-fests.
This specification is implemented at least by the <a href="http://www.thingweb.io/">Eclipse Thingweb</a>
project also known as <a href="https://github.com/eclipse/thingweb.node-wot">node-wot</a>, which is considered the reference open source implementation at the moment. Check its <a href="https://github.com/eclipse/thingweb.node-wot"> source code</a>, including <a href="https://github.com/eclipse/thingweb.node-wot/examples">examples</a>.
</p>
</section>

Expand All @@ -145,7 +150,7 @@
<section id="introduction"> <h2>Introduction</h2>
<p>
WoT provides layered interoperability based on how <a>Thing</a>s are used:
"consumed" and "exposed", as <a href="https://www.w3.org/TR/2019/CR-wot-architecture-20190516/#terminology">defined</a> in [[WOT-ARCHITECTURE]].
"consumed" and "exposed", as defined in the [[[WOT-ARCHITECTURE]]] terminology.
</p>
<p>
By <a>consuming a TD</a>, a client <a>Thing</a> creates a local runtime resource model that allows accessing the <a>Properties</a>, <a>Actions</a> and <a>Events</a> exposed by the server <a>Thing</a> on a remote device.
Expand Down Expand Up @@ -185,15 +190,16 @@
<section><h4>Consuming a Thing</h4>
<ul>
<li>
<a>Consume a TD</a>, i.e. create a programmatic object from a <a>Thing Description</a> that exposes <a>WoT Interactions</a>:
<a>Consume a TD</a>, i.e. create a programmatic object from a
<a>Thing Description</a> that exposes <a>WoT Interactions</a>:
<ul>
<li>Read the value of a <a>Property</a> or a set of properties.</li>
<li>Set the value of a <a>Property</a> or a set of properties.</li>
<li>Observe value changes of a <a>Property</a>.</li>
<li>Invoke an <a>Action</a>.</li>
<li>Observe WoT <a>Events</a> emitted by the <a>Thing</a>.</li>
<li>
Introspect the <a>Thing Description</a>, including the list of linked resources based on the <a>Thing Description</a>.
Introspect the <a>Thing Description</a>.
</li>
</ul>
</li>
Expand All @@ -203,27 +209,45 @@
<section><h4>Exposing a Thing</h4>
<ul>
<li>
Exposing the <a>Thing</a> includes generating the protocol bindings in order to access lower level functionality.
Exposing the <a>Thing</a> includes generating the protocol bindings in
order to access lower level functionality.
</li>
<li>
Create a local <a>Thing</a> to be exposed, based on <a>Thing Description</a>.
</li>
<li>
Create a local <a>Thing</a> to be exposed, based on a <a>Thing Description</a> provided in string serialized format, or out of an existing <a>Thing</a> object.
The following use cases can be implemented before creating the
<a>Thing</a> by editing the <a>Thing Description</a>:
<ul>
<li>Add a <a>Property</a> definition to the <a>Thing</a>.</li>
<li>Remove a <a>Property</a> definition from the <a>Thing</a>.</li>
<li>Add an <a>Action</a> definition to the <a>Thing</a>.</li>
<li>Remove an <a>Action</a> definition from the <a>Thing</a>.</li>
<li>Add a WoT <a>Event</a> definition to the <a>Thing</a>.</li>
<li>Remove a WoT <a>Event</a> definition from the <a>Thing</a>.</li>
</ul>
<p class="ednote">
After evaluating dynamic modifications to <a>Thing Descriptions</a>
through several versions of this API, the editors concluded that the
simplest way to represent these use cases is to take an existing
<a>TD</a>, modify it (i.e. add or remove definitions) and then create
a new <a>Thing</a> based on the modified <a>TD</a>.
</p>
</li>
<li>Add a <a>Property</a> definition to the <a>Thing</a>.</li>
<li>Remove a <a>Property</a> definition from the <a>Thing</a>.</li>
<li>Add an <a>Action</a> definition to the <a>Thing</a>.</li>
<li>Remove an <a>Action</a> definition from the <a>Thing</a>.</li>
<li>Add a WoT <a>Event</a> definition to the <a>Thing</a>.</li>
<li>Remove a WoT <a>Event</a> definition from the <a>Thing</a>.</li>
<li>
Emit a WoT <a>Event</a>, i.e. notify all subscribed listeners.
</li>
<li>Register service handlers for external requests:
<ul>
<li>to retrieve a <a>Property</a> value;</li>
<li>to update a <a>Property</a> value;</li>
<li>to observe a <a>Property</a>;</li>
<li>to unobserve a <a>Property</a>;</li>
<li>
to invoke an <a>Action</a>: take the parameters from the request, execute the defined action, and return the result;
</li>
<li>to subscribe to an <a>Event</a>;</li>
<li>to unsubscribe from an <a>Event</a>.</li>
</ul>
</li>
</ul>
Expand All @@ -233,8 +257,9 @@
<ul>
<li>Discover <a>Thing</a>s in a network by sending a broadcast request.</li>
<li>Discover <a>Thing</a>s running in the local <a>WoT Runtime</a>.</li>
<li>Discover nearby <a>Thing</a>s, for instance connected by NFC or Bluetooth.</li>
<li>Discover <a>Thing</a>s by sending a discovery request to a given registry.</li>
<li>Discover nearby <a>Thing</a>s, for instance connected by NFC or Bluetooth,
or within a <a href="https://en.wikipedia.org/wiki/Geo-fence">geo-fence</a>.</li>
<li>Discover <a>Thing</a>s by sending a discovery request to a given <a>Thing Directory</a>.</li>
<li>Discover <a>Thing</a>s filtered by filters defined on <a>Thing Description</a>s</li>
<li>Discover <a>Thing</a>s filtered by semantic queries.</li>
<li>Stop or suppress an ongoing discovery process.</li>
Expand Down Expand Up @@ -326,9 +351,9 @@ <h2>The <dfn>ThingDescription</dfn> type</h2>

<section> <h3>Expanding a Thing Description</h3>
<p>
Note that [[WOT-TD]] allows using a shortened <a>Thing Description</a>
by the means of <a href="https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#sec-default-values">defaults</a> and requiring clients to expand them with default values specified in
[[WOT-TD]] for the properties that are not explicitly defined in a given
Note that the [[[WOT-TD]]] specification allows using a shortened <a>Thing Description</a>
by the means of <a href="https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#sec-default-values">defaults</a> and requiring clients to expand them with default values specified in the
[[[WOT-TD]]] specification for the properties that are not explicitly defined in a given
<a>TD</a>.
</p>
<div>
Expand Down Expand Up @@ -470,7 +495,7 @@ <h2>The <dfn>WOT</dfn> namespace</dfn></h2>

<section> <h2>Handling interaction data</h2>
<p>
As specified in [[WOT-TD]], <a>WoT interactions</a> extend <a>DataSchema</a>
As specified in the [[[WOT-TD]]] specification, <a>WoT interactions</a> extend <a>DataSchema</a>
and include a number of possible <a>Form</a>s, out of which one is selected
for the interaction. The
<a href="https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#form">
Expand Down Expand Up @@ -546,7 +571,7 @@ <h2>The <dfn>InteractionOutput</dfn> interface</h2>
<a>WoT Interactions</a> as a {{ReadableStream}}, initially `null`.
</p>
<p>
The <dfn>dataUsed</dfn> property tells whether the <a>data</a> stream has
The <dfn>dataUsed</dfn> property tells whether the data stream has
been <a href="https://fetch.spec.whatwg.org/#concept-readablestream-disturbed">
disturbed</a>. Initially `false`.
</p>
Expand Down Expand Up @@ -987,23 +1012,23 @@ <h2>The <dfn>ConsumedThing</dfn> interface</h2>
Promise&lt;PropertyMap&gt; readMultipleProperties(
sequence&lt;DOMString&gt; propertyNames,
optional InteractionOptions options = null);
Promise&lt;void&gt; writeProperty(DOMString propertyName,
Promise&lt;undefined&gt; writeProperty(DOMString propertyName,
InteractionInput value,
optional InteractionOptions options = null);
Promise&lt;void&gt; writeMultipleProperties(PropertyMap valueMap,
Promise&lt;undefined&gt; writeMultipleProperties(PropertyMap valueMap,
optional InteractionOptions options = null);
Promise&lt;InteractionOutput&gt; invokeAction(DOMString actionName,
optional InteractionInput params = null,
optional InteractionOptions options = null);
Promise&lt;void&gt; observeProperty(DOMString name,
Promise&lt;undefined&gt; observeProperty(DOMString name,
WotListener listener,
optional InteractionOptions options = null);
Promise&lt;void&gt; unobserveProperty(DOMString name,
Promise&lt;undefined&gt; unobserveProperty(DOMString name,
optional InteractionOptions options = null);
Promise&lt;void&gt; subscribeEvent(DOMString name,
Promise&lt;undefined&gt; subscribeEvent(DOMString name,
WotListener listener,
optional InteractionOptions options = null);
Promise&lt;void&gt; unsubscribeEvent(DOMString name,
Promise&lt;undefined&gt; unsubscribeEvent(DOMString name,
optional InteractionOptions options = null);
ThingDescription getThingDescription();
};
Expand All @@ -1016,7 +1041,7 @@ <h2>The <dfn>ConsumedThing</dfn> interface</h2>

typedef object PropertyMap;

callback WotListener = void(InteractionOutput data);
callback WotListener = undefined(InteractionOutput data);
</pre>

<section>
Expand Down Expand Up @@ -1079,7 +1104,7 @@ <h3>
parsed JSON objects</a> defined in [[!WOT-TD]].
</p>
<p class="ednote">
The support for URI variables comes from the need exposed by [[WOT-TD]] to be able to describe existing <a>TD</a>s that use them, but it should be possible to write a <a>Thing Description</a> that would use <a>Action</a>s for representing the interactions that need URI variables and represent the URI variables as parameters to the <a>Action</a> and in that case that could be encapsulated by the implementations and the |options| parameter could be dismissed from the methods exposed by this API.
The support for URI variables comes from the need exposed by the [[[WOT-TD]]] specification to be able to describe existing <a>TD</a>s that use them, but it should be possible to write a <a>Thing Description</a> that would use <a>Action</a>s for representing the interactions that need URI variables and represent the URI variables as parameters to the <a>Action</a> and in that case that could be encapsulated by the implementations and the |options| parameter could be dismissed from the methods exposed by this API.
</p>
<p>
The <dfn>data</dfn> property if defined, represents additional opaque
Expand Down Expand Up @@ -1735,24 +1760,24 @@ <h2>The <dfn>ExposedThing</dfn> interface</h2>
EventSubscriptionHandler handler);
ExposedThing setEventHandler(DOMString name,
EventListenerHandler eventHandler);
void emitEvent(DOMString name, InteractionInput data);
undefined emitEvent(DOMString name, InteractionInput data);

Promise&lt;void&gt; expose();
Promise&lt;void&gt; destroy();
Promise&lt;undefined&gt; expose();
Promise&lt;undefined&gt; destroy();
};

callback PropertyReadHandler = Promise&lt;any&gt;(
optional InteractionOptions options = null);

callback PropertyWriteHandler = Promise&lt;void&gt;(
callback PropertyWriteHandler = Promise&lt;undefined&gt;(
InteractionOutput value,
optional InteractionOptions options = null);

callback ActionHandler = Promise&lt;InteractionInput&gt;(
InteractionOutput params,
optional InteractionOptions options = null);

callback EventSubscriptionHandler = Promise&lt;void&gt;(
callback EventSubscriptionHandler = Promise&lt;undefined&gt;(
optional InteractionOptions options = null);

callback EventListenerHandler = Promise&lt;InteractionInput&gt;();
Expand Down Expand Up @@ -2910,9 +2935,9 @@ <h2>The <dfn>ThingDiscovery</dfn> interface</h2>
readonly attribute boolean active;
readonly attribute boolean done;
readonly attribute Error? error;
void start();
undefined start();
Promise&lt;ThingDescription&gt; next();
void stop();
undefined stop();
};
</pre>
<p class="ednote">
Expand Down Expand Up @@ -3464,7 +3489,7 @@ <h2>API design rationale</h2>
lock.open('withThisKey');
</pre>
</section>
<section> <h3>This API, aligned with [[WOT-TD]]</h3>
<section> <h3>This API, aligned with the [[[WOT-TD]]] specification</h3>
<p>
Since the direct mapping of <a>Thing</a>s to software objects have had
some challenges, this specification takes another approach that
Expand All @@ -3490,11 +3515,11 @@ <h2>API design rationale</h2>
</section>
<p>
In conclusion, the WoT WG decided to explore the third option that
closely follows the [[WOT-TD]] specification. Based on this, a simple
closely follows the [[[WOT-TD]]] specification. Based on this, a simple
API can also be implemented.
Since Scripting is an optional module in WoT, this leaves room for
applications that only use the WoT network interface.
Therefore all three approaches above are supported by [[WOT-TD]].
Therefore all three approaches above are supported by the [[[WOT-TD]]] specification.
</p>
<p>
Moreover, the WoT network interface can be implemented in many languages
Expand All @@ -3508,8 +3533,9 @@ <h2>API design rationale</h2>
</p>
<p>
Since fetching a <a>TD</a> has been scoped out, and <a>TD</a> validation
is defined externally in [[WOT-TD]], that is scoped out, too. This specification expects a <a>TD</a> as
<a href="https://infra.spec.whatwg.org/#parse-json-from-bytes">parsed JSON object</a> that has been validated according to the [[WOT-TD]] specification.
is defined externally in the [[[WOT-TD]]] specification, that is scoped out, too.
This specification expects a <a>TD</a> as
<a href="https://infra.spec.whatwg.org/#parse-json-from-bytes">parsed JSON object</a> that has been validated according to the [[[WOT-TD]]] specification.
</p>
</section>
<section> <h4>Factory vs constructors</h4>
Expand Down Expand Up @@ -3546,7 +3572,7 @@ <h2>API design rationale</h2>
</section>
<section> <h4>Polymorphic functions</h4>
<p>
The reason to use function names like <code>readProperty()</code>, <code>readMultipleProperties()</code> etc. instead of a generic polymorphic <code>read()</code> function is that the current names map exactly to the <code>"op"</code> vocabulary from the <a href="https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#form">Form</a> definition in [[WOT-TD]].
The reason to use function names like <code>readProperty()</code>, <code>readMultipleProperties()</code> etc. instead of a generic polymorphic <code>read()</code> function is that the current names map exactly to the <code>"op"</code> vocabulary from the <a href="https://www.w3.org/TR/2019/CR-wot-thing-description-20190516/#form">Form</a> definition in the [[[WOT-TD]]] specification.
</p>
</section>
</section>
Expand Down