The aim of this document is to create a functional guide to ensure the understanding of the enabler, so the users are able to exploit it to its fullest.
The Context Broker Data Visualisation enabler has been created to ease the understanding of the Context Broker and its data, and to fasten its learning curve for new stakeholders who would like to experiment with it. therefore, it consists in a visualisation layer over the Context Broker, used for playground purposes.
The enabler is available for use in local or remote environments (like the FIWARE lab). A deployment manual is also available to facilitate the implementation and deployment of the enabler.
The enabler gives the opportunity to experiment with a sensor’s real-time data as well as historical data, if configured. Having selected a range of time, it can be represented in a table or graph format, or even downloaded in a CSV file to further exploit.
This section describes how to start using the Context Broker Data Visualisation enabler, once it has been deployed on a local or remote server.
Once the Enabler has been deployed either on a local or remote server, the user will be able to access it via a web browser, as this Enabler is a web application.
In order to access it, the user should introduce in the web browser’s search bar the URL where the Enabler has been deployed, i.e. localhost is set by default.
Illustration 1. Enabler's URL.
When the user accesses the Enabler for the first time, the first step is to configure a Context Broker instance in order for data to start flowing. Hence, an information panel will appear giving the user the option to begin this configuration through the Configuration page.
Illustration 2. Initial configuration pop-up
With the purpose of facilitating the integration of one or multiple Context Broker instances and historical data tools, the Enabler provides a visual and intuitive configuration panel. The user will be able to use this panel to configure the information that is desired to be visualized.
This Configuration page is divided into different sections, for the configuration of the Context Broker (including its services) or the historical data tools.
If the tools to be used have been configured following the tutorials for deployment of the enabler, the URLs to be configured are defined here.
The Add Context Broker button should be pressed to starting configuring a new Context Broker instance.
The user should introduce the desired name for that particular Context Broker instance and the URL where the data is available. Note that there may be a need to indicate the Context Broker’s port if the instance is serving in a specific one. For instance, if it is configured in a local environment and the port number is 1026, the URL should be localhost:1026.
Before proceeding, it is recommended to check the status of the Context Broker instance to ensure that the configuration provided is valid and ready to be used. This can be done by pressing the yellow checkbox next to the URL.
Illustration 3. Configuration Panel
Illustration 4. Adding a new Context Broker
If the URL introduced for the Context Broker is incorrect, the user will be informed with an unsuccesful connection message under the URL input.
Illustration 5. Incorrect Context Broker URL.
After the initial configuration of the Context Broker instance is done, the user must choose the desired entities and attributes to be displayed in the enabler by pressing the Choose entities and attributes button.
Illustration 6. Successful Context Broker connection.
Illustration 7. Selecting the entities and attributes.
The entities and attributes can be selected and unselected by pressing the checkbox or the name of the desired option. At least one entity must be selected, otherwise an error message will appear.
If various Context Broker instances are configured, they will appear as a group of tabs where each one can be displayed for its edition. In order to delete a Context Broker instance, the bin icon must be pressed. A confirmation message will appear asking the user to confirm the action.
Illustration 8. Context Broker List.
Illustration 9. Deleting a Context Broker.
The information of a Context Broker instance can be organized and divided in what is called Services. By using these services, the information can be encapsulated in different logical groups and their access has to be granted.
The aim of the services, which are optional, is to increase the security of the Context Broker's data. A user may have access to one service but not to the rest. Therefore, the user has the option of adding a service if necessary.
More information of services can be found here.
If the user has access to one or several services, they can be added, edited and eliminated in the enabler. In order to add a new service to a Context Broker instance, the The context Broker uses services checkbox must be selected. A new panel with the Services configuration will be opened where the user will be able to start configuring them.
Illustration 10. Configuring services.
The user will be able to create services by pressing the Add service button.
Illustration 11. Adding services.
The user will need to configure the name of the service and, if needed, the service path. To check its availability, the Choose entities and attributes button should be pressed. If the configuration is incorrect, the user will be informed with an entities not found message under the button.
Illustration 12. Incorrect service name.
Illustration 13. Incorrect service path.
If the configuration is correct, a list of the available entities and attributes will appear, where the user will be able to select or unselect the desired ones. At least one entity must be selected, otherwise an error message will appear.
Illustration 14. Correct service name and path.
Illustration 15. Error message for no entities selected.
If various services are configured, they will appear as a group of tabs where each one can be displayed for its edition. In order to delete a service, the garbage icon must be pressed. A confirmation message will appear asking the user to confirm the action.
Illustration 16. List of services.
Illustration 17. Deleting a Service.
Once the entities and the attributes of the Context Broker instance (or one of its services) have been selected, the user will be able to select one single main attribute of the entity by pressing the star icon. This main attribute represents the data that will be statically displayed on the map next to the geo-localized sensor.
The user will only be allowed to select one main attribute per each category.
Illustration 18. Configuring main attributes
This information will be explained in the Main attributes section of this document.
In order to check if the attributes of the entities of a Context Broker instance (or its services) are subscribed to changes (this means, they are generating historical data), there is a button called Subscriptions Overview.
This button shows if there are active subscriptions for the current configuration, and also indicates if there are not.
Illustration 19. Subscriptions Overview button in the Configuration page
If there are subscriptions for the current configuration, a new window is displayed in read-only mode. It is also possible to copy the technical information (in JSON format) by pressing the button Copy subscriptions JSON.
Illustration 20. Subscriptions Overview
Additionally, a message is displayed under the button if there are not subscriptions.
Illustration 21. No subscriptions found
In order to complement the real-time data, the Enabler offers the possibility to combine it with historical data. Hence, the user is able to optionally configure tools for its implementation in the Configuration page.
The historical data in the Enabler supports two tools that should be configured for each of the Context Broker instances as they work together: Cygnus and STH-Comet.
The architecture of the enabler has been designed to integrate both Cygnus and STH-Comet, as the documentation of the formal mode indicates. However, it is also possible to use the enabler with the minimal mode architecture (configuring only STH-Comet).
The first of this two tools is Cygnus. It acts as a connector between the Context Broker’s information that the sensors produce and the MongoDB database that will store that information. In other words, Cygnus is subscribed to the information the Context Broker produces and creates the historical data for the database. More information can be found here.
The second tool is STH-Comet. In essence, this tool retrieves the historical data created by Cygnus from the database and allows the user to consult and work with it. More information can be found here.
If the user wants to use the historical data in the enabler, Cygnus and STH-Comet must be configured for each of the Context Broker instances (unless the minimal mode architecture is being used). The user should introduce the desired URL and the chosen port for each of the tools.
Before proceeding, it is recommended to check the status of the tools to ensure that the configuration provided is valid and ready to be used. This can be done by pressing the yellow checkbox next to the URL. If any of the tools is not available, the configuration and exportation of the historical data will not be possible. If the configuration is incorrect, the user will be informed with an unsuccessful connection message.
Illustration 22. Cygnus and STH-Comet tools.
Illustration 23. Incorrect Cygnus or STH-Comet URL.
Once the user has finished configuring the Context Broker instance, its services and tools, the Apply Configuration button at the top of the page must be pressed to save the overall configurations. Otherwise, the current configuration will not be effective.
Illustration 24. Saving the configuration.
The map that supports the Enabler is the open source World map OpenStreetMap.
The Enabler supports the use of various Context Broker instances, therefore, all of the information contained in the configured Context Broker instances is shown on the map with the real-time data they provide.
Regarding the representation of the sensors, all of them must have coordinates for their geo-location and, taking advantage of those coordinates, they can be displayed directly over the map.
When zooming out of the map, the icons will start to cluster together in a single notification, showing the number of sensors available in the area. As the user zooms in, the sensors will start to separate and appear in the exact locations.
Illustration 25. The Enabler Map.
The user is be able to select one single main attribute for each entity from the Configuration page. If an important attribute has been configured, the visualisation of the map will include the visualisation of the selected main attribute.
The user will also be able to visualize on a side panel the list of main attributes selected for each type of sensor.
Illustration 26. Main attributes over the sensors
The enabler will also give the user the possibility to enable or disable the display of the main attributes and the side panel through a switch option.
Illustration 27. Main attributes disabled
The icons that appear on the map correspond to a list of categories that classifies the data in different groups depending on the type of information it gives:
Alerts: Alerts Events related to risk or warning conditions which require action taking.
Smart Environment: Domain repository for topics related with environment. Currently available Environment, Waster management and Weather.
Environment: Enable to monitor air quality and other environmental conditions for a healthier living.
Point of interest: Specific point locations that someone may find useful or interesting. For instance, weather stations, touristic landmarks, etc.
Civic issue tracking: Data models for civic issue tracking interoperable with the de-facto standard Open311.
Street lighting: Modeling street lights and all their controlling equipment towards energyefficient and effective urban illuminance.
Device: IoT devices (sensors, actuators, wearables, etc.) with their characteristics and dynamic status.
Transportation: Transportation data models for smart mobility and efficient management of municipal services.
Indicators: Key performance indicators intended to measure the success of an organization or of a particular activity in which it engages.
Waste management: Enable efficient, recycling friendly, municipal or industrial waste management using containers, litters, etc.
Parking: Real time and static parking data (on street and off street) interoperable with the EU standard DATEX II.
Weather: Weather observed, weather forecasted or warnings about potential extreme weather conditions.
Generic: For other categories not included in the FIWARE data models.
If more information about these categories is needed, the FIWARE data models can be consulted through this link.
Whenever a geo-localized sensor is selected on the map, an information panel with the sensor’s information will appear. This panel will contain the attributes that were selected while configuring the Context Broker instance along with the real time data they have available.
Illustration 28. Example of pop-up attributes.
Illustration 29. Sensor pop-up.
If the user unselects any of the attributes in the configuration of the desired Context Broker instance, they will disappear from the pop-up as seen in the information panel.
Illustration 30.Example of unselecting pop-up attributes.
Illustration 31. Same information panel without the attributes.
Illustration 32. Sensor's information panel characteristics.
Apart from showing the real-time data of the sensor, the information panel offers two other functionalities: raw data overview and historical data overview.
The RAW data Overview consists in showing the sensor’s information in a RAW format, just as the Context Broker provides it, without being processed. This raw information will appear in a side panel.
The user will be able to copy the complete JSON by pressing on the Copy button.
Illustration 33. RAW data Overview
The historical data overview consists in providing a consultation page of the historical data of the selected sensor. Note that this option will only be available if the historical data tools were previously configured.
In this page, this data will be read from the available historical data of the sensor and the user will be able to choose the rage of time for it to be represented i.e. from one date to other.
Illustration 34. Historical data option.
Note that the applied filters will be maintained when consulting the historical data. For more information, consult the section How the historical data page gets the subscribed attributes in the technical documentation.
Illustration 35. Historical data window.
This page is divided into two sections: table representation and graph representation.
After selecting the option of visualizing historical data from a sensor, a table with the sensor’s attributes’ information (as columns) will appear.
Illustration 36. Attribute table.
The user will be able to filter the data in the table by date and time. The filter appears at the top of the table and gives the opportunity to select between two dates or just to put a limit for the data. For instance, if there is only the need to check the data from a certain date, only the From input will need to be filled.
Illustration 37. Date and time filters
Pressing on the date and time options, the user will be able to configure the filter. A calendar will appear allowing the user to select the desired day and time. If the filter is no longer needed it can be deleted by pressing on the Clear button next to the filters.
Illustration 38. Filter calendar.
The information of the table is based on RAW data, just as stored in the database.
This table maintains the date filters that were configured before and displays the attributes in the table from the newest to the oldest. The number of results per page can be configured, allowing to show 10, 25, 50, 75 or 100 results per page.
The rest of the entries can be consulted by different means:
-
By clicking the number of the desired page.
-
By clicking the red highlighted buttons, which shows the previous or the subsequent page.
-
By clicking the green highlighted buttons, which will show the first or the last page of the table.
Illustration 39. Moving between pages
Illustration 40. Total entries.
Also, the table informs of the entries that are being shown at the moment and the total number of entries that are available to consult.
Note the attributes of complex type (lists, JSONs, etc) won't be represented in the table, but they will be exported in the CSV export.
The information of the graph is based on aggregated data, collecting the historical data of the database and transforming it.
The purpose of this functionality is to help the user to further understand the meassures being displayed on the table. With the aid of the graph representation of the attribute’s evolution, the user can comprehend more specific aspects.
Illustration 41. Historical data graph.
Currently, the enabler provides two types of graphs:
- Line graphs for numerical attributes.
- Bar graphs for text (String) attributes.
Depending on the type of the selected attribute, a type of graph will be displayed.
It is also possible to develop new graphs for new purposes, following the How to generate new graphs tutorial of the technical documentation.
The user will be able to choose different ranges of time for a same attribute. The ranges of times available are:
- Hours
- Days
- Months
- Years
The user will also be able to customize the beginning of the time period depending on the range selected, in case a specific range of dates or times is required. This can be selected with the calendar option next to the range selection, which will adapt to the range selected. For instance, if the user has selected months, a calendar with the months to choose from will appear.
The table or graph will show up to the next time level. For instance, if the user selects hours, information up to a day will appear. If the user selects months, information of the 12 months will appear. Note that the range selection is independent for tables and graphs.
Illustration 42. Range Selection.
The user should choose one of the attributes from the sensor and the range of time desired to be visualized on the graph, as previously mentioned. After selecting all the options, a linear graph will appear automatically with the configuration that the user chose. If the range of time selected is greater than the data available, the graph will appear empty.
Illustration 43. Graph of one Attribute.
The default graph will show the information connected with lines and the evolution of the maximum, minimum and average values for that specific attribute. For instance, if a month is being represented it will show the minimum, maximum and average of each day.
If any of these options is not desired, the user can hide it by pressing on the name at the legend that is placed above the graph.
After the table has been configured, the user will have the possibility to export the historical data to a compatible format file such as CSV.
Taking advantage of this functionality, the user is able to export the same data of the table and use it for its own purposes, even to generate new graphs in other software.
Illustration 44. Historical data exportation.
A search bar is available to localize cities on the map in a faster way. The user will have to introduce the name of the city they wish to see and, after selecting one of the results, the map will automatically change its focus to the city.
Illustration 45. Using the search bar.
The user will be able to add dynamic filters to hide or show certain sensors on the map in case they want to focus in a specific aspect of any of the attributes. For instance, if there is a need to localize the higher priority risk alerts in order to take actions faster.
There are two types of filters available: the first is the layers option, based on checking or unchecking entities/attributes to be displayed, and the second is the filters option, based on filtering sensors based on attribute's conditions.
Illustration 46. Filtering Options.
This option is available by clicking the Layers button. Its objective is to show/hide types of sensors on the map by selecting/unselecting, respectively, the checkboxes next to the desired variables.
Illustration 47. Selecting entities and attributes.
This configuration is not stored, so it will be discarded after closing the enabler.
In order to add a new condition to any of the attributes of the current sensors, the user has to press the Filters button.
The objective of this functionality is to provide a filter mechanism to show the sensors that match the specified conditions and hide the ones that do not. For instance, the user would like to visualize only the parking sensors that have more than 50 free slots.
Illustration 48. Adding a condition.
Illustration 49. After the Condition is Added.
This filtering mechanism is dynamically generated based on the configured data of the Context Broker instance. The creation of a specific condition is done by steps:
- The user will have to select the category.
- The user will have to select the entity.
- The user will have to select the attribute. Depending on its type (text or numeric), a different type of filter will appear and the user will be able to add the desired condition.
The types of conditions are the following:
- Numeric conditions. The user introduces the desired numeric value and chooses between:
- Greater than “>”.
- Greater or equal to “>=”.
- Less than “<”.
- Less or equal to “<=”.
- Equal to “=”.
- Text conditions:
- Contains “Word”.
- Has prefix or suffix.
After choosing the desired condition, the user will have to write the comparing value in the empty box and press the Add button.
By pressing the Clear button, the user will be able to clear the current filter condition that is being created. In order to delete an existing filter condition, the user should press the bin icon. Furthermore, to delete all the existing filters, the Clear all button should be pressed.