X-Git-Url: https://git.piment-noir.org/?a=blobdiff_plain;f=README.md;h=3c4a77a7eb28c4831a0848953d267c6535e018b9;hb=d3140adc8c6ad502eb9566aabfc1af8f66d0ef24;hp=c194028653561ba08bead95b41e3a311d3d1d310;hpb=251fff5c7fd6f92c1f1acb921233c7e9c7c89003;p=e-mobility-charging-stations-simulator.git diff --git a/README.md b/README.md index c1940286..3c4a77a7 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,15 @@ -# [emobility-charging-stations-simulator](https://github.com/jerome-benoit/emobility-charging-stations-simulator) +# [e-mobility charging stations simulator](https://github.com/sap/e-mobility-charging-stations-simulator) + +[![REUSE status](https://api.reuse.software/badge/github.com/SAP/e-mobility-charging-stations-simulator)](https://api.reuse.software/info/github.com/SAP/e-mobility-charging-stations-simulator) ## Summary -Simple [node.js](https://nodejs.org/) program to simulate a set of charging stations based on the OCPP-J 1.6 protocol. +Simple [node.js](https://nodejs.org/) software to simulate a set of charging stations based on the OCPP-J 1.6 protocol as part of SAP e-Mobility solution. ## Prerequisites +Install the [node.js](https://nodejs.org/) LTS runtime environment: + ### Windows - [Chocolatey](https://chocolatey.org/): @@ -24,13 +28,36 @@ brew install node@16 ### GNU/Linux: -- [NodeSource](https://github.com/nodesource/distributions) Node.js Binary Distributions for version 16.X +- [NodeSource](https://github.com/nodesource/distributions) Node.js Binary Distributions for version >= 16.X + +## Installation + +In the repository root, run the following command: + +```shell +npm install +``` + +## Initial configuration + +Copy the configuration template file [src/assets/config-template.json](src/assets/config-template.json) to [src/assets/config.json](src/assets/config.json). +Copy the authorization RFID tags template file [src/assets/authorization-tags-template.json](src/assets/authorization-tags-template.json) to [src/assets/authorization-tags.json](src/assets/authorization-tags.json). + +Tweak them to your needs by following the section [configuration files syntax](README.md#configuration-files-syntax). + +## Start + +To start the program, run: `npm start`. + +## Start Web UI + +See Web UI [README.md](src/ui/web/README.md) for more information. ## Configuration files syntax All configuration files are in the JSON standard format. -**Configuration files list**: +**Configuration files locations**: - charging stations simulator configuration: [src/assets/config.json](src/assets/config.json); - charging station configuration templates: [src/assets/station-templates](src/assets/station-templates); @@ -55,39 +82,33 @@ The charging stations simulator have an automatic configuration files reload fea - charging station configuration templates; - charging station authorization RFID tags lists. -But the modifications to test have to be done to the files in the build result directory [dist/assets](dist/assets). Once the modifications are finished, they have to be reported or copied to the matching files in the build source directory [src/assets](src/assets) to ensure they will be taken into account at next build. +But the modifications to test have to be done to the files in the build target directory [dist/assets](dist/assets). Once the modifications are finished, they have to be reported or copied to the matching files in the build source directory [src/assets](src/assets) to ensure they will be taken into account at next build. ### Charging stations simulator configuration **src/assets/config.json**: -| Key | Value(s) | Default Value | Value type | Description | -| -------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| supervisionUrls | | [] | string \| string[] | string or array of global connection URIs to OCPP-J servers | -| supervisionUrlDistribution | round-robin/random/sequential | round-robin | boolean | supervision urls distribution policy to simulated charging stations | -| workerProcess | workerSet/staticPool/dynamicPool | workerSet | string | worker threads process type | -| workerStartDelay | | 500 | integer | milliseconds to wait at worker threads startup (only for workerSet threads process type) | -| elementStartDelay | | 0 | integer | milliseconds to wait at charging station startup | -| workerPoolMinSize | | 4 | integer | worker threads pool minimum number of threads | -| workerPoolMaxSize | | 16 | integer | worker threads pool maximum number of threads | -| workerPoolStrategy | ROUND_ROBIN/LESS_RECENTLY_USED/... | [poolifier](https://github.com/poolifier/poolifier) default: ROUND_ROBBIN | string | worker threads pool [poolifier](https://github.com/poolifier/poolifier) worker choice strategy | -| chargingStationsPerWorker | | 1 | integer | number of charging stations per worker threads for the `workerSet` process type | -| logStatisticsInterval | | 60 | integer | seconds between charging stations statistics output in the logs | -| logConsole | true/false | false | boolean | output logs on the console | -| logFormat | | simple | string | winston log format | -| logRotate | true/false | true | boolean | enable daily log files rotation | -| logMaxFiles | | 7 | integer | maximum number of log files to keep | -| logLevel | emerg/alert/crit/error/warning/notice/info/debug | info | string | winston logging level | -| logFile | | combined.log | string | log file relative path | -| logErrorFile | | error.log | string | error log file relative path | -| uiServer | | { "enabled": true, "options": { "host: "localhost", "port": 8080 } } | { enabled: boolean; options: ServerOptions; } | UI WebSocket server configuration section | -| performanceStorage | | { "enabled": false, "type": "jsonfile", "file:///performanceRecords.json" } | { enabled: boolean; type: string; URI: string; } where type can be 'jsonfile' or 'mongodb' | performance storage configuration section | -| stationTemplateUrls | | {}[] | { file: string; numberOfStations: number; }[] | array of charging station configuration templates URIs configuration section (charging station configuration template file name and number of stations) | +| Key | Value(s) | Default Value | Value type | Description | +| -------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| supervisionUrls | | [] | string \| string[] | string or array of global connection URIs to OCPP-J servers | +| supervisionUrlDistribution | round-robin/random/sequential | round-robin | boolean | supervision urls distribution policy to simulated charging stations | +| logStatisticsInterval | | 60 | integer | seconds between charging stations statistics output in the logs | +| logConsole | true/false | false | boolean | output logs on the console | +| logFormat | | simple | string | winston log format | +| logRotate | true/false | true | boolean | enable daily log files rotation | +| logMaxFiles | | 7 | integer | maximum number of log files to keep | +| logLevel | emerg/alert/crit/error/warning/notice/info/debug | info | string | winston logging level | +| logFile | | combined.log | string | log file relative path | +| logErrorFile | | error.log | string | error log file relative path | +| worker | | {
"processType": "workerSet",
"startDelay": 500,
"elementStartDelay": 0,
"elementsPerWorker": 1,
"poolMinSize": 4,
"poolMaxSize": 16,
"poolStrategy": "ROUND_ROBBIN"
} | {
processType: WorkerProcessType;
startDelay: number;
elementStartDelay: number;
elementsPerWorker: number;
poolMinSize: number;
poolMaxSize: number;
poolStrategy: WorkerChoiceStrategy;
} | Worker configuration section:
- processType: worker threads process type (workerSet/staticPool/dynamicPool)
- startDelay: milliseconds to wait at worker threads startup (only for workerSet threads process type)
- elementStartDelay: milliseconds to wait at charging station startup
- elementsPerWorker: number of charging stations per worker threads for the `workerSet` process type
- poolMinSize: worker threads pool minimum number of threads
- poolMaxSize: worker threads pool maximum number of threads
- poolStrategy: worker threads pool [poolifier](https://github.com/poolifier/poolifier) worker choice strategy | +| uiServer | | {
"enabled": true,
"type": "ws",
"options": {
"host: "localhost",
"port": 8080
}
} | {
enabled: boolean;
type: ApplicationProtocol;
options: ServerOptions;
} | UI server configuration section | +| performanceStorage | | {
"enabled": false,
"type": "jsonfile",
"file:///performanceRecords.json"
} | {
enabled: boolean;
type: string;
URI: string;
}
where type can be 'jsonfile' or 'mongodb' | performance storage configuration section | +| stationTemplateUrls | | {}[] | {
file: string;
numberOfStations: number;
}[] | array of charging station configuration templates URIs configuration section (charging station configuration template file name and number of stations) | #### Worker process model: - **workerSet**: - Worker set executing each a static number (chargingStationsPerWorker) of simulated charging stations from the total + Worker set executing each a static number (elementsPerWorker) of simulated charging stations from the total - **staticPool**: Statically sized worker pool executing a static total number of simulated charging stations @@ -99,55 +120,58 @@ But the modifications to test have to be done to the files in the build result d **src/assets/station-templates/\.json**: -| Key | Value(s) | Default Value | Value type | Description | -| --------------------------------- | ---------- | --------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| supervisionUrls | | '' | string \| string[] | string or array of connection URIs to OCPP-J servers | -| supervisionUser | | '' | string | basic HTTP authentication user to OCPP-J server | -| supervisionPassword | | '' | string | basic HTTP authentication password to OCPP-J server | -| supervisionUrlOcppConfiguration | true/false | false | boolean | allow supervision URL configuration via a vendor OCPP parameter key | -| supervisionUrlOcppKey | | 'ConnectionUrl' | string | the vendor string that will be used as a vendor OCPP parameter key to set the supervision URL | -| ocppVersion | 1.6 | 1.6 | string | OCPP version | -| ocppProtocol | json | json | string | OCPP protocol | -| ocppStrictCompliance | true/false | false | boolean | strict adherence to the OCPP version and protocol specifications | -| ocppPersistentConfiguration | true/false | true | boolean | enable persistent OCPP parameters storage by charging stations 'hashId'. The persistency is ensured by the charging stations configuration files in dist/assets/configurations | -| wsOptions | | {} | ClientOptions & ClientRequestArgs | [ws](https://github.com/websockets/ws) and node.js [http](https://nodejs.org/api/http.html) clients options intersection | -| authorizationFile | | '' | string | RFID tags list file relative to src/assets path | -| baseName | | '' | string | base name to build charging stations id | -| nameSuffix | | '' | string | name suffix to build charging stations id | -| fixedName | true/false | false | boolean | use the baseName as the charging stations unique name | -| chargePointModel | | '' | string | charging stations model | -| chargePointVendor | | '' | string | charging stations vendor | -| chargePointSerialNumberPrefix | | '' | string | charge point serial number prefix | -| chargeBoxSerialNumberPrefix | | '' | string | charge box serial number prefix (deprecated in OCPP 1.6) | -| firmwareVersion | | '' | string | charging stations firmware version | -| power | | | float \| float[] | charging stations maximum power value(s) | -| powerSharedByConnectors | true/false | false | boolean | charging stations power shared by its connectors | -| powerUnit | W/kW | W | string | charging stations power unit | -| currentOutType | AC/DC | AC | string | charging stations current out type | -| voltageOut | | AC:230/DC:400 | integer | charging stations voltage out | -| numberOfPhases | 0/1/3 | AC:3/DC:0 | integer | charging stations number of phase(s) | -| numberOfConnectors | | | integer \| integer[] | charging stations number of connector(s) | -| useConnectorId0 | true/false | true | boolean | use connector id 0 definition from the charging station configuration template | -| randomConnectors | true/false | false | boolean | randomize runtime connector id affectation from the connector id definition in charging station configuration template | -| resetTime | | 60 | integer | seconds to wait before the charging stations come back at reset | -| autoRegister | true/false | false | boolean | set charging stations as registered at boot notification for testing purpose | -| autoReconnectMaxRetries | | -1 (unlimited) | integer | connection retries to the OCPP-J server | -| reconnectExponentialDelay | true/false | false | boolean | connection delay retry to the OCPP-J server | -| registrationMaxRetries | | -1 (unlimited) | integer | charging stations boot notification retries | -| amperageLimitationOcppKey | | undefined | string | charging stations OCPP parameter key used to set the amperage limit, per phase for each connector on AC and global for DC | -| amperageLimitationUnit | A/cA/dA/mA | A | string | charging stations amperage limit unit | -| enableStatistics | true/false | true | boolean | enable charging stations statistics | -| mayAuthorizeAtRemoteStart | true/false | true | boolean | always send authorize at remote start transaction when AuthorizeRemoteTxRequests is enabled | -| beginEndMeterValues | true/false | false | boolean | enable Transaction.{Begin,End} MeterValues | -| outOfOrderEndMeterValues | true/false | false | boolean | send Transaction.End MeterValues out of order. Need to relax OCPP specifications strict compliance ('ocppStrictCompliance' parameter) | -| meteringPerTransaction | true/false | true | boolean | enable metering history on a per transaction basis | -| transactionDataMeterValues | true/false | false | boolean | enable transaction data MeterValues at stop transaction | -| mainVoltageMeterValues | true/false | true | boolean | include charging stations main voltage MeterValues on three phased charging stations | -| phaseLineToLineVoltageMeterValues | true/false | true | boolean | include charging stations line to line voltage MeterValues on three phased charging stations | -| customValueLimitationMeterValues | true/false | true | boolean | enable limitation on custom fluctuated value in MeterValues | -| Configuration | | | ChargingStationConfiguration | charging stations OCPP parameters configuration section | -| AutomaticTransactionGenerator | | | AutomaticTransactionGenerator | charging stations ATG configuration section | -| Connectors | | | Connectors | charging stations connectors configuration section | +| Key | Value(s) | Default Value | Value type | Description | +| ---------------------------------- | ---------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| supervisionUrls | | '' | string \| string[] | string or array of connection URIs to OCPP-J servers | +| supervisionUser | | '' | string | basic HTTP authentication user to OCPP-J server | +| supervisionPassword | | '' | string | basic HTTP authentication password to OCPP-J server | +| supervisionUrlOcppConfiguration | true/false | false | boolean | allow supervision URL configuration via a vendor OCPP parameter key | +| supervisionUrlOcppKey | | 'ConnectionUrl' | string | the vendor string that will be used as a vendor OCPP parameter key to set the supervision URL | +| ocppVersion | 1.6 | 1.6 | string | OCPP version | +| ocppProtocol | json | json | string | OCPP protocol | +| ocppStrictCompliance | true/false | false | boolean | strict adherence to the OCPP version and protocol specifications | +| ocppPersistentConfiguration | true/false | true | boolean | enable persistent OCPP parameters storage by charging stations 'hashId'. The persistency is ensured by the charging stations configuration files in dist/assets/configurations | +| stationInfoPersistentConfiguration | true/false | true | boolean | enable persistent station information and specifications storage by charging stations 'hashId'. The persistency is ensured by the charging stations configuration files in dist/assets/configurations | +| wsOptions | | {} | ClientOptions & ClientRequestArgs | [ws](https://github.com/websockets/ws) and node.js [http](https://nodejs.org/api/http.html) clients options intersection | +| authorizationFile | | '' | string | RFID tags list file relative to src/assets path | +| baseName | | '' | string | base name to build charging stations id | +| nameSuffix | | '' | string | name suffix to build charging stations id | +| fixedName | true/false | false | boolean | use the baseName as the charging stations unique name | +| chargePointModel | | '' | string | charging stations model | +| chargePointVendor | | '' | string | charging stations vendor | +| chargePointSerialNumberPrefix | | '' | string | charge point serial number prefix | +| chargeBoxSerialNumberPrefix | | '' | string | charge box serial number prefix (deprecated in OCPP 1.6) | +| firmwareVersion | | '' | string | charging stations firmware version | +| power | | | float \| float[] | charging stations maximum power value(s) | +| powerSharedByConnectors | true/false | false | boolean | charging stations power shared by its connectors | +| powerUnit | W/kW | W | string | charging stations power unit | +| currentOutType | AC/DC | AC | string | charging stations current out type | +| voltageOut | | AC:230/DC:400 | integer | charging stations voltage out | +| numberOfPhases | 0/1/3 | AC:3/DC:0 | integer | charging stations number of phase(s) | +| numberOfConnectors | | | integer \| integer[] | charging stations number of connector(s) | +| useConnectorId0 | true/false | true | boolean | use connector id 0 definition from the charging station configuration template | +| randomConnectors | true/false | false | boolean | randomize runtime connector id affectation from the connector id definition in charging station configuration template | +| resetTime | | 60 | integer | seconds to wait before the charging stations come back at reset | +| autoRegister | true/false | false | boolean | set charging stations as registered at boot notification for testing purpose | +| autoReconnectMaxRetries | | -1 (unlimited) | integer | connection retries to the OCPP-J server | +| reconnectExponentialDelay | true/false | false | boolean | connection delay retry to the OCPP-J server | +| registrationMaxRetries | | -1 (unlimited) | integer | charging stations boot notification retries | +| amperageLimitationOcppKey | | undefined | string | charging stations OCPP parameter key used to set the amperage limit, per phase for each connector on AC and global for DC | +| amperageLimitationUnit | A/cA/dA/mA | A | string | charging stations amperage limit unit | +| enableStatistics | true/false | true | boolean | enable charging stations statistics | +| mustAuthorizeAtRemoteStart | true/false | true | boolean | always send authorize at remote start transaction when AuthorizeRemoteTxRequests is enabled | +| payloadSchemaValidation | true/false | true | boolean | validate OCPP commands PDU against [OCA](https://www.openchargealliance.org/) JSON schemas | +| beginEndMeterValues | true/false | false | boolean | enable Transaction.{Begin,End} MeterValues | +| outOfOrderEndMeterValues | true/false | false | boolean | send Transaction.End MeterValues out of order. Need to relax OCPP specifications strict compliance ('ocppStrictCompliance' parameter) | +| meteringPerTransaction | true/false | true | boolean | enable metering history on a per transaction basis | +| transactionDataMeterValues | true/false | false | boolean | enable transaction data MeterValues at stop transaction | +| mainVoltageMeterValues | true/false | true | boolean | include charging stations main voltage MeterValues on three phased charging stations | +| phaseLineToLineVoltageMeterValues | true/false | true | boolean | include charging stations line to line voltage MeterValues on three phased charging stations | +| customValueLimitationMeterValues | true/false | true | boolean | enable limitation on custom fluctuated value in MeterValues | +| commandsSupport | | {
"incomingCommands": {},
"outgoingCommands": {}
} | {
incomingCommands: Record;
outgoingCommands?: Record;
} | Configuration section for OCPP commands support. Empty section or subsections means all implemented commands are supported | +| Configuration | | | ChargingStationConfiguration | charging stations OCPP parameters configuration section | +| AutomaticTransactionGenerator | | | AutomaticTransactionGenerator | charging stations ATG configuration section | +| Connectors | | | Connectors | charging stations connectors configuration section | #### Configuration section @@ -238,13 +262,6 @@ The syntax is similar to charging station configuration template with some added The syntax is similar to the charging station configuration template 'Configuration' section. -## Start - -To start the program, run: `npm start`. - -To start the program with a UI controller, run: `npm start:server`. -Then, start/stop the simulator by going to `https://` in a browser. Localhost port will default to 8080. For Cloud Foundry, the port is assigned based on the `process.env.PORT` environment variable. - ## Docker In the [docker](./docker) folder: @@ -365,9 +382,155 @@ All kind of OCPP parameters are supported in a charging station configuration or - _none_ +## UI protocol + +Protocol to control the simulator via a Websocket or HTTP server. + +### HTTP Protocol + +A Postman or [Insomnia](https://insomnia.rest/) collection, to learn how to use the HTTP protocol to pilot the simulator, is available in [src/assets](./src/assets/) directory. + +### WebSocket Protocol + +PDU stands for Protocol Data Unit. + +- Request: + [`uuid`, `ProcedureName`, `PDU`] + `uuid`: String uniquely representing this request + `ProcedureName`: The procedure to run on the simulator + `PDU`: The parameters for said procedure + +- Response: + [`uuid`, `PDU`] + `uuid`: String uniquely linking the response to the request + `PDU`: Response data to requested procedure + +#### Version 0.0.1 + +Set the WebSocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. + +##### Procedures + +###### Start Simulator + +- Request: + `ProcedureName`: 'startSimulator' + `PDU`: {} + +- Response: + `PDU`: { + `status` + } + +###### Stop Simulator + +- Request: + `ProcedureName`: 'stopSimulator' + `PDU`: {} + +- Response: + `PDU`: { + `status` + } + +###### List Charging Stations + +- Request: + `ProcedureName`: 'listChargingStations' + `PDU`: {} + +- Response: + `PDU`: { + `status`, + `index`: ChargingStationData, + ... + `index`: ChargingStationData + } + +###### Start Transaction + +- Request: + `ProcedureName`: 'startTransaction' + `PDU`: { + `hashId`: charging station unique identifier string (deprecated) | `hashIds`: charging station unique identifier strings array, + `connectorId`: connector id integer, + `idTag`: RFID tag string + } + +- Response: + `PDU`: { + `status` + } + +###### Stop Transaction + +- Request: + `ProcedureName`: 'stopTransaction' + `PDU`: { + `hashId`: charging station unique identifier string (deprecated) | `hashIds`: charging station unique identifier strings array, + `transactionId`: transaction id integer + } + +- Response: + `PDU`: { + `status` + } + +###### Start Charging Station + +- Request: + `ProcedureName`: 'startChargingStation' + `PDU`: { + `hashId`: charging station unique identifier string (deprecated) | `hashIds`: charging station unique identifier strings array + } + +- Response: + `PDU`: { + `status` + } + +###### Stop Charging Station + +- Request: + `ProcedureName`: 'stopChargingStation' + `PDU`: { + `hashId`: charging station unique identifier string (deprecated) | `hashIds`: charging station unique identifier strings array + } + +- Response: + `PDU`: { + `status` + } + +###### Open Connection + +- Request: + `ProcedureName`: 'openConnection' + `PDU`: { + `hashId`: charging station unique identifier string (deprecated) | `hashIds`: charging station unique identifier strings array + } + +- Response: + `PDU`: { + `status` + } + +###### Close Connection + +- Request: + `ProcedureName`: 'closeConnection' + `PDU`: { + `hashId`: charging station unique identifier string (deprecated) | `hashIds`: charging station unique identifier strings array + } + +- Response: + `PDU`: { + `status` + } + ## Support, Feedback, Contributing -This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/SAP/emobility-charging-stations-simulator/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md). +This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/SAP/e-mobility-charging-stations-simulator/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md). ## Code of Conduct @@ -375,4 +538,4 @@ We as members, contributors, and leaders pledge to make participation in our com ## Licensing -Copyright 2020-2022 SAP SE or an SAP affiliate company and emobility-charging-stations-simulator contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/emobility-charging-stations-simulator). +Copyright 2020-2022 SAP SE or an SAP affiliate company and e-mobility-charging-stations-simulator contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/e-mobility-charging-stations-simulator).