CityIoT - Alusta

6Aika: Tulevaisuuden toimijariippumaton dataintegraatioalusta · cityiot.fi

Tälle sivustolle on koottu teknisiä tietoja pilotointialustasta, sen komponenteista ja avoimesta datasta. Sivuston sisältöä muokataan ja laajennetaan hankkeen edetessä.

Lisätietoja hankkeesta sivustolla cityiot.fi.

Rajoitukset

Alusta on jatkuvan kehitystyön alla. Alustan käyttäjien on suositeltavaa varautua seuraaviin tilanteisiin.

Alustalle tallennettu data ei välttämättä säily
Alusta ei välttämättä ole saavutettavissa kaiken aikaa
Pääsyä alustan toimintoihin on rajoitettu
Käytettävät komponentit saattavat vaihtua

Pilotointialusta

Yleinen kuvaus pilotointialustasta ja datavirroista

IoT-laitteen ja Context brokerin välinen kommunikaatio

https://github.com/telefonicaid/iotagent-node-lib#device-to-ngsi-mapping

Lähde: FIWARE IoT Agent Framework - Device to NGSI Mapping

Komponentit

Orion Context Broker

STH-Comet - FIWARE Short Time Historic

FIWARE IoT Agent for Ultralight 2.0

MongoDB

mongodb.com

Ohje- ja tukimateriaalia

FIWAREn kehitys ja kehitykseen vaikuttaneet

Skaalaaminen

FIWARE-pilotointialusta valinta

Tuotantoympäristö: https://pan0107.panoulu.net
- Vaatii lisäksi jokaisen kutsun headerin "Platform-ApiKey": {SECRET_API_KEY}
Sandbox-ympäristö: http://pan0108.panoulu.net
- Testausta varten. Tyhjennetään aina puolen yön aikoihin.
- Ei vaadi erillistä headeria api-avainta varten
- Osoite saattaa muuttua https-versioksi myöhemmin.

Datalähteen integraatio

1. Suunnittelu

Toimivan kokonaisuuden kannalta on tärkeää suunnitella käytettävät tietorakenteet ja tiedon ryhmittely kunnolla. Onnistunut suunnittelu mahdollistaa kerätyn datan sujuvan ja monipuolisen hyödyntämisen.

Tässä esimerkissä otetaan huomioon vain yksittäinen mittauspiste eikä sen ympärille tuoda kaikkea kuvaavan kontekstin luomiseksi.

A) Liittyvä dokumentaatio

Fiware-Service: FIWARE - Multi tenancy
Fiware-ServicePath: FIWARE - Entity service paths
Rajoitukset
- NGSIv2 - Specific restrictions for ID fields
- Orion Context Broker - Forbidden characters
- Orion Context Broker - Known limitations
- FIWARE - Multi tenancy
- Käytettävän pitkäaikaistallennuksen tuomat rajoitteet: MongoDB/STH character set and size limitations

B) Datamallit

FIWARE Data Models
Attribute Metadata
Tips on how to model your project entities with the IoT Platform
Performance considerations
UNECE - Codes for Units of Measure Used in International Trade
(suora linkki zip-pakettiin, josta yksikkökoodit löytyvät Excel-tiedostosta: rec20_Rev7e_2010.zip)

C) Suunnittelussa otettava huomioon

Datan hyödyntäjä tarvitsee datan lisäksi myös niin sanottua metadataa eli tietoa datasta. Alla muutamia esimerkkejä.
- Mistä data on peräisin?
- Milloin yksittäinen arvo on syntynyt?
- Mikä on mittalaitteen virhemarginaali?
- Millä laitteella mittaus on tehty?
- Missä yksiköissä mittaustulos ilmoitetaan?

D) Esimerkki - Ilmanlaatu

{
    "id": "rio202",
    "type": "AirQualityObserved",
    "TimeInstant": {
        "type": "ISO8601",
        "value": "2018-11-14T09:10:06.00Z",
        "metadata": {}
    },
    "CO2": {
        "type": "Number",
        "value": 1198,
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-14T09:10:06.877Z"
            },
            "description": {
                "type": "Text",
                "value": "Room 202 - Carbon dioxide concentration"
            },
            "unitCode": {
                "type": "Text",
                "value": "59"
            }
        }
    },
    "relativeHumidity": {
        "type": "Percentage",
        "value": "26.6",
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-14T09:10:06.877Z"
            },
            "description": {
                "type": "Text",
                "value": "Room 202 - Relative humidity"
            },
            "unitCode": {
                "type": "Text",
                "value": "P1"
            }
        }
    },
    "temperature": {
        "type": "Number",
        "value": 21.1,
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-14T09:10:06.877Z"
            },
            "description": {
                "type": "Text",
                "value": "Room 202 - Temperature"
            },
            "unitCode": {
                "type": "Text",
                "value": "CEL"
            }
        }
    },
    "VOC": {
        "type": "Number",
        "value": 107,
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-14T09:10:06.877Z"
            },
            "description": {
                "type": "Text",
                "value": "Room 202 - Total Volatile Organic Compound"
            },
            "unitCode": {
                "type": "Text",
                "value": "61"
            }
        }
    }
}

2. Entiteetin rekisteröinti

Uuden entiteein rekisteröintiin vaaditaan

Fiware-Service - FIWARE - Multi tenancy
Fiware-ServicePath - FIWARE - Entity service paths
Entiteetin JSON muotoinen minimikuvaus
Liityvä API dokumentaatio - Orion NGSI APIv2 Specification

A) Rekisteröinti

Entiteetin rekisteröinti

