Open e-Mobility NodeJs Server
Summary
This application server (NodeJs) collects and stores the data (MongoDB) received from the Charging Stations via the OCPP protocol and exposes a REST service to an Angular front-end dashboard application (Open e-Mobility Angular Dashboard).
The application features:
- Charging Stations details and real-time statuses
- Charging sessions curves in real time
- Charging stations remote control (Reboot, Clear Cache, Stop Transaction, Unlock Connector)
- Charging Station Template management: Zero configuration
- User management
- Badge management
- Role management (ABAC)
- Static Energy Management: Manually limit the charging station
- Smart Charging with Assets, Fair Sharing, Peak Shaving, Cost Management and Phase Balancing
- Realtime Asset Management (Building, Battery, Solar Panel)
- Billing with Stripe
- Complex Pricing
- Roaming integration (Gire, Hubject)
- Refunding (SAP Concur)
- Simple Statistics + Advanced Analytics (SAP Analytics)
- Car Connector Management (Get the car's data to optimize the charging session)
Contact the author Serge FABIANO
Installation
- Install NodeJS: https://nodejs.org/ (install the LTS version)
- Install Python: https://www.python.org/ (needed by node-gyp)
- Install MongoDB: https://www.mongodb.com/
- Clone this GitHub project
- Install required build tools:
- Under Windows as an administrator:
npm install --global --production windows-build-tools
- Under Mac OS X, install Xcode from the Apple store
- Under Debian based GNU/Linux distribution:
sudo apt install build-essential
- Under Windows as an administrator:
- Go into the ev-server directory and run npm install or yarn install
NOTE:
- On Windows with chocolatey (https://chocolatey.org/), do as an administrator:
choco install -y nodejs-lts mongodb python postman robot3t microsoft-build-tools
- On Mac OSX with Homebrew (https://brew.sh/), do:
brew tap mongodb/brew
brew install node mongodb-community@4.4 python@3.9 postman robo-3t
- Follow the rest of the setup below
The Database
Start MongoDB
Manually
mongod --port <port> --dbpath <path> --replSet <replcaSetName>
For instance:
mongod --port 27017 --dbpath "/var/lib/mongodb" --replSet "rs0"
As a Windows service
Add to /path/to/mongod.cfg (open -a TextEdit /usr/local/etc/mongod.cfg)
...
replication:
replSetName: "rs0"
...
Restart the MongoDB service with Powershell as an administrator:
Restart-Service -Name "MongoDB"
Activate the Replica Set
Activate the replica set:
- Start the Mongo client
mongo
- Activate the Replica Set
rs.initiate()
Check here for more info: Mongo DB Replica Set
Create the Admin user
This user will be used to connect to the database as an administrator with tools like MongoDB shell or RoboMongo:
Create Admin User on Admin schema:
use admin
db.createUser({
user: "evse-admin",
pwd: "<YourPassword>",
roles: [
"read",
"readWrite",
"dbAdmin",
"userAdmin",
"clusterAdmin",
"readAnyDatabase",
"readWriteAnyDatabase",
"userAdminAnyDatabase",
"dbAdminAnyDatabase"
],
passwordDigestor: "server"
})
Restart MongoDB with authentication enabled
Manually
This will restart MongoDB and will accept only authenticated connections from now:
mongod --auth --port <port> --dbpath <path> --replSet <replcaSetName>
As a Windows service
Add to /path/to/mongod.cfg:
...
security:
authorization: enabled
...
Restart the MongoDB service with Powershell as an administrator:
Restart-Service -Name "MongoDB"
Create the Application User
Connect using the admin user
mongo -u evse-admin -p <YourPassword> --authenticationDatabase admin
Create Application User on EVSE schema
use evse
db.createUser({
user: "evse-user",
pwd: "<YourPassword>",
roles: [
"readWrite"
],
passwordDigestor: "server"
})
Now your database is ready to be used.
NOTE: You can also use empty-db.zip or empty-db-service.zip on the share to do the initial setup of the databases required by simply deleting all files in the MongoDB databases path and then dropping its content inside instead.
The Application Server
The application server consists of:
- Central Service Server: Serves the charging stations
- Central Service REST Server: Serves the Angular front-end dashboard
The Central Service Server (CSS)
This application server will listen to the charging stations and store the data exchanged into to the database.
It can also communicate with the charging stations (reboot, stop a transaction...)
The protocol used by this application server is OCPP (Open Charge Point Protocol) in version 1.2, 1.5 and 1.6 (OCPP-S or OCPP-J).
Other protocols, like the ISO 15118, or OCPP version 2.0 will also be supported in the future.
Configuration
In src/assets folder there are two templates already provided named config-template-http.json for HTTP and config-template-https.json for HTTPS.
Choose one and rename it to config.json.
Listen to the Charging Stations
Set the protocol, host and the port which you want the server to listen to:
SOAP (OCPP-S):
"CentralSystems": [
{
"implementation": "soap",
"protocol": "http",
"host": "localhost",
"port": 8000
}
]
JSON (OCPP-J):
"CentralSystems": [
{
"implementation": "json",
"protocol": "ws",
"host": "localhost",
"port": 8010
}
]
There can be several central systems with different protocols.
The Central Service REST Server (CSRS)
The server also exposes a set of REST services to serve the front-end Angular Dashboard.
This application displays the charging stations with their statuses, charging curves, user management...
To set the end point, fill the following information in the config.json file
Secure Configuration (SSL)
"CentralSystemRestService": {
"protocol": "https",
"host": "localhost",
"port": 443,
"sslKey": "ssl/64933587-localhost.key",
"sslCert": "ssl/64933587-localhost.cert",
"sslCa": [],
"userTokenKey": "MySecureKeyToEncodeTokenAuth",
"userTokenLifetimeHours": 12,
"userDemoTokenLifetimeDays": 365,
"userTechnicalTokenLifetimeDays": 365,
"debug": false
}
Simple Configuration
"CentralSystemRestService": {
"protocol": "http",
"host": "localhost",
"port": 80,
"userTokenKey": "YourSecureKeyToEncodeTokenAuth",
"userTokenLifetimeHours": 12,
"userDemoTokenLifetimeDays": 365,
"userTechnicalTokenLifetimeDays": 365,
"debug": false
}
In order to properly call the REST endpoints, both ev-server and clients (ev-dashboard, ev-mobile, etc.) must reference a Google reCaptcha key. You can refer to this link https://www.google.com/recaptcha/admin/create, then copy the server key in config.json file, in section CentralSystemRestService:
...
"captchaSecretKey": "<GOOGLE_RECAPTCHA_KEY_SERVER>"
...
Central Service Server (CSS) > Database
You have now to connect the server to the database.
Configuration
Database connection info:
"Storage": {
"implementation": "mongodb",
"host": "localhost",
"port": 27017,
"user": "evse-user",
"password": "YourPassword",
"database" : "evse"
}
Front-End
When the user will be notified (by email for instance), a link to the front-end application will be built based on the configuration below:
"CentralSystemFrontEnd": {
"protocol": "https",
"host": "localhost",
"port": 8080
}
Notifications
The user will receive a notification when, for instance, his vehicle will be fully charged.
Only notification via emails is implemented today.
Email Notification
Edit the following info:
"Email": {
"smtp": {
"from": "evse.adm.noreply@gmail.com",
"host": "smtp.gmail.com",
"port": 465,
"secure": true,
"requireTLS": true,
"type": "login",
"user": "YourEmailUser",
"password": "YourEmailPassword",
"debug": false
}
}
Users
Authentication
The authentication is done via user login/password and the server will deliver a token that will expire after a certain period of time.
Then there are neither session nor cookies sent around and this will allow to scale easily.
The token key is provided is the config.json file:
"CentralSystemRestService": {
...
"userTokenKey": "MySecureKeyToEncodeTokenAuth",
"userTokenLifetimeHours": 12,
"userDemoTokenLifetimeDays": 365,
"userTechnicalTokenLifetimeDays": 365,
...
}
You can set your own key to encode it in key userTokenKey and change its lifetime in userTokenLifetimeHours (12 hours by default.)
The Demo users can have a longer lifetime for demo purposes with key userDemoTokenLifetimeDays (365 days by default)
Authorization
The users can have differents roles:
- SuperAdmin (S)
- Admin (A)
- Basic (B)
- Demo (D)
Authorization Matrix
SuperAdmin | Admin | Basic | Demo | |
---|---|---|---|---|
Users | List | - | - | |
User | Create, Read, Update, Delete, Logout | Read, Update (Only logged user), Logout | (user hidden) | |
ChargingStations | List | List | List | |
ChargingStation | Read, Update, Delete, Reset, ClearCache, GetConfiguration, ChangeConfiguration, StopTransaction, UnlockConnector | Read | Read | |
Logging | List | List | - | |
Tenant | Create, Read, Update, Delete | - |
Notifications
The user will receive a notification when, for instance, his vehicle will be fully charged.
Email Notification
Set the following info:
"Email": {
"smtp": {
"from": "evse.adm.noreply@gmail.com",
"host": "smtp.gmail.com",
"port": 465,
"secure": true,
"requireTLS": true,
"type": "login",
"user": "YourEmailUser",
"password": "YourEmailPassword",
"debug": false
}
}
Charging Station Parameters
Here are the charging station parameters:
"ChargingStation": {
"heartbeatIntervalSecs": 60,
"checkEndOfChargeNotificationAfterMin": 5,
"notifBeforeEndOfChargePercent": 50,
"notifBeforeEndOfChargeEnabled": false,
"notifEndOfChargePercent": 0,
"notifEndOfChargeEnabled": true,
"notifStopTransactionAndUnlockConnector": false
},
- heartbeatIntervalSecs: The time interval which the charging station will send the data to the server
- checkEndOfChargeNotificationAfterMin: The delay to wait before the notification will be sent when the charge will be finished
- notifBeforeEndOfChargePercent: The threshold for the intermediate notification (% of the energy delivered by the charging station)
- notifBeforeEndOfChargeEnabled: Enable the intermediate notification
- notifEndOfChargePercent: The threshold for the end of charge (% of the energy delivered by the charging station)
- notifEndOfChargeEnabled: Enable the end of charge notification
- notifStopTransactionAndUnlockConnector: Enable the stop transaction and unlock of the connector when the charge will be finished
Internationalization
Here are the default delivered locales:
"Locales": {
"default": "en_US",
"supported": [
"en_US",
"fr_FR",
"es_ES",
"de_DE",
"pt_PT",
"it_IT",
]
},
The Charging Stations
Each charging station vendor has its own configuration interface, so I'll just describe in general terms what's to be setup on those:
- Set this server URL in the charging station's interface
- Rename the charging station ID if necessary: this will be the key (use Company-Town-Number)
- Set the charging station endpoint public URL to a reachable URL so the server can use it to trigger action on it (avoid using localhost)
All charging stations supporting OCPP-J and OCPP-S version 1.5 and 1.6 protocols are compatibles.
Start the Central Service Server (CSS)
Production Mode
Start the application:
npm run start
You can also start the application with the standard nodejs profiler:
npm run start:prod:prof
Development Mode
In a console, start the application (rebuild and restarts if any changes is detected):
npm run start:dev
You can also start the application with the standard nodejs profiler:
npm run start:dev:prof
clinic
Profiling withnpm run start:(prod|dev):(doctorprof|flameprof|bubbleprof)
NOTE: You can also use the files in the ev-config-scripts.zip on the share to have a correct initial setup of your development environment and some server startup helpers.
Tests
Prerequisite: The database must contain an admin user.
- Create a local configuration file located in './test/config/local.json' from the template file './test/config-template.json' with the parameters to override like
{
"superadmin": {
"username": "YOUR_SUPERADMIN_USERNAME",
"password": "YOUR_SUPERADMIN_PASSWORD"
},
"admin": {
"username": "YOUR_ADMIN_USERNAME",
"password": "YOUR_ADMIN_PASSWORD"
},
"server": {
"logs": "json"
},
"ocpp": {
"json": {
"logs": "json"
}
}
}
For further parameters, check the config
content. It is also possible to use environment variables as defined in the config
file
- Start a server containing the configured admin user in the database
- If you have not done it yet, run the command
npm run mochatest:createContext
- Run the command
npm run mochatest
Docker Mode
Depending on the need it is possible to start different docker containers.
Each following command has to be executed in folder docker.
Minimal local environment
It consist in starting a pre configured empty mongo database plus a mail service and mongo express. To start it, execute command:
make local-env
To stop it, execute command:
make clean-local-env-containers
The mongo database folder will be kept along multiple restarts. To remove it:
make clean-mongo-data
Due to fixed replica set configuration, the database hostname has to be referenced in the host machine to be accessible.
To enable it, as admin, add the entry ev_mongo 127.0.0.1
in /private/etc/hosts
for MacOSX or in C:\Windows\System32\Drivers\etc\hosts
for Windows.
The database is then accessible using the credential evse-admin/evse-admin-pwd
.
The default login/password on the master tenant is super.admin@ev.com/Super.admin00. The default login/password on the SLF tenant is slf.admin@ev.com/Slf.admin00.
ev-server
In case of UI development or test purpose, the server has been containerized. To start it, execute command:
make server
In order to rebuild the image in case of changes:
make server-force
To stop it, execute command:
make clean-server-container
mongo express
If needed, it is possible to start or stop a mongo express instance auto connected to mongodb independently. To start it, execute command:
make mongo-express
To stop it, execute command:
make clean-mongo-express-container
All in one
It is possible to build and start all containers in one command:
make
Or without the optional git submodules:
make SUBMODULES_INIT=false
That Makefile option works for all targets.
Architecture
TAM Model
License
This file and all other files in this repository are licensed under the Apache Software License, v.2 and copyrighted under the copyright in NOTICE file, except as noted otherwise in the LICENSE file.
Please note that Docker images can contain other software which may be licensed under different licenses. This LICENSE and NOTICE files are also included in the Docker image. For any usage of built Docker images please make sure to check the licenses of the artifacts contained in the images.