Thing Template Requirements - Additional use cases

[mlagally]

Improve requirements document: https://github.com/w3c/wot-architecture/blob/master/REQUIREMENTS/thing-templates.md

Identify potentailly new use cases.

[sebastiankb]

UCs:

• Mass production: define a class of device with a TDT
• Expose a Servient: Templates are used to define a WoT producer such as for a WoT runtime implementations (e.g., node-wot)
• Simulation: simulate an application based on the data model that is defined in a TDT

[zolkis]

Expose a Servient: Templates are used to define a WoT producer such as for a WoT runtime implementations (e.g., node-wot)

That is not a TD template, but a partial TD (or TD fragment) that may contain parts that cannot be part of a TDT.

[sebastiankb]

That is not a TD template, but a partial TD (or TD fragment) that may contain parts that cannot be part of a TDT.

As already mentioned here it would be cool if you can provide concrete examples what kind of parts cannot be part of a TDT.

[takuki]

I think we should distinguish interface inheritance and object (or class) inheritance. TD for most part is an interface definition, but "form" for example is an "implementation" of the interface. In my opinion, TD Template inheritance hierarchy is about interface definition, which means "implementation" such as form definitions do not propagate down the inheritance chain. If "implementation" is also propagated down inheritance hierarchy, it would be very complex to manage changes such as unexpected change of implementation up in the hierarchy.

[benfrancis]

Has any more work gone into documenting the use cases of Thing Description Templates? The requirements currently list two use cases:

1. Digital Twin
2. Big Data for Manufacturing

I would argue that every Thing Description is a digital twin of a device in the real world and it's not clear from the documentation what Thing Description Templates would add to this.

I can see why automatically generating Thing Descriptions would be useful in use cases with a large number of devices, but the document does not explain the benefits of making a template syntax part of the Thing Description specification vs. just using software to generate concrete Thing Descriptions (similar to how server-side and client-side templating engines generate HTML).

I remember on a conference call another use case that was brought up was using a Thing Description Template in a search operation to find Thing Descriptions which match a given template. However, as I understand it there is currently no standard mechanism for searching a collection of Thing Descriptions, or even expressing a collection of Thing Descriptions, so it's not clear where this would fit in.

[benfrancis]

• Mass production: define a class of device with a TDT

What are schemas[1][2] if not classes of devices? When should a schema be used (via semantic annotations) vs. when a template should be used?

1. http://iotschema.org/docs/full.html
2. https://iot.mozilla.org/schemas/

• Expose a Servient: Templates are used to define a WoT producer such as for a WoT runtime implementations (e.g., node-wot)
• Simulation: simulate an application based on the data model that is defined in a TDT

What does "define a WoT producer" mean?

What does "simulate an application" mean and why do Thing Description Templates help with this?

[sebastiankb]

What are schemas[1][2] if not classes of devices? When should a schema be used (via semantic annotations) vs. when a template should be used?

Just referring to a schema definition like iot.schema.org does not help here, because you want to be more precise. A TDT gives a concrete structure with (a subset of schema) vocabularies which should definitely be used in a TD instance.

What does "define a WoT producer" mean?

This is something from the Scripting API .

What does "simulate an application" mean and why do Thing Description Templates help with this?

If you have not yet deployed a real Think (i.e. there is no communication and security metadata available), TDT will at least give you an indication of the expected data model and functionality.

[mlagally]

What does "simulate an application" mean and why do Thing Description Templates help with this?

If you have not yet deployed a real Think (i.e. there is no communication and security metadata available), TDT will at least give you an indication of the expected data model and functionality.

To elaborate what Sebastian wrote a bit further:

A template describes a model of a thing in terms of generic metadata, interactions and properties. It is basically an interface description, that needs to be instantiated by adding concrete device specific metadata and an implementation for the behavior of the interface. A thing can implement multiple templates. The behavior can be either implemented in a real device (e.g. using the scripting API) or by a simulation (engine). For a pure simulation model you don't need a concrete protocol binding. Also if you decouple the protocol binding from the interface you have more flexibility on the implementation, i.e. you can use the same model independently from a concrete protocol. If we have thing directories, you could have a query like: "give me all thermostats that implement a 'celsius thermostat' interface with a MQTT binding and a heater interface".

[benfrancis]

@sebastiankb wrote:

Just referring to a schema definition like iot.schema.org does not help here, because you want to be more precise. A TDT gives a concrete structure with (a subset of schema) vocabularies which should definitely be used in a TD instance.

I see what problem you are trying to solve. The Mozilla implementation solves this problem with capability schemas that define which properties, actions and events are required for a given device capability. Individual Thing Descriptions are then instances of those classes of capabilities, and a single Thing Description can implement multiple capabilities. There is no need for a client parsing a Thing Description document to fill in gaps in a template as the concrete Thing Descriptions are generated on the server side, and therefore no need for templating syntax in the Thing Description, similar to how a PHP server side script might generate HTML.