curl -X 'POST' -H 'Content-Type: application/json' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' -d '{"source": {"type": "Text", "value": "Pointer to a physical place where data has been collected."}, "type": "AirQualityObserved", "id": "b3ea", "location": {"type": "geo:json", "value": {"type": "Point", "coordinates": [65.0459409, 25.586883]}}}' '{PLATFORM_DOMAIN}:8000/orion/v2/entities'

Edellä oleva auki purettuna
{PLATFORM_DOMAIN} = valittu FIWARE-ympäristö

POST {PLATFORM_DOMAIN}:8000/orion/v2/entities

Headers:
{
  "Fiware-Service": "air_quality_def8",
  "Content-Type": "application/json",
  "Fiware-ServicePath": "/air"
}

Payload:
{
  "source": {
    "type": "Text",
    "value": "Pointer to a physical..."
  },
  "type": "AirQualityObserved",
  "id": "b3ea",
  "location": {
    "type": "geo:json",
    "value": {
      "type": "Point",
      "coordinates": [
        65.0459409,
        25.586883
      ]
    }
  }
}

B) Rekisteröidyn entiteetin hakeminen Orion Contecxt Brokerilta

curl -X 'GET' -H 'Accept: application/json' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' '{PLATFORM_DOMAIN}:8000/orion/v2/entities/b3ea'

Vastaus pyyntöön

{
  "id": "b3ea",
  "location": {
    "metadata": {},
    "type": "geo:json",
    "value": {
      "coordinates": [
        65.0459409,
        25.586883
      ],
      "type": "Point"
    }
  },
  "source": {
    "metadata": {},
    "type": "Text",
    "value": "Pointer to a physical..."
  },
  "type": "AirQualityObserved"
}

3. Palvelukonfiguraation rekisteröinti IoT Agentille

Uuden palvelukonfiguraation rekisteröintiin vaaditaan

Fiware-Service - FIWARE - Multi tenancy
Fiware-ServicePath - FIWARE - Entity service paths
Konfiguraation JSON muotoinen kuvaus
Liityvä API dokumentaatio - IoT Agent Configuration API

A) Rekisteröinti

Palvelukonfiguraation rekisteröinti

curl -X 'POST' -H 'Content-Type: application/json' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' -d '{"services": [{"apikey": "sensors-def8", "resource": "/iot/d", "entity_type": "AirQualityObserved", "cbroker": "{PLATFORM_DOMAIN}:8000/orion"}]}' '{PLATFORM_DOMAIN}:8000/idasmgmt/iot/services'

Edellä oleva auki purettuna

POST {PLATFORM_DOMAIN}:8000/idasmgmt/iot/services

Headers:
{
  "Fiware-Service": "air_quality_def8",
  "Content-Type": "application/json",
  "Fiware-ServicePath": "/air"
}

Payload:
{
  "services": [
    {
      "apikey": "sensors-def8",
      "resource": "/iot/d",
      "entity_type": "AirQualityObserved",
      "cbroker": "{PLATFORM_DOMAIN}:8000/orion"
    }
  ]
}

4. Sensorin tai useita sensoreita sisältävän laitteen rekisteröinti IoT Agentille

Uuden sensorin tai useita sensoreita sisältävän laitten rekisteröintiin vaaditaan

Fiware-Service - FIWARE - Multi tenancy
Fiware-ServicePath - FIWARE - Entity service paths
JSON muotoinen kuvaus rekisteröitävistä sensoreista ja niiden tuottamista attribuuteista
Liityvä API dokumentaatio - IoT Agent Configuration API

A) Rekisteröinti

Laitteen rekisteröinti

curl -X 'POST' -H 'Content-Type: application/json' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' -d '{"devices": [{"protocol": "UL20", "entity_name": "b3ea", "entity_type": "AirQualityObserved", "timezone": "Europe/Helsinki", "attributes": [{"type": "Number", "name": "temperature", "object_id": "temp"}, {"type": "Percentage", "name": "relativeHumidity", "object_id": "humidity"}, {"type": "Percentage", "name": "CO2", "object_id": "co2"}, {"type": "Text", "name": "airQualityLevel", "object_id": "aql"}, {"type": "Number", "name": "airQualityIndex", "object_id": "aqi"}], "device_id": "b3ea-118a"}]}' '{PLATFORM_DOMAIN}:8000/idasmgmt/iot/devices'

Edellä oleva auki purettuna

POST {PLATFORM_DOMAIN}:8000/idasmgmt/iot/devices

Headers:
{
  "Fiware-Service": "air_quality_def8",
  "Content-Type": "application/json",
  "Fiware-ServicePath": "/air"
}

Payload:
{
  "devices": [
    {
      "protocol": "UL20",
      "entity_name": "b3ea",
      "entity_type": "AirQualityObserved",
      "timezone": "Europe/Helsinki",
      "attributes": [
        {
          "type": "Number",
          "name": "temperature",
          "object_id": "temp"
        },
        {
          "type": "Percentage",
          "name": "relativeHumidity",
          "object_id": "humidity"
        },
        {
          "type": "Percentage",
          "name": "CO2",
          "object_id": "co2"
        },
        {
          "type": "Text",
          "name": "airQualityLevel",
          "object_id": "aql"
        },
        {
          "type": "Number",
          "name": "airQualityIndex",
          "object_id": "aqi"
        }
      ],
      "device_id": "b3ea-118a"
    }
  ]
}

5. Attribuuttien metadatan täydentäminen

Metadatan lisäämiseen tarvitaan

Fiware-Service - FIWARE - Multi tenancy
Fiware-ServicePath - FIWARE - Entity service paths
Päivitettävä attribuutti kaikkine tietoineen
Lisättävä metadata
Liityvä API dokumentaatio - Orion NGSI APIv2 Specification

