telefonicaid/fiware-here-adaptor

Name: fiware-here-adaptor

Owner: Telefónica I+D

Description: Backend implementation of the integration between FIWARE and HERE Maps

Created: 2015-11-16 15:56:14.0

Updated: 2016-01-21 10:07:44.0

Pushed: 2016-02-16 16:28:46.0

Homepage: null

Size: 36

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Fiware HERE Adaptor

Adaptor component for the FIWARE-NGSI-HERE integration for Smarter car navigation through cities.

How to install and run

The following instructions are for development setups:

Prerequisites:

• Node JS 0.12.0 or higher (see NodeJS).
• Tools: git and npm.

Download the source code from git repository:

git clone https://github.com/telefonicaid/fiware-here-adaptor.git

Install dependencies:

npm install

When npm process finishes the dependencies installation, you could run the fiware-here-adaptor executing this command:

NFIG_DIR={path_to_config_folder} ./bin/fiware-here-adaptor

CONFIG_DIR environment variable is optional. The default configuration has the following aspect:

 Port where fiware-here-adaptor is available
erverPort": 7007,

ogLevel": "INFO",

 Log format: "json", "pipe", or "dev"
ogFormat": "json",

 If true, disable unauthorized SSL (NODE_TLS_REJECT_UNAUTHORIZED = 0)
entleSsl": true,

Global city broker directory configuration
ontextBroker": {
"cityContextBrokerDirectoryName": "CityBrokerFHA",
"maxDistanceCityDirectory": 10,
"cityBrokerDirectoryConfig": {
  // Global city broker endpoint
  "url": "http://{contextBrokerIp}:1026/v1",
  "userAgent": "fiware-here-adapter"
}


 HERE configuration to consume the API
ere": {
"geocodingUrl": "http://geocoder.cit.api.here.com",
"reverseGeocodingUrl": "http://reverse.geocoder.cit.api.here.com",
// You can obtain your API keys in HERE service.
"appId": "myAppId",
"appCode": "myAppCode"

The internal config is stored in '{installation_path}/lib/config/config.json' but you can use the environment variable CONFIG_DIR to set a folder that merges the configs obtained from json files against the internal config file.

Example taking into account the internal config file above included:

CONFIG_DIR=/opt/fiware-here-adaptor

File /opt/fiware-here-adaptor/config.json:

erverPort": 8080,
ere": {
"geocodingUrl": "http://geocoder.cit.api.here.com",
"reverseGeocodingUrl": "http://reverse.geocoder.cit.api.here.com",
// You can obtain your API keys in HERE service.
"appId": "534g23df325df23gf4",
"appCode": "63gdsgv23d78ads5bgv"

The server will merge /opt/fiware-here-adaptor/config.json into {installation_path}/lib/config/config.json in order to get the following final configuration:

 Port where fiware-here-adaptor is available
erverPort": 8080,

ogLevel": "INFO",

 Log format: "json", "pipe", or "dev"
ogFormat": "json",

 If true, disable unauthorized SSL (NODE_TLS_REJECT_UNAUTHORIZED = 0)
entleSsl": true,

Global city broker directory configuration
ontextBroker": {
"cityContextBrokerDirectoryName": "CityBrokerFHA",
"maxDistanceCityDirectory": 10,
"cityBrokerDirectoryConfig": {
  // Global city broker endpoint
  "url": "http://{contextBrokerIp}:1026/v1",
  "userAgent": "fiware-here-adapter"
}


 HERE configuration to consume the API
ere": {
"geocodingUrl": "http://geocoder.cit.api.here.com",
"reverseGeocodingUrl": "http://reverse.geocoder.cit.api.here.com",
// You can obtain your API keys in HERE service.
"appId": "534g23df325df23gf4",
"appCode": "63gdsgv23d78ads5bgv"

Other commands:

• Launch unit tests:

  m test
  

• Generate coverage report:

  m run coverage
  

• Check style rules:

  m run lint
  

Contribute

Server

The source code files are found in 'lib' folder.

Main files:

