2022-02-24-wot-integration.md

title	published	permalink	layout	author	tags	hide_sidebar	sidebar	toc
W3C WoT (Web of Things) integration	true	2022-02-24-wot-integration.html	post	thomas_jaeckle	blog wot http	true	false	true

The upcoming Eclipse Ditto version 2.4.0 will add support for W3C WoT (Web of Things) integration by referencing to WoT Thing Model in Ditto managed twins describing the Things' capabilities.

By integrating WoT, Ditto does a big step forward towards:

• increased interoperability
• introspection of twins to find out their capabilities
  • which properties are provided and their data types and formats
  • which actions can be invoked on the devices, including their expected input/output data types and formats
  • which events the devices are able to emit, including their data type and format
• addition of semantic context to Ditto managed digital twins and their capabilities
• description of Ditto twin HTTP APIs in an open, established, well specified, "web optimized", active IoT standard
• backing Ditto managed twins with WoT models, also supporting "brownfield" setups, without the need for actual devices to be aware of WoT
• opening the door to a new ecosystem of tools

To learn more about WoT (Web of Things), please visit: Web of Things in a Nutshell

WoT integration in Ditto

The WoT integration in Ditto covers several aspects:

• referencing HTTP(s) URLs to WoT Thing Models in Thing Definitions and in Feature Definitions
• generation of WoT Thing Descriptions for Thing and Feature instances based on referenced Thing Models
  • resolving potential extensions via tm:extends and imports via tm:ref
  • resolving potential Thing level compositions via tm:submodel
  • resolving potential TM placeholders
• upon creation of new Things, generation of a "JSON skeleton" following the WoT Thing Model, including referenced TM submodels as Features of the Thing

For additional details about the WoT integration, please check the full WoT integration documentation.

The WoT integration is still marked as "experimental" as the WoT Thing Description version 1.1 is not yet published as "W3C Recommendation" and may still change - as well as the implementation of the standard in Ditto.

{% include note.html content="In order to enable the experimental support for WoT in Ditto 2.4.0, please configure the environment variable DITTO_DEVOPS_FEATURE_WOT_INTEGRATION_ENABLED to true." %}

Example

For a full example of the different aspects of the WoT integration, please check the full WoT integration example.

To summarize:

• you can "link" a Thing via its Thing Definition to a public available WoT Thing Model via its HTTP(s) endpoint.
• creation of a new Thing can use a Thing Model (e.g. the example model https://eclipse.github.io/ditto-examples/wot/models/floor-lamp-1.0.0.tm.jsonld) in order to generate a JSON skeleton:

  curl --location --request PUT -u ditto:ditto 'http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "definition": "https://eclipse.github.io/ditto-examples/wot/models/floor-lamp-1.0.0.tm.jsonld"
  }'

• resulting to a Thing looking like this:

  {
    "thingId": "io.eclipseprojects.ditto:floor-lamp-0815",
    "policyId": "io.eclipseprojects.ditto:floor-lamp-0815",
    "definition": "https://eclipse.github.io/ditto-examples/wot/models/floor-lamp-1.0.0.tm.jsonld",
    "attributes": {
      "manufacturer": "",
      "serialNo": ""
    },
    "features": {
      "Spot1": {
        "definition": [
          "https://eclipse.github.io/ditto-examples/wot/models/dimmable-colored-lamp-1.0.0.tm.jsonld",
          "https://eclipse.github.io/ditto-examples/wot/models/colored-lamp-1.0.0.tm.jsonld",
          "https://eclipse.github.io/ditto-examples/wot/models/switchable-1.0.0.tm.jsonld"
        ],
        "properties": {
          "dimmer-level": 0.0,
          "color": {
            "r": 0,
            "g": 0,
            "b": 0
          },
          "on": false
        }
      },
      "Spot2": {
        "definition": [
          "https://eclipse.github.io/ditto-examples/wot/models/dimmable-colored-lamp-1.0.0.tm.jsonld",
          "https://eclipse.github.io/ditto-examples/wot/models/colored-lamp-1.0.0.tm.jsonld",
          "https://eclipse.github.io/ditto-examples/wot/models/switchable-1.0.0.tm.jsonld"
        ],
        "properties": {
          "dimmer-level": 0.0,
          "color": {
            "r": 0,
            "g": 0,
            "b": 0
          },
          "on": false
        }
      },
      "Spot3": {
        "definition": [
          "https://eclipse.github.io/ditto-examples/wot/models/dimmable-colored-lamp-1.0.0.tm.jsonld",
          "https://eclipse.github.io/ditto-examples/wot/models/colored-lamp-1.0.0.tm.jsonld",
          "https://eclipse.github.io/ditto-examples/wot/models/switchable-1.0.0.tm.jsonld"
        ],
        "properties": {
          "dimmer-level": 0.0,
          "color": {
            "r": 0,
            "g": 0,
            "b": 0
          },
          "on": false
        }
      },
      "ConnectionStatus": {
        "definition": [
          "https://eclipse.github.io/ditto-examples/wot/models/connection-status-1.0.0.tm.jsonld"
        ],
        "properties": {
          "readySince": "",
          "readyUntil": ""
        }
      },
      "PowerConsumptionAwareness": {
        "definition": [
          "https://eclipse.github.io/ditto-examples/wot/models/power-consumption-aware-1.0.0.tm.jsonld"
        ],
        "properties": {
          "reportPowerConsumption": {}
        }
      },
      "SmokeDetection": {
        "definition": [
          "https://eclipse.github.io/ditto-examples/wot/models/smoke-detector-1.0.0.tm.jsonld"
        ]
      },
      "Status-LED": {
        "definition": [
          "https://eclipse.github.io/ditto-examples/wot/models/colored-lamp-1.0.0.tm.jsonld",
          "https://eclipse.github.io/ditto-examples/wot/models/switchable-1.0.0.tm.jsonld"
        ],
        "properties": {
          "color": {
            "r": 0,
            "g": 0,
            "b": 0
          },
          "on": false
        }
      }
    }
  }

• the WoT Thing Description of Things containing a Thing Model in their "definition" may then be retrieved by invoking the existing
  GET /api/2/things/<thingId> endpoint, providing the Accept header pointing to application/td+json:

  curl --location --request GET -u ditto:ditto 'http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815' \
  --header 'Accept: application/td+json'

• Features of Things are handled as WoT "submodels" and also can describe themselves with the same approach, e.g.:

  curl --location --request GET -u ditto:ditto 'http://localhost:8080/api/2/things/io.eclipseprojects.ditto:floor-lamp-0815/features/Spot1' \
  --header 'Accept: application/td+json'

Ditto WoT Java model

As part of the integration of WoT in Ditto, a Java module has been added to provide a Java API for the WoT "Thing Description"/"Thing Model" and their parts - this module can also be used separately from Ditto in order to e.g. have a builder based API for building new objects or to read a TD/TM from a string:

<dependency>
    <groupId>org.eclipse.ditto</groupId>
    <artifactId>ditto-wot-model</artifactId>
    <version>${ditto.version}</version> <!-- the ditto-wot-model is available since "ditto.version" 2.4.0 -->
</dependency>

Please have a look at the added ditto-wot-model module to find out more about example usage.

Feedback?

Please get in touch if you have feedback or questions towards this new functionality.

{% include image.html file="ditto.svg" alt="Ditto" max-width=500 %} --
The Eclipse Ditto team