FIWARE « ORION » Context Broker API

Online courses to understand FIWARE Context Broker
FIWARE Context Broker Github repository
FIWARE Context Broker - User & Programmer Guide full version

• Context broker endpoint: http://orion.lab.fiware.org:1026/
• To reach some Santander sensors
  • urn:smartsantander:testbed:10002 (santander:lux)
  • urn:x-iot:smartsantander:u7jcfa:fixed:t3314 (santander:device)
  • urn:smartsantander:testbed:481 (santander:soundacc)
  • urn:smartsantander:testbed:3314 (santander:traffic)
  • urn:smartsantander:testbed:3315 (santander:traffic)

FIWARE NGSI API
For FIWARE Context Broker we have implemented the standardized interface using OMA NGSI standards for Context Management:

NGSI 9:

NGSI 9 provides operations to answer the following questions: How to create an entity which will provide contextual information, how to discover this entity and how to subscribe to the flow of information of this entity.
In the TM Forum hackfest, FIWARE is providing real-time sensors data, each sensor being a dedicated entity
API examples

• Example of creation of two rooms which include their embedded sensors (temperature and pressure). We are doing in the same time registration and description: registerContext

  (curl localhost:1026/v1/registry/registerContext s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -d @ | python -mjson.tool) <<EOF { "contextRegistrations": [ { "entities": [ { "type": " Room ", "isPattern": "false", "id": "Room1" }, { "type": "Room", "isPattern": "false", "id": "Room2" } ], "attributes": [ { "name": "temperature", "type": "float", "isDomain": "false" }, { "name": "pressure", "type": "integer", "isDomain": "false" } ], "providingApplication": "http://mysensors.com/Rooms" } ], "duration": "P1M" } EOF

• Example to discover data that could be provided by Room1: discoverContextAvailability

  (curl localhost:1026/v1/registry/discoverContextAvailability s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -d @ | python -mjson.tool) <<EOF { "entities": [ { "type": "Room", "isPattern": "false", "id": "Room1" } ] } EOF

• and the related response:

  { "contextRegistrationResponses": [ { "contextRegistration": { "attributes": [ { "isDomain": "false", "name": "temperature", "type": "float" }, { "isDomain": "false", "name": "pressure", "type": "integer" } ], "entities": [ { "id": "Room1", "isPattern": "false", "type": "Room" } ], "providingApplication": "http://mysensors.com/Rooms" } } ] }

• How to be aware of new rooms availability: use subscribeContextAvailability

  (curl localhost:1026/v1/registry/subscribeContextAvailability s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -d @ | python -mjson.tool) <<EOF { "entities": [ { "type": "Room", "isPattern": "true", "id": ".*" } ], "attributes": [ "temperature" ], "reference": "http://localhost:1028/accumulate", "duration": "P1M" } EOF

  We are using the URL of an accumulator-server.py program to collect all these data.

• The response to the subscribeContextAvailability request is a subscription ID (a 24 hexadecimal number used for updating and cancelling the subscription

  { "duration": "P1M", "subscriptionId": "52a745e011f5816465943d59" }

   

  NGSI 10

  After creating or discovering the entities you have just to collect regularly entity information (updateContext) or in a more asynchronous mode collect from time to time entity information (queryContext).

• You have already discovered Room1, so with NGSI 10 updateContext you can regularly receive new data:

  (curl localhost:1026/v1/updateContext s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -d @ | python -mjson.tool) <<EOF { "contextElements": [ { "type": "Room", "isPattern": "false", "id": "Room1", "attributes": [ { "name": "temperature", "type": "float", "value": "23" }, { "name": "pressure", "type": "integer", "value": "720" } ] } ], "updateAction": "APPEND" } EOF

• The response is the following:

  { "contextResponses": [ { "contextElement": { "attributes": [ { "name": "temperature", "type": "float", "value": "" }, { "name": "pressure", "type": "integer", "value": "" } ], "id": "Room1", "isPattern": "false", "type": "Room" }, "statusCode": { "code": "200", "reasonPhrase": "OK" } } ] }

• Now let's play the role of a consumer application, wanting to access the context information at a dedicated moment. The NGSI10 queryContext request is used in this case, e.g. to get context information for Room1:

  (curl localhost:1026/v1/queryContext s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -d @ | python -mjson.tool) <<EOF { "entities": [ { "type": "Room", "isPattern": "false", "id": "Room1" } ] } EOF

  The response includes all the attributes belonging to Room1 :

  { "contextResponses": [ { "contextElement": { "attributes": [ { "name": "temperature", "type": "float", "value": "23" }, { "name": "pressure", "type": "integer", "value": "720" } ], "id": "Room1", "isPattern": "false", "type": "Room" }, "statusCode": { "code": "200", "reasonPhrase": "OK" } } ] }

• To subscribe to an entity and receive regularly new data, use the ONTIMEINTERVAL subscription:

  (curl localhost:1026/v1/subscribeContext s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -d @ | python -mjson.tool) <<EOF { "entities": [ { "type": "Room", "isPattern": "false", "id": "Room1" } ], "attributes": [ "temperature" ], "reference": "http://localhost:1028/accumulate", "duration": "P1M", "notifyConditions": [ { "type": "ONTIMEINTERVAL", "condValues": [ "PT10S" ] } ] } EOF

  Let's examine in detail the different elements included in the payload:

• 'entities' and 'attributes' define which context elements will be included in the notification message. You can even include lists or patterns to specify entities. In this example, we are specifying that the notification has to include the temperature attribute for entity Room1.
• The callback URL to send notifications is defined with the reference element. We are using the URL of the accumulator-server.py program (see full documentation for this part) . Only one reference can be included per subscribeContext request. However, you can have several subscriptions on the same context elements without any problem. Default URL schema (in the case you don't specify any) is "http", e.g. using "localhost:1028" as reference will be actually interpreted as "http://localhost:1028".
• Subscriptions have a duration, specified using the ISO 8601 standard format. Once that duration is expired, the subscription is simply ignored. You can extend the duration of a subscription by updating it, as described later in this document. We are using "P1M" which means "one month".
• The notifyCondition element defines the "trigger" for the subscription. There is a type element (which value in this case is ONTIMERINTERVAL) and a condValueList element. The condValueList element structure depends on the type. In the case of ONTIMEINTERVAL, it includes exactly one condValue child element whose value is a time interval (using again, as usual in NGSI, the ISO 8601 format). A notification is sent with a frequency equal to that interval. In the example above we are using 10 seconds as interval.

The response corresponding to that request contains a subscription ID (a 24 hexadecimal number used for updating and cancelling the subscription - write it down because you will need it later in this tutorial) and a duration acknowledgement:

If you look at the accumulator-script.py terminal window, you will see that a message resembling the following one is received each 10 seconds: