Skip to content

Commit a0301e1

Browse files
corneliusclaussencorneliusclaussen
committed
Documentation for EvseManager and YetiDriver
Signed-off-by: Cornelius Claussen <cc@pionix.de>
1 parent fe52847 commit a0301e1

File tree

2 files changed

+348
-1
lines changed

2 files changed

+348
-1
lines changed

‎docs/modules/EvseManager.rst

+174-1
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,177 @@
55
Additional documentation
66
************************
77

8-
Some example documentation for the module ``EvseManager``.
8+
The module ``EvseManager`` is a central module that manages one EVSE
9+
(i.e. one connector to charge a car).
10+
It may control multiple physical connectors if they are not usable at the same
11+
time and share one connector id,
12+
but one EvseManager always shows as one connector in OCPP for example. So in
13+
general each connector should have a dedicated EvseManager module loaded.
14+
15+
The EvseManager contains the high level charging logic (Basic charging and
16+
HLC/SLAC interaction), collects all relevant data for the charging session
17+
(e.g. energy delivered during this charging session) and provides control over
18+
the charging port/session. For HLC it uses two helper protocol modules that it
19+
controls (SLAC and ISO15118).
20+
21+
Protocol modules such as OCPP or other APIs use EvseManagers to control the
22+
charging session and get all relevant data.
23+
24+
The following charge modes are supported:
25+
26+
* AC charging: Basic Charging according to IEC61851/SAE J1772 and HLC according
27+
to ISO15118-2
28+
* DC charging: ISO15118-2 and DIN SPEC 70121
29+
30+
Additional features:
31+
32+
* Autocharge support (PnC coming soon)
33+
* Seamlessly integrates into EVerest Energy Management
34+
* The lowest level IEC61851 state machine can be run on a dedicated
35+
microcontroller for improved electrical safety
36+
* Support for seperate AC and DC side metering in DC application
37+
38+
Typical connections
39+
===================
40+
41+
TODO: AC and DC module graphs and description
42+
43+
AC Configuration
44+
----------------
45+
46+
DC Configuration
47+
----------------
48+
49+
In DC applications, the EvseManager still has an AC side that behaves similar
50+
to a normal AC charger. The board_support module therefore still has to report
51+
AC capabilities which refer to the AC input of the AC/DC power supply. If an AC
52+
side RCD is used it also belongs to the board_support driver.
53+
An AC side power meter can be connected and it will be used for Energy
54+
management.
55+
56+
In addition, on the DC side the following hardware modules can be connected:
57+
58+
* A DC powermeter: This will be used for billing purposes if present.
59+
If not connected, billing will fall back to the AC side power meter.
60+
* Isolation monitoring: This will be used to monitor isolation during
61+
CableCheck, PreCharge and CurrentDemand steps.
62+
* DC power supply: This is the AC/DC converter that actually charges the car.
63+
64+
Published variables
65+
===================
66+
67+
session_events
68+
--------------
69+
70+
EvseManager publishes the session_events variable whenever an event happens.
71+
It does not publish its internal state but merely events that happen that can
72+
be used to drive an state machine within another module.
73+
74+
Example: Write a simple module that lights up an LED if the evse is reserved.
75+
This module requires an EvseManager and subscribes to the session_events
76+
variable. Internally it has only two states: Reserved (LED on), NotReserved
77+
(LED off).
78+
79+
The state machine transitions are driven by the two events from EvseManager:
80+
ReservationStart and ReservationEnd.
81+
82+
All other events are ignored in this module as they are not needed.
83+
84+
powermeter
85+
----------
86+
87+
EvseManager republishes the power meter struct that if it has a powermeter
88+
connected. This struct should be used for OCPP and display purposes. It comes
89+
from the power meter that can be used for billing (DC side on DC, AC side on
90+
AC). If no powermeter is connected EvseManager will never publish this
91+
variable.
92+
93+
94+
Authentication
95+
==============
96+
97+
The Auth modules validates tokens and assignes tokens to EvseManagers, see Auth
98+
documentation. It will call ``Authorize(id_tag, pnc)`` on EvseManager to
99+
indicated that the EvseManager may start the charging session.
100+
Auth module may revoke authorization (``withdraw_authorization`` command) if
101+
the charging session has not begun yet (typically due to timeout), but not once
102+
charging has started.
103+
104+
105+
Autocharge / PnC
106+
----------------
107+
108+
Autocharge is fully supported, PnC support is coming soon and will use the same
109+
logic. The car itself is a token provider that can provide an auth token to be
110+
validated by the Auth system (see Auth documentation for more details).
111+
EvseManager provides a ``token_provider`` interface for that purpose.
112+
113+
If external identification (EIM) is used in HLC (no PnC) then Autocharge is
114+
enabled by connecting the ``token_provider`` interface to Auth module. When the
115+
car sends its EVCCID in the HLC protocol it is converted to Autocharge format
116+
and published as Auth token. It is based on the following specification:
117+
118+
https://github.com/openfastchargingalliance/openfastchargingalliance/blob/master/autocharge-final.pdf
119+
120+
To enable PnC the config option ``payment_enable_contract`` must be set to
121+
true. If the car selects Contract instead of EIM PnC will be used instead of
122+
Autocharge.
123+
124+
Reservation
125+
-----------
126+
127+
Reservation handling logic is implemented in the Auth module. If the Auth
128+
module wants to reserve a specific EvseManager (or cancel the reservation) it
129+
needs to call the reserve/cancel_reservation commands. EvseManager does not
130+
check reservation id against the token id when it should start charging, this
131+
must be handled in Auth module. EvseManager only needs to know whether it is
132+
reserved or not to emit an ReservatonStart/ReservationEnd event to notify other
133+
modules such as OCPP and API or e.g. switch on a specific LED signal on the
134+
charging port.
135+
136+
Energy Management
137+
=================
138+
139+
EvseManager seamlessly intergrates into the EVerest Energy Management.
140+
For further details refer to the documentation of the EnergyManager module.
141+
142+
EvseManager has a grid facing Energy interface which the energy tree uses to
143+
provide energy for the charging sessions. New energy needs to be provided on
144+
regular intervals (with a timeout).
145+
146+
If the supplied energy limits time out, EvseManager will stop charging.
147+
This prevents e.g. overload conditions when the network connection drops
148+
between the energy tree and EvseManager.
149+
150+
EvseManager will send out its wishes at regular intervals: It sends a
151+
requested energy schedule into the energy tree that is merged from hardware
152+
capabilities (as reported by board_support module), EvseManager module
153+
configuration settings
154+
(max_current, three_phases) and external limts (via ``set_local_max_current``
155+
command) e.g. set by OCPP module.
156+
157+
The combined schedule sent to the energy tree is the minimum of all energy
158+
limits.
159+
160+
After traversing the energy tree the EnergyManager will use this information
161+
to assign limits (and a schedule)
162+
for this EvseManager and will call enforce_limits on the energy interface.
163+
These values will then be used
164+
to configure PWM/DC power supplies to actually charge the car and must not
165+
be confused with the original wishes that
166+
were sent to the energy tree.
167+
168+
The EvseManager will never assign energy to itself, it always requests energy
169+
from the energy manager and only charges
170+
if the energy manager responds with an assignment.
171+
172+
The ``set_local_max_current`` command will be extended to schedules (and not
173+
just one instantaneous limit) soon to fully
174+
support schedules from OCPP smart charging profile.
175+
176+
Limits in the energy object can be specified in ampere (per phase) and/or watt.
177+
Currently watt limits are unsupported, but it should behave according to that
178+
logic:
179+
180+
If both are specified also both limits will be applied, whichever is lower. With DC charging, ampere limits apply
181+
to the AC side and watt limits apply to both AC and DC side.