A) Metadatan lisääminen laitteiden rekisteröinnin tuottamille attribuuteille

Metadatan lisääminen lämpötilaa kuvaavalle attribuutille

curl -X 'PUT' -H 'Content-Type: application/json' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' -d '{"type": "Number", "value": 0, "metadata": {"unitCode": {"type": "Text", "value": "CEL"}, "description": {"type": "Text", "value": "Temperature is a physical quantity expressing hot and cold. Temperature is measured with a thermometer, historically calibrated in various temperature scales and units of measurement. [Wikipedia]"}}}' '{PLATFORM_DOMAIN}:8000/orion/v2/entities/b3ea/attrs/temperature'

Edellä oleva auki purettuna

PUT {PLATFORM_DOMAIN}:8000/orion/v2/entities/b3ea/attrs/temperature

Headers:
{
  "Fiware-Service": "air_quality_def8",
  "Content-Type": "application/json",
  "Fiware-ServicePath": "/air"
}

Payload:
{
  "type": "Number",
  "value": 0,
  "metadata": {
    "unitCode": {
      "type": "Text",
      "value": "CEL"
    },
    "description": {
      "type": "Text",
      "value": "Temperature is a physical..."
    }
  }
}

B) Lisättyn metadatan tarkistaminen

Curl-esimerkki pyynnöstä

curl -X 'GET' -H 'Accept: application/json' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' '{PLATFORM_DOMAIN}:8000/orion/v2/entities/b3ea'

Vastaus pyyntöön

{
  "CO2": {
    "metadata": {
      "description": {
        "type": "Text",
        "value": "Carbon dioxide is..."
      }
    },
    "type": "Percentage",
    "value": " "
  },
  "TimeInstant": {
    "metadata": {},
    "type": "ISO8601",
    "value": " "
  },
  "airQualityIndex": {
    "metadata": {
      "description": {
        "type": "Text",
        "value": "Air quality index..."
      },
      "referenceSpecification": {
        "type": "URL",
        "value": "https://airnow.gov/index.cfm"
      }
    },
    "type": "Number",
    "value": 0
  },
  "airQualityLevel": {
    "metadata": {
      "description": {
        "type": "Text",
        "value": "Overall qualitative level..."
      },
      "referenceSpecification": {
        "type": "URL",
        "value": "https://airnow.gov/index.cfm"
      }
    },
    "type": "Text",
    "value": " "
  },
  "id": "b3ea",
  "location": {
    "metadata": {},
    "type": "geo:json",
    "value": {
      "coordinates": [
        65.0459409,
        25.586883
      ],
      "type": "Point"
    }
  },
  "relativeHumidity": {
    "metadata": {
      "description": {
        "type": "Text",
        "value": "Relative humidity is..."
      }
    },
    "type": "Percentage",
    "value": " "
  },
  "source": {
    "metadata": {},
    "type": "Text",
    "value": "Pointer to a physical place where data has been collected."
  },
  "temperature": {
    "metadata": {
      "description": {
        "type": "Text",
        "value": "Temperature is a physical..."
      },
      "unitCode": {
        "type": "Text",
        "value": "CEL"
      }
    },
    "type": "Number",
    "value": 0
  },
  "type": "AirQualityObserved"
}

6. Datalähetyksen testaus

Datan lähettämiseen tarvitaan

Fiware-Service - FIWARE - Multi tenancy
Fiware-ServicePath - FIWARE - Entity service paths
Laitteen API-Key
Laitteen tunniste
Määrämuotoinen esitys datasta
Liityvä API dokumentaatio - IoT Agent Data API - Ultralight 2.0 Protocol

A) Datan lähetys UltraLight2.0 protokollaa hyödyntäen

Datan lähetys

curl -X 'POST' -H 'Content-Type: text/plain' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' -d 'temp|17.6|humidity|0.32|co2|0.05784|aql|moderate|aqi|64.0' '{PLATFORM_DOMAIN}:8000/idasdata/iot/d?k=sensors-def8&i=b3ea-118a'

Edellä oleva auki purettuna

POST {PLATFORM_DOMAIN}:8000/idasdata/iot/d?k=sensors-def8&i=b3ea-118a

Headers:
{
  "Fiware-Service": "air_quality_def8",
  "Content-Type": "text/plain",
  "Fiware-ServicePath": "/air"
}

Payload:
temp|17.6|humidity|0.32|co2|0.05784|aql|moderate|aqi|64.0

7. Viimeisimmän datan hakeminen Context Brokerilta

A) Ajantasaisimman kontekstitiedon hakeminen Context Brokerilta

curl -X 'GET' -H 'Accept: application/json' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' '{PLATFORM_DOMAIN}:8000/orion/v2/entities/b3ea'

Vastaus pyyntöön

