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