- The main Web of Things (WoT) concepts are described in the WoT Architecture document. The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable Thing Description (TD) and expose these capabilities through the WoT Interface, that is, network interactions modeled as Properties (for reading and writing values), Actions (to execute remote procedures with or without return values) and Events (for signaling notifications). + The Web of Things is made of entities (Things) that can describe their capabilities in a machine-interpretable Thing Description (TD) and expose these capabilities through the WoT Interface, that is, network interactions modeled as Properties (for reading and writing values), Actions (to execute remote procedures with or without return values) and Events (for signaling notifications).
- Scripting is an optional "convenience" building block in WoT and it is typically used in gateways that are able to run a WoT Runtime and script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications such as Thing Directory. + The main Web of Things (WoT) concepts are described in the [[[WOT-ARCHITECTURE]]] specification. +
++ Scripting is an optional building block in WoT and it is typically used in gateways or browsers that are able to run a WoT Runtime and + script management, providing a convenient way to extend WoT support to new types of endpoints and implement WoT applications such as Thing Directory.
This specification describes a programming interface representing the WoT Interface that allows scripts to discover, operate Things and to expose locally defined Things characterized by WoT Interactions specified by a script.
- The specification deliberately follows the WoT Thing Description 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 WoT Interface). + 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 WoT Interface).
- This specification is implemented at least by the Thingweb project also known as node-wot, which is considered the reference open source implementation at the moment. Check its source code, including examples. Other, closed source implementations have been made by WG member companies and tested against node-wot in plug-fests. + This specification is implemented at least by the Eclipse Thingweb + project also known as node-wot, which is considered the reference open source implementation at the moment. Check its source code, including examples.
WoT provides layered interoperability based on how Things are used: - "consumed" and "exposed", as defined in [[WOT-ARCHITECTURE]]. + "consumed" and "exposed", as defined in the [[[WOT-ARCHITECTURE]]] terminology.
By consuming a TD, a client Thing creates a local runtime resource model that allows accessing the Properties, Actions and Events exposed by the server Thing on a remote device.
@@ -185,7 +190,8 @@
+ After evaluating dynamic modifications to Thing Descriptions
+ through several versions of this API, the editors concluded that the
+ simplest way to represent these use cases is to take an existing
+ TD, modify it (i.e. add or remove definitions) and then create
+ a new Thing based on the modified TD.
+
- Note that [[WOT-TD]] allows using a shortened Thing Description
- by the means of defaults 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 Thing Description
+ by the means of defaults 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
TD.
- As specified in [[WOT-TD]], WoT interactions extend DataSchema
+ As specified in the [[[WOT-TD]]] specification, WoT interactions extend DataSchema
and include a number of possible Forms, out of which one is selected
for the interaction. The
@@ -546,7 +571,7 @@
- The dataUsed property tells whether the data stream has
+ The dataUsed property tells whether the data stream has
been
disturbed. Initially `false`.
- The support for URI variables comes from the need exposed by [[WOT-TD]] to be able to describe existing TDs that use them, but it should be possible to write a Thing Description that would use Actions for representing the interactions that need URI variables and represent the URI variables as parameters to the Action 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 TDs that use them, but it should be possible to write a Thing Description that would use Actions for representing the interactions that need URI variables and represent the URI variables as parameters to the Action 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 data property if defined, represents additional opaque
@@ -1735,16 +1760,16 @@
@@ -3464,7 +3489,7 @@
Since the direct mapping of Things to software objects have had
some challenges, this specification takes another approach that
@@ -3490,11 +3515,11 @@
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.
Moreover, the WoT network interface can be implemented in many languages
@@ -3508,8 +3533,9 @@
Since fetching a TD has been scoped out, and TD validation
- is defined externally in [[WOT-TD]], that is scoped out, too. This specification expects a TD as
- parsed JSON object 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 TD as
+ parsed JSON object that has been validated according to the [[[WOT-TD]]] specification.
- The reason to use function names like Consuming a Thing
Exposing a Thing
@@ -233,8 +257,9 @@
+
+
The ThingDescription type
Expanding a Thing Description
The WOT namespace
Handling interaction data
The InteractionOutput interface
WoT Interactions as a {{ReadableStream}}, initially `null`.
The ConsumedThing interface
Promise<PropertyMap> readMultipleProperties(
sequence<DOMString> propertyNames,
optional InteractionOptions options = null);
- Promise<void> writeProperty(DOMString propertyName,
+ Promise<undefined> writeProperty(DOMString propertyName,
InteractionInput value,
optional InteractionOptions options = null);
- Promise<void> writeMultipleProperties(PropertyMap valueMap,
+ Promise<undefined> writeMultipleProperties(PropertyMap valueMap,
optional InteractionOptions options = null);
Promise<InteractionOutput> invokeAction(DOMString actionName,
optional InteractionInput params = null,
optional InteractionOptions options = null);
- Promise<void> observeProperty(DOMString name,
+ Promise<undefined> observeProperty(DOMString name,
WotListener listener,
optional InteractionOptions options = null);
- Promise<void> unobserveProperty(DOMString name,
+ Promise<undefined> unobserveProperty(DOMString name,
optional InteractionOptions options = null);
- Promise<void> subscribeEvent(DOMString name,
+ Promise<undefined> subscribeEvent(DOMString name,
WotListener listener,
optional InteractionOptions options = null);
- Promise<void> unsubscribeEvent(DOMString name,
+ Promise<undefined> unsubscribeEvent(DOMString name,
optional InteractionOptions options = null);
ThingDescription getThingDescription();
};
@@ -1016,7 +1041,7 @@ The ConsumedThing interface
typedef object PropertyMap;
- callback WotListener = void(InteractionOutput data);
+ callback WotListener = undefined(InteractionOutput data);
parsed JSON objects defined in [[!WOT-TD]].
The ExposedThing interface
EventSubscriptionHandler handler);
ExposedThing setEventHandler(DOMString name,
EventListenerHandler eventHandler);
- void emitEvent(DOMString name, InteractionInput data);
+ undefined emitEvent(DOMString name, InteractionInput data);
- Promise<void> expose();
- Promise<void> destroy();
+ Promise<undefined> expose();
+ Promise<undefined> destroy();
};
callback PropertyReadHandler = Promise<any>(
optional InteractionOptions options = null);
- callback PropertyWriteHandler = Promise<void>(
+ callback PropertyWriteHandler = Promise<undefined>(
InteractionOutput value,
optional InteractionOptions options = null);
@@ -1752,7 +1777,7 @@ The ExposedThing interface
InteractionOutput params,
optional InteractionOptions options = null);
- callback EventSubscriptionHandler = Promise<void>(
+ callback EventSubscriptionHandler = Promise<undefined>(
optional InteractionOptions options = null);
callback EventListenerHandler = Promise<InteractionInput>();
@@ -2910,9 +2935,9 @@ The ThingDiscovery interface
readonly attribute boolean active;
readonly attribute boolean done;
readonly attribute Error? error;
- void start();
+ undefined start();
Promise<ThingDescription> next();
- void stop();
+ undefined stop();
};
API design rationale
lock.open('withThisKey');
This API, aligned with [[WOT-TD]]
+ This API, aligned with the [[[WOT-TD]]] specification
API design rationale
API design rationale
Factory vs constructors
@@ -3546,7 +3572,7 @@ API design rationale
Polymorphic functions
readProperty(), readMultipleProperties() etc. instead of a generic polymorphic read() function is that the current names map exactly to the "op" vocabulary from the Form definition in [[WOT-TD]].
+ The reason to use function names like readProperty(), readMultipleProperties() etc. instead of a generic polymorphic read() function is that the current names map exactly to the "op" vocabulary from the Form definition in the [[[WOT-TD]]] specification.