{
  "CO2": {
    "metadata": {
      "TimeInstant": {
        "type": "ISO8601",
        "value": "2018-07-02T10:42:24.814Z"
      },
      "description": {
        "type": "Text",
        "value": "Carbon dioxide is..."
      }
    },
    "type": "Percentage",
    "value": "0.05784"
  },
  "TimeInstant": {
    "metadata": {},
    "type": "ISO8601",
    "value": "2018-07-02T10:42:24.00Z"
  },
  "airQualityIndex": {
    "metadata": {
      "TimeInstant": {
        "type": "ISO8601",
        "value": "2018-07-02T10:42:24.814Z"
      },
      "description": {
        "type": "Text",
        "value": "Air quality index..."
      },
      "referenceSpecification": {
        "type": "URL",
        "value": "https://airnow.gov/index.cfm"
      }
    },
    "type": "Number",
    "value": 64
  },
  "airQualityLevel": {
    "metadata": {
      "TimeInstant": {
        "type": "ISO8601",
        "value": "2018-07-02T10:42:24.814Z"
      },
      "description": {
        "type": "Text",
        "value": "Overall qualitative level..."
      },
      "referenceSpecification": {
        "type": "URL",
        "value": "https://airnow.gov/index.cfm"
      }
    },
    "type": "Text",
    "value": "moderate"
  },
  "id": "b3ea",
  "location": {
    "metadata": {},
    "type": "geo:json",
    "value": {
      "coordinates": [
        65.0459409,
        25.586883
      ],
      "type": "Point"
    }
  },
  "relativeHumidity": {
    "metadata": {
      "TimeInstant": {
        "type": "ISO8601",
        "value": "2018-07-02T10:42:24.814Z"
      },
      "description": {
        "type": "Text",
        "value": "Relative humidity is..."
      }
    },
    "type": "Percentage",
    "value": "0.32"
  },
  "source": {
    "metadata": {},
    "type": "Text",
    "value": "Pointer to a physical..."
  },
  "temperature": {
    "metadata": {
      "TimeInstant": {
        "type": "ISO8601",
        "value": "2018-07-02T10:42:24.814Z"
      },
      "description": {
        "type": "Text",
        "value": "Temperature is a physical..."
      },
      "unitCode": {
        "type": "Text",
        "value": "CEL"
      }
    },
    "type": "Number",
    "value": 17.6
  },
  "type": "AirQualityObserved"
}

8. Datan pitkäaikaisvarastointi STH-Comet komponenttia hyödyntäen

Varastointi toteutetaa tilaamalla dataa koskevat muutokset Orion Context Brokerilta. Ilmoitukset ohjataan STH-Comet komponentille.

Muutosten tilaamiseen tarvitaan

Fiware-Service - FIWARE - Multi tenancy
Fiware-ServicePath - FIWARE - Entity service paths
Tiedot varastoitavasta datasta
Liityvä API dokumentaatio - Orion Subscribtion API

A) Muutosten tilaaminen

curl -X 'POST' -H 'Content-Type: application/json' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' -d '{"throttling": 5, "notification": {"attrsFormat": "legacy", "http": {"url": "http://sth-comet:8666/notify"}, "attrs": ["temperature", "relativeHumidity"]}, "expires": "2019-07-01T10:00:00.00Z", "description": "Subscription to collect data available via FiwareServicePath /air with Entity type AirQualityObserved", "subject": {"entities": [{"idPattern": ".*", "type": "AirQualityObserved"}], "condition": {"attrs": ["temperature", "relativeHumidity"]}}}' '{PLATFORM_DOMAIN}:8000/orion/v2/subscriptions'

Edellä oleva auki purettuna

POST {PLATFORM_DOMAIN}:8000/orion/v2/subscriptions

Headers:
{
  "Fiware-Service": "air_quality_def8",
  "Fiware-ServicePath": "/air",
  "Accept": "application/json"
}

Payload:
{
  "throttling": 5,
  "notification": {
    "attrsFormat": "legacy",
    "http": {
      "url": "http://sth-comet:8666/notify"
    },
    "attrs": [
      "temperature",
      "relativeHumidity"
    ]
  },
  "expires": "2019-07-01T10:00:00.00Z",
  "description": "Subscription to collect data available via FiwareServicePath /air with Entity type AirQualityObserved",
  "subject": {
    "entities": [
      {
        "idPattern": ".*",
        "type": "AirQualityObserved"
      }
    ],
    "condition": {
      "attrs": [
        "temperature",
        "relativeHumidity"
      ]
    }
  }
}

Datan hyödyntäminen

1. Oulun säätila

A) Muutosten tilaaminen Context Brokerilta

Muutosten tilaaminen on suositeltu tapa ajantasaisimman datan seuraamiseen. Muutokset voi tilata Orion Context Brokerin Subscribtion APIn kautta.

Fiware-Service - FIWARE - Multi tenancy
Fiware-ServicePath - FIWARE - Entity service paths
Liityvä API dokumentaatio - Orion Subscribtion API
Tiedot tilattavasta datasta
HTTP POST pyyntöjä vastaanottamaan kykenevä palvelin

A) Muutosten tilaaminen

curl -X 'POST' -H 'Content-Type: application/json' -H 'Fiware-Service: air_quality_def8' -H 'Fiware-ServicePath: /air' -d '{"throttling": 5, "notification": {"http": {"url": "{RECEIPENT_HOST_ADDRESS}"}, "attrs": ["temperature", "relativeHumidity"]}, "expires": "2019-07-01T10:00:00.00Z", "description": "Subscription to collect data available via FiwareServicePath /air with Entity type AirQualityObserved", "subject": {"entities": [{"idPattern": ".*", "type": "AirQualityObserved"}], "condition": {"attrs": ["temperature", "relativeHumidity"]}}}' '{PLATFORM_DOMAIN}:8000/orion/v2/subscriptions'

Edellä oleva auki purettuna

{RECEIPENT_HOST_ADDRESS} = tilauksen vastaanottajan osoite
- käytettäessä pilottiympäristössä pyörivää STH-Cometia arvo on "http://sth-comet:8666/notify"

POST {PLATFORM_DOMAIN}:8000/orion/v2/subscriptions

Headers:
{
  "Fiware-Service": "air_quality_def8",
  "Fiware-ServicePath": "/air",
  "Accept": "application/json"
}

