Skip to content

Semantic interoperability

Creating a Thing Description step by step

If you are already familiar with the concepts feel free to jump to the examples and concrete documentation for the AURORAL ontology.

Examples and documentation

In case you want to know a bit more about the Thing Description, you are welcome to keep reading.

In AURORAL every device and service is described by a simple JSON document. This JSON document describes the thing and how to interact with it. In this short story we will walk through the process of describing a thermometer.

Example on GitHub

The example is the same as the basic-example available on GitHub: Examples and documentation. In GitHub you can access to the complete Thing Description and mapping.

What is a Thing?

We will call Things any device or service registered into AURORAL platform. To give some examples:

  • Devices: Sensors, smart appliances, actuators, photovoltaic panels, human data input …

  • Services: Applications that will use device data for monitor & alerting, analysis, optimisation of resources …

For being able to communicate with the thing, AURORAL platform needs to know how to answer the following questions:

  • What is it?

  • How to interact with it?

  • What data is returning?

The following section of this tutorial will give the answers.

Thing and Thing Description

Thing and Thing Description are part of the WoT ontology, however hereafter when we use the term Thing we are making reference to the physical object not the ontology. Similarly, for us Thing Description is how we will refer to the description of a thing in plain JSON. However, this descriptions are transformed into a RDF document that follows the WoT ontology by our semantic services.

The official definition of Thing Description can be found here

STEP 0 — Overview

First let us have a look on the JSON schema of a Thing Description, so we can see the type of each field and if it is mandatory or not before starting.

We could divide this schema in three main parts:

  • IDs: oid, adapterId.

    • oid: Id in AURORAL of the Thing, it is assigned by the AURORAL Node on registration.
    • adapterId: Id of the thing in your infrastructure [OPTIONAL]

  • Metadata: title, type, security, description, version, context and located-in.

    • title: Human readable name of your Thing
    • security & securityDefinition: Security definition of your Thing, see official Thing Description documentation for more details.
    • description: Description of your Thing [OPTIONAL]
    • version: Current version of your Thing [OPTIONAL]
    • context: Related ontologies necessary to understand all the TD annotations
    • geo:location: Static location of your Thing [OPTIONAL]

  • Interaction patterns: Or what resources is my device/service exposing. Actions, events and properties. To serve as an orientation, properties are used to get or write a value into our thing, actions are used to start a process that will take some time to finish and events are used to subscribe to a channel where some notifications will be pushed. For example, property current blood pressure or action start charging my battery.

Note: In AURORAL for now we will skip ACTIONS, as most of the current use cases are covered with properties and events. In future releases the ACTIONS will also be supported.

STEP 1— Minimal configuration

Following the schema above we can build our first minimalistic Thing Description for a thermometer. This description provides, very little information and no interaction patterns.

    {
     "title": "MyRoomTemperature",
     "@type": "Thermometer",
     "adapterId": "1234",
     "security" : [
        "nosec_sc"
      ],
     "securityDefinitions" : {
        "nosec_sc": {
          "scheme": "nosec"
        }
      },
     "@context": [
        "https://www.w3.org/2019/wot/td/v1",
        { 
        "adp": "https://auroral.iot.linkeddata.es/def/adapters#",
        "om": "http://www.ontology-of-units-of-measure.org/resource/om-2/",
        "geo": "http://www.w3.org/2003/01/geo/wgs84_pos#"
        }
    ],
    }

Note: We are not adding OID because for the registration is not needed, however, after the registration the platform will return and store for you the complete TD with the new OID assigned for you.

For a minimal representation of a service, replacing the type for Service in the example provided would suffice.

STEP 2 — Interacting with the Things

Adding interaction patterns to the Thing Description is the way how the platform knows how to interact with the registered Thing. We can make use of three types of interaction patterns:

  • Properties
  • Events

We will now choose some interaction patterns to add to our thermometer.

Properties

The property chosen is AmbientTemperature. We will expose this property and make it only readable, therefore we need to describe in the Thing Description how is it possible to interact with it.

    "properties": {
    "room_temperature": {
      "title": "room_temperature",
      "@type": "adp:AmbientTemperature",
      "unit": "om:degree_Celsius",
      "readOnly": true,
      "type": "number",
      "forms": [
        {
          "op": [
            "readproperty"
          ],
          "href": "www.mydata.example.com/api/object/1234/property/room_temperature"
        }
      ]
    }
  }
* pid: ID of our property, it is the key of the JSON object of the property, in this case "room_temperature".

  • title: Human readable name

  • @type: Annotation representing the property type according the AURORAL ontology.

  • unit: Units of measurement of the property. It also follows the AURORAL ontology, available options in adapters ontology.

  • readOnly: Whether read only or writable

  • type: Data type of the value return when reading this property

  • forms: Where to read the property

Events

We are worried about the environment, and we bought a temperature sensor that can measure its consumption. It would be great to know how much energy is using. We can subscribe to a channel where the thermometer will be publishing this information and maybe more, depending on the capabilities of the thermometer.

    "events": {
      "thing_consumption": {
          "title": "consumption",
          "data": {
              "type": "object",
              "properties": {
                  "consumption": {
                      "@type": "adp:TotalEnergy",
                      "unit": "om:watt",
                      "type": "number"
                  }
             }
        },
      "forms": [
        {
          "op": [
            "readproperty"
          ],
          "href": "www.mydata.example.com/api/object/1234/event/consumption"
        }
      ]
    }
     }
* eid: ID of our event, it is the key of the JSON object of the property, in this case "thing_consumption".

  • data: Contains the properties that the event is going to return and the description of all of them. In this case we return and object containing just one property, TotalEnergy.

  • @type: Annotation representing the property type according the AURORAL ontology that is published with the event.

  • readOnly: Whether read only or writable

  • unit: Units of measurement of the property. It also follows the AURORAL ontology, available options in adapters ontology.

  • type: Data type of the value return when reading this property

  • forms: Where to subscribe the event channel

STEP 3 — Location

Location adds geographical or environmental information that can be interpreted by the semantic services. We see reuse the ontology Basic GEO WGS84 http://www.w3.org/2003/01/geo/ in AURORAL.

    "geo:location": {
        "geo:lat": "48.1516",
        "geo:long": "17.1674"
  }
Thus our thermometer is located in Bratislava in the Office 3A of our company building.

Note: The location_id refers to a valid URL containing an RDF description of the resource (i.e. city, country, building)

Note: Remember that if you prefer your thermometer’s location to remain unknown, location is a non mandatory field so you can skip it.

Writing SPARQL queries

TBD