Reading Data from IoT Devices

The first thing you need to do is to connect your IoT devices or Gateways to FIWARE. This basically means that your IoT devices’ observations reach a Context Broker.

During this tutorial, we provide an example on how you would connect your devices using Ultralight2.0 (UL2.0) - which is a proposed simplification of the SensorML (SML) standard - and get those devices sending their measurements (observations) to the FIWARE Lab public Context Broker. Ultralight2.0 is selected in this example because of its simplicity. In addition we show you how you can do the same locally with the FIWARE Tour Guide Application as it integrates the IDAS UL2.0 IoT Agent.

If you want to quickly connect or simulate virtual devices you may also check https://github.com/telefonicaid/fiware-figway, a set of simple python scripts working as a client SDK for any desktop PC, laptop or gateway supporting a Python 2.7 environment. This way you may skip the steps described below and use the python commands as described in the README.md file available at the GitHub repository linked above.

For a more detailed description of the IDAS (FIWARE IoT Agent suite) APIs, please have a look here.

A typical IoT data workflow using FIWARE consists of the following steps:

Step 1 : Create an IDAS Service

If you are using the public IDAS instance with the public openiot testing service available at 130.206.80.47 (Port 5073) you may skip this step. Just keep in mind the shared secret for this public service (that your devices need to know) is the string 4jggokgpepnvsb2uv4s40d59ov. Otherwise, creating an IDAS Service consists of a simple HTTP POST like this:

POST http://130.206.80.40:5371/iot/services

Headers:

{
  'Content-Type':       'application/json',
  'X-Auth-Token' :      '[TOKEN]',
  'Fiware-Service':     'openiot',
  'Fiware-ServicePath': '/'
}

Payload:

{
  "services": [
    {
      "apikey":      "4jggokgpepnvsb2uv4s40d59ov",
      "cbroker":     "http://0.0.0.0:1026",
      "entity_type": "thing",
      "resource":    "/iot/d"
    }
  ]
}

Where 0.0.0.0:1026 might be replaced by a private instance of a Context Broker or just leave it as it is (0.0.0.0:1026) if the public instance is running at the same VM (130.206.80.40:1026) will be used. The apikey string should be updated with a shared secret to be known by your IoT devices. An OAuth token is needed as well, a simple way of obtaining one is described here.

Likewise, you may want to experiment using the FIWARE Tour Guide Application. Assuming you have installed it locally, you can issue the following request:

POST http://localhost:4041/iot/services/

Headers:

{
  'Content-Type':       'application/json',
  'Fiware-Service':     'tourguide',
  'Fiware-ServicePath': '/'
}

Payload:

{
  "services": [
    {
      "apikey":   "tourguide-devices",
      "cbroker":  "http://orion:1026",
      "resource": "/iot/dev-restaurants"
    }
  ]
}

Step 2: Register your IoT device

Before your device sends observations or receives commands a register operation is needed:

POST http://130.206.80.40:5371/iot/devices

Headers:

{
  'Content-Type':       'application/json',
  'X-Auth-Token' :      '[TOKEN]',
  'Fiware-Service' :    'openiot',
  'Fiware-ServicePath': '/'
}

Payload:

{
  "devices": [
    {
      "device_id":   "[DEV_ID]",
      "entity_name": "[ENTITY_ID]",
      "entity_type": "thing",
      "timezone":    "Europe/Madrid",
      "attributes": [
        {
          "object_id": "t",
          "name":      "temperature",
          "type":      "number"
        }
      ],
      "static_attributes": [
        {
          "name":  "attr_name",
          "type":  "string",
          "value": "value"
        }
      ]
    }
  ]
}

The important parameters to be provided are:

  • entity_type the entity type to be used at the Context Broker. In the example above, thing.
  • entity_name the entity ID to be used at the Context Broker. In the example above, thing:[ENTITY\_ID].
  • attributes they should include an alias (a letter representing this attribute).
  • static_attributes only if your device needs to define static attributes (sent in every observation).

Likewise, using the Tour Guide Application, you can create a device bound to a restaurant entity. Such device will provide ambient measurements, for instance temperature, for a specific restaurant.

POST http://localhost:4041/iot/devices/

Headers:

{
  'Content-Type':       'application/json',
  'Fiware-Service':     'tourguide',
  'Fiware-ServicePath': '/'
}

Payload:

{
  "devices": [
    {
      "device_id": "restaurant-sensor-0115206c51f60b48b77e4c937835795c33bb953f",
      "protocol": "UL20",
      "entity_name": "0115206c51f60b48b77e4c937835795c33bb953f",
      "entity_type": "Restaurant",
      "attributes": [
        {
          "object_id": "t",
          "name":      "temperature",
          "type":      "number"
        }
      ]
    }
  ]
}

Step 3: Send Observations related to your IoT device

Sending an observation from an IoT device is extremely efficient and simple with the following HTTP request:

POST  http://130.206.80.40:5371/iot/d?k=[APIKEY]&i=[DEV_ID]

Headers:

{
  'Content-Type':  'text/plain',
  'X-Auth-Token' : '[TOKEN]'
}

Payload:

't|25'

The previous example sends a new temperature measurement which is automatically propagated to the corresponding entity at the Context Broker and FIWARE Service defined previously in our IDAS service. [API_KEY] must be the one used when creating the service and [DEV_ID]must be the device identifier formerly registered.

Similarly, you can do the same with the Tour Guide Application:

POST http://localhost:7896/iot/d?k=tourguide-devices&i=restaurant-sensor-0115206c51f60b48b77e4c937835795c33bb953f

Headers:

{
  'Content-Type': 'text/plain',
}

Payload:

't|22.3'

Sending multiple observations in the same message is also possible with the following payload:

"alias1|value1#alias2|value2#alias3|value3..."

't|23#h|80#l|95#m|Quiet'

Step 4: Reading measurements sent by your IoT device

Finally, after connecting your IoT devices you (or any other developer with the right access permissions) should be able to use the Context Broker NGSI API to query the NGSI entity assigned to your device.

In the first example, using the public FIWARE instance, you may check in the public Context Broker (at 130.206.80.40:1026), the Entity_ID=”thing:[ENTITY_ID]” and the attribute temperature with the correct updated value.

In the Tour Guide Application example you can check that the temperature value has been properly propagated by running (with extra headers fiware-service: tourguide):

GET http://localhost:1026/v2/entities/0115206c51f60b48b77e4c937835795c33bb953f?attrs=temperature

{
  "id": "0115206c51f60b48b77e4c937835795c33bb953f",
  "type": "Restaurant",
  "temperature": {
    "type": "number",
    "value": "22.3",
    "metadata": {}
  }
}

For more examples on how to access the Context Broker, please refer to such component section.