Payload:
{
  "throttling": 5,
  "notification": {
    "http": {
      "url": "{RECEIPENT_HOST_ADDRESS}"
    },
    "attrs": [
      "temperature",
      "relativeHumidity"
    ]
  },
  "expires": "2019-07-01T10:00:00.00Z",
  "description": "Subscription to collect data available via FiwareServicePath /air with Entity type AirQualityObserved",
  "subject": {
    "entities": [
      {
        "idPattern": ".*",
        "type": "AirQualityObserved"
      }
    ],
    "condition": {
      "attrs": [
        "temperature",
        "relativeHumidity"
      ]
    }
  }
}

B) Ajantasaisimman säätiedon hakeminen Context Brokerilta

curl -X 'GET' -H 'Accept: application/json' -H 'Fiware-Service: weather' -H 'Fiware-ServicePath: /oulu' '{PLATFORM_DOMAIN}:8000/orion/v2/entities/0e72'

Vastaus pyyntöön

{
    "id": "0e72",
    "type": "WeatherObserved",
    "TimeInstant": {
        "type": "ISO8601",
        "value": "2018-11-09T13:24:22.00Z",
        "metadata": {}
    },
    "atmosphericPressure": {
        "type": "Number",
        "value": 1023,
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-09T13:24:22.939Z"
            },
            "unitCode": {
                "type": "Text",
                "value": "A97"
            }
        }
    },
    "dateObserved": {
        "type": "DateTime",
        "value": "2018-06-14T10:18:16.00Z",
        "metadata": {}
    },
    "name": {
        "type": "Text",
        "value": "OpenWeathermapAPI",
        "metadata": {}
    },
    "relativeHumidity": {
        "type": "Number",
        "value": 93,
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-09T13:24:22.939Z"
            },
            "unitCode": {
                "type": "Text",
                "value": "P1"
            }
        }
    },
    "source": {
        "type": "Text",
        "value": "RaspberryPi",
        "metadata": {}
    },
    "temperature": {
        "type": "Number",
        "value": 6,
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-09T13:24:22.939Z"
            },
            "unitCode": {
                "type": "Text",
                "value": "CEL"
            }
        }
    },
    "weatherType": {
        "type": "Text",
        "value": "Rain",
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-09T13:24:22.939Z"
            }
        }
    },
    "windDirection": {
        "type": "Number",
        "value": 140,
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-09T13:24:22.939Z"
            },
            "unitCode": {
                "type": "Text",
                "value": "DD"
            }
        }
    },
    "windSpeed": {
        "type": "Number",
        "value": 2.1,
        "metadata": {
            "TimeInstant": {
                "type": "ISO8601",
                "value": "2018-11-09T13:24:22.939Z"
            },
            "unitCode": {
                "type": "Text",
                "value": "MTS"
            }
        }
    }
}

C) Säätietojen hakeminen STH-Comet pitkäaikaisvarastosta - Raakadata

curl -X 'GET' -H 'Accept: application/json' -H 'Fiware-Service: weather' -H 'Fiware-ServicePath: /oulu' '{PLATFORM_DOMAIN}:8000/comet/STH/v1/contextEntities/type/WeatherObserved/id/0e72/attributes/temperature?lastN=5'

Vastaus pyyntöön

{
  "contextResponses": [
    {
      "contextElement": {
        "attributes": [
          {
            "name": "temperature",
            "values": [
              {
                "recvTime": "2018-11-09T13:04:15.965Z",
                "attrType": "Number",
                "attrValue": "6"
              },
              {
                "recvTime": "2018-11-09T13:09:19.842Z",
                "attrType": "Number",
                "attrValue": "6"
              },
              {
                "recvTime": "2018-11-09T13:14:20.523Z",
                "attrType": "Number",
                "attrValue": "6"
              },
              {
                "recvTime": "2018-11-09T13:19:22.420Z",
                "attrType": "Number",
                "attrValue": "6"
              },
              {
                "recvTime": "2018-11-09T13:24:22.939Z",
                "attrType": "Number",
                "attrValue": "6"
              }
            ]
          }
        ],
        "id": "0e72",
        "isPattern": false,
        "type": "WeatherObserved"
      },
      "statusCode": {
        "code": "200",
        "reasonPhrase": "OK"
      }
    }
  ]
}

D) Säätietojen hakeminen STH-Comet pitkäaikaisvarastosta - Aggregoidut aikasarjat

curl -X 'GET' -H 'Accept: application/json' -H 'Fiware-Service: weather' -H 'Fiware-ServicePath: /oulu' '{PLATFORM_DOMAIN}:8000/comet/STH/v1/contextEntities/type/WeatherObserved/id/0e72/attributes/temperature?aggrMethod=max&aggrPeriod=hour&dateFrom=2018-10-10T00:00:00.000Z&dateTo=2018-10-10T23:59:59.999Z'

Vastaus pyyntöön

