From 8e0d953124032dea6ce35273750316003be67589 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 17 Aug 2020 11:03:55 +0300 Subject: [PATCH 1/4] Fix ReSpec errors Signed-off-by: Zoltan Kis --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index a6f0b28d..fdc01b82 100644 --- a/index.html +++ b/index.html @@ -52,7 +52,7 @@ ] }, ], - xref: "web-platform", + xref: ["web-platform", "streams"], localBiblio: { "WOT-ARCHITECTURE" : { href:"https://www.w3.org/TR/2019/CR-wot-architecture-20190516/", @@ -546,7 +546,7 @@

The InteractionOutput interface

WoT Interactions as a {{ReadableStream}}, initially `null`.

- The dataUsed property tells whether the data stream has + The dataUsed property tells whether the data stream has been disturbed. Initially `false`.

From 40689533c91fd27543b35280ff429687fba414cb Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Mon, 17 Aug 2020 10:55:17 +0300 Subject: [PATCH 2/4] Address #230: update first chapters Signed-off-by: Zoltan Kis --- index.html | 61 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 18 deletions(-) diff --git a/index.html b/index.html index fdc01b82..57640e35 100644 --- a/index.html +++ b/index.html @@ -52,7 +52,7 @@ ] }, ], - xref: ["web-platform", "streams"], + 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/", @@ -116,19 +116,24 @@

- 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]] document. +

+

+ 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.

@@ -145,7 +150,7 @@

Introduction

WoT provides layered interoperability based on how Things are used: - "consumed" and "exposed", as defined in [[WOT-ARCHITECTURE]]. + "consumed" and "exposed", as defined in [[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 @@

Consuming a Thing

  • - Consume a TD, i.e. create a programmatic object from a Thing Description that exposes WoT Interactions: + Consume a TD, i.e. create a programmatic object from a + Thing Description that exposes WoT Interactions:
    • @@ -203,17 +209,31 @@

    Exposing a Thing

    • - Exposing the Thing includes generating the protocol bindings in order to access lower level functionality. + Exposing the Thing includes generating the protocol bindings in + order to access lower level functionality. +
      • +
    • + Create a local Thing to be exposed, based on Thing Description.
    • - Create a local Thing to be exposed, based on a Thing Description provided in string serialized format, or out of an existing Thing object. + The following use cases can be implemented before creating the + Thing by editing the Thing Description: + +

      + 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. +

      • -
    • Add a Property definition to the Thing.
      • -
    • Remove a Property definition from the Thing.
      • -
    • Add an Action definition to the Thing.
      • -
    • Remove an Action definition from the Thing.
      • -
    • Add a WoT Event definition to the Thing.
      • -
    • Remove a WoT Event definition from the Thing.
    • Emit a WoT Event, i.e. notify all subscribed listeners.
      • @@ -221,9 +241,13 @@
      • to retrieve a Property value;
      • to update a Property value;
        • +
      • to observe a Property;
        • +
      • to unobserve a Property;
      • to invoke an Action: take the parameters from the request, execute the defined action, and return the result;
        • +
      • to subscribe to an Event;
        • +
      • to unsubscribe from an Event.
    @@ -233,8 +257,9 @@
    • Discover Things in a network by sending a broadcast request.
    • Discover Things running in the local WoT Runtime.
      • -
    • Discover nearby Things, for instance connected by NFC or Bluetooth.
      • -
    • Discover Things by sending a discovery request to a given registry.
      • +
    • Discover nearby Things, for instance connected by NFC or Bluetooth, + or within a geo-fence.
      • +
    • Discover Things by sending a discovery request to a given Thing Directory.
    • Discover Things filtered by filters defined on Thing Descriptions
    • Discover Things filtered by semantic queries.
    • Stop or suppress an ongoing discovery process.
      • From ada430cbf8424f7fb9196778b28a5dd92433cc85 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 18 Aug 2020 15:27:33 +0300 Subject: [PATCH 3/4] Make refs to other WoT specs direct links Signed-off-by: Zoltan Kis --- index.html | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/index.html b/index.html index 57640e35..227c195a 100644 --- a/index.html +++ b/index.html @@ -119,7 +119,7 @@ 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 main Web of Things (WoT) concepts are described in the [[WOT-ARCHITECTURE]] document. + 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 @@ -129,7 +129,7 @@ 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-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). + 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 Eclipse Thingweb @@ -150,7 +150,7 @@

      Introduction

      WoT provides layered interoperability based on how Things are used: - "consumed" and "exposed", as defined in [[WOT-ARCHITECTURE]] terminology. + "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. @@ -351,9 +351,9 @@

      The ThingDescription type

      Expanding a Thing Description

      - 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.

      @@ -495,7 +495,7 @@

      The WOT namespace

      Handling interaction data

      - 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 @@ -1104,7 +1104,7 @@

      parsed JSON objects defined in [[!WOT-TD]].

      - 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 @@ -3489,7 +3489,7 @@

      API design rationale

      lock.open('withThisKey');
      -

      This API, aligned with [[WOT-TD]]

      +

      This API, aligned with the [[[WOT-TD]]] specification

      Since the direct mapping of Things to software objects have had some challenges, this specification takes another approach that @@ -3515,11 +3515,11 @@

      API design rationale

      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 @@ -3533,8 +3533,9 @@

      API design rationale

      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.

      Factory vs constructors

      @@ -3571,7 +3572,7 @@

      API design rationale

      Polymorphic functions

      - 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 [[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.

      From 1ec0a9e103f904a15b041281e533fb3b10da893c Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Tue, 18 Aug 2020 22:57:12 +0300 Subject: [PATCH 4/4] Replace void with undefined as WebIDL spec changed Signed-off-by: Zoltan Kis --- index.html | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/index.html b/index.html index 227c195a..5fd0b136 100644 --- a/index.html +++ b/index.html @@ -1012,23 +1012,23 @@

      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(); }; @@ -1041,7 +1041,7 @@

      The ConsumedThing interface

      typedef object PropertyMap; - callback WotListener = void(InteractionOutput data); + callback WotListener = undefined(InteractionOutput data);
      @@ -1760,16 +1760,16 @@

      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); @@ -1777,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>(); @@ -2935,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(); };