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

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"
        }
      }
    }
  }
]

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

Yhteys

CityIoT - Alusta