{
  "contextResponses": [
    {
      "contextElement": {
        "attributes": [
          {
            "name": "temperature",
            "values": [
              {
                "_id": {
                  "origin": "2018-10-10T00:00:00.000Z",
                  "resolution": "hour"
                },
                "points": [
                  {
                    "offset": 0,
                    "samples": 12,
                    "max": 7
                  },
                  {
                    "offset": 1,
                    "samples": 12,
                    "max": 8
                  },
                  {
                    "offset": 2,
                    "samples": 12,
                    "max": 8
                  },
                  {
                    "offset": 3,
                    "samples": 12,
                    "max": 7
                  },
                  {
                    "offset": 4,
                    "samples": 12,
                    "max": 7
                  },
                  {
                    "offset": 5,
                    "samples": 12,
                    "max": 7
                  },
                  {
                    "offset": 6,
                    "samples": 12,
                    "max": 8
                  },
                  {
                    "offset": 7,
                    "samples": 12,
                    "max": 8
                  },
                  {
                    "offset": 8,
                    "samples": 12,
                    "max": 9
                  },
                  {
                    "offset": 9,
                    "samples": 12,
                    "max": 9
                  },
                  {
                    "offset": 10,
                    "samples": 12,
                    "max": 9
                  },
                  {
                    "offset": 11,
                    "samples": 12,
                    "max": 9
                  },
                  {
                    "offset": 12,
                    "samples": 12,
                    "max": 9
                  },
                  {
                    "offset": 13,
                    "samples": 12,
                    "max": 9
                  },
                  {
                    "offset": 14,
                    "samples": 12,
                    "max": 9
                  },
                  {
                    "offset": 15,
                    "samples": 12,
                    "max": 8
                  },
                  {
                    "offset": 16,
                    "samples": 12,
                    "max": 7
                  },
                  {
                    "offset": 17,
                    "samples": 12,
                    "max": 7
                  },
                  {
                    "offset": 18,
                    "samples": 12,
                    "max": 6
                  },
                  {
                    "offset": 19,
                    "samples": 12,
                    "max": 6
                  },
                  {
                    "offset": 20,
                    "samples": 12,
                    "max": 6
                  },
                  {
                    "offset": 21,
                    "samples": 12,
                    "max": 6
                  },
                  {
                    "offset": 22,
                    "samples": 12,
                    "max": 6
                  },
                  {
                    "offset": 23,
                    "samples": 12,
                    "max": 6
                  }
                ]
              }
            ]
          }
        ],
        "id": "0e72",
        "isPattern": false,
        "type": "WeatherObserved"
      },
      "statusCode": {
        "code": "200",
        "reasonPhrase": "OK"
      }
    }
  ]
}

Usean mittauksen lähettäminen kerralla

Aikaisemmissa esimerkeissä on lähetetty vain yksi FIWARE-entiteetti kerralla. Orion Context Broker tarjoaa mahdollisuuden myös siihen, että lähetetään useampi entiteetti yhdellä http-kutsulla.

Huomautus: jos samassa lähetyksessä on useita päivityksiä samalle entiteetille (sama id ja tyyppi), kannattaa järjestää entiteettilista siten, että viimeisin arvopäivitys on listassa viimeisenä. Lisäksi tässä tapauksessa on vaarana, että mittausarvojen historiaa ylläpitävälle STH-Comet-komponentille välittyy vain osa lähetyksessä olleista arvopäivityksistä. Suositus on, että samalle entiteetille tehtävät päivitykset jaetaan erillisiin lähetyksiin.

FIWARE-dokumentaatiota

API-kuvaus - Orion - API description (vasemmasta reunasta Batch Operations)
Orion-dokumentaatio - Orion - Patch operations

1. Esimerkin datamalli

Seuraavia esimerkkejä varten luodun yksinkertaisen entiteetin datamalli.

description-attribuutti asetetaan vain kerran luotaessa uusi entiteetti.
numberAttr- ja textAttr-attribuuttien arvoja päivitetään uusilla aina uusien arvojen ollessa saatavilla.

{
  "id": "id_text",
  "type": "TestEntity",
  "description": {
    "type": "Text",
    "value": {ENTITY_DESCRIPTION}
  },
  "numberAttr": {
    "type": "Number",
    "value" {NUMERIC_VALUE},
    "metadata": {
      "timestamp": {
        "type": "DateTime",
        "value": {TIMESTAMP}
      }
    }
  },
  "textAttr": {
    "type": "Text",
    "value" {TEXT_VALUE},
    "metadata": {
      "timestamp": {
        "type": "DateTime",
        "value": {TIMESTAMP}
      }
    }
  }
}

2. Uusien entiteettien luominen

Esimerkki kolmen uuden entiteetin luomisesta yhdellä kutsulla.

curl -X 'POST' -H 'Content-Type: application/json' -H 'Fiware-Service: test' -H 'Fiware-ServicePath: /city/location' -d '{"actionType": "append", "entities": [{"id": "TestEntity:test_abc", "type": "TestEntity", "description": {"type": "Text", "value": "This is test_abc."}}, {"id": "TestEntity:test_def", "type": "TestEntity", "description": {"type": "Text", "value": "This is test_def."}}, {"id": "TestEntity:test_ghi", "type": "TestEntity", "description": {"type": "Text", "value": "This is test_ghi."}}]}' '{PLATFORM_DOMAIN}:8000/orion/v2/op/update'

Edellä oleva auki purettuna

POST {PLATFORM_DOMAIN}:8000/orion/v2/op/update

Headers:
{
  "Accept": "application/json",
  "Fiware-Service": "test",
  "Fiware-ServicePath": "/city/location"
}

Payload:
{
  "actionType": "append",
  "entities": [
    {
      "id": "TestEntity:test_abc",
      "type": "TestEntity",
      "description": {
        "type": "Text",
        "value": "This is test_abc."
      }
    },
    {
      "id": "TestEntity:test_def",
      "type": "TestEntity",
      "description": {
        "type": "Text",
        "value": "This is test_def."
      }
    },
    {
      "id": "TestEntity:test_ghi",
      "type": "TestEntity",
      "description": {
        "type": "Text",
        "value": "This is test_ghi."
      }
    }
  ]
}

3. Päivityksien lähettäminen entiteetteihin

Esimerkki kolmen entiteetin attribuuttiarvojen päivittämisestä yhdellä kutsulla.

