From 6ca7a41d2c840661015f2006d395c3ab91a54c60 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= Date: Sun, 4 Feb 2024 16:11:01 +0100 Subject: [PATCH] docs: refine UI protocol section in README.md MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérôme Benoit --- README.md | 158 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 92 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 33044f10..f7ca9e41 100644 --- a/README.md +++ b/README.md @@ -498,7 +498,7 @@ All kind of OCPP parameters are supported in charging station configuration or c ## UI protocol -Protocol to control the simulator via a Websocket or HTTP server. +Protocol to control the simulator via a Websocket or HTTP server: ```mermaid sequenceDiagram @@ -507,10 +507,6 @@ UI Server->>Client: response Note over UI Server,Client: Transport protocol: HTTP, WebSocket ``` -### HTTP Protocol - -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. - ### Websocket Protocol SRPC protocol over Websocket. PDU stands for 'Protocol Data Unit'. @@ -542,7 +538,7 @@ Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. - Response: `PDU`: { - `status`: 'success' | 'failure' + `status`: 'success' | 'failure' } ###### Stop Simulator @@ -553,7 +549,33 @@ Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. - Response: `PDU`: { - `status`: 'success' | 'failure' + `status`: 'success' | 'failure' + } + +###### List Charging Station Templates + +- Request: + `ProcedureName`: 'listTemplates' + `PDU`: {} + +- Response: + `PDU`: { + `status`: 'success' | 'failure', + `templates`: string[] + } + +###### Add Charging Stations + +- Request: + `ProcedureName`: 'addChargingStations' + `PDU`: { + `template`: string, + `numberOfStations`: number + } + +- Response: + `PDU`: { + `status`: 'success' | 'failure' } ###### List Charging Stations @@ -564,8 +586,8 @@ Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. - Response: `PDU`: { - `status`: 'success' | 'failure', - `chargingStations`: ChargingStationData[] + `status`: 'success' | 'failure', + `chargingStations`: ChargingStationData[] } ###### Start Charging Station @@ -573,15 +595,15 @@ Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. - Request: `ProcedureName`: 'startChargingStation' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations) + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations) } - Response: `PDU`: { - `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional) - `responsesFailed`: failed responses payload array (optional) + `status`: 'success' | 'failure', + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } ###### Stop Charging Station @@ -589,15 +611,15 @@ Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. - Request: `ProcedureName`: 'stopChargingStation' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations) + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations) } - Response: `PDU`: { - `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional), - `responsesFailed`: failed responses payload array (optional) + `status`: 'success' | 'failure', + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } ###### Open Connection @@ -605,15 +627,15 @@ Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. - Request: `ProcedureName`: 'openConnection' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations) + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations) } - Response: `PDU`: { - `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional), - `responsesFailed`: failed responses payload array (optional) + `status`: 'success' | 'failure', + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } ###### Close Connection @@ -621,15 +643,15 @@ Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. - Request: `ProcedureName`: 'closeConnection' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations) + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations) } - Response: `PDU`: { - `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional), - `responsesFailed`: failed responses payload array (optional) + `status`: 'success' | 'failure', + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } ###### Start Automatic Transaction Generator @@ -637,16 +659,16 @@ Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. - Request: `ProcedureName`: 'startAutomaticTransactionGenerator' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), - `connectorIds`: connector id integer array (optional, default: all connectors) + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), + `connectorIds`: connector id integer array (optional, default: all connectors) } - Response: `PDU`: { - `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional), - `responsesFailed`: failed responses payload array (optional) + `status`: 'success' | 'failure', + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } ###### Stop Automatic Transaction Generator @@ -654,16 +676,16 @@ Set the Websocket header _Sec-Websocket-Protocol_ to `ui0.0.1`. - Request: `ProcedureName`: 'stopAutomaticTransactionGenerator' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), - `connectorIds`: connector id integer array (optional, default: all connectors) + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), + `connectorIds`: connector id integer array (optional, default: all connectors) } - Response: `PDU`: { - `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional), - `responsesFailed`: failed responses payload array (optional) + `status`: 'success' | 'failure', + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } ###### OCPP commands trigger @@ -690,17 +712,17 @@ Examples: - Request: `ProcedureName`: 'startTransaction' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), - `connectorId`: connector id integer, - `idTag`: RFID tag string + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), + `connectorId`: connector id integer, + `idTag`: RFID tag string } - Response: `PDU`: { - `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional), - `responsesFailed`: failed responses payload array (optional) + `status`: 'success' | 'failure', + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } - **Stop Transaction** @@ -708,16 +730,16 @@ Examples: - Request: `ProcedureName`: 'stopTransaction' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), - `transactionId`: transaction id integer + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), + `transactionId`: transaction id integer } - Response: `PDU`: { `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional), - `responsesFailed`: failed responses payload array (optional) + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } - **Status Notification** @@ -725,18 +747,18 @@ Examples: - Request: `ProcedureName`: 'statusNotification' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), - `connectorId`: connector id integer, - `errorCode`: connector error code, - `status`: connector status + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), + `connectorId`: connector id integer, + `errorCode`: connector error code, + `status`: connector status } - Response: `PDU`: { - `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional), - `responsesFailed`: failed responses payload array (optional) + `status`: 'success' | 'failure', + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } - **Heartbeat** @@ -744,17 +766,21 @@ Examples: - Request: `ProcedureName`: 'heartbeat' `PDU`: { - `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), + `hashIds`: charging station unique identifier strings array (optional, default: all charging stations), } - Response: `PDU`: { - `status`: 'success' | 'failure', - `hashIdsSucceeded`: charging station unique identifier strings array, - `hashIdsFailed`: charging station unique identifier strings array (optional), - `responsesFailed`: failed responses payload array (optional) + `status`: 'success' | 'failure', + `hashIdsSucceeded`: charging station unique identifier strings array, + `hashIdsFailed`: charging station unique identifier strings array (optional), + `responsesFailed`: failed responses payload array (optional) } +### HTTP Protocol + +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. + ## Support, Feedback, Contributing 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). -- 2.34.1