{"info":{"_postman_id":"b5650122-d605-4517-ae17-fa21733d725d","name":"FIWARE Querying Time Series Data (Mongo-DB)","description":"

This tutorial is an introduction to FIWARE STH-Comet - a generic enabler which is used to retrieve trend data from a Mongo-DB database. The tutorial activates the IoT sensors connected in the previous tutorial and persists measurements from those sensors into a database and retrieves time-based aggregations of that data.

The docker-compose files for this tutorial can be found on GitHub:

$\"GitHub\"$ FIWARE 303: Short Term Historic Data

Querying Time Series Data

\n
\"The \"moment\" has no yesterday or tomorrow. It is not the result of thought and therefore has no time.\"
\n
— Bruce Lee
\n

Within the FIWARE platform, historical context data can be persisted to a database using a combination of the Orion \nContext Broker and the Cygnus generic enabler. This results in a series of data points being written to the\ndatabase of your choice. Each time-stamped data point represents the state of context entities at a given moment in time.\nThe individual data points are relatively meaningless on their own, it is only through combining a series data points\nthat meaningful statistics such as maxima, minima and trends can be observed.

The creation and analysis of trend data is a common requirement of context-driven systems - therefore the FIWARE platform \noffers a generic enabler (STH-Comet) specifically to deal with the issue of persisting and interpreting time series data. STH-Comet itself can be used in two modes:

In minimal mode, STH-Comet is responsible for both data collection and interpreting the data when requested
In formal mode, the collection of data is delegated to Cygnus, STH-Comet merely reads from an existing database.

Of the two modes of operation, the formal mode is more flexible, but minimal mode is simpler and easier to set-up. The key differences between the two are summarized in the table below:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

	minimal mode	formal mode
Is the system easy to set-up properly?	Only one configuration supported - Easy to set up	Highly configurable - Complex to set up
Which component is responsible for a data persistance?	STH-Comet	Cygnus
What is the role of STH-Comet?	Reading and writing data	Data Read only
What is the role of Cygnus?	Not Used	Data Write only
Where is the data aggregated?	Mongo-DB database connected to STH-Comet only	Mongo-DB database connected to both Cygnus and STH-Comet
Can the system be configured to use other databases?	No	Yes
Does the solution scale easily?	Does not scale easily - use for simple systems	Scales easily - use for complex systems
Can the system cope with high rates of throughput?	No - use where throughput is low	Yes - use where throughput is high

Analyzing time series data

The appropriate use of time series data analysis will depend on your use case and the reliability of the data measurements you receive. Time series data analysis can be used to answer questions such as:

What was the maximum measurement of a device within a given time period?
What was the average measurement of a device within a given time period?
What was the sum of the measurements sent by a device within a given time period?

It can also be used to reduce the signficance of each individual data point to exclude outliers by smoothing.

Device Monitor

For the purpose of this tutorial, a series of dummy IoT devices have been created, which will be attached to the context broker. Details of the architecture and protocol used can be found in the IoT Sensors tutorial.\nThe state of each device can be seen on the UltraLight device monitor web-page found at: http://localhost:3000/device/monitor

$\"FIWARE$

Architecture

This application builds on the components and dummy IoT devices created in \nprevious tutorials. It will use three or four FIWARE components depending on the configuration of the system:\nthe Orion Context Broker, the\nIoT Agent for Ultralight 2.0,\nSTH-Comet and\nCygnus.

Therefore the overall architecture will consist of the following elements:

Four FIWARE Generic Enablers:
- The FIWARE Orion Context Broker which will receive requests using NGSI
- The FIWARE IoT Agent for Ultralight 2.0 which will receive northbound measurements from the dummy IoT devices in Ultralight 2.0 format and convert them to NGSI requests for the context broker to alter the state of the context entities
- FIWARE STH-Comet will:
  - interpret time-based data queries
  - subscribe to context changes and persist them into a Mongo-DB database (minimal mode only)
  \n
- FIWARE Cygnus where it will subscribe to context changes and persist them into a Mongo-DB database (formal mode only)
\n

\n
:information_source: Note: Cygnus will only be used if STH-Comet is configured in formal mode.
\n

A MongoDB database:
- Used by the Orion Context Broker to hold context data information such as data entities, subscriptions and registrations
- Used by the IoT Agent to hold device information such as device URLs and Keys
- Used as a data sink to hold time-based historical context data
  - In minimal mode - this is read and populated by STH-Comet
  - In formal mode - this is populated by Cygnus and read by STH-Comet
  \n
\n
Three Context Providers:
- The Stock Management Frontend is not used in this tutorial. It does the following:
  - Display store information and allow users to interact with the dummy IoT devices
  - Show which products can be bought at each store
  - Allow users to \"buy\" products and reduce the stock count.
  \n
- A webserver acting as set of dummy IoT devices using the Ultralight 2.0 protocol running over HTTP.
- The Context Provider NGSI proxy is not used in this tutorial. It does the following:
  - receive requests using NGSI
  - makes requests to publicly available data sources using their own APIs in a proprietary format
  - returns context data back to the Orion Context Broker in NGSI format.
  \n
\n

Since all interactions between the elements are initiated by HTTP requests, the entities can be containerized and run from exposed ports.

The specific architecture of both the minimal and formal configurations is discussed below.

Prerequisites

Docker and Docker Compose

To keep things simple all components will be run using Docker. Docker is a container technology which allows to different components isolated into their respective environments.

To install Docker on Windows follow the instructions here
To install Docker on Mac follow the instructions here
To install Docker on Linux follow the instructions here

Docker Compose is a tool for defining and running multi-container Docker applications. A series of YAML files are used configure the required\nservices for the application. This means all container services can be brought up in a single command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users will need to follow the instructions found here

Cygwin for Windows

We will start up our services using a simple Bash script. Windows users should download cygwin to provide a command line functionality similar to a Linux distribution on Windows.

Start Up

Before you start you should ensure that you have obtained or built the necessary Docker images locally. Please run

./services create\n

\n
Note The context-provider image has not yet been pushed to Docker hub.\nFailing to build the Docker sources before proceeding will result in the following error:
\n
Pulling context-provider (fiware/cp-web-app:latest)...\nERROR: The image for the service you're trying to recreate has been removed.\n

Thereafter, all services can be initialized from the command line by running the services Bash script provided within the repository:

./services <command>\n

Where <command> will vary depending upon the mode we wish to activate.\nThis command will also import seed data from the previous tutorials and provision the dummy IoT sensors on startup.

\n
:information_source: Note: If you want to clean up and start over again you can do so with the following command:
\n
./services stop\n
\n

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Querying Time Series Data","slug":"querying-time-series-data"},{"content":"Architecture","slug":"architecture"},{"content":"Prerequisites","slug":"prerequisites"},{"content":"Start Up","slug":"start-up"}],"owner":"513743","collectionId":"b5650122-d605-4517-ae17-fa21733d725d","publishedId":"RWEgqe8Q","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"233C68"},"publishDate":"2020-01-02T11:07:30.000Z"},"item":[{"name":"Minimal Mode (STH-Comet only) ","item":[{"name":"STH-Comet - Obtain version information","id":"07ebc47c-b139-4978-ab00-0ede19f38598","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:8666/version","description":"

Once STH-Comet is running, You can check the status by making an HTTP request to the exposed STH_PORT port. \nIf the response is blank, this is usually because STH-Comet is not running or is listening on another port.

\n
Troubleshooting: What if the response is blank ?
\n
\n
To check that a docker container is running try
\n
\n
docker ps\n
\n
You should see several containers running. If sth-comet is not running, you can restart the containers as necessary.
\n

\n","urlObject":{"protocol":"http","path":["version"],"host":["localhost:8666"],"query":[],"variable":[]}},"response":[],"_postman_id":"07ebc47c-b139-4978-ab00-0ede19f38598"},{"name":"Orion - STH-Comet - Aggregate Motion Sensor Count Events","id":"b9e3e17f-a3f9-43d4-ac71-f7dacfc431fc","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"raw","raw":"{\n \"description\": \"Notify STH-Comet of all Motion Sensor count changes\",\n \"subject\": {\n \"entities\": [\n {\n \"idPattern\": \"Motion.*\"\n }\n ],\n \"condition\": {\n \"attrs\": [\n \"count\"\n ]\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://sth-comet:8666/notify\"\n },\n \"attrs\": [\n \"count\"\n ],\n \"attrsFormat\": \"legacy\"\n }\n}"},"url":"http://localhost:1026/v2/subscriptions/","description":"

Once a dynamic context system is up and running, we need to inform STH-Comet directly of changes in context.\nThe rate of change of the Motion Sensor is driven by events in the real-world. We need to receive\nevery event to be able to aggregate the results.

This is done by making a POST request to the /v2/subscription endpoint of the Orion Context Broker.

The fiware-service and fiware-servicepath headers are used to filter the subscription to only listen to measurements from the attached IoT Sensors
The idPattern in the request body ensures that STH-Comet will be informed of all Motion Sensor data changes.
The notification url must match the configured STH_PORT
The attrsFormat=legacy is required since STH-Comet currently only accepts notifications in the older NGSI v1 format.

\n","urlObject":{"protocol":"http","path":["v2","subscriptions",""],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"b9e3e17f-a3f9-43d4-ac71-f7dacfc431fc"},{"name":"Orion - STH-Comet - Sample Lamp Luminosity","id":"aa0ede41-b8ab-4ee7-8495-82b4e2d546aa","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"raw","raw":"{\n \"description\": \"Notify STH-Comet to sample Lamp changes every five seconds\",\n \"subject\": {\n \"entities\": [\n {\n \"idPattern\": \"Lamp.*\"\n }\n ],\n \"condition\": {\n \"attrs\": [\n \"luminosity\"\n ]\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://sth-comet:8666/notify\"\n },\n \"attrs\": [\n \"luminosity\"\n ],\n \"attrsFormat\": \"legacy\"\n },\n \"throttling\": 5\n}"},"url":"http://localhost:1026/v2/subscriptions/","description":"

Once a dynamic context system is up and running, we need to inform STH-Comet directly of changes in context.

The luminosity of the Smart Lamp is constantly changing, we only need to sample the values to be\nable to work out relevant statistics such as minimum and maximum values and rates of change.

This is done by making a POST request to the /v2/subscription endpoint of the Orion Context Broker\nand including the throttling attribute in the request body.

The fiware-service and fiware-servicepath headers are used to filter the subscription to only listen to measurements from the attached IoT Sensors
The idPattern in the request body ensures that STH-Comet will be informed of all Smart Lamp data changes only
The notification url must match the configured STH_PORT
The attrsFormat=legacy is required since STH-Comet currently only accepts notifications in the older NGSI v1 format.
The throttling value defines the rate that changes are sampled.

\n","urlObject":{"protocol":"http","path":["v2","subscriptions",""],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"aa0ede41-b8ab-4ee7-8495-82b4e2d546aa"},{"name":"Orion - STH-Comet Check Subscriptions are working","id":"a31dc7ec-502a-48f1-acfd-441a6c1d6337","request":{"method":"GET","header":[{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"raw","raw":""},"url":"http://localhost:1026/v2/subscriptions/","description":"

If the subscription have been created, you can check to see if they are firing by making a GET \nrequest to the /v2/subscriptions endpoint.

Within the notification section of the response, you can see several additional attributes which describe the health of the subscription

If the criteria of the subscription have been met, timesSent should be greater than 0.\nA zero value would indicate that the subject of the subscription is incorrect or the subscription \nhas created with the wrong fiware-service-path or fiware-service header

The lastNotification should be a recent timestamp - if this is not the case, then the devices\nare not regularly sending data. Remember to unlock the Smart Door and switch on the Smart Lamp

The lastSuccess should match the lastNotification date - if this is not the case \nthen STH-Comet is not receiving the subscription properly. Check that the host name\nand port are correct.

Finally, check that the status of the subscription is active - an expired subscription\nwill not fire.

In the minimal configuration, STH-Comet is used to persisting historic context data and also used to make time-based queries.\nAll operations take place on the same port 8666. The MongoDB instance listening on the standard\n27017 port is used to hold data the historic context data as well as holding data related to the Orion Context Broker and the IoT Agent.\nThe overall architecture can be seen below:

Database Server Configuration

  mongo-db:\n    image: mongo:3.6\n    hostname: mongo-db\n    container_name: db-mongo\n    ports:\n        - \"27017:27017\"\n    networks:\n        - default\n    command: --bind_ip_all --smallfiles\n

STH-Comet Configuration

  sth-comet:\n    image: fiware/sth-comet\n    hostname: sth-comet\n    container_name: fiware-sth-comet\n    depends_on:\n        - mongo-db\n    networks:\n        - default\n    ports:\n        - \"8666:8666\"\n    environment:\n        - STH_HOST=0.0.0.0\n        - STH_PORT=8666\n        - DB_PREFIX=sth_\n        - DB_URI=mongo-db:27017\n        - LOGOPS_LEVEL=DEBUG\n

The sth-comet container is listening on one port:

The Operations for port for STH-Comet - 8666 is where the service will be listening for notifications from the Orion context broker as well\nas time based query requests from cUrl or Postman

The sth-comet container is driven by environment variables as shown:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Value	Description
STH_HOST	`0.0.0.0`	The address where STH-Comet is hosted - within this container it means all IPv4 addresses on the local machine
STH_PORT	`8666`	Operations Port that STH-Comet listens on, it is also used when subscribing to context data changes
DB_PREFIX	`sth_`	The prefix added to each database entity if none is provided
DB_URI	`mongo-db:27017`	The Mongo-DB server which STH-Comet will contact to persist historical context data
LOGOPS_LEVEL	`DEBUG`	The logging level for STH-Comet

minimal configuration - Start up

To start the system using the minimal configuration using STH-Comet only, run the following command:

./services sth-comet\n

\n","event":[{"listen":"prerequest","script":{"id":"a63e990e-c30a-419c-a54c-5d24baa792f2","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"d2710f35-1e52-4ac5-87ad-d7a93c640386","type":"text/javascript","exec":[""]}}],"_postman_id":"fbfe4be2-af15-41ee-9736-829c91613522"},{"name":"Formal Mode (Cygnus + STH-Comet)","item":[{"name":"Cygnus - Obtain version information","id":"f8a20caf-5d0d-4a58-bd39-78657f61c6e7","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:5080/v1/version","description":"

Once Cygnus is running, You can check the status by making an HTTP request to the exposed CYGNUS_API_PORT port. \nIf the response is blank, this is usually because Cygnus is not running or is listening on another port.

\n
Troubleshooting: What if the response is blank ?
\n
\n
To check that a docker container is running try
\n
\n
docker ps\n
\n
You should see several containers running. If cygnus is not running, you can restart the containers as necessary.
\n

\n","urlObject":{"protocol":"http","path":["v1","version"],"host":["localhost:5080"],"query":[],"variable":[]}},"response":[],"_postman_id":"f8a20caf-5d0d-4a58-bd39-78657f61c6e7"},{"name":"STH-Comet - Obtain version information","id":"a77a2e1c-de78-431b-8aac-a1294a5b7205","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:8666/version","description":"

\n
Troubleshooting: What if the response is blank ?
\n
\n
To check that a docker container is running try
\n
\n
docker ps\n
\n
You should see several containers running. If sth-comet is not running, you can restart the containers as necessary.
\n

\n","urlObject":{"protocol":"http","path":["version"],"host":["localhost:8666"],"query":[],"variable":[]}},"response":[],"_postman_id":"a77a2e1c-de78-431b-8aac-a1294a5b7205"},{"name":"Orion - Cygnus - Aggregate Motion Sensor Count Events","id":"2c472896-103b-4239-94cb-8bea10959d83","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"raw","raw":"{\n \"description\": \"Notify Cygnus of all Motion Sensor count changes\",\n \"subject\": {\n \"entities\": [\n {\n \"idPattern\": \"Motion.*\"\n }\n ],\n \"condition\": {\n \"attrs\": [\n \"count\"\n ]\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://cygnus:5051/notify\"\n },\n \"attrs\": [\n \"count\"\n ]\n }\n}"},"url":"http://localhost:1026/v2/subscriptions/","description":"

Once a dynamic context system is up and running, we need to inform Cygnus of changes in context.\nCygnus will store the historical context data in a Mongo-DB database and STH-Comet will only\nbe used to read the persisted data.

The rate of change of the Motion Sensor is driven by events in the real-world. We need to receive\nevery event to be able to aggregate the results.

This is done by making a POST request to the /v2/subscription endpoint of the Orion Context Broker.

The fiware-service and fiware-servicepath headers are used to filter the subscription to only listen to measurements from the attached IoT Sensors
The idPattern in the request body ensures that Cygnus will be informed of all Motion Sensor data changes.
The notification url must match the configured CYGNUS_MONGO_SERVICE_PORT

\n","urlObject":{"protocol":"http","path":["v2","subscriptions",""],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"2c472896-103b-4239-94cb-8bea10959d83"},{"name":"Orion - Cygnus - Sample Lamp Luminosity","id":"c7ee6bcf-f25a-40d4-b31e-a28a94e4d5bf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"raw","raw":"{\n \"description\": \"Notify Cygnus to sample Lamp changes every five seconds\",\n \"subject\": {\n \"entities\": [\n {\n \"idPattern\": \"Lamp.*\"\n }\n ],\n \"condition\": {\n \"attrs\": [\n \"luminosity\"\n ]\n }\n },\n \"notification\": {\n \"http\": {\n \"url\": \"http://cygnus:5051/notify\"\n },\n \"attrs\": [\n \"luminosity\"\n ]\n },\n \"throttling\": 5\n}"},"url":"http://localhost:1026/v2/subscriptions/","description":"

The luminosity of the Smart Lamp is constantly changing, we only need to sample the values to be\nable to work out relevant statistics such as minimum and maximum values and rates of change.

This is done by making a POST request to the /v2/subscription endpoint of the Orion Context Broker\nand including the throttling attribute in the request body.

The fiware-service and fiware-servicepath headers are used to filter the subscription to only listen to measurements from the attached IoT Sensors
The idPattern in the request body ensures that Cygnus will be informed of all Smart Lamp data changes only
The notification url must match the configured CYGNUS_MONGO_SERVICE_PORT
The throttling value defines the rate that changes are sampled.

\n","urlObject":{"protocol":"http","path":["v2","subscriptions",""],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"c7ee6bcf-f25a-40d4-b31e-a28a94e4d5bf"},{"name":"Orion - Cygnus - Check Subscriptions are working","id":"6fb5017f-6a30-4cb6-a0b5-f3a26696e07d","request":{"method":"GET","header":[{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"raw","raw":""},"url":"http://localhost:1026/v2/subscriptions/","description":"

If the subscriptions have been created, you can check to see if they is firing by making a GET \nrequest to the /v2/subscriptions endpoint.

Within the notification section of the response, you can see several additional attributes which describe the health of the subscription

The lastNotification should be a recent timestamp - if this is not the case, then the devices\nare not regularly sending data. Remember to unlock the Smart Door and switch on the Smart Lamp

The lastSuccess should match the lastNotification date - if this is not the case \nthen Cygnus is not receiving the subscription properly. Check that the host name\nand port are correct.

Finally, check that the status of the subscription is active - an expired subscription\nwill not fire.

The formal configuration is uses Cygnus to persist historic context data into a MongoDB database in the same manner as had been presented in the\nprevious tutorial. The existing MongoDB instance (listening on the standard\n27017 port) is used to hold data related to the Orion Context Broker, the IoT Agent and the historic\ncontext data persisted by Cygnus. STH-Comet is also attached to the same database to read data from it. The overall architecture can be seen below:

Database Server Configuration

  mongo-db:\n    image: mongo:3.6\n    hostname: mongo-db\n    container_name: db-mongo\n    ports:\n        - \"27017:27017\"\n    networks:\n        - default\n    command: --bind_ip_all --smallfiles\n

STH-Comet Configuration

  sth-comet:\n    image: fiware/sth-comet\n    hostname: sth-comet\n    container_name: fiware-sth-comet\n    depends_on:\n        - mongo-db\n    networks:\n        - default\n    ports:\n        - \"8666:8666\"\n    environment:\n        - STH_HOST=0.0.0.0\n        - STH_PORT=8666\n        - DB_PREFIX=sth_\n        - DB_URI=mongo-db:27017\n        - LOGOPS_LEVEL=DEBUG\n

Cygnus Configuration

  cygnus:\n    image: fiware/cygnus-ngsi:latest\n    hostname: cygnus\n    container_name: fiware-cygnus\n    depends_on:\n        - mongo-db\n    networks:\n        - default\n    expose:\n        - \"5080\"\n    ports:\n        - \"5050:5050\"\n        - \"5080:5080\"\n    environment:\n        - \"CYGNUS_MONGO_HOSTS=mongo-db:27017\"\n        - \"CYGNUS_LOG_LEVEL=DEBUG\"\n        - \"CYGNUS_SERVICE_PORT=5050\"\n        - \"CYGNUS_API_PORT=5080\"\n

The sth-comet container is listening on one port:

The Operations for port for STH-Comet - 8666 is where the service will be listening for time based query requests from cUrl or Postman

The sth-comet container is driven by environment variables as shown:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Value	Description
STH_HOST	`0.0.0.0`	The address where STH-Comet is hosted - within this container it means all IPv4 addresses on the local machine
STH_PORT	`8666`	Operations Port that STH-Comet listens on
DB_PREFIX	`sth_`	The prefix added to each database entity if none is provided
DB_URI	`mongo-db:27017`	The Mongo-DB server which STH-Comet will contact to persist historical context data
LOGOPS_LEVEL	`DEBUG`	The logging level for STH-Comet

The cygnus container is listening on two ports:

The Subscription Port for Cygnus - 5050 is where the service will be listening for notifications from the Orion context broker
The Management Port for Cygnus - 5080 is exposed purely for tutorial access - so that cUrl or Postman can make provisioning commands\nwithout being part of the same network.

The cygnus container is driven by environment variables as shown:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Value	Description
CYGNUS_MONGO_HOSTS	`mongo-db:27017`	Comma separated list of Mongo-DB servers which Cygnus will contact to persist historical context data
CYGNUS_LOG_LEVEL	`DEBUG`	The logging level for Cygnus
CYGNUS_SERVICE_PORT	`5050`	Notification Port that Cygnus listens when subscribing to context data changes
CYGNUS_API_PORT	`5080`	Port that Cygnus listens on for operational reasons

formal configuration - Start up

To start the system using the formal configuration using Cygnus and STH-Comet, run the following command:

./services cygnus\n

\n","event":[{"listen":"prerequest","script":{"id":"f8ca5d71-4eb4-42b9-95e0-c3ef11567514","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"43d701ab-eb41-472e-875e-4ac51e27579a","type":"text/javascript","exec":[""]}}],"_postman_id":"5ae8856f-954c-4e6b-a577-e03644bebb70"},{"name":"Time Series Data Queries","item":[{"name":"List the first N Sampled Values","id":"634bac5f-2f02-428d-91dd-d17d7596ba70","request":{"method":"GET","header":[{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:8666/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?hLimit=3&hOffset=0","description":"

This example shows the first 3 sampled luminosity values from Lamp:001.

To obtain the short term history of a context entity attribute, send a GET request to\n../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

the hLimit parameter restricts the result to N values. hOffset=0 will start with the first value.

\n","urlObject":{"protocol":"http","path":["STH","v1","contextEntities","type","Lamp","id","Lamp:001","attributes","luminosity"],"host":["localhost:8666"],"query":[{"description":{"content":"

The number of entries per page.

\n","type":"text/plain"},"key":"hLimit","value":"3"},{"description":{"content":"

The pagination offset

\n","type":"text/plain"},"key":"hOffset","value":"0"}],"variable":[]}},"response":[],"_postman_id":"634bac5f-2f02-428d-91dd-d17d7596ba70"},{"name":"List N Sampled Values at an Offset","id":"94016943-ef04-48ed-b75e-4653cae0f707","request":{"method":"GET","header":[{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:8666/STH/v1/contextEntities/type/Motion/id/Motion:001/attributes/count?hLimit=3&hOffset=3","description":"

This example shows the fourth, fifth and sixth sampled count values from Motion:001.

To obtain the short term history of a context entity attribute, send a GET request to\n../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

the hLimit parameter restricts the result to N values. \nSetting hOffset to a non-zero value will start from the Nth measurement

\n","urlObject":{"protocol":"http","path":["STH","v1","contextEntities","type","Motion","id","Motion:001","attributes","count"],"host":["localhost:8666"],"query":[{"description":{"content":"

The number of entries per page.

\n","type":"text/plain"},"key":"hLimit","value":"3"},{"description":{"content":"

The pagination offset

\n","type":"text/plain"},"key":"hOffset","value":"3"}],"variable":[]}},"response":[],"_postman_id":"94016943-ef04-48ed-b75e-4653cae0f707"},{"name":"List the latest N sampled Values","id":"66f98b01-e076-475a-8d21-603caaae9288","request":{"method":"GET","header":[{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:8666/STH/v1/contextEntities/type/Motion/id/Motion:001/attributes/count?lastN=3","description":"

This example shows latest three sampled count values from Motion:001.

To obtain the short term history of a context entity attribute, send a GET request to\n../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

if the lastN parameter is set, the result will return the N latest measurements only.

\n","urlObject":{"protocol":"http","path":["STH","v1","contextEntities","type","Motion","id","Motion:001","attributes","count"],"host":["localhost:8666"],"query":[{"description":{"content":"

The number of entries to return

\n","type":"text/plain"},"key":"lastN","value":"3"}],"variable":[]}},"response":[],"_postman_id":"66f98b01-e076-475a-8d21-603caaae9288"},{"name":"List the Sum of Values over a time period","id":"be790a37-1abf-4773-8612-99b212973f0e","request":{"method":"GET","header":[{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:8666/STH/v1/contextEntities/type/Motion/id/Motion:001/attributes/count?aggrMethod=sum&aggrPeriod=minute","description":"

This example shows total count values from Motion:001 over each minute

To obtain the short term history of a context entity attribute, send a GET request to\n../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

The aggrMethod parameter determines the type of aggregation to perform over the time series, \nthe aggrPeriod is one of second, minute, hour or day.

Always select the most appropiate time period based on the frequency of your data collection.\nminute has been selected because the Motion:001 is firing a few times within each minute.

\n","urlObject":{"protocol":"http","path":["STH","v1","contextEntities","type","Motion","id","Motion:001","attributes","count"],"host":["localhost:8666"],"query":[{"key":"aggrMethod","value":"sum"},{"key":"aggrPeriod","value":"minute"},{"disabled":true,"description":{"content":"

The starting date and time

\n","type":"text/plain"},"key":"dateFrom","value":"2018-01-01T00:00:00.000Z"},{"disabled":true,"description":{"content":"

The final date and time

\n","type":"text/plain"},"key":"dateTo","value":"2019-12-31T00:00:00.000Z"}],"variable":[]}},"response":[],"_postman_id":"be790a37-1abf-4773-8612-99b212973f0e"},{"name":"List the Minimum Values over a time period","id":"dde8db9a-fb84-454f-a5be-dddcf94f4432","request":{"method":"GET","header":[{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:8666/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?aggrMethod=min&aggrPeriod=minute","description":"

This example shows minimum luminosity values from Lamp:001 over each minute

To obtain the short term history of a context entity attribute, send a GET request to\n../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

The aggrMethod parameter determines the type of aggregation to perform over the time series, \nthe aggrPeriod is one of second, minute, hour or day.

The luminocity of the Smart Lamp is continually changing and therefore tracking the minimum value makes sense.\nThe Motion Sensor is not suitable for this as it only offers binary values.

\n","urlObject":{"protocol":"http","path":["STH","v1","contextEntities","type","Lamp","id","Lamp:001","attributes","luminosity"],"host":["localhost:8666"],"query":[{"key":"aggrMethod","value":"min"},{"key":"aggrPeriod","value":"minute"},{"disabled":true,"description":{"content":"

The starting date and time

\n","type":"text/plain"},"key":"dateFrom","value":"2018-01-01T00:00:00.000Z"},{"disabled":true,"description":{"content":"

The final date and time

\n","type":"text/plain"},"key":"dateTo","value":"2019-12-31T00:00:00.000Z"}],"variable":[]}},"response":[],"_postman_id":"dde8db9a-fb84-454f-a5be-dddcf94f4432"},{"name":"List the Maximum Values over a time period","id":"ca3a9141-e621-4646-b7e1-b9deeec7baa0","request":{"method":"GET","header":[{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:8666/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?aggrMethod=max&aggrPeriod=minute","description":"

This example shows maximum luminosity values from Lamp:001 over each minute

To obtain the short term history of a context entity attribute, send a GET request to\n../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

The aggrMethod parameter determines the type of aggregation to perform over the time series, \nthe aggrPeriod is one of second, minute, hour or day.

\n","urlObject":{"protocol":"http","path":["STH","v1","contextEntities","type","Lamp","id","Lamp:001","attributes","luminosity"],"host":["localhost:8666"],"query":[{"key":"aggrMethod","value":"max"},{"key":"aggrPeriod","value":"minute"},{"disabled":true,"description":{"content":"

The starting date and time

\n","type":"text/plain"},"key":"dateFrom","value":"2018-01-01T00:00:00.000Z"},{"disabled":true,"description":{"content":"

The final date and time

\n","type":"text/plain"},"key":"dateTo","value":"2019-12-31T00:00:00.000Z"}],"variable":[]}},"response":[],"_postman_id":"ca3a9141-e621-4646-b7e1-b9deeec7baa0"},{"name":"List Average Values over a time period","id":"2e1e9b78-84f6-49c1-b0f9-93344c535ce9","request":{"method":"GET","header":[{"key":"fiware-service","value":"openiot"},{"key":"fiware-servicepath","value":"/"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:8666/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?aggrMethod=sum&aggrPeriod=minute","description":"

Querying for the mean value within a time period is not directly supported.\nThis example shows sum of luminosity values from Lamp:001 over each minute.\nWhen combined with the number of samples the within the time period an average can be calculated from the data.

To obtain the short term history of a context entity attribute, send a GET request to\n../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

The aggrMethod parameter determines the type of aggregation to perform over the time series, \nthe aggrPeriod is one of second, minute, hour or day.

\n","urlObject":{"protocol":"http","path":["STH","v1","contextEntities","type","Lamp","id","Lamp:001","attributes","luminosity"],"host":["localhost:8666"],"query":[{"key":"aggrMethod","value":"sum"},{"key":"aggrPeriod","value":"minute"},{"disabled":true,"description":{"content":"

The starting date and time

\n","type":"text/plain"},"key":"dateFrom","value":"2018-01-01T00:00:00.000Z"},{"disabled":true,"description":{"content":"

The final date and time

\n","type":"text/plain"},"key":"dateTo","value":"2019-12-31T00:00:00.000Z"}],"variable":[]}},"response":[],"_postman_id":"2e1e9b78-84f6-49c1-b0f9-93344c535ce9"}],"id":"276620eb-17ba-4afa-b1fd-38c6630f21ef","description":"

The queries in this section assume you have already connected STH-Comet using either minimal mode or formal mode and have collected some data.

\n","event":[{"listen":"prerequest","script":{"id":"9e70a754-3893-4617-adc7-c0471f7372f7","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"c43d1162-ac29-4852-9094-b1b86604352b","type":"text/javascript","exec":[""]}}],"_postman_id":"276620eb-17ba-4afa-b1fd-38c6630f21ef"}],"event":[{"listen":"prerequest","script":{"id":"d1cff9ac-8932-417c-b6e2-582ba712ff79","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"cc3f098c-a786-4112-a15e-b1c8c83cc657","type":"text/javascript","exec":[""]}}],"variable":[{"key":"orion","value":"localhost:1026"},{"key":"cygnus","value":"localhost:5080"},{"key":"sth-comet","value":"localhost:8666"}]}