repositories / e-mobility-charging-stations-simulator.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
docs: add branching model to README.md
[e-mobility-charging-stations-simulator.git] / README.md
CommitLineData
d6b76da3 1<!-- markdownlint-disable-file MD033 MD024 -->
aef08642 2<div align="center">
9e0845f7 3
aef08642 4# [e-Mobility charging stations simulator](https://github.com/sap/e-mobility-charging-stations-simulator)
7dde0b73 5
aef08642
JB		 6</div>
7
8<div align="center">
7b0ca523 9
b0b6537f
JB		 10[![GitHub Clones](https://img.shields.io/badge/dynamic/json?color=brightgreen&label=Clone&query=count&url=https://gist.githubusercontent.com/jerome-benoit/c7c669b881d5b27dc0b44a639504ff93/raw/clone.json&logo=github)](https://github.com/SAP/e-mobility-charging-stations-simulator/graphs/traffic)
11[![GitHub commit activity (main)](https://img.shields.io/github/commit-activity/m/SAP/e-mobility-charging-stations-simulator/main?color=brightgreen&logo=github)](https://github.com/SAP/e-mobility-charging-stations-simulator/graphs/commit-activity)
f1fded7b 12[![CI workflow](https://github.com/SAP/e-mobility-charging-stations-simulator/actions/workflows/ci.yml/badge.svg)](https://github.com/SAP/e-mobility-charging-stations-simulator/actions/workflows/ci.yml)
4d188eb9 13[![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)
b157a1df 14[![Javascript Standard Style Guide](<https://badgen.net/static/code style/standard/green>)](https://standardjs.com)
0a3d08ef 15
aef08642
JB		 16</div>
17
18Simple [node.js](https://nodejs.org/) software to simulate and scale a set of charging stations based on the OCPP-J protocol as part of [SAP e-Mobility](https://www.sap.com/products/scm/e-mobility.html) solution.
19
99a3209e
JB		 20## Table of contents
21
99a3209e
JB		 22- [Installation](#installation)
23 - [Prerequisites](#prerequisites)
24 - [Windows](#windows)
25 - [MacOSX](#macosx)
26 - [GNU/Linux](#gnulinux)
17c91636
JB		 27 - [Development prerequisites (optional)](#development-prerequisites-optional)
28 - [Unix](#unix)
29 - [Windows](#windows-1)
99a3209e
JB		 30 - [Dependencies](#dependencies)
31- [Initial configuration](#initial-configuration)
ea208169 32- [Start simulator](#start-simulator)
99a3209e
JB		 33- [Start Web UI](#start-web-ui)
34- [Configuration files syntax](#configuration-files-syntax)
35 - [Charging stations simulator configuration](#charging-stations-simulator-configuration)
783b9545 36 - [Charging station template configuration](#charging-station-template-configuration)
99a3209e
JB		 37 - [Charging station configuration](#charging-station-configuration)
38- [Docker](#docker)
39- [OCPP-J commands supported](#ocpp-j-commands-supported)
40 - [Version 1.6](#version-16)
41 - [Version 2.x.x](#version-2xx)
42- [OCPP-J standard parameters supported](#ocpp-j-standard-parameters-supported)
43 - [Version 1.6](#version-16-1)
44 - [Version 2.x.x](#version-2xx-1)
e35d61ad 45- [UI Protocol](#ui-protocol)
99a3209e
JB		 46 - [Websocket Protocol](#websocket-protocol)
47 - [HTTP Protocol](#http-protocol)
48- [Support, Feedback, Contributing](#support-feedback-contributing)
49- [Code of Conduct](#code-of-conduct)
50- [Licensing](#licensing)
51
99a3209e
JB		 52## Installation
53
54### Prerequisites
696ce53a 55
5845e83d 56Install the [node.js](https://nodejs.org/) current LTS or superior version runtime environment:
007ee642 57
99a3209e 58#### Windows
696ce53a 59
e7aeea18 60- [Chocolatey](https://chocolatey.org/):
696ce53a
JB		 61
62```powershell
5845e83d 63choco install -y nodejs
696ce53a
JB		 64```
65
99a3209e 66#### MacOSX
696ce53a 67
e7aeea18 68- [Homebrew](https://brew.sh/):
696ce53a
JB		 69
70```shell
5845e83d 71brew install node
696ce53a
JB		 72```
73
99a3209e 74#### GNU/Linux
511780c3 75
17c91636 76- [NodeSource](https://github.com/nodesource/distributions) node.js binary distributions for all supported versions.
511780c3 77
17c91636 78### Development prerequisites (optional)
007ee642 79
17c91636
JB		 80Install [volta](https://volta.sh/) for managing automatically the node.js runtime and package manager version:
81
82#### Unix
83
84```shell
85curl https://get.volta.sh | bash
86```
87
88#### Windows
89
90```powershell
91choco install volta
92```
93
783b9545 94Setup [volta](https://volta.sh/) with [pnpm](https://github.com/pnpm/pnpm) package manager support: https://docs.volta.sh/advanced/pnpm
17c91636 95
d295031f
JB		 96### Branching model
97
98The `main` branch is the default development branch.
99The `vX` branches are the maintenance branches for the corresponding major version `X`.
100The `vX.Y` branches are the maintenance branches for the corresponding major and minor version `X.Y`.
101
17c91636
JB		 102### Dependencies
103
104Enable corepack, if [volta](https://volta.sh/) is not installed and configured, and install latest pnpm version:
5845e83d
JB		 105
106```shell
107corepack enable
1a662d29 108corepack prepare pnpm@latest --activate
5845e83d
JB		 109```
110
007ee642
JB		 111In the repository root, run the following command:
112
113```shell
881f450c 114pnpm install
007ee642
JB		 115```
116
117## Initial configuration
118
f80e9e18
JB		 119Copy the configuration template file [src/assets/config-template.json](./src/assets/config-template.json) to [src/assets/config.json](./src/assets/config.json).
120Copy the RFID tags template file [src/assets/idtags-template.json](./src/assets/idtags-template.json) to [src/assets/idtags.json](./src/assets/idtags.json).
db70b600 121
352ea56d 122Tweak them to your needs by following the section [configuration files syntax](#configuration-files-syntax): OCPP server supervision URL(s), charging station templates, etc.
007ee642 123
ea208169 124## Start simulator
007ee642 125
c1936747
JB		 126```shell
127pnpm start
128```
007ee642 129
4e3ff94d 130## Start Web UI
007ee642 131
f80e9e18 132See Web UI [README.md](./ui/web/README.md) for more information.
b8cc885d 133
4d3821a2 134## Configuration files syntax
2c28fc83 135
ea208169 136All configuration files are using the JSON standard syntax.
2c28fc83 137
ff82dc5f 138**Configuration files locations**:
2c28fc83 139
f80e9e18
JB		 140- charging stations simulator configuration: [src/assets/config.json](./src/assets/config.json);
141- charging station configuration templates: [src/assets/station-templates](./src/assets/station-templates);
142- charging station configurations: [dist/assets/configurations](./dist/assets/configurations);
143- charging station RFID tags lists: [src/assets](./src/assets).
2c28fc83 144
f80e9e18 145The charging stations simulator's configuration parameters must be within the `src/assets/config.json` file. A charging station simulator configuration template file is available at [src/assets/config-template.json](./src/assets/config-template.json).
1816f743 146
f80e9e18 147All charging station configuration templates are in the directory [src/assets/station-templates](./src/assets/station-templates).
1816f743 148
f80e9e18 149A list of RFID tags must be defined for the automatic transaction generator in a file with the default location and name: `src/assets/idtags.json`. A template file is available at [src/assets/idtags-template.json](./src/assets/idtags-template.json).
1816f743
JB		 150
151**Configuration files hierarchy and priority**:
152
f80e9e18
JB		 1531. charging station configuration: [dist/assets/configurations](./dist/assets/configurations);
1542. charging station configuration template: [src/assets/station-templates](./src/assets/station-templates);
1553. charging stations simulator configuration: [src/assets/config.json](./src/assets/config.json).
511780c3 156
3a28512c 157The charging stations simulator has an automatic configuration files reload feature at change for:
511780c3 158
170bec53 159- charging stations simulator configuration;
1816f743 160- charging station configuration templates;
170bec53 161- charging station authorization RFID tags lists.
2c28fc83 162
f80e9e18 163But the modifications to test have to be done to the files in the build target directory [dist/assets](./dist/assets). Once the modifications are done, they have to be reported to the matching files in the build source directory [src/assets](./src/assets) to ensure they will be taken into account at next build.
e7aeea18 164
170bec53 165### Charging stations simulator configuration
2c28fc83 166
b1d6e944 167**src/assets/config.json**:
2c28fc83 168
da47bc29
JB		 169| Key | Value(s) | Default Value | Value type | Description |
170| -------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
171| supervisionUrls | | [] | string \| string[] | string or strings array containing global connection URIs to OCPP-J servers |
172| supervisionUrlDistribution | round-robin/random/charging-station-affinity | charging-station-affinity | string | supervision urls distribution policy to simulated charging stations |
173| log | | {<br />"enabled": true,<br />"file": "logs/combined.log",<br />"errorFile": "logs/error.log",<br />"statisticsInterval": 60,<br />"level": "info",<br />"console": false,<br />"format": "simple",<br />"rotate": true<br />} | {<br />enabled?: boolean;<br />file?: string;<br />errorFile?: string;<br />statisticsInterval?: number;<br />level?: string;<br />console?: boolean;<br />format?: string;<br />rotate?: boolean;<br />maxFiles?: string \| number;<br />maxSize?: string \| number;<br />} | Log configuration section:<br />- _enabled_: enable logging<br />- _file_: log file relative path<br />- _errorFile_: error log file relative path<br />- _statisticsInterval_: seconds between charging stations statistics output in the logs<br />- _level_: emerg/alert/crit/error/warning/notice/info/debug [winston](https://github.com/winstonjs/winston) logging level</br >- _console_: output logs on the console<br />- _format_: [winston](https://github.com/winstonjs/winston) log format<br />- _rotate_: enable daily log files rotation<br />- _maxFiles_: maximum number of log files: https://github.com/winstonjs/winston-daily-rotate-file#options<br />- _maxSize_: maximum size of log files in bytes, or units of kb, mb, and gb: https://github.com/winstonjs/winston-daily-rotate-file#options |
174| worker | | {<br />"processType": "workerSet",<br />"startDelay": 500,<br />"elementAddDelay": 0,<br />"elementsPerWorker": 'auto',<br />"poolMinSize": 4,<br />"poolMaxSize": 16<br />} | {<br />processType?: WorkerProcessType;<br />startDelay?: number;<br />elementAddDelay?: number;<br />elementsPerWorker?: number \| 'auto' \| 'all';<br />poolMinSize?: number;<br />poolMaxSize?: number;<br />resourceLimits?: ResourceLimits;<br />} | Worker configuration section:<br />- _processType_: worker threads process type (`workerSet`/`fixedPool`/`dynamicPool`)<br />- _startDelay_: milliseconds to wait at worker threads startup (only for `workerSet` worker threads process type)<br />- _elementAddDelay_: milliseconds to wait between charging station add<br />- _elementsPerWorker_: number of charging stations per worker threads for the `workerSet` process type (`auto` means (number of stations) / (number of CPUs) \* 1.5 if (number of stations) > (number of CPUs), otherwise 1; `all` means a unique worker will run all charging stations)<br />- _poolMinSize_: worker threads pool minimum number of threads</br >- _poolMaxSize_: worker threads pool maximum number of threads<br />- _resourceLimits_: worker threads [resource limits](https://nodejs.org/api/worker_threads.html#new-workerfilename-options) object option |
175| uiServer | | {<br />"enabled": false,<br />"type": "ws",<br />"version": "1.1",<br />"options": {<br />"host": "localhost",<br />"port": 8080<br />}<br />} | {<br />enabled?: boolean;<br />type?: ApplicationProtocol;<br />version?: ApplicationProtocolVersion;<br />options?: ServerOptions;<br />authentication?: {<br />enabled: boolean;<br />type: AuthenticationType;<br />username?: string;<br />password?: string;<br />}<br />} | UI server configuration section:<br />- _enabled_: enable UI server<br />- _type_: 'http' or 'ws'<br />- _version_: HTTP version '1.1' or '2.0'<br />- _options_: node.js net module [listen options](https://nodejs.org/api/net.html#serverlistenoptions-callback)<br />- _authentication_: authentication type configuration section |
176| performanceStorage | | {<br />"enabled": true,<br />"type": "none",<br />} | {<br />enabled?: boolean;<br />type?: string;<br />uri?: string;<br />} | Performance storage configuration section:<br />- _enabled_: enable performance storage<br />- _type_: 'jsonfile', 'mongodb' or 'none'<br />- _uri_: storage URI |
8f8f87c4 177| stationTemplateUrls | | {}[] | {<br />file: string;<br />numberOfStations: number;<br />provisionedNumberOfStations?: number;<br />}[] | array of charging station templates URIs configuration section:<br />- _file_: charging station configuration template file relative path<br />- _numberOfStations_: template number of stations at startup<br />- _provisionedNumberOfStations_: template provisioned number of stations after startup |
e7aeea18 178
d6b76da3 179#### Worker process model
a6b3c6c3
JB		 180
181- **workerSet**:
1d8f226b 182 Worker set executing each a fixed number (elementsPerWorker) of simulated charging stations from the total
a6b3c6c3 183
1d8f226b
JB		 184- **fixedPool**:
185 Fixedly sized worker pool executing a fixed total number of simulated charging stations
a6b3c6c3 186
56e2e1ab 187- **dynamicPool** (experimental):
1d8f226b 188 Dynamically sized worker pool executing a fixed total number of simulated charging stations
a6b3c6c3 189
783b9545 190### Charging station template configuration
1816f743 191
afccb423 192**src/assets/station-templates/\<name\>.json**:
1816f743 193
f80e9e18
JB		 194| Key | Value(s) | Default Value | Value type | Description |
195| ---------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
196| supervisionUrls | | [] | string \| string[] | string or strings array containing connection URIs to OCPP-J servers |
197| supervisionUser | | undefined | string | basic HTTP authentication user to OCPP-J server |
198| supervisionPassword | | undefined | string | basic HTTP authentication password to OCPP-J server |
199| supervisionUrlOcppConfiguration | true/false | false | boolean | enable supervision URL configuration via a vendor OCPP parameter key |
200| supervisionUrlOcppKey | | 'ConnectionUrl' | string | the vendor string that will be used as a vendor OCPP parameter key to set the supervision URL |
201| autoStart | true/false | true | boolean | enable automatic start of added charging station from template |
202| ocppVersion | 1.6/2.0/2.0.1 | 1.6 | string | OCPP version |
203| ocppProtocol | json | json | string | OCPP protocol |
204| ocppStrictCompliance | true/false | true | boolean | enable strict adherence to the OCPP version and protocol specifications with OCPP commands PDU validation against [OCA](https://www.openchargealliance.org/) JSON schemas |
205| 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](./dist/assets/configurations) |
206| 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](./dist/assets/configurations) |
207| automaticTransactionGeneratorPersistentConfiguration | true/false | true | boolean | enable persistent automatic transaction generator configuration storage by charging stations 'hashId'. The persistency is ensured by the charging stations configuration files in [dist/assets/configurations](./dist/assets/configurations) |
208| wsOptions | | {} | ClientOptions & ClientRequestArgs | [ws](https://github.com/websockets/ws) and node.js [http](https://nodejs.org/api/http.html) clients options intersection |
209| idTagsFile | | undefined | string | RFID tags list file relative to [src/assets](./src/assets) path |
210| baseName | | undefined | string | base name to build charging stations id |
211| nameSuffix | | undefined | string | name suffix to build charging stations id |
212| fixedName | true/false | false | boolean | use the 'baseName' as the charging stations unique name |
213| chargePointModel | | undefined | string | charging stations model |
214| chargePointVendor | | undefined | string | charging stations vendor |
215| chargePointSerialNumberPrefix | | undefined | string | charge point serial number prefix |
216| chargeBoxSerialNumberPrefix | | undefined | string | charge box serial number prefix (deprecated since OCPP 1.6) |
217| firmwareVersionPattern | | Semantic versioning regular expression: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string | string | charging stations firmware version pattern |
218| firmwareVersion | | undefined | string | charging stations firmware version |
219| power | | | float \| float[] | charging stations maximum power value(s) |
220| powerSharedByConnectors | true/false | false | boolean | charging stations power shared by its connectors |
221| powerUnit | W/kW | W | string | charging stations power unit |
222| currentOutType | AC/DC | AC | string | charging stations current out type |
223| voltageOut | | AC:230/DC:400 | integer | charging stations voltage out |
224| numberOfPhases | 0/1/3 | AC:3/DC:0 | integer | charging stations number of phase(s) |
225| numberOfConnectors | | | integer \| integer[] | charging stations number of connector(s) |
226| useConnectorId0 | true/false | true | boolean | use connector id 0 definition from the charging station configuration template |
227| randomConnectors | true/false | false | boolean | randomize runtime connector id affectation from the connector id definition in charging station configuration template |
228| resetTime | | 60 | integer | seconds to wait before the charging stations come back at reset |
229| autoRegister | true/false | false | boolean | set charging stations as registered at boot notification for testing purpose |
230| autoReconnectMaxRetries | | -1 (unlimited) | integer | connection retries to the OCPP-J server |
231| reconnectExponentialDelay | true/false | false | boolean | connection delay retry to the OCPP-J server |
232| registrationMaxRetries | | -1 (unlimited) | integer | charging stations boot notification retries |
233| 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 |
234| amperageLimitationUnit | A/cA/dA/mA | A | string | charging stations amperage limit unit |
235| enableStatistics | true/false | false | boolean | enable charging stations statistics |
236| remoteAuthorization | true/false | true | boolean | enable RFID tags remote authorization |
237| beginEndMeterValues | true/false | false | boolean | enable Transaction.{Begin,End} MeterValues |
238| outOfOrderEndMeterValues | true/false | false | boolean | send Transaction.End MeterValues out of order. Need to relax OCPP specifications strict compliance ('ocppStrictCompliance' parameter) |
239| meteringPerTransaction | true/false | true | boolean | enable metering history on a per transaction basis |
240| transactionDataMeterValues | true/false | false | boolean | enable transaction data MeterValues at stop transaction |
241| stopTransactionsOnStopped | true/false | true | boolean | enable stop transactions on charging station stop |
242| mainVoltageMeterValues | true/false | true | boolean | include charging stations main voltage MeterValues on three phased charging stations |
243| phaseLineToLineVoltageMeterValues | true/false | false | boolean | include charging stations line to line voltage MeterValues on three phased charging stations |
244| customValueLimitationMeterValues | true/false | true | boolean | enable limitation on custom fluctuated value in MeterValues |
245| firmwareUpgrade | | {<br />"versionUpgrade": {<br />"step": 1<br />},<br />"reset": true<br />} | {<br />versionUpgrade?: {<br />patternGroup?: number;<br />step?: number;<br />};<br />reset?: boolean;<br />failureStatus?: 'DownloadFailed' \| 'InstallationFailed';<br />} | Configuration section for simulating firmware upgrade support. |
246| commandsSupport | | {<br />"incomingCommands": {},<br />"outgoingCommands": {}<br />} | {<br /> incomingCommands: Record<IncomingRequestCommand, boolean>;<br />outgoingCommands?: Record<RequestCommand, boolean>;<br />} | Configuration section for OCPP commands support. Empty section or subsections means all implemented OCPP commands are supported |
247| messageTriggerSupport | | {} | Record<MessageTrigger, boolean> | Configuration section for OCPP commands trigger support. Empty section means all implemented OCPP trigger commands are supported |
248| Configuration | | | ChargingStationOcppConfiguration | charging stations OCPP parameters configuration section |
249| AutomaticTransactionGenerator | | | AutomaticTransactionGeneratorConfiguration | charging stations ATG configuration section |
250| Connectors | | | Record<string, ConnectorStatus> | charging stations connectors configuration section |
251| Evses | | | Record<string, EvseTemplate> | charging stations EVSEs configuration section |
c94a349a 252
3e1dfe42 253#### Configuration section syntax example
c94a349a
JB		 254
255```json
0302da79 256 "Configuration": {
c94a349a
JB		 257 "configurationKey": [
258 ...
259 {
260 "key": "StandardKey",
261 "readonly": false,
262 "value": "StandardValue",
263 "visible": true,
264 "reboot": false
265 },
266 ...
267 {
268 "key": "VendorKey",
269 "readonly": false,
270 "value": "VendorValue",
271 "visible": false,
272 "reboot": true
273 },
274 ...
275 ]
276 }
277```
278
3e1dfe42 279#### AutomaticTransactionGenerator section syntax example
c94a349a 280
20f09970 281##### Type definition:
c72f6634
JB		 282
283```ts
284type AutomaticTransactionGeneratorConfiguration = {
66a7748d
JB		 285 enable: boolean
286 minDuration: number
287 maxDuration: number
288 minDelayBetweenTwoTransactions: number
289 maxDelayBetweenTwoTransactions: number
290 probabilityOfStart: number
291 stopAfterHours: number
46a830d2 292 stopAbsoluteDuration: boolean
66a7748d
JB		 293 requireAuthorize?: boolean
294 idTagDistribution?: 'random' | 'round-robin' | 'connector-affinity'
295}
c72f6634
JB		 296```
297
20f09970 298##### Example:
c72f6634 299
c94a349a 300```json
0302da79 301 "AutomaticTransactionGenerator": {
c94a349a
JB		 302 "enable": false,
303 "minDuration": 60,
304 "maxDuration": 80,
305 "minDelayBetweenTwoTransactions": 15,
306 "maxDelayBetweenTwoTransactions": 30,
307 "probabilityOfStart": 1,
308 "stopAfterHours": 0.3,
c72f6634
JB		 309 "requireAuthorize": true,
310 "idTagDistribution": "random"
c94a349a
JB		 311 }
312```
e7aeea18 313
3e1dfe42 314#### Connectors section syntax example
c94a349a
JB		 315
316```json
0302da79 317 "Connectors": {
c94a349a
JB		 318 "0": {},
319 "1": {
320 "bootStatus": "Available",
321 "MeterValues": [
9bd87386
JB		 322 ...
323 {
324 "unit": "W",
325 "measurand": "Power.Active.Import",
326 "phase": "L1-N",
327 "value": "5000",
328 "fluctuationPercent": "10"
329 },
c94a349a
JB		 330 ...
331 {
332 "unit": "A",
860ef183
JB		 333 "measurand": "Current.Import",
334 "minimum": "0.5"
c94a349a
JB		 335 },
336 ...
337 {
338 "unit": "Wh"
339 },
340 ...
341 ]
342 }
343 },
344```
345
3e1dfe42
JB		 346#### Evses section syntax example
347
348```json
349 "Evses": {
350 "0": {
351 "Connectors": {
352 "0": {}
353 }
354 },
355 "1": {
356 "Connectors": {
357 "1": {
358 "bootStatus": "Available",
359 "MeterValues": [
360 ...
361 {
362 "unit": "W",
363 "measurand": "Power.Active.Import",
364 "phase": "L1-N",
365 "value": "5000",
366 "fluctuationPercent": "10"
367 },
368 ...
369 {
370 "unit": "A",
371 "measurand": "Current.Import",
372 "minimum": "0.5"
373 },
374 ...
375 {
376 "unit": "Wh"
377 },
378 ...
379 ]
380 }
381 }
382 }
383 },
384```
385
1816f743
JB		 386### Charging station configuration
387
1c51fd1d 388**dist/assets/configurations/\<hashId\>.json**:
1816f743 389
a9ec2018 390The charging station configuration file is automatically generated at startup from the charging station configuration template file and is persistent.
1816f743
JB		 391
392The charging station configuration file content can be regenerated partially on matching charging station configuration template file changes. The charging station serial number is kept unchanged.
393
09810639 394#### stationInfo section (optional)
1816f743
JB		 395
396The syntax is similar to charging station configuration template with some added fields like the charging station id (name) and the 'Configuration' section removed.
397
10211789 398That section is overwritten on matching charging station configuration template file changes.
1816f743 399
10211789
JB		 400#### connectorsStatus section
401
402The syntax is similar to charging station configuration template 'Connectors' section with some added fields.
403
404That section is overwritten on matching charging station configuration template file changes.
1816f743 405
0aa874ce
JB		 406#### evsesStatus section
407
408The syntax is similar to charging station configuration template 'Evses' section with some added fields.
409
410That section is overwritten on matching charging station configuration template file changes.
411
09810639 412#### automaticTransactionGenerator section (optional)
3a28512c
JB		 413
414The syntax is similar to the charging station configuration template 'AutomaticTransactionGenerator' section.
415
10211789
JB		 416That section is overwritten on matching charging station configuration template file changes.
417
418#### automaticTransactionGeneratorStatuses section
419
420That section is not overwritten on matching charging station configuration template file changes.
421
09810639 422#### configurationKey section (optional)
10211789
JB		 423
424The syntax is similar to the charging station configuration template 'Configuration' section.
425
426That section is not overwritten on matching charging station configuration template file changes.
427
6f0ec20e
JB		 428## Docker
429
430In the [docker](./docker) folder:
431
81ed2a48 432```shell
6f0ec20e
JB		 433make
434```
435
673dceeb 436<!-- Or with the optional git submodules:
6f0ec20e 437
81ed2a48 438```shell
bfcad885 439make SUBMODULES_INIT=true
673dceeb 440``` -->
6f0ec20e
JB		 441
442## OCPP-J commands supported
c94a349a
JB		 443
444### Version 1.6
445
c56d42f1 446#### Core Profile
6f0ec20e 447
778f7924
JB		 448- :white_check_mark: Authorize
449- :white_check_mark: BootNotification
450- :white_check_mark: ChangeAvailability
451- :white_check_mark: ChangeConfiguration
452- :white_check_mark: ClearCache
91a7d3ea 453- :white_check_mark: DataTransfer
778f7924
JB		 454- :white_check_mark: GetConfiguration
455- :white_check_mark: Heartbeat
456- :white_check_mark: MeterValues
457- :white_check_mark: RemoteStartTransaction
458- :white_check_mark: RemoteStopTransaction
459- :white_check_mark: Reset
460- :white_check_mark: StartTransaction
461- :white_check_mark: StatusNotification
462- :white_check_mark: StopTransaction
463- :white_check_mark: UnlockConnector
6f0ec20e 464
c56d42f1 465#### Firmware Management Profile
6f0ec20e 466
b652b0c3 467- :white_check_mark: GetDiagnostics
d50343bd 468- :white_check_mark: DiagnosticsStatusNotification
c9a4f9ea
JB		 469- :white_check_mark: FirmwareStatusNotification
470- :white_check_mark: UpdateFirmware
6f0ec20e 471
c56d42f1 472#### Local Auth List Management Profile
6f0ec20e 473
9e1b12e4
JB		 474- :x: GetLocalListVersion
475- :x: SendLocalList
6f0ec20e 476
c56d42f1 477#### Reservation Profile
6f0ec20e 478
24578c31
JB		 479- :white_check_mark: CancelReservation
480- :white_check_mark: ReserveNow
6f0ec20e 481
c56d42f1 482#### Smart Charging Profile
6f0ec20e 483
778f7924 484- :white_check_mark: ClearChargingProfile
e1d9a0f4 485- :white_check_mark: GetCompositeSchedule
778f7924 486- :white_check_mark: SetChargingProfile
6f0ec20e 487
c56d42f1 488#### Remote Trigger Profile
6f0ec20e 489
802cfa13 490- :white_check_mark: TriggerMessage
7dde0b73 491
d4371252
JB		 492### Version 2.x.x
493
494#### Provisioning
495
496- :white_check_mark: BootNotification
497
bc950df1 498#### Authorization
d4371252
JB		 499
500- :white_check_mark: ClearCache
501
502#### Availability
503
504- :white_check_mark: StatusNotification
505- :white_check_mark: Heartbeat
506
7e1dc878
JB		 507## OCPP-J standard parameters supported
508
3a28512c 509All kind of OCPP parameters are supported in charging station configuration or charging station configuration template file. The list here mention the standard ones also handled automatically in the simulator.
7e1dc878
JB		 510
511### Version 1.6
512
c56d42f1 513#### Core Profile
7e1dc878
JB		 514
515- :white_check_mark: AuthorizeRemoteTxRequests (type: boolean) (units: -)
516- :x: ClockAlignedDataInterval (type: integer) (units: seconds)
291cb255 517- :white_check_mark: ConnectionTimeOut (type: integer) (units: seconds)
7e1dc878
JB		 518- :x: GetConfigurationMaxKeys (type: integer) (units: -)
519- :white_check_mark: HeartbeatInterval (type: integer) (units: seconds)
520- :x: LocalAuthorizeOffline (type: boolean) (units: -)
521- :x: LocalPreAuthorize (type: boolean) (units: -)
522- :x: MeterValuesAlignedData (type: CSL) (units: -)
523- :white_check_mark: MeterValuesSampledData (type: CSL) (units: -)
524- :white_check_mark: MeterValueSampleInterval (type: integer) (units: seconds)
525- :white_check_mark: NumberOfConnectors (type: integer) (units: -)
526- :x: ResetRetries (type: integer) (units: times)
527- :white_check_mark: ConnectorPhaseRotation (type: CSL) (units: -)
528- :x: StopTransactionOnEVSideDisconnect (type: boolean) (units: -)
529- :x: StopTransactionOnInvalidId (type: boolean) (units: -)
530- :x: StopTxnAlignedData (type: CSL) (units: -)
531- :x: StopTxnSampledData (type: CSL) (units: -)
36f6a92e 532- :white_check_mark: SupportedFeatureProfiles (type: CSL) (units: -)
7e1dc878
JB		 533- :x: TransactionMessageAttempts (type: integer) (units: times)
534- :x: TransactionMessageRetryInterval (type: integer) (units: seconds)
535- :x: UnlockConnectorOnEVSideDisconnect (type: boolean) (units: -)
36f6a92e 536- :white_check_mark: WebSocketPingInterval (type: integer) (units: seconds)
7e1dc878 537
c56d42f1 538#### Firmware Management Profile
7e1dc878 539
e7aeea18 540- _none_
7e1dc878 541
c56d42f1 542#### Local Auth List Management Profile
7e1dc878 543
36f6a92e 544- :white_check_mark: LocalAuthListEnabled (type: boolean) (units: -)
7e1dc878
JB		 545- :x: LocalAuthListMaxLength (type: integer) (units: -)
546- :x: SendLocalListMaxLength (type: integer) (units: -)
547
c56d42f1 548#### Reservation Profile
7e1dc878 549
66dd3447 550- :white_check_mark: ReserveConnectorZeroSupported (type: boolean) (units: -)
7e1dc878 551
c56d42f1 552#### Smart Charging Profile
7e1dc878
JB		 553
554- :x: ChargeProfileMaxStackLevel (type: integer) (units: -)
555- :x: ChargingScheduleAllowedChargingRateUnit (type: CSL) (units: -)
556- :x: ChargingScheduleMaxPeriods (type: integer) (units: -)
557- :x: MaxChargingProfilesInstalled (type: integer) (units: -)
558
c56d42f1 559#### Remote Trigger Profile
7e1dc878 560
e7aeea18 561- _none_
7e1dc878 562
d4371252
JB		 563### Version 2.x.x
564
e35d61ad 565## UI Protocol
32de5a57 566
6ca7a41d 567Protocol to control the simulator via a Websocket or HTTP server:
32de5a57 568
5d8bbc63
JB		 569```mermaid
570sequenceDiagram
571Client->>UI Server: request
572UI Server->>Client: response
738acbf7 573Note over UI Server,Client: HTTP or Websocket
5d8bbc63
JB		 574```
575
02cde3b7 576### Websocket Protocol
32de5a57 577
02cde3b7 578SRPC protocol over Websocket. PDU stands for 'Protocol Data Unit'.
32de5a57 579
03ebf4c1
JB		 580- Request:
581 [`uuid`, `ProcedureName`, `PDU`]
582 `uuid`: String uniquely representing this request
583 `ProcedureName`: The procedure to run on the simulator
584 `PDU`: The parameters for said procedure
32de5a57 585
03ebf4c1
JB		 586- Response:
587 [`uuid`, `PDU`]
588 `uuid`: String uniquely linking the response to the request
02cde3b7 589 `PDU`: Response parameters to requested procedure
32de5a57 590
c03dea88 591To learn how to use the Websocket protocol to pilot the simulator, an [Insomnia](https://insomnia.rest/) Websocket requests collection is available in [src/assets/ui-protocol](./src/assets/ui-protocol) directory.
97c19696 592
d3140adc 593#### Version 0.0.1
4e3ff94d 594
02cde3b7 595Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`.
4e3ff94d 596
d3140adc 597##### Procedures
32de5a57 598
a997fb63
JB		 599###### Simulator State
600
601- Request:
602 `ProcedureName`: 'simulatorState'
603 `PDU`: {}
604
605- Response:
606 `PDU`: {
df893e68 607 `status`: 'success' | 'failure',
a997fb63 608 `state`: {
df893e68 609 `version`: string,
74bb0739 610 `configuration`: ConfigurationData,
df893e68 611 `started`: boolean,
a997fb63
JB		 612 `templateStatistics`: Record<string, TemplateStatistics>
613 }
614 }
615
d3140adc 616###### Start Simulator
5612b691 617
03ebf4c1
JB		 618- Request:
619 `ProcedureName`: 'startSimulator'
620 `PDU`: {}
5612b691 621
03ebf4c1
JB		 622- Response:
623 `PDU`: {
6ca7a41d 624 `status`: 'success' | 'failure'
03ebf4c1 625 }
5612b691 626
d3140adc 627###### Stop Simulator
5612b691 628
03ebf4c1
JB		 629- Request:
630 `ProcedureName`: 'stopSimulator'
631 `PDU`: {}
5612b691 632
03ebf4c1
JB		 633- Response:
634 `PDU`: {
6ca7a41d
JB		 635 `status`: 'success' | 'failure'
636 }
637
638###### List Charging Station Templates
639
640- Request:
641 `ProcedureName`: 'listTemplates'
642 `PDU`: {}
643
644- Response:
645 `PDU`: {
646 `status`: 'success' | 'failure',
647 `templates`: string[]
648 }
649
650###### Add Charging Stations
651
652- Request:
653 `ProcedureName`: 'addChargingStations'
654 `PDU`: {
655 `template`: string,
95c7658e
JB		 656 `numberOfStations`: number,
657 `options?`: {
6eb63615 658 `supervisionUrls?`: string | string[],
9a08f38e 659 `persistentConfiguration?`: boolean,
52c58949 660 `autoStart?`: boolean,
43e04bb7
JB		 661 `autoRegister?`: boolean,
662 `enableStatistics?`: boolean,
1feac591
JB		 663 `ocppStrictCompliance?`: boolean,
664 `stopTransactionsOnStopped?`: boolean
95c7658e 665 }
6ca7a41d
JB		 666 }
667
668- Response:
669 `PDU`: {
5aeeae82 670 `status`: 'success' | 'failure',
3b09e788
JB		 671 `hashIdsSucceeded`: charging station unique identifier strings array (optional),
672 `hashIdsFailed`: charging station unique identifier strings array (optional)
03ebf4c1 673 }
5612b691 674
09e5a7a8
JB		 675###### Delete Charging Stations
676
677- Request:
678 `ProcedureName`: 'deleteChargingStations'
679 `PDU`: {
680 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations),
681 `deleteConfiguration?`: boolean
682 }
683
684- Response:
685 `PDU`: {
686 `status`: 'success' | 'failure',
687 `hashIdsSucceeded`: charging station unique identifier strings array,
688 `hashIdsFailed`: charging station unique identifier strings array (optional),
689 `responsesFailed`: failed responses payload array (optional)
690 }
691
1e534dab
JB		 692###### Set Charging Station Supervision Url
693
694- Request:
695 `ProcedureName`: 'setSupervisionUrl'
696 `PDU`: {
697 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations),
a66bbcfe 698 `url`: string
1e534dab
JB		 699 }
700
701- Response:
702 `PDU`: {
703 `status`: 'success' | 'failure',
704 `hashIdsSucceeded`: charging station unique identifier strings array,
705 `hashIdsFailed`: charging station unique identifier strings array (optional),
706 `responsesFailed`: failed responses payload array (optional)
707 }
708
a66bbcfe
JB		 709###### Performance Statistics
710
711- Request:
712 `ProcedureName`: 'performanceStatistics'
713 `PDU`: {}
714
715- Response:
716 `PDU`: {
df893e68 717 `status`: 'success' | 'failure',
a66bbcfe
JB		 718 `performanceStatistics`: Statistics[]
719 }
720
d3140adc 721###### List Charging Stations
32de5a57 722
03ebf4c1
JB		 723- Request:
724 `ProcedureName`: 'listChargingStations'
725 `PDU`: {}
32de5a57 726
03ebf4c1
JB		 727- Response:
728 `PDU`: {
6ca7a41d
JB		 729 `status`: 'success' | 'failure',
730 `chargingStations`: ChargingStationData[]
03ebf4c1 731 }
32de5a57 732
d3140adc 733###### Start Charging Station
80a3704c 734
03ebf4c1
JB		 735- Request:
736 `ProcedureName`: 'startChargingStation'
737 `PDU`: {
6ca7a41d 738 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations)
03ebf4c1 739 }
80a3704c 740
03ebf4c1
JB		 741- Response:
742 `PDU`: {
6ca7a41d
JB		 743 `status`: 'success' | 'failure',
744 `hashIdsSucceeded`: charging station unique identifier strings array,
745 `hashIdsFailed`: charging station unique identifier strings array (optional),
746 `responsesFailed`: failed responses payload array (optional)
03ebf4c1 747 }
80a3704c 748
d3140adc 749###### Stop Charging Station
80a3704c 750
03ebf4c1
JB		 751- Request:
752 `ProcedureName`: 'stopChargingStation'
753 `PDU`: {
6ca7a41d 754 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations)
03ebf4c1 755 }
80a3704c 756
03ebf4c1
JB		 757- Response:
758 `PDU`: {
6ca7a41d
JB		 759 `status`: 'success' | 'failure',
760 `hashIdsSucceeded`: charging station unique identifier strings array,
761 `hashIdsFailed`: charging station unique identifier strings array (optional),
762 `responsesFailed`: failed responses payload array (optional)
03ebf4c1 763 }
80a3704c 764
d3140adc 765###### Open Connection
e4df816e 766
03ebf4c1
JB		 767- Request:
768 `ProcedureName`: 'openConnection'
769 `PDU`: {
6ca7a41d 770 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations)
03ebf4c1 771 }
e4df816e 772
03ebf4c1
JB		 773- Response:
774 `PDU`: {
6ca7a41d
JB		 775 `status`: 'success' | 'failure',
776 `hashIdsSucceeded`: charging station unique identifier strings array,
777 `hashIdsFailed`: charging station unique identifier strings array (optional),
778 `responsesFailed`: failed responses payload array (optional)
03ebf4c1 779 }
e4df816e 780
d3140adc 781###### Close Connection
e4df816e 782
03ebf4c1
JB		 783- Request:
784 `ProcedureName`: 'closeConnection'
785 `PDU`: {
6ca7a41d 786 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations)
03ebf4c1
JB		 787 }
788
789- Response:
790 `PDU`: {
6ca7a41d
JB		 791 `status`: 'success' | 'failure',
792 `hashIdsSucceeded`: charging station unique identifier strings array,
793 `hashIdsFailed`: charging station unique identifier strings array (optional),
794 `responsesFailed`: failed responses payload array (optional)
853ed24a
JB		 795 }
796
797###### Start Automatic Transaction Generator
798
799- Request:
800 `ProcedureName`: 'startAutomaticTransactionGenerator'
801 `PDU`: {
6ca7a41d
JB		 802 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations),
803 `connectorIds`: connector id integer array (optional, default: all connectors)
853ed24a
JB		 804 }
805
806- Response:
807 `PDU`: {
6ca7a41d
JB		 808 `status`: 'success' | 'failure',
809 `hashIdsSucceeded`: charging station unique identifier strings array,
810 `hashIdsFailed`: charging station unique identifier strings array (optional),
811 `responsesFailed`: failed responses payload array (optional)
853ed24a
JB		 812 }
813
814###### Stop Automatic Transaction Generator
815
816- Request:
817 `ProcedureName`: 'stopAutomaticTransactionGenerator'
818 `PDU`: {
6ca7a41d
JB		 819 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations),
820 `connectorIds`: connector id integer array (optional, default: all connectors)
853ed24a
JB		 821 }
822
823- Response:
824 `PDU`: {
6ca7a41d
JB		 825 `status`: 'success' | 'failure',
826 `hashIdsSucceeded`: charging station unique identifier strings array,
827 `hashIdsFailed`: charging station unique identifier strings array (optional),
828 `responsesFailed`: failed responses payload array (optional)
03ebf4c1
JB		 829 }
830
91a7d3ea 831###### OCPP commands trigger
a9ed42b2 832
82cbef8d
JB		 833- Request:
834 `ProcedureName`: 'commandName' (the OCPP command name in camel case)
835 `PDU`: {
836 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations),
837 ...`commandPayload`
1e534dab 838 } (the OCPP command payload with some optional fields added to target the simulated charging stations)
10db00b2 839
82cbef8d 840- Response:
7f9d5299 841 `PDU`: {
82cbef8d
JB		 842 `status`: 'success' | 'failure',
843 `hashIdsSucceeded`: charging station unique identifier strings array,
844 `hashIdsFailed`: charging station unique identifier strings array (optional),
845 `responsesFailed`: failed responses payload array (optional)
1e534dab 846 }
10db00b2 847
91a7d3ea 848Examples:
10db00b2 849
91a7d3ea 850- **Start Transaction**
a9ed42b2 851
91a7d3ea
JB		 852 - Request:
853 `ProcedureName`: 'startTransaction'
854 `PDU`: {
6ca7a41d
JB		 855 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations),
856 `connectorId`: connector id integer,
857 `idTag`: RFID tag string
91a7d3ea
JB		 858 }
859
860 - Response:
861 `PDU`: {
6ca7a41d
JB		 862 `status`: 'success' | 'failure',
863 `hashIdsSucceeded`: charging station unique identifier strings array,
864 `hashIdsFailed`: charging station unique identifier strings array (optional),
865 `responsesFailed`: failed responses payload array (optional)
91a7d3ea
JB		 866 }
867
868- **Stop Transaction**
869
870 - Request:
871 `ProcedureName`: 'stopTransaction'
872 `PDU`: {
6ca7a41d
JB		 873 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations),
874 `transactionId`: transaction id integer
91a7d3ea
JB		 875 }
876
877 - Response:
878 `PDU`: {
1e534dab 879 `status`: 'success' | 'failure',
6ca7a41d
JB		 880 `hashIdsSucceeded`: charging station unique identifier strings array,
881 `hashIdsFailed`: charging station unique identifier strings array (optional),
882 `responsesFailed`: failed responses payload array (optional)
91a7d3ea
JB		 883 }
884
885- **Status Notification**
886
887 - Request:
82cbef8d 888 `ProcedureName`: 'statusNotification'
91a7d3ea 889 `PDU`: {
6ca7a41d
JB		 890 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations),
891 `connectorId`: connector id integer,
892 `errorCode`: connector error code,
893 `status`: connector status
91a7d3ea
JB		 894 }
895
896 - Response:
897 `PDU`: {
6ca7a41d
JB		 898 `status`: 'success' | 'failure',
899 `hashIdsSucceeded`: charging station unique identifier strings array,
900 `hashIdsFailed`: charging station unique identifier strings array (optional),
901 `responsesFailed`: failed responses payload array (optional)
91a7d3ea
JB		 902 }
903
904- **Heartbeat**
905
906 - Request:
82cbef8d 907 `ProcedureName`: 'heartbeat'
91a7d3ea 908 `PDU`: {
5aeeae82 909 `hashIds`: charging station unique identifier strings array (optional, default: all charging stations)
91a7d3ea
JB		 910 }
911
912 - Response:
913 `PDU`: {
6ca7a41d
JB		 914 `status`: 'success' | 'failure',
915 `hashIdsSucceeded`: charging station unique identifier strings array,
916 `hashIdsFailed`: charging station unique identifier strings array (optional),
917 `responsesFailed`: failed responses payload array (optional)
91a7d3ea 918 }
a9ed42b2 919
6ca7a41d
JB		 920### HTTP Protocol
921
922To learn how to use the HTTP protocol to pilot the simulator, an [Insomnia](https://insomnia.rest/) HTTP requests collection is available in [src/assets/ui-protocol](./src/assets/ui-protocol) directory.
923
251fff5c 924## Support, Feedback, Contributing
7dde0b73 925
f80e9e18 926This 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).
7dde0b73 927
251fff5c
JB		 928## Code of Conduct
929
f80e9e18 930We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](./CODE_OF_CONDUCT.md) at all times.
251fff5c
JB		 931
932## Licensing
933
f80e9e18 934Copyright 2020-2024 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).
Charging stations simulator mirror - https://github.com/SAP/e-mobility-charging-stations-simulator