Skip to content

Latest commit

 

History

History
488 lines (332 loc) · 18.5 KB

index.md

File metadata and controls

488 lines (332 loc) · 18.5 KB
Raw

Technical documentation

The technical documentation focuses in the technical aspects of the Context Broker Data Visualization enabler, as well as it explains how to develop new features or how specific parts of the enabler work.

Content

Launch the application for development

To use the application, it is recommended to follow the deployment manuals. However, to launch the application for development purposes, follow these instructions.

Prerequisites

Installation

Execute the following commands:

git clone https://github.com/ConnectingEurope/Context-Broker-Data-Visualisation.git
cd Context-Broker-Data-Visualisation
npm install -g @angular/cli
cd client
npm install
cd ../server
npm install

Usage

To launch the application, execute the following command in the client and server folders.

npm start

Then, access to the application here: localhost:4200

Architecture

The following image represents the architecture of the Context Broker Data Visualization enabler and its integration with the rest of the tools:

Architecture

Illustration 1. Architecture of the Context Broker Visualization enabler

It is recommended to read the links of the Reference documentation section before continuing reading the rest of this documentation.

Hereunder, the set of tools of the architecture are going to be detailed:

Context Broker

The Context Broker is responsible of providing real-time data to the Back-end of the enabler. The most recent information is stored in the MongoDB.

It is also integrated with Cygnus and, optionally, it notifies the changes of the data to Cygnus, by the subscriptions.

By default, it serves on the port 1026.

More information of the Context Broker can be found here.

Top

Cygnus

Through its integration with the Context Broker, Cygnus is subscribed to the changes of the real-time data information.

Because of that, Cygnus generates historical data, storing all the data that is received in the MongoDB.

By default, it serves on the port 5050.

More information of Cygnus can be found here.

Top

STH-Comet

Once the MongoDB contains historical data (generated by the integration of the Context Broker and Cygnus), STH-Comet is in charge of read the historical data information, and also to generate aggregated data (averages, etc.).

It provides the historical data information to the Enabler Back-end.

By default, it serves on the port 8666.

More information of STH-Comet can be found here.

Top

MongoDB

MongoDB is the database which stores both real-time data (from the Context Broker) and historical data (from Cygnus).

It also provides the information to the rest of the tools, when they need to read the data.

By default, it serves on the port 27017.

More information of MongoDB can be found here.

Top

Enabler Back-end

The Back-end of the enabler is a NodeJS module that acts as the server of the Front-end of the enabler.

It is responsible of sending all the requests to the Context Broker and STH-Comet, managing all the data of the enabler.

It also stores the configuration of the Configuration page in an internal JSON file called configuration.

By default, it serves on the port 3000.

Top

Enabler Front-end

The Front-end of the enabler consists on the visualization layer. It contains all the views of the enabler (map, configuration, historical data, etc.) and requests all the information to be displayed directly to the Back-end.

By default, it serves on the port 80.

Top

Used technologies

The following technologies have been used for the development and the deployment of the Context Broker Data Visualization enabler:

Top

Images in DockerHub

As detailed in the deployment manuals, the public images for the deployment of the enabler are available in DockerHub.

As the project is divided in two parts (Front-end and Back-end), there are two Docker images for its deployment:

  • cb-visualisation-data-enabler (Front-end)
  • cb-visualisation-data-enabler-server (Back-end)

Additionally, there are images for two branches of the GitHub repository, so each branch has its own images in DockerHub.

Top

Master branch

The tag for the two Docker images of the master branch is called latest.

The commands to download the master branch images are:

docker pull cbenablereveris/cb-visualisation-data-enabler:latest
docker pull cbenablereveris/cb-visualisation-data-enabler-server:latest

Top

Develop branch

The tag for the two Docker images of the develop branch is called dev. Those images are used for testing purposes (deployments, etc).

The commands to download the develop branch images are:

docker pull cbenablereveris/cb-visualisation-data-enabler:dev
docker pull cbenablereveris/cb-visualisation-data-enabler-server:dev

Top

Understanding the code

The objective of this section is to explain different technical aspects of the enabler, including new developments, modifying parts of the enabler, etc.

Top

How to generate new graphs

The graphs of the enabler are generated using ChartJS. There are available different types of graphs.