curl -X 'POST' -H 'Content-Type: application/json' -H 'Fiware-Service: test' -H 'Fiware-ServicePath: /city/location' -d '{"actionType": "append", "entities": [{"id": "TestEntity:test_abc", "type": "TestEntity", "numberAttr": {"type": "Number", "value": 12.5, "metadata": {"timestamp": {"type": "DateTime", "value": "2019-01-01T00:00:01Z"}}}, "textAttr": {"type": "Text", "value": "Red", "metadata": {"timestamp": {"type": "DateTime", "value": "2019-01-01T00:00:02Z"}}}}, {"id": "TestEntity:test_def", "type": "TestEntity", "numberAttr": {"type": "Number", "value": 1234, "metadata": {"timestamp": {"type": "DateTime", "value": "2019-01-01T11:11:11Z"}}}, "textAttr": {"type": "Text", "value": "Green", "metadata": {"timestamp": {"type": "DateTime", "value": "2019-01-01T11:11:11Z"}}}}, {"id": "TestEntity:test_ghi", "type": "TestEntity", "numberAttr": {"type": "Number", "value": -5000.001, "metadata": {"timestamp": {"type": "DateTime", "value": "2019-02-02T10:12:34Z"}}}, "textAttr": {"type": "Text", "value": "Blue", "metadata": {"timestamp": {"type": "DateTime", "value": "2019-02-11T15:35:57Z"}}}}]}' '{PLATFORM_DOMAIN}:8000/orion/v2/op/update'

Edellä oleva auki purettuna

POST {PLATFORM_DOMAIN}:8000/orion/v2/op/update

Headers:
{
  "Accept": "application/json",
  "Fiware-Service": "test",
  "Fiware-ServicePath": "/city/location"
}

Payload:
{
  "actionType": "append",
  "entities": [
    {
      "id": "TestEntity:test_abc",
      "type": "TestEntity",
      "numberAttr": {
        "type": "Number",
        "value": 12.5,
        "metadata": {
          "timestamp": {
            "type": "DateTime",
            "value": "2019-01-01T00:00:01Z"
          }
        }
      },
      "textAttr": {
        "type": "Text",
        "value": "Red",
        "metadata": {
          "timestamp": {
            "type": "DateTime",
            "value": "2019-01-01T00:00:02Z"
          }
        }
      }
    },
    {
      "id": "TestEntity:test_def",
      "type": "TestEntity",
      "numberAttr": {
        "type": "Number",
        "value": 1234,
        "metadata": {
          "timestamp": {
            "type": "DateTime",
            "value": "2019-01-01T11:11:11Z"
          }
        }
      },
      "textAttr": {
        "type": "Text",
        "value": "Green",
        "metadata": {
          "timestamp": {
            "type": "DateTime",
            "value": "2019-01-01T11:11:11Z"
          }
        }
      }
    },
    {
      "id": "TestEntity:test_ghi",
      "type": "TestEntity",
      "numberAttr": {
        "type": "Number",
        "value": -5000.001,
        "metadata": {
          "timestamp": {
            "type": "DateTime",
            "value": "2019-02-02T10:12:34Z"
          }
        }
      },
      "textAttr": {
        "type": "Text",
        "value": "Blue",
        "metadata": {
          "timestamp": {
            "type": "DateTime",
            "value": "2019-02-11T15:35:57Z"
          }
        }
      }
    }
  ]
}

4. Päivityksien onnistumisen testaus

Esimerkki päivityksien onnistumisen testauksesta.

curl -X 'GET' -H 'Accept: application/json' -H 'Fiware-Service: test' -H 'Fiware-ServicePath: /city/location' '{PLATFORM_DOMAIN}:8000/orion/v2/entities'

Vastaus pyyntöön

[
  {
    "id": "TestEntity:test_abc",
    "type": "TestEntity",
    "description": {
      "type": "Text",
      "value": "This is test_abc.",
      "metadata": {}
    },
    "numberAttr": {
      "type": "Number",
      "value": 12.5,
      "metadata": {
        "timestamp": {
          "type": "DateTime",
          "value": "2019-01-01T00:00:01.00Z"
         }
      }
    },
    "textAttr": {
      "type": "Text",
      "value": "Red",
      "metadata": {
        "timestamp": {
          "type": "DateTime",
          "value": "2019-01-01T00:00:02.00Z"
        }
      }
    }
  },
  {
    "id": "TestEntity:test_def",
    "type": "TestEntity",
    "description": {
      "type": "Text",
      "value": "This is test_def.",
      "metadata": {}
    },
    "numberAttr": {
      "type": "Number",
      "value": 1234,
      "metadata": {
        "timestamp": {
          "type": "DateTime",
          "value": "2019-01-01T11:11:11.00Z"
        }
      }
    },
    "textAttr": {
      "type": "Text",
      "value": "Green",
      "metadata": {
        "timestamp": {
          "type": "DateTime",
          "value": "2019-01-01T11:11:11.00Z"
        }
      }
    }
  },
  {
    "id": "TestEntity:test_ghi",
    "type": "TestEntity",
    "description": {
      "type": "Text",
      "value": "This is test_ghi.",
      "metadata": {}
    },
    "numberAttr": {
      "type": "Number",
      "value": -5000.001,
      "metadata": {
        "timestamp": {
          "type": "DateTime",
         "value": "2019-02-02T10:12:34.00Z"
        }
      }
    },
    "textAttr": {
      "type": "Text",
      "value": "Blue",
      "metadata": {
        "timestamp": {
          "type": "DateTime",
          "value": "2019-02-11T15:35:57.00Z"
        }
      }
    }
  }
]

Datan perusvisualisointi