• 'lib/fiware-here-adaptor.js' : It has the express js code.

• 'lib/routes/index.js': It has the definition of the exposed endpoints.

  • GET on '/v2/entities'
  • GET on '/getCenterCoords'

• 'lib/services/carNavigatorService.js': It contains the main flow to resolve the information of a city using the endpoint '/v2/entities'. Steps:

  • (HERE) Get city info from request coordinates.
  • (HERE) Get canonical coordinates of a city using city info.
  • (Global Context Broker) Using canonical coordinates the global context broker responses with the City Context Brokers of the city.
  • Get the different information of the current city depending the 'type' request parameter. (Parallel process)
    • Requests to fiware-orion server or ngsi10 compliant servers.
    • Adaptation of the requests when it is needed.

• 'lib/services/here': Folder where HERE integrations are. (Integrations: getCoordsByCityInfo, searchCityByCoords)

• 'lib/services/ngsi10': Folder where NGSI10 integrations are. (Integrations: getCityContextBrokerInfo)

• 'lib/services/ngsi10/utils': Folder where NGSI10 utilities are. (Utilities: ObjectAdaptor, helperFunctions)

• 'lib/services/orion': Folder where fiware-orion integrations are. (Integrations: getCityContextBrokerFromDirectory, getCityContextBrokerInfo)

• 'lib/services/orion/utils': Folder where fiware-orion utilities are. (Utilities: ObjectAdaptor depending the type of the event, queryContext Common use of Orion-Client)

• 'lib/errors.js': File that contains the error definitions.

Object adaptations:

The object adaptations are based on a JSON pointer rule system. Using this way it is very simple to change the outcoming data. Files:

• lib/services/ngsi10/utils/objectAdaptors.js
• lib/services/orion/utils/objectAdaptors.js

Object adaptation example:

• Rules example:

  rules = [
  gin: '/geom_feature', destination: '/location'},
  tination: '/closingTime', default: '23:00'},
  tination: '/metered', default: false},
  tination: '/maximumAllowedDuration', default: 480},
  tination: '/totalSpotNumber', default: 210},
  tination: '/availableSpotNumber', func: helperFunctions.randomIntInc, arg: [50, 100]},
  gin: '/name', destination: '/name'},
  gin: '/metadata/description/eng', destination: '/description'},
  tination: '/type', default: 'ParkingLot'},
  gin: '/id', destination: '/id'}
  
  

• Origin Object:

  
  m_feature": "geom_feature",
  : "id",
  e": "name",
  adata": {"description": { "eng": "English Description" }}
  
  

• Result Object:

  
  ation": "geom_feature",
  sing_time": "23:00",
  ered": false,
  imumAllowedDuration": 480,
  alSpotNumber": 210,
  ilableSpotNumber": 55,
  : "id",
  e": "name",
  e": "ParkingLot",
  cription": "English Description",
  
  

Context Broker provisioner script

This script contains examples to set the context information about the cities. This information contains the URLs where the city context broker is.

 cbProvisioner
de --harmony index.js

It supports arguments to set information of a certain city. Arguments supported: madrid, oporto, guadalajara, aveiro, amsterdam

Example:

 cbProvisioner
de --harmony index.js oporto madrid

Deployment

Generate a tgz file with the code content.

m pack

Copy it to server using scp or other methods. Extract content:

r -xvzf fiware-here-adaptor-1.0.0.tgz

Go to package folder and install all dependencies:

 package
m install

Launch the server:

IG_DIR={path_to_config_folder} ./bin/fiware-here-adaptor

Or launch it using nohup:

IG_DIR={path_to_config_folder} nohup ./bin/fiware-here-adaptor &

Server Features:

• Logops library for logging to the standard output. (Pipe or json format supported). Use tee command to log to a file. https://github.com/telefonicaid/logops#writing-to-files
• Cluster. Take advantage of multi-core systems.
• Therror to define platform errors.
• Json schemas to check configuration.
• Configuration merge process using CONFIG_DIR environment var.

Documentation

HERE API doc

Smart Parking Data Models