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