Semantic description of IoT infrastructures

This blog entry will discuss the ways to create a Thing Description and to annotate semantically the data exposed by a sensor.

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.

Thing Descriptions in AURORAL

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.

Note: The example is the same as the basic-example available in the GitHub repository shared above. 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. In general they do not need to be smart:). To give some examples:

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

The following section of this tutorial will give the answers.

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

Note: 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:

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”,
     “security” : [
        "nosec_sc"
      ],
     “securityDefinitions” : {
        "nosec_sc": {
          "scheme": "nosec"
        }
      },
    "@context": [
        "https://www.w3.org/2019/wot/td/v1",
        "https://w3c.github.io/wot-discovery/context/discovery-context.jsonld"
      ],
    }

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:

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",
      "monitors": "AmbientTemperature",
      "measures": "degreeCelsius",
      "readOnly": true,
      "type": "number",
      "forms": [
        {
          "op": [
            "readproperty"
          ],
          "href": "www.mydata.example.com/api/object/1234/property/room_temperature"
        }
      ]
    }
  }

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": {
                      "monitors": "TotalEnergy",
                      "measures": "watt",
                      "type": "number"
                  }
             }
        },
      "forms": [
        {
          "op": [
            "readproperty"
          ],
          "href": "www.mydata.example.com/api/object/1234/event/consumption"
        }
      ]
    }
     }

STEP 2 — Location

Note: Location is still not included in the ontology, SUBJECT TO CHANGES

Location adds geographical or environmental information that can be interpreted by the semantic services. We see below a possible configuration using all the available location fields.

    “located-in”: [{
     “location_type”: “s4bldg:Building”,
     “label”: “My Building”,
     “location_id” : “Link pointing to my building web"
     },
     {
     “location_type”: “s4bldg:BuildingSpace”,
     “label”: “Office 3A”
     },
     {
     “location_type”: “s4city:City”,
     “label”: “Bratislava”,
     “location_id” : “http://dbpedia.org/resource/Bratislava"
     },
     {
     “location_type”: “s4city:AdministrativeArea”,
     “label”: “Bratislava Region”,
     “location_id”: “http://dbpedia.org/resource/Bratislava"
     },
     { 
     “location_type”: “s4city:Country”,
     “label”: “Slovakia”,
     “location_id”: “http://dbpedia.org/resource/Slovakia"
    }]

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.

Brought to you by the AURORAL community, keep posted! 💪