synchronicityiot/parking-estimator-api repository overview

⁠IMPORTANT BEFORE STARTING

It is worth starting up this documentation by stating that this module does not work alone, but it needs to interact with others (see here⁠). For the sake of a generic view of the whole service, the reader might refer to e.g. this GitLab's repo⁠, where we include and document all the stuff needed to deploy the parking flow estimator service

⁠Description

By means of the information retrieved from the different parking intensity context entities, this service will generate an estimation of the parking intensity flow in the short term (namely, in the next 15, 30, 45 or 60 minutes).

⁠Interface and API

API Documentation⁠ (Apiary)

⁠Service Architecture

The parking-estimator is the consequence of the joint operation between various micro-services. We briefly outline each of them below:

• parking-estimator-api [GitLab⁠] : (REST) API that extracts data from the parkingFlowObserved entities and yield the estimated intensity.
• ai-prediction-engine [Docker Hub⁠]: Core module that carries out all the operations related to the estimations. Namely, we rely on the Keras framework to perform AI operations from the data harvested from the cities. Concerning the training process followed, we have stuck to an online training system, where we periodically re-train the models with the new data received from the parking Flow Estimator API. NOTE From versions >=0.9.0, this component makes use of Elasticsearch⁠ to store all the related stuff (data used for training + models + history of estimations).
• Orion CB (internal) [Docker Hub⁠]: FIWARE's General Enabler (GE) instance that will be used in the context (internally) of this atomic service to keep track (concentrate) of the parking context elements. Moreover, the output coming from the AI prediction engine is saved as an additional attribute within the context element information, behaving like a sort of caching mechanism. Besides, we cannot forget that Orion CB works together with a MongoDB⁠ instance.

⁠Service configuration

The service relies on two different configuration files to work properly. For the sake of illustration, we show here some samples of how the should look like (it goes without saying that they are mere samples and some attributes must be changed):

• config.js (sample file⁠)
• auth.js (sample file⁠)

Although one of them is already present in the image (it is ready-to-use as it is), there is another that handles private data (i.e. the tokens to access the different RZs context Brokers). Namely, this file is called auth.js and must be present within the /usr/src/app/configfolder; otherwise, the service will basically not behave normally. As a illustrative example, this is how the file should look like, where users have to tamper all the RZs that require an Oauth token:

⁠Config.js

These are the attributes that are to be changed by an user (all the rest should be left intact, or the whole system may not behave as expected).

config / api / subscriptions / endpoint
config / orion / endpoint
config / ai_prediction_module / endpoint

Where the subscriptions endpoint is where the RZs' Orion CBs will deliver their notifications, meaning that it must be an accessible address. For the sake of illustration, an example could be http://your-host:3000, being this 3000 the port defined on the variable config / api /port.

NOTE: By default, Orion, AI prediction engine and Elastic Search containers are deployed on the same host as the rest of the atomic service components. Therefore, their configuration might be left as they are).

config / orion / endpoint: 'http://orion:1026'
config / ai_prediction_module / endpoint: 'http://ai-prediction-engine:5000'

⁠RZs Context broker information

We offer the possibility to modify the underlying CBs that we want to play around with. In config.js, we have the array config / rzs / brokers, where we can modify/add/remove new elements. Let's see an example and analyze the fields therein:

rzs: {
   brokers: [{
        rz: 'Santander',
        orion_host: 'https://context.san.synchronicity-iot.eu',
        historic_host: 'https://historical.san.synchronicity-iot.eu',
        auth: true,
        // fiware_service: '',
        // fiware_servicepath: '',
        area: [
          [-4.198940, 43.332055],
          [-3.369473, 43.686628]
    ],
 },

⁠Auth.js

In case an OAuth2 based framework is in between you and the underlying Orions (RZs'), you can put (static for the moment) tokens. Though it is documented in the auth.js.sample file, here is the template to tweak:

auth.orion = {
  Santander: {
    key: 'header',   //(example: 'X-Auth-Token)
    token: 'token'
  },
};

⁠Service Deployment

To run the service, it is only needed to run the following Docker command:

docker run -p HOST_PORT:3000  -v "$(pwd)/config":/usr/src/app/config --name="CONTAINER_NAME"  synchronicityiot/parking-estimator-api

Where <host-port> is the listening port at the host and <container_name> will be the label of the container, Besides, as hinted above, users must include both config.js and auth.js files within the config folder. This is the part set after the -v option, where users have to specify the path to the auth.js file in their host machines.

⁠Support

The support for this baseline services can be request via the issue tracker here⁠

⁠License & Terms and Conditions

This atomic service is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Please refer to gnu licenses for more information.

The software is released as it is and we discharge any liability.