Skip to content

Commit bc0f86d

Browse files
author
Cédric Jimenez
committed
[readme] Add readme for install, build, usage and mqtt messaging
1 parent ecf6f1e commit bc0f86d

File tree

5 files changed

+321
-2
lines changed

5 files changed

+321
-2
lines changed

‎README.md‎

Lines changed: 321 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,321 @@
1-
# open-ocpp-simu
2-
Charge Point simulator based on Open OCPP library
1+
# Open OCPP simulator
2+
3+
Charge Point simulator environment based on [Open OCPP](https://github.com/c-jimenez/open-ocpp) library and [MQTT](https://mqtt.org/) protocol.
4+
5+
![Alt text](imgs/simu.png "Simulator environment")
6+
7+
The simulators contains 3 applications :
8+
9+
* chargepoint : Simulated Charge Point based on Open OCPP
10+
* launcher : Daemon which will add/remove/start/stop the simulated Charge Points instances
11+
* supervisor : User friendly HMI to monitor and configure the Charge Point simulators
12+
13+
These 3 applications are communicating using the MQTT protocol and the simulated Charge Point instances communicate also using OCPP protocol with a Central System.
14+
15+
## Table of contents
16+
- [Install and build](#install-and-build)
17+
- [Usage](#usage)
18+
- [Under the hood](#under-the-hood)
19+
20+
21+
## Install and build
22+
23+
### Pre-requisites
24+
25+
* Open OCPP library (see [Build and installation procedure](https://github.com/c-jimenez/open-ocpp#build))
26+
* Python 3.8 or greater with the following packages : kivy, paho-mqtt
27+
* [Mosquitto MQTT broker](https://mosquitto.org/) 2.0.11 or greater
28+
29+
For information, most of the development has been made on the following environment:
30+
31+
* Debian 11 (Bullseye)
32+
* gcc 10.2 and clang 11.0
33+
* Python 3.9
34+
* Mosquitto 2.0.11
35+
36+
On Debian the pre-requisites (except for Open OCPP) can be installed using the following commands:
37+
38+
```
39+
sudo apt install python3 mosquitto
40+
python3 -m pip install kivy paho-mqtt
41+
```
42+
43+
### Build options
44+
45+
The build is based on CMake, the following definitions must be passed to the CMake command to customize the build :
46+
47+
* **TARGET** : Allow to load the appropriate *CMakeLists_TARGET.txt* file
48+
* **BIN_DIR** : Output directory for the generated binaries
49+
* **CMAKE_BUILD_TYPE** : Can be set to either Debug or Release (Release build produces optimized stripped binaries)
50+
51+
Additionnaly, the **CMakeLists_Options.txt** contains several options that can be switched on/off.
52+
53+
An helper makefile is available at project's level to simplify the use of CMake. Just use the one of the following commands to build using gcc or gcc without cross compilation :
54+
55+
```make gcc-native``` or ```make clang-native``` or ```make gcc-native BUILD_TYPE=Debug``` or ```make clang-native BUILD_TYPE=Debug```
56+
57+
This makefile also contains the corresponding cleaning targets :
58+
59+
```make clean-gcc-native``` or ```make clean-clang-native```
60+
61+
62+
The build generates the following 2 executables :
63+
64+
* chargepoint
65+
* launcher
66+
67+
## Usage
68+
69+
The whole simulation environment is based on MQTT so the mosquitto broker must always be started to make it work.
70+
On Debian, the mosquitto broker can be started or stopped using th following commands:
71+
72+
```
73+
systemctl start mosquitto
74+
systemctl stop mosquitto
75+
```
76+
77+
It can also be started automatically at system's startup using the following commands :
78+
79+
```
80+
systemctl enable mosquitto
81+
systemctl disable mosquitto
82+
```
83+
84+
### Working directory
85+
86+
The working directory of the simulation environment must contain the following files :
87+
88+
* chargepoint
89+
* launcher
90+
* config.ini
91+
92+
The first 2 files are the binaries generated during the build. The last one is a configuration file which will be used as a template for the configuration of all the instances of the simulated Charge Points. You will find an example in the binaries directory alongside the 2 other files.
93+
94+
Then the **launcher** daemon will create a **charepoints** directory with a dedicated subdirectory for each simulated Charge Point instance and containing their persistent data.
95+
96+
### Starting the simulation
97+
98+
To start the simulation environment, use the following command :
99+
100+
```./launcher```
101+
102+
You must then see the following logs indicating that it has successfully connected to the MQTT broker and that it is wainting for commands :
103+
104+
```
105+
OCPP charge point simulator launcher
106+
Connecting to the broker (tcp://localhost:1883)...
107+
Subscribing to simulated charge point's topics...
108+
Subscribing to launcher's command topic...
109+
Ready!
110+
```
111+
112+
The **launcher** daemon must run to allow the **supervisor** to monitor and configure the simulated Charge Point instances.
113+
114+
To stop the **launcher**, just press Ctrl+C.
115+
116+
### Monitoring the simulation
117+
118+
To start the **supervisor**, use the following command from within the **src/supervisor** directory :
119+
120+
```python3 main.py```
121+
122+
The **supervisor** window will appear :
123+
124+
![Alt text](imgs/connect.png "Supervisor window")
125+
126+
Click on the "Connect!" button to connect to the MQTT broker and to the **launcher**.
127+
128+
You will now have access to the simulated Charge Point instances :
129+
130+
![Alt text](imgs/instances.png "Supervisor window")
131+
132+
On the left of the window is the list of the simulated Charge Point instances. After selecting an instance, the right part of the window will contain :
133+
134+
* The instance's information : name, registration status with the Central System, configuration
135+
* For each connector :
136+
- Id and OCPP status
137+
- Simulated inputs : car cable, car suspension, car consumption and id tag
138+
139+
On the bottom of the window are the command buttons :
140+
141+
* Add CP : instanciate a new simulated Charge Point
142+
* Remove CP : remove a simulated Charge Point from the simulation environment
143+
* Kill CP/Restart CP : kill/restart the simulated Charge Point instance
144+
* Save setup : save the current simulation environment into a JSON file
145+
* Load setup : load a previously save simulation environment from a JSON file
146+
147+
When adding a new simulated Charge Point, the following window will appear :
148+
149+
![Alt text](imgs/add.png "Supervisor window")
150+
151+
At this step you will configure the simulated Charge Point's behavior for current consumption and the URL of the Central System it must connect to.
152+
153+
**Warning** : These settings cannot be modified afterwards. You will have to remove the current Charge Point and add a new one to "modify" them.
154+
155+
### Ending the simulation
156+
157+
Once started, the simulated Charge Points will keep running even if the **launcher** and/or the **supervisor** are not running anymore.
158+
To take back control of the simulated Charge Points, just restart the **launcher** and the **supervisor** : they will appear into the list on the left side of the window.
159+
160+
You can then kill or remove the simulated Charge Points if needed.
161+
162+
## Under the hood
163+
164+
The whole simulation environment can be monitored and controled through MQTT messages.
165+
166+
Here is the MQTT topic tree of the simulation environment :
167+
168+
```
169+
cp_simu
170+
|--launcher
171+
| |-cmd
172+
| |-status
173+
|--cps
174+
| |-simu_cp_XXX
175+
| | |-status
176+
| | |-connectors
177+
| | | |-1
178+
| | | | |-car
179+
| | | | |-id_tag
180+
| | | | |-status
181+
| | | |-N
182+
| | | | |-car
183+
| | | | |-id_tag
184+
| | | | |-status
185+
| |-simu_cp_YYY
186+
| | |-status
187+
| | |-connectors
188+
| | | |-1
189+
| | | | |-car
190+
| | | | |-id_tag
191+
| | | | |-status
192+
| | | |-N
193+
| | | | |-car
194+
| | | | |-id_tag
195+
| | | | |-status
196+
```
197+
198+
The simulation environment takes advantage of 2 MQTT features :
199+
200+
* Retained messages : all the status messages are retained to allow to obtain the simulation environment status on connection
201+
* Will messages : the **launcher** and the simulated Charge Points both register a will message on their status topic so that it can be automatically updated when they stop after a crash or a user interruption
202+
203+
To remove a simulated Charge Point from the simulation environment, use the following protocol :
204+
205+
* Kill the simulated Charge Point instance through the **launcher** API
206+
* Remove the retained status of the simulated Charge Point and its connectors in the MQTT broker by sending a retained message with an empty payload on their status topics
207+
208+
### Launcher API
209+
210+
The **launcher** publishes its status as a retained message on the following topic : **cp_simu/launcher/status**.
211+
212+
The status can be either ```Alive``` or ```Dead```.
213+
214+
The **launcher** listens to the following topic : **cp_simu/launcher/cmd**.
215+
216+
#### Start command
217+
218+
The start command allow to instanciate and start one or more new simulated Charge Points.
219+
220+
Payload :
221+
222+
```
223+
{
224+
"type": "start",
225+
"charge_points": [
226+
{ "id": "simu_cp_XXX", "vendor": "Open OCPP", "model": "Simulated CP", "serial": "S/NABCD1234", "central_system": "ws://localhost:8080", "nb_connectors": 1, "nb_phases": 3, "max_current": 32, "max_current_per_connector": 16 },
227+
{ "id": "simu_cp_YYY", "vendor": "Open OCPP", "model": "Simulated CP", "serial": "S/NABCD5678", "central_system": "ws://localhost:8080", "nb_connectors": 2, "nb_phases": 1, "max_current": 32, "max_current_per_connector": 32 }
228+
]
229+
}
230+
```
231+
232+
#### Kill command
233+
234+
The kill command allow to kill one or more running simulated Charge Point instances.
235+
236+
Payload :
237+
238+
```
239+
{
240+
"type": "kill",
241+
"charge_points": [
242+
{ "id": "simu_cp_XXX" },
243+
{ "id": "simu_cp_YYY" }
244+
]
245+
}
246+
```
247+
248+
#### Restart command
249+
250+
The restart command allow to restart one or more previously killed simulated Charge Point instances.
251+
252+
Payload :
253+
254+
```
255+
{
256+
"type": "restart",
257+
"charge_points": [
258+
{ "id": "simu_cp_XXX", "vendor": "Open OCPP", "model": "Simulated CP", "serial": "S/NABCD1234", "central_system": "ws://localhost:8080", "nb_connectors": 1, "nb_phases": 3, "max_current": 32, "max_current_per_connector": 16 },
259+
{ "id": "simu_cp_YYY", "vendor": "Open OCPP", "model": "Simulated CP", "serial": "S/NABCD5678", "central_system": "ws://localhost:8080", "nb_connectors": 2, "nb_phases": 1, "max_current": 32, "max_current_per_connector": 32 }
260+
]
261+
}
262+
```
263+
264+
### Charge Point API
265+
266+
The simulated Charge Points publish their status as a retained message on the following topic : **cp_simu/cps/simu_cp_XXX/status**.
267+
268+
The status message has the following payload :
269+
270+
```
271+
{
272+
"pid":69672,
273+
"status":"Disconnected",
274+
"vendor":"Open OCPP",
275+
"model":"Simulated CP",
276+
"serial":"S/NABCD1234",
277+
"nb_phases":3,
278+
"max_setpoint":32.0,
279+
"central_system":"wss://127.0.0.1:9980/"
280+
}
281+
```
282+
283+
Each connector of the simulated Charge Point publishes its status as a retained message on the following topic : **cp_simu/cps/simu_cp_XXX/connectors/N/status** where **N** stands for the connector number.
284+
285+
The status message has the following payload :
286+
287+
```
288+
{
289+
"status":"Available",
290+
"id_tag":"",
291+
"max_setpoint":32.0,
292+
"ocpp_setpoint":32.0,
293+
"setpoint":0.0,
294+
"consumption":0.0,
295+
"car_consumption":0.0,
296+
"car_cable_capacity":0.0,
297+
"car_ready":true
298+
}
299+
```
300+
301+
Each connector of the simulated Charge Point are listening to the following topic to simulate interaction with a car : **cp_simu/cps/simu_cp_XXX/connectors/N/car** where **N** stands for the connector number.
302+
303+
The expected command payload is :
304+
305+
```
306+
{
307+
"cable": 32,
308+
"ready": true,
309+
"consumption": 10
310+
}
311+
```
312+
313+
Each connector of the simulated Charge Point are listening to the following topic to simulate interaction with a user resenting an RFID card : **cp_simu/cps/simu_cp_XXX/connectors/N/id_tag** where **N** stands for the connector number.
314+
315+
The expected command payload is :
316+
317+
```
318+
{
319+
"id": "ID_TAG"
320+
}
321+
```

‎imgs/add.png‎

34 KB
Loading

‎imgs/connect.png‎

16.9 KB
Loading

‎imgs/instances.png‎

42.3 KB
Loading

‎imgs/simu.png‎

22.3 KB
Loading

0 commit comments

Comments
 (0)