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