For example, the OnOffSwitch capability requires an OnOffProperty. Here is an instance of a Thing Description generated by the server which instantiates that capability.

{
  "@context": "https://iot.mozilla.org/schemas/",
  "@type": ["OnOffSwitch"],
  "id": "https://mywebthingserver.com/things/switch",
  "title":"My Switch",
  "description": "A web connected on/off switch",
  "properties": {
    "on": {
      "@type": "OnOffProperty",
      "type": "boolean",
      "title": "On/Off",
      "description": "Whether the switch is turned on",
      "links": [{"href": "/things/switch/properties/on"}]
    }
  }
}

This is something from the Scripting API.

Hmm. Any web server can use any templating engine to generate a JSON resource to serve. For example, with Node.js + Express.js + Handlebars you'd do something like...

var template = Handlebars.compile(`{
    "@context": "https://iot.mozilla.org/schemas/",
    "@type": ["OnOffSwitch"],
    "id": "{{thingID}}",
    "title":"{{thingTitle}}",
    "description": "A web connected on/off switch",
    "properties": {
      "on": {
        "@type": "OnOffProperty",
        "type": "boolean",
        "title": "On/Off",
        "description": "Whether the switch is turned on",
        "links": [{"href": "{{propertyPath}}"}]
      }
    }
  }`);

app.get('/things/switch', (req, res) => res.send(template({
  thingId: 'https://mywebthingserver.com/things/switch',
  thingTitle: 'My Switch',
  propertyPath: '/things/switch/properties/on'
})));

This is really bog standard stuff, there's really no need for standardising a scripting API or templating syntax specifically for Thing Descriptions in order to solve this problem.

If you have not yet deployed a real Think (i.e. there is no communication and security metadata available), TDT will at least give you an indication of the expected data model and functionality.

If you have not yet deployed a real thing, why do you need a Thing Description? Under what circumstances would a WoT client need to parse an incomplete Thing Description and how is it useful in practice?

What am I missing?

[benfrancis]

@mlagally wrote:

For a pure simulation model you don't need a concrete protocol binding.

I'm struggling to imagine the usefulness of a simulation of a connected device which you can't actually connect to and communicate with. Do you have a concrete use case in mind, or is this just a theoretical example?

If we have thing directories, you could have a query like: "give me all thermostats that implement a 'celsius thermostat' interface with a MQTT binding and a heater interface".

We don't currently have a specification for how to define a directory of things, but I agree that would be very useful. Perhaps we should define how to describe a thing directory before defining a template syntax for querying one?

[relu91]

@benfrancis could you pleas elaborate a little more on the points below?

How are capability schemas defined? It seems that https://iot.mozilla.org/schemas/ does not provide a valid JSON-LD context file. Is it intended? What about validation? Does it follow the same rules as any other JSON-LD file?

Thank you in advice!

[benfrancis]

How are capability schemas defined? It seems that https://iot.mozilla.org/schemas/ does not provide a valid JSON-LD context file. Is it intended? What about validation? Does it follow the same rules as any other JSON-LD file?

That's correct, the schemas page is currently just a human-readable technical specification for developers to implement. Thing Descriptions which include JSON-LD style annotations following these schemas can then be recognised by the WebThings Gateway, which uses the annotations as hints to provide a more meaningful user interface for devices which support a given capability. For example, telling the gateway that a device follows the "motion sensor" capability schema and has a "motion property" allows for a more useful UI than simply knowing it's a connected device with a boolean property.

This is similar in principle to how search engines, social networks and web browsers detect OpenGraph metadata as lightweight semantic annotations in web pages and use them to enhance the visual representation of those resources. There's no complex processing of RDF graphs going on, just parsing of simple metadata from a web page.

I'm sure it would be possible to formally express the schemas themselves in machine-readable JSON-LD, we just never found a practical need for it.

The client source code which generates a user interface for a device based on its Thing Description is here and you can find the web components representing the different capability schemas here.

[mlagally]

For a pure simulation model you don't need a concrete protocol binding.

I'm struggling to imagine the usefulness of a simulation of a connected device which you can't actually connect to and communicate with. Do you have a concrete use case in mind, or is this just a theoretical example?

When you simulate a digital twin it can be an aggregation of multiple things that are just hosted in a cloud service, hence you don't have protocol interfaces. These instances can directly invoke actions or generate messages that are consumed by applications. Among other use cases this kind of simulation and modeling is very useful in the design phase of a thing (device) to play with different device models / abstractions before actually impleemnting them.