Alustalle tallenettua dataa voidaan visualisoida Fiwaren tarjoamalla WireCloud-sovelluksella. Wirecloud tarjoaa alustan, minne voi rakentaa erilaisia sovellusyhdistelmiä (Mashup), jotka koostuvat yksittäisistä komponenteista (Widget).

Seuraavaksi kuvattu Mashup/Widgetit on rakennettu pilotin tarpeita varten. Tällä hetkellä tarjolla on kiinteä Mashup, jolla pystyy ainoastaan tarkastelemaan dataa. Tavoitteena kuitenkin on viimeistellä rakennetut Widgetit ja julkaista ne Wireclouden kaupassa, jolloin niitä voisi vapaasti kuka tahansa hyödyntää ja muokata omien tarpeiden mukaan.

1. Wirecloud esittely

Wirecloud-sovellus löytyy Fiware Lab:sta. Käyttäjän tulee rekisteröityä Fiware Lab:iin ja pyytää pilotin yhteyshenkilöä lisäämään käyttäjälle oikeudet alla näkyvään Mashup:iin.

Mashup rakentuu kolmesta (3) tärkeimmästä widgetistä, joilla data saadaan visualisoitua.

mainWidgetV2 - On ns. masterwidget, joka tarjoaa näkymän eri datalähteisiin nappien avulla ja hakee datan orionilta/cometilta.
Input Widget - Tukee mainWidgetV2:sta ja tarjoaa mahdollisuuden valita aikasarjahaun (timeperiod) ja viimesimpien arvojen (lastN) -haun väliltä, halutuilla parametreilla.
Highcharts Widget - Hyödyntää JavaScipt-kirjastoa Highcharts.js ja näyttää haetun datan graafisesti.

Wirecloud Mashup

2. Mashupin toiminta

Mashupin toimintaa on demonstroitu alla olevissa kuvissa. Kuvassa 2.1 näkyy mainWidgetV2:sen toimintaperiaate.

> Harmaat napit luodaan kullekin yritykselle/datalähteelle.

> Vihreät napit edustavat yrityksen kutakin mittauspaikkaa esim. huonetta.

> Siniset napit taas kuvaavat kunkin paikan/huoneen sensoria.

2.1 Mashupin yleisnäkymä ja esimerkki lastN-hausta

Harmaat ja vihreät napit tehtävänä on yleisesti luoda vain uusia nappeja kuvatakseen kunkin tietokannan rakennetta. Siniset napit lähettävät kutsuja orionille/cometille ja syöttävät datan Highcarts Widgetille. Dataa voidaan hakea usealta eri sensorilta yhtäaikaa ja visualisoida ne esimerkin mukaisesti vertailua varten. Ennen datan hakemista valitaan hakumetodi käyttämällä Input Widgetia.

2.2 Esimerkki aikaperiodi-hausta

Tässä esimerkissä on haettu aikaväliltä 29.07.2019 00:00 - 04.08.2019 00:00 käyttäjien seuranta dataa.

2.3 Esimerkki hälytyksiin pohjautuvasta tietorakenteesta ja hälytysten visualisoinnista

Tämä esimerkki poikkeaa hieman aiemmista datalähteistä. Paikkojen/huoneiden tilalla on yksittäisiä hälytyksiä, joita tässä tapauksessa on syntynyt aina kun on havaittu polttimon palaminen. Hälytykset kertomat polttimoiden tilan hälytyksen ajan hetkellä ja näiden perusteella voidaan rakentaa graafi, jolla voidaan seurata polttimoiden palamista ja huoltamista pitkällä aikavälillä.

Yksittäisiä hälytyksiä voidaan myös tarkastella tarkemmin ja katsoa mitatun datan arvoja hälytyksen ympärillä.

Yhteys

CityIoT - Alusta

6Aika: Tulevaisuuden toimijariippumaton dataintegraatioalusta · cityiot.fi

CityIoT - Alusta

Rajoitukset

Pilotointialusta

Yleinen kuvaus pilotointialustasta ja datavirroista

IoT-laitteen ja Context brokerin välinen kommunikaatio

Komponentit

Orion Context Broker

STH-Comet - FIWARE Short Time Historic

FIWARE IoT Agent for Ultralight 2.0

MongoDB

Ohje- ja tukimateriaalia

Datamallit

IoT Framework Architecture

IoT Big Data

FIWAREn kehitys ja kehitykseen vaikuttaneet

Skaalaaminen

FIWARE-pilotointialusta valinta

Datalähteen integraatio

1. Suunnittelu

2. Entiteetin rekisteröinti

3. Palvelukonfiguraation rekisteröinti IoT Agentille

4. Sensorin tai useita sensoreita sisältävän laitteen rekisteröinti IoT Agentille

5. Attribuuttien metadatan täydentäminen

6. Datalähetyksen testaus

7. Viimeisimmän datan hakeminen Context Brokerilta

8. Datan pitkäaikaisvarastointi STH-Comet komponenttia hyödyntäen

Datan hyödyntäminen

1. Oulun säätila

Usean mittauksen lähettäminen kerralla

1. Esimerkin datamalli

2. Uusien entiteettien luominen

3. Päivityksien lähettäminen entiteetteihin

4. Päivityksien onnistumisen testaus

Datan perusvisualisointi

1. Wirecloud esittely

Wirecloud Mashup

2. Mashupin toiminta

2.1 Mashupin yleisnäkymä ja esimerkki lastN-hausta

2.2 Esimerkki aikaperiodi-hausta

2.3 Esimerkki hälytyksiin pohjautuvasta tietorakenteesta ja hälytysten visualisoinnista

Yhteys

CityIoT - Alusta