‎docs/modules/YetiDriver.rst

+174
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
.. This file will be included in the autogenerated module documentation.
2+
Please keep the headline and insert your documentation below.
3+
4+
************************
5+
Additional documentation
6+
************************
7+
8+
The module ``YetiDriver`` is a board support driver for Pionix Yeti Power
9+
Board.
10+
11+
Communication between the Yeti microcontroller and this driver module
12+
=====================================================================
13+
14+
The hardware connection between Yeti and Yak (the board running EVerest and
15+
this module) is 3.3V TTL UART plus 2 GPIOs (one to reset the microcontroller
16+
from Linux and one to wakeup Linux from the microcontroller, which is
17+
currrently unused).
18+
19+
The default configuration is 115200 bps 8N1.
20+
21+
Protocol
22+
========
23+
24+
EVerest can send commands to Yeti and Yeti publishes data and events back
25+
to EVerest. The packets are defined with protobuf to serialize the C structs
26+
into a binary representation that is transferred over the serial wire in a
27+
stream:
28+
29+
https://developers.google.com/protocol-buffers
30+
31+
To be able to split the stream back into packets all data is encoded using COBS
32+
before it is transmitted on the UART:
33+
34+
https://en.wikipedia.org/wiki/Consistent_Overhead_Byte_Stuffing
35+
36+
COBS
37+
----
38+
39+
COBS is implemented in ``yeti_comms/evSerial.cpp``. Whenever a new packet
40+
was extracted from the stream ``handlePacket()`` is called to decode protobuf
41+
and generate the corresponding signals.
42+
Other parts of the module subscribe to these signals to handle the incoming
43+
packets.
44+
45+
For TX ``linkWrite`` encodes the packet with COBS and outputs it to the UART.
46+
47+
Protobuf
48+
--------
49+
50+
The actual packet definitions are located under ``yeti_comms/protobuf``.
51+
52+
``hi2lo.proto`` contains all messages that can be sent from EVerest to Yeti
53+
while ``lo2hi.proto`` defines all messages that Yeti sends to EVerest.
54+
55+
Refer to these files for an up to date definition as they may change
56+
frequently.
57+
58+
To generate the C code nanopb is used:
59+
60+
``nanopb_generator -I . -D . *.proto``
61+
62+
The output should also be manually copied to Yeti Firmware to ensure the same
63+
definition is used on both sides when making changes.
64+
65+
EVerest to Yeti
66+
---------------
67+
68+
The most important commands that EVerest sends to Yeti are the following:
69+
70+
``SetControlMode(mode)``: Yeti firmware can operate in different modes:
71+
72+
``Mode NONE = 0``: In this mode Yeti does not allow control over UART. It will
73+
still send telemetry data. Yeti operates as a standalone non-smart AC charger
74+
and EVerest does not need to be running.
75+
76+
``HIGH = 1``: In this mode high level control is possible.
77+
Yeti operates as a standalone AC charger and EVerest does not need to be
78+
running, but it does allow certain control such as setMaxCurrent from EVerest.
79+
This mode is not documented here as it is not used by EVerest anymore.
80+
81+
``LOW = 2``: In this mode Yeti allows low level control. Yeti does not act
82+
as a standalone charger, it needs to be controlled by EVerest. It does however
83+
still run the very basic state machine to follow the car's states A-F and
84+
switches relais on and off accordingly. This ensures that basic electrical
85+
safety remains within the microcontroller and not within EVerest.
86+
It generates more human readable events from state A-F transitions.
87+
88+
PWM is directly controlled from EVerest in this mode.
89+
90+
Low control mode:
91+
_________________
92+
93+
The following commands describe the Low level control mode only:
94+
95+
``AllowPowerOn(bool)``: Inform yeti that it is allowed to switch on the power
96+
relais/contactors to the car on (true) or must switch off now (false). The
97+
final decision remains with Yeti in case of power on, it should only power on
98+
after all other requirements are met (such as RCD current is below limit,
99+
car is in CP state B etc). On power off Yeti must switch off immediately.
100+
101+
``SetPWM(mode, duty_cycle)``: mode 0: OFF (+12V), 1: ON (PWM with duty_cycle),
102+
2: F (-12V). Yeti sets the PWM immediately.
103+
104+
105+
Other commands for all modes:
106+
_____________________________
107+
108+
``FirmwareUpdate(bool)``: Send true to reboot Yeti into ROM boot loader.
109+
After that stm32flash tool can be used to flash any firmware binary to it.
110+
Note that this is a dev kit and for a real product this needs to be implemented
111+
differently.
112+
113+
``KeepAliveHi``: Send this packet to Yeti at 1Hz. If no heartbeat is received
114+
for a longer amount of time Yeti may fall back to control mode NONE to act
115+
as a stand alone emergency backup charger or go into failure mode (can be
116+
modified in the firmware).
117+
118+
``SetThreePhases``: true: switches to 3ph on next switch on, else single phase.
119+
Only works on hardware configurations with dual relais. Does not switch while
120+
charging session is running, Yeti firmware will delay the change to the next
121+
charging session.
122+
123+
``EnableRCD``: enable or disable the onboard RCD. Some cars generate quite high
124+
residual current spikes and may not charge properly if RCD is enabled.
125+
126+
``Enable``: Enable CP output
127+
128+
``Disable``: Disable CP output (goes to floating/high impedance)
129+
130+
``Reset``: Reset yeti firmware
131+
132+
``Replug``: Initiate special virtual replug sequence without starting a new
133+
charging session.
134+
135+
``SwitchThreePhasesWhileCharging``: Change between 1 and 3 phases while
136+
charging. This is currently not implemented in yeti firmware and will need
137+
special precautions because some cars may be destroyed by switching from one
138+
phase to three phase while charging is running (E.g. Zoe 1)
139+
140+
``ForceUnlock``: Force unlock motor lock now regardless of state.
141+
142+
Yeti to EVerest
143+
---------------
144+
145+
The following messages are relevant for LOW control mode:
146+
147+
``Event``: This is the most important message from Yeti. It will send an event
148+
on CP transitions:
149+
150+
* ``CAR_PLUGGED_IN``: CP State A -> B
151+
* ``CAR_REQUESTED_POWER``: CP State B->C or B->D
152+
* ``POWER_ON``: Relais switched on succesfully (i.e. after mirror contact check)
153+
* ``POWER_OFF``: Relais switched off succesfully
154+
* ``CAR_REQUESTED_STOP_POWER``: CP State C/D -> any other state
155+
* ``CAR_UNPLUGGED``: any other state -> A
156+
* ``ERROR_E``: any other state -> E
157+
* ``ERROR_DF``: Car diode failure detected
158+
* ``ERROR_RELAIS``: Relais error (mirror contact check failed)
159+
* ``ERROR_RCD``:: RCD over current event
160+
* ``ERROR_VENTILATION_NOT_AVAILABLE``: Car requested D but no ventilation available
161+
* ``ERROR_OVER_CURRENT``: Yeti detected quick over current on AC lines
162+
* ``ENTER_BCD``: any other state -> B/C/D. Used to start SLAC
163+
* ``LEAVE_BCD``: B/C/D -> any other state. Stops SLAC.
164+
* ``PERMANENT_FAULT``: Permanent fault that cannot be cleared by unplugging car
165+
* ``EVSE_REPLUG_STARTED``: Replugging sequence started
166+
* ``EVSE_REPLUG_FINISHED``: Replugging sequence completed
167+
168+
``PowerMeter``: Contains all data from the power measurement, sent at roughly
169+
1Hz
170+
171+
``KeepAliveLo``: Yeti sends this at 1Hz to keep up connection.
172+
173+
``ResetDone``: Sent once on boot of yeti firmware.
174+

0 commit comments

Comments
 (0)