If we have thing directories, you could have a query like: "give me all thermostats that implement a 'celsius thermostat' interface with a MQTT binding and a heater interface".

We don't currently have a specification for how to define a directory of things, but I agree that would be very useful. Perhaps we should define how to describe a thing directory before defining a template syntax for querying one?

I completely agree - we need to start describing the use cases first, understand the stakeholders (i.e. who is actually providing a thing directory, what are the privacy implications, is there a business model for a stand-alone "thing directory provider" at all, or is it just a function block in some big data cloud service?

[egekorkan]

I'm struggling to imagine the usefulness of a simulation of a connected device which you can't actually connect to and communicate with. Do you have a concrete use case in mind, or is this just a theoretical example?

For us, we already cases where one sensor (color sensor for example) is not available (not delivered yet or the device API is not good/stable and needing a custom implementation) and instead of waiting for it, we can simulate it so that we can start programming the mashup level code. You can use the shadow-thing to quickly simulate a Thing based on a TD. Out of the box, you cannot simulate physical processes (like how the temperature evolves over time) but it looks identical to the actual Thing from the TD perspective, which is enough for writing the mashup code.

[benfrancis]

@mlagally wrote:

When you simulate a digital twin it can be an aggregation of multiple things that are just hosted in a cloud service, hence you don't have protocol interfaces. These instances can directly invoke actions or generate messages that are consumed by applications.

I'm not sure what you mean when you say "just hosted in a cloud service", but I think this may indicate we have different assumptions about the use cases of a Thing Description. The WoT Architecture specification defines a Thing Description as follows:

"The Web of Things (WoT) Thing Description [WOT-THING-DESCRIPTION] normatively provides a machine-readable data format for describing the metadata and network-facing interfaces of Things."

If a Thing Description has no network interfaces then it is not possible to communicate with the thing over the web and it is therefore not part of the web of things or the internet of things, it is just a thing. This is true whether the Thing Description represents a single device or an aggregation of devices and whether it is hosted in a cloud service or by any other means.

Among other use cases this kind of simulation and modeling is very useful in the design phase of a thing (device) to play with different device models / abstractions before actually impleemnting them.

It might be useful to differentiate here between what you do to develop a web thing, and what you do to describe a complete web thing. Development tools can use all kinds of templating mechanisms for Thing Descriptions during development, just like any other resource on the web. Those mechanisms don't necessarily need to be part of the Thing Description specification. There is no templating mechanism built into the Web App Manifest specification or the Browser Extension manifest specification for example, but there are general purpose templating tools which can be used to generate any kind of web resource.

I completely agree - we need to start describing the use cases first, understand the stakeholders (i.e. who is actually providing a thing directory, what are the privacy implications, is there a business model for a stand-alone "thing directory provider" at all, or is it just a function block in some big data cloud service?

Great, is there an existing document for use cases and requirements for the Discovery work item in the new WG charter yet, or do we need to start one?

[benfrancis]

@egekorkan wrote:

For us, we already cases where one sensor (color sensor for example) is not available (not delivered yet or the device API is not good/stable and needing a custom implementation) and instead of waiting for it, we can simulate it so that we can start programming the mashup level code. You can use the shadow-thing to quickly simulate a Thing based on a TD. Out of the box, you cannot simulate physical processes (like how the temperature evolves over time) but it looks identical to the actual Thing from the TD perspective, which is enough for writing the mashup code.

Whether the Thing Description describes a physical device in the real world or a simulation of a physical device in the real world is surely irrelevant? The WebThings Gateway has a virtual things add-on which generates simulated web things to interact with, but the Thing Descriptions are indistinguishable from one describing a physical device. To a WoT client they are the same.

Regardless of whether a device is simulated or real, how do you interact with its web thing representation if it has no network interfaces?

[egekorkan]

Whether the Thing Description describes a physical device in the real world or a simulation of a physical device in the real world is surely irrelevant? The WebThings Gateway has a virtual things add-on which generates simulated web things to interact with, but the Thing Descriptions are indistinguishable from one describing a physical device. To a WoT client they are the same.

I completely agree with those points. In the paper we wrote to publish the shadow-thing package, the virtual things adapter is referenced.

Regardless of whether a device is simulated or real, how do you interact with its web thing representation if it has no network interfaces?

They have network interfaces when they are instantiated but the input for the simulation is a template. It can also be a full TD but then the forms are ignored.

[memelet]

@benfrancis It does not seem like your issue was ever resolved. Somewhat new to wot I was having the same confusion. Did the concept of thing-model overtake this?

[egekorkan]

Thing Model in the editor version of the TD spec has overtaken this (https://w3c.github.io/wot-thing-description/#thing-model). You can also create issues in the TD repository.