Currently, the enabler uses the line graph for numerical attributes and the bar graph for text (String) attributes.

The following steps explain how to develop a new graph:

  1. Open the historical-data-graph.component.ts and historical-data-graph.component.html files.

  2. In the historical-data-graph.component.ts, there are two different configurations for the line and bar graphs of the enabler:

        protected chartConfigForNumber: any = {
        type: 'line',
        options: { scales: { yAxes: [{ ticks: { beginAtZero: false } }] } },
    };

    protected chartConfigForString: any = {
        type: 'bar',
        options: {
            scales: { yAxes: [{ ticks: { beginAtZero: true } }] },
            legend: { labels: { boxWidth: 0 } },
        },
    };

    A new configuration is needed for the new graph to be developed:

        protected newChartConfig: any = {
        type: 'TYPE_OF_CHART',
        options: { OPTIONS_OF_THE_CHART } },
    };

  3. There are also two ViewChild for the current graphs:

        @ViewChild('graphicCardForNumber', { static: false }) private graphicCardForNumber: GraphicCardComponent;
    @ViewChild('graphicCardForString', { static: false }) private graphicCardForString: GraphicCardComponent;

    So a new ViewChild is needed for the new graph. With the following structure:

        @ViewChild('newGraphicCard', { static: false }) private newGraphicCard: GraphicCardComponent;

  4. There is a function called getHistoricalData() which is in charge of obtaining the historical data for each type of graph. Inside of that functions, there are other functions, and all of them end up coming to the getAggregatedData() function. This function is inside the service HistoricalDataService, which has the needed functions in order to retrieve the data (raw or aggregated) from the STH-Comet.

  5. The available aggregated methods of STH-Comet are already defined in the AggregateMethod enum.

  6. At this point, new functions may be needed to manage the desired data, based on the new graph purposes.

  7. Go to the historical-data-graph.component.html file and look at the two existent graphs:

        <!-- Graphic for numbers -->
    <app-graphic-card [style.display]="attrType === attrTypeEnum.NUMBER ? 'block' : 'none'" #graphicCardForNumber [chartConfig]="chartConfigForNumber"></app-graphic-card>

    <!-- Graphic for strings -->
    <app-graphic-card [style.display]="attrType === attrTypeEnum.STRING ? 'block' : 'none'"  #graphicCardForString [chartConfig]="chartConfigForString"></app-graphic-card>

    The new graph has to be added below them, with its correspondent variables:

        <!-- New graphic -->
    <app-graphic-card [style.display]="attrType === attrTypeEnum.NUMBER ? 'block' : 'none'" #newGraphicCard [chartConfig]="newChartConfig"></app-graphic-card>

  8. If all the previous steps are completed and the new needed functions have been correctly added, the development of the new graph should be ready.

Top

How to change the refresh time of the information

By default, the refresh time of the real-time data in the map is 1 minute. In milliseconds, it is 60000.

This refresh time can be changed, modifying a the value of a variable in the map-dashboard.component.ts.

    private intervalRefreshMilliseconds: number = 60000;

In this case, the value of the intervalRefreshMilliseconds variable (60000) can be replaced by the desired refresh time (in milliseconds).

Top

How the information of the map is updated

In order to optimize the load and update of the information of the map, it is updated based on the following actions:

  • For the first load of information (after completing the configuration on the Configuration page), all the sensors are situated on the map. Additionally, the loaded attributes are:

    • ID
    • Type
    • Location
    • Main attribute. More information can be found here.

  • Once the initial load of information is completed, the previous attributes are updated every 60 seconds by default. This action allows to visualize sensors whose location is changing during the time (i.e. buses).

  • The rest of attributes are updated when the user clicks on a sensor, showing the visualization panel.

  • Additionally, when a filter is added, the values for the selected attributes as filters are also automatically updated every 60 seconds by default.

The previous procedure optimizes the load of information and allows to manage high amounts of information in the enabler, avoiding efficiency problems.

Top

Supported types of locations

The supported types of locations of the sensors are GeoJSON.

This is an example:

"location": {
    "type": "geo:json",
    "value": {
        "type": "Point",
        "coordinates": [-3.712247222222222, 40.423852777777775]
    }
},

The location attribute of the sensors has to follow the previous schema. The type of the coordinates has to be Point, and its value has to be a list of two coordinates. Otherwise, the sensors won't be supported in the enabler (i.e. LineString).

