The ThingTemplate dictionary

A `ThingTemplate` is a dictionary that provides Thing related semantic metadata.

        typedef (object or USVString or sequence<USVString>) JsonLdDefinition;
        interface ThingTemplate {
          getter JsonLdDefinition (USVString name);
          setter void (USVString name, JsonLdDefinition value);
        };
      

The JsonLdDefinition type can be either a JSON object, a string representing an IRI, or an array of strings.

The ThingTemplate dictionary initializes a Thing:

• The @context attribute represents a semantic context as USVString.
• The @type attribute represents a semantic type as USVString.
• The @id attribute represents an identifier, typically a URI, IRI, or URN as USVString.
• The base attribute represents a base URL as USVString.
• The name attribute represents a user given name as DOMString.
• Apart from the core semantic properties defined above, others may also be defined on a Thing, for instance "gms:COVParams" (with namespace definition), or "iotschema:unit" etc.

Support for configuration and security metadata will be added later.

The ThingDescription type

Representation of the Thing Description, standardized in the [Wot Things Description](https://w3c.github.io/wot-thing-description/) specification.

In this version of the API, Thing Descriptions are represented as an opaque `USVString` representing a serialized TD.

The fetch() method

Accepts an url argument of type `USVString` and returns a Promise that resolves with a ThingDescription.

The consume() method

Accepts an td argument of type ThingDescription and returns a ConsumedThing object instantiated based on that description.

The produce() method

Accepts a model argument of type ThingTemplate and returns an ExposedThing object, locally created based on the provided initialization parameters. An ExposedThing can be created in the following ways:

1. from an initial model (including a user given name and semantic metadata properties), then adding Properties, Actions, Events and request handlers;
2. from a Thing Description (possibly of a ConsumedThing object), then adding request handlers.

The discover() method

Starts the discovery process that will provide ThingDescriptions that match the optional argument ThingFilter. When the argument is not provided, uses all supported discovery methods. Returns an [Observable](https://github.com/tc39/proposal-observable) object that can be subscribed to and unsubscribed from.

          typedef DOMString DiscoveryMethod;
        

          dictionary ThingFilter {
            DiscoveryMethod method = "any";
            USVString url;
            USVString query;
            sequence<Dictionary> constraints;
          };
        

Examples

        let discoveryFilter = {
          method: "directory",
          url: "http://directory.wotservice.org"
        };
        let subscription = wot.discover(discoveryFilter).subscribe(
          td => {
            console.log("Found Thing " + td.name);
            // fetch the TD and create a ConsumedThing
            let thing = wot.consume(td);
          },
          error => { console.log("Discovery finished because an error: " + error.message); },
          () => { console.log("Discovery finished successfully");}
        );
        setTimeout( () => {
            subscription.unsubscribe();
            console.log("Discovery timeout");
          },
          5000);
      

Note that canceling a discovery (through `unsubscribe()`) may not be successful in all cases, for instance when discovery is based on open ended broadcast requests. However, once `unsubscribe()` has been called, implementations MUST suppress further event handling ( i.e. further discoveries and errors) on the Observable. Also, a discovery error may not mean the end of the discovery process. However, in order to respect Observable semantics (error always terminates processing), implementations MUST close or suppress further event handling on the Observable.

        let subscription = wot.discover({ method: "local" }).subscribe(
          td => { console.log("Found local Thing " + td.name); },
          error => { console.log("Discovery error: " + error.message); },
          () => { console.log("Discovery finished successfully");}
        );
      

        let subscription = wot.discover({ method: "local" }).subscribe({
          td => { console.log("Found local Thing " + td.name); },
          error: err => { console.log("Discovery error: " + err.message); },
          complete: () => { console.log("Discovery finished successfully");}
        });
      

        let subscription = wot.discover({
          method: "ble",
          constraints: [{ protocol: "BLE-4.2" }]
        }).subscribe(
          td => { console.log("Found nearby Thing " + td.name); },
          error => { console.log("Discovery error: " + error.message); },
          () => { console.log("Discovery finished successfully");}
        );
      

        let subscription = wot.discover({
          method: "other",
          constraints: [{ solution: "XYZ123", key: "..."}]
        }).subscribe(
          td => { console.log("Found Thing " + td.name); },
          error => { console.log("Discovery error: " + error.message); },
          () => { console.log("Discovery finished successfully");}
        );
      

Examples

Below a ConsumedThing interface example is given.

        try {
          let td = await wot.discover({ url: "http://mmyservice.org/mySensor"});
          let thing = wot.consume(td);
          console.log("Thing " + thing.name + " has been consumed.");
          let subscription = thing.onPropertyChange("temperature")
            .subscribe(function(value) {
              console.log("Temperature + " has changed to " + value);
            });
          thing.actions["startMeasurement"].run({ units: "Celsius" })
            .then(() => { console.log("Temperature measurement started."); })
            .catch(e => {
               console.log("Error starting measurement.");
               subscription.unsubscribe();
             })
        } catch(error) {
          console.log("Error during fetch or consume: " + error.message);
        };
      

The expose() method

Start serving external requests for the Thing.

The register() method

Generates the Thing Description given the properties, Actions and Event defined for this object. If a directory argument is given, make a request to register the Thing Description with the given WoT repository by invoking its register Action.

The unregister() method

If a directory argument is given, make a request to unregister the Thing Description with the given WoT repository by invoking its unregister Action.

The destroy() method

Stop serving external requests for the Thing and destroy the object. Note that eventual unregistering should be done before invoking this method.

The emitEvent() method

Emits an the event initialized with the event name specified by the eventName argument and data specified by the payload argument.

The DataSchema type

        typedef USVString DataSchema;
      

The DataSchema type represents a data type specified in the Thing Description in a serialized form.

DataSchema is under development, currently it can denote any type supported by the Thing Description and the WoT Runtime.

The addProperty() method

Adds a Property defined by the argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

          dictionary ThingPropertyInit: ThingTemplate {
            required DataSchema schema;
            any value;
            boolean writable = false;
            boolean observable = false;
          };
        

The removeProperty() method

Removes the Property specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

The addAction() method

Adds an Action to the Thing object as defined by the action argument of type ThingAction and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

          dictionary ThingActionInit: ThingTemplate {
            DataSchema inputSchema;
            DataSchema outputSchema;
          };
      

The removeAction() method

Removes the Action specified by the name argument and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

The addEvent() method

Adds an event to the Thing object as defined by the event argument of type ThingEvent and updates the Thing Description. Throws on error. Returns a reference to the same object for supporting chaining.

          dictionary ThingEventInit: ThingTemplate {
            required DOMString name;
            DataSchema schema;
          };
        

The removeEvent() method

Removes the event specified by the name argument and updates the Thing Description. Returns a reference to the same object for supporting chaining.

The PropertyReadHandler callback

A function that returns a Promise and resolves it with the value of the Property matching the name argument to the setPropertyReadHandler function, or rejects with an error if the property is not found or the value cannot be retrieved.

The PropertyWriteHandler callback

A function called with value as argument that returns a Promise which is resolved when the value of the Property matching the name argument to the setPropertyReadHandler function is updated with value, or rejects with an error if the property is not found or the value cannot be updated.

Note that this function is invoked by implementations before the property is updated, so the code in this callback function can invoke the readProperty() method to find out the old value of the property, if needed. Therefore the old value is not provided to this method.

The ActionHandler callback

A function called with a parameters dictionary argument assembled by the WoT runtime based on the Thing Description and the external client request. It returns a Promise that rejects with an error or resolves if the action is successful or ongoing (may also resolve with a control object such as an Observable for actions that need progress notifications or that can be canceled).

The setPropertyReadHandler() method

Takes name as string argument and readHandler as argument of type PropertyReadHandler. Sets the handler function for reading the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining.

The readHandler callback function will implement reading a Property and SHOULD be called by implementations when a request for reading a Property is received from the underlying platform.

There SHOULD be at most one handler for any given Property and newly added handlers replace the old handlers. If no handler is initialized for any given Property, implementations SHOULD implement a default property read handler.

The setPropertyWriteHandler() method

Takes name as string argument and writeHandler as argument of type PropertyWriteHandler. Sets the handler function for writing the specified Property matched by name. Throws on error. Returns a reference to the same object for supporting chaining.

There SHOULD be at most one write handler for any given Property and newly added handlers replace the old handlers. If no write handler is initialized for any given Property, implementations SHOULD implement default property update and notifying observers on change.

The setActionHandler() method

Takes name as string argument and action as argument of type ActionHandler. Sets the handler function for the specified Action matched by name. Throws on error. Returns a reference to the same object for supporting chaining.

If provided, this callback function will implement invoking an Action and SHOULD be called by implementations when a request for invoking a Action is received from the underlying platform. The callback will receive a parameters dictionary argument.

There SHOULD be exactly one handler for any given Action. If no handler is initialized for any given Action, implementations SHOULD return error if the action is invoked by any client.

Examples

Below some ExposedThing interface examples are given.

        try {
          var thing = WoT.produce({ name: "tempSensor" });
          // manually add Interactions
          thing.addProperty({
            name: "temperature",
            value: 0.0,
            schema: '{ "type": "number" }'
            // use default values for the rest
          }).addProperty({
            name: "max",
            value: 0.0,
            schema: '{ "type": "number" }'
            // use default values for the rest
          }).addAction({
            name: "reset",
            // no input, no output
          }).addEvent({
            name: "onchange",
            schema: '{ "type": "number" }'
          });
          // add server functionality
          thing.setActionHandler("reset", () => {
            console.log("Resetting maximum");
            thing.writeProperty("max", 0.0);
          });
          thing.start().then(() => {
              thing.register();
          });
          // define Thing business logic
          setInterval( async () => {
            let mock = Math.random()*100;
            thing.writeProperty("temperature", mock);
            let old = await thing.readProperty("max");
            if (old < mock) {
              thing.writeProperty("max", mock);
              thing.emitEvent("onchange");
            }
          }, 1000);
        } catch (err) {
           console.log("Error creating ExposedThing: " + err);
        }
      

        let thingDescription = '{ "@context": [ "https://w3c.github.io/wot/w3c-wot-td-context.jsonld", "https://w3c.github.io/wot/w3c-wot-common-context.jsonld" ], "@type": [ "Thing", "Sensor" ], "name": "mySensor", "geo:location": "testspace", "interaction": [ { "@type": [ "Property", "Temperature" ], "name": "prop1", "schema": { "type": "number" }, "saref:TemperatureUnit": "degree_Celsius" } ] }';
        try {
          // note that produce() fails if thingDescription contains error
          let thing = WoT.produce(thingDescription);
          // Interactions were added from TD
          // WoT adds generic handler for reading any property
          // define a specific handler for one property
          let name = "examplePropertyName";
          thing.setPropertyReadHandler(name, () => {
            console.log("Handling read request for " + name);
            return new Promise((resolve, reject) => {
                let examplePropertyValue = 5;
                resolve(examplePropertyValue);
              },
              e => {
                console.log("Error");
              });
          });
          thing.start();
        } catch(err) {
           console.log("Error creating ExposedThing: " + err);
        }
      

        // fetch an external TD, e.g., to set up a proxy for that Thing
        WoT.fetch("http://myservice.org/mySensor/description").then(td => {
          // WoT.produce() ignores instance-specific metadata (security, form)
          let thing = WoT.produce(td);
          // Interactions were added from TD
          // add server functionality
          // ...
        });