Top

Supported types of subscriptions

With the objective of generating historical data, Cygnus is subscribed to the Context Broker. Then, when the Context Broker receives new data and, if this data matches with the configuration of the subscription, it is sent to Cygnus (and stored in MongoDB).

There are some examples for subscriptions in this link.

In relation with the subscriptions, there are lots of possibilities to configure them. Depending on the IDs of the entities, their attributes, the conditions for the notification, etc.

For the Context Broker Data Visualization enabler, the supported subscriptions between Cygnus and the Context Broker are:

Subscriptions for a specific ID with multiple attributes

This type of subscription is focused on the entity whose ID is the same as the one indicated in the request. Concretely, in the id key.

All the desired attributes to be subscribed for the specific entity, need to be included in the notification -> attrs list.

This is the structure of the request for this kind of subscription:

URL: http://localhost:1026/v2/subscriptions/

{
  "description": "Notify Cygnus the changes of the attributes for the entity ENTITY_ID_1",
  "subject": {
    "entities": [
      {
        "id": "ENTITY_ID_1",
        "type": "TYPE_OF_THE_ENTITY"
      }
    ],
    "condition": {
      "attrs": []
    }
  },
  "notification": {
    "http": {
      "url": "http://cygnus:5051/notify"
    },
    "attrs": [
      "ATTRIBUTE_1",
      "ATTRIBUTE_2",
      "ATTRIBUTE_N"
    ]
  }
}

Top

Subscriptions for a group of entities of the same type with multiple attributes

This type of subscription is focused on a group of entities of the same type.

All the desired attributes to be subscribed for the specific entity, need to be included in the notification -> attrs list.

This is the structure of the request for this kind of subscription:

URL: http://localhost:1026/v2/subscriptions/

{
  "description": "Notify Cygnus the changes of the attributes for the entities of type TYPE_OF_THE_ENTITIES",
  "subject": {
    "entities": [
      {
        "idPattern": ".*",
        "type": "TYPE_OF_THE_ENTITIES"
      }
    ],
    "condition": {
      "attrs": []
    }
  },
  "notification": {
    "http": {
      "url": "http://cygnus:5051/notify"
    },
    "attrs": [
      "ATTRIBUTE_1",
      "ATTRIBUTE_2",
      "ATTRIBUTE_N"
    ]
  }
}

Top

Subscriptions for a group of entities with an idPattern with multiple attributes

This type of subscription is focused on a group of entities of the same type, whose id matches the regex of the idPattern key.

All the desired attributes to be subscribed for the specific entity, need to be included in the notification -> attrs list.

This is the structure of the request for this kind of subscription:

URL: http://localhost:1026/v2/subscriptions/

{
  "description": "Notify Cygnus the changes of the attributes for the entities of type TYPE_OF_THE_ENTITIES which IDs start by PARKING",
  "subject": {
    "entities": [
      {
        "idPattern": "PARKING.*",
        "type": "TYPE_OF_THE_ENTITIES"
      }
    ],
    "condition": {
      "attrs": []
    }
  },
  "notification": {
    "http": {
      "url": "http://cygnus:5051/notify"
    },
    "attrs": [
      "ATTRIBUTE_1",
      "ATTRIBUTE_2",
      "ATTRIBUTE_N"
    ]
  }
}

Top

How the historical data page gets the subscribed attributes

First of all and before loading the historical data page, a calculation is made in order to collect the attributes which have subscriptions for changes.

For that, the Enabler gets the subscribed attributes from the subscription list of the Context Broker (it is external to the enabler, configuration of the Context Broker) and compares it with the configured attributes on the Configuration page for the type of the selected sensor (which are the ones displayed on the information panel).

Then, using that information, the enabler connects with STH-Comet in order to receive the information of the page.

As a resume, the information is previously collected, combined and structured before being displayed in the historical data page of the enabler.

This is an example of a calculation:

  • List of attributes of the subscription list of the Context Broker: [ATTR1, ATTR2, ATTR3, ATTR4, ATTR5]
  • List of attributes for the type of the sensor in the Configuration page: [ATTR2, ATTR4, ATTR5, ATTR6]
  • Attributes to be displayed in the historical data page: [ATTR2, ATTR4, ATTR5]

Top