EvseManager¶
Handwritten Documentation¶
The module EvseManager is a central module that manages one EVSE
(i.e. one connector to charge a car).
It may control multiple physical connectors if they are not usable at the same
time and share one connector id,
but one EvseManager always shows as one connector in OCPP for example. So in
general each connector should have a dedicated EvseManager module loaded.
The EvseManager contains the high level charging logic (Basic charging and HLC/SLAC interaction), collects all relevant data for the charging session (e.g. energy delivered during this charging session) and provides control over the charging port/session. For HLC it uses two helper protocol modules that it controls (SLAC and ISO15118).
Protocol modules such as OCPP or other APIs use EvseManagers to control the charging session and get all relevant data.
The following charge modes are supported:
AC charging: Basic Charging according to IEC61851/SAE J1772 and HLC according to ISO15118-2
DC charging: ISO15118-2 and DIN SPEC 70121
Additional features:
Autocharge support (PnC coming soon)
Seamlessly integrates into EVerest Energy Management
The lowest level IEC61851 state machine can be run on a dedicated microcontroller for improved electrical safety
Support for seperate AC and DC side metering in DC application
Typical connections¶
TODO: AC and DC module graphs and description
AC Configuration¶
Captive cable mode¶
For AC sockets with a connector lock in fleet or private installations, the
cable can be kept permanently locked in the socket as theft protection. Set
keep_cable_locked to true to enable this captive cable mode. It requires
a board_support driver that publishes ac_pp_ampacity on every change, also
outside of charging sessions, so that plug presence is known even in CP state A.
With the option enabled:
The connector locks whenever a plug is present, in every CP state including state A with no EV attached.
The lock is latched: losing plug presence without a preceding force unlock (for example the Proximity Pilot contact opening while the cable is pulled against the lock pin) does not release it.
The only way to release the cable is the
force_unlockcommand (for example an OCPPUnlockConnector) or disabling the option again. After a force unlock the connector stays unlocked until the cable is removed; the next plug insertion locks it again.It takes precedence over
lock_connector_in_state_bandunlock_when_deauthorized.The normal locking rules still apply on top. For example, after a force unlock with the cable left in the socket, the connector is locked again for the next charging session as usual, before the relays close.
Captive cable mode only applies to AC charging with a socket and a connected
connector lock. With charge_mode other than AC, without a connector
lock, or when the board_support driver reports a fixed attached cable
(IEC62196Type2Cable), the option is ignored with a warning and setting it at
runtime is rejected. The connector type is only known once the board_support
capabilities arrive, so the mode activates then; a runtime change made before
that is accepted and, if the driver reports a fixed cable, ignored with a
warning.
keep_cable_locked can be changed at runtime through the configuration
service and is applied immediately without a restart.
keep_cable_locked_lock_delay_ms (default 500) sets the delay in
milliseconds between detecting a plug and engaging the lock. It gives the plug
time to seat fully before the lock pin extends, so a lock triggered on the first
Proximity Pilot contact cannot jam a half-inserted plug. If the plug is pulled
back out within the delay, no lock is engaged. Set it to 0 to lock
immediately. The timer checks every 500 ms, so the effective delay is rounded up
to the next multiple of 500 ms.
DC Configuration¶
In DC applications, the EvseManager still has an AC side that behaves similar to a normal AC charger. The board_support module therefore still has to report AC capabilities which refer to the AC input of the AC/DC power supply. If an AC side RCD is used it also belongs to the board_support driver. An AC side power meter can be connected and it will be used for Energy management.
In addition, on the DC side the following hardware modules can be connected:
A DC powermeter: This will be used for billing purposes if present. If not connected, billing will fall back to the AC side power meter.
Isolation monitoring: This will be used to monitor isolation during CableCheck, PreCharge and CurrentDemand steps.
DC power supply: This is the AC/DC converter that actually charges the car.
Software over-voltage supervision is always active during DC charging. The configuration option
internal_over_voltage_duration_ms defines for how long the measured DC voltage
must exceed the negotiated limit before EvseManager raises MREC5OverVoltage.
Set it to 0 to trigger immediately once the threshold is crossed.
Published variables¶
session_events¶
EvseManager publishes the session_events variable whenever an event happens. It does not publish its internal state but merely events that happen that can be used to drive an state machine within another module.
Example: Write a simple module that lights up an LED if the evse is reserved. This module requires an EvseManager and subscribes to the session_events variable. Internally it has only two states: Reserved (LED on), NotReserved (LED off).
The state machine transitions are driven by the two events from EvseManager: ReservationStart and ReservationEnd.
All other events are ignored in this module as they are not needed.
powermeter¶
EvseManager republishes the power meter struct that if it has a powermeter connected. This struct should be used for OCPP and display purposes. It comes from the power meter that can be used for billing (DC side on DC, AC side on AC). If no powermeter is connected EvseManager will never publish this variable.
In DC charge mode, the car side power meter may publish its capabilities
(minimum measurable currents, e.g. due to calibration law accuracy limits).
These minimum currents are merged into the DC limits advertised to the EV over
ISO 15118 (ChargeParameterDiscovery and mid-session limit updates), but they
never affect internal power supply control such as cable check, precharge or
setpoint clamping.
Charging State Machine¶
stateDiagram-v2
direction TB
[*] --> Idle
%% Enable / Disable
Idle --> Disabled : disable
Disabled --> Idle : enable
%% Happy path
Idle --> WaitingForAuthentication : EV plugged in
WaitingForAuthentication --> PrepareCharging : Authorized
PrepareCharging --> Charging : Contactor close allowed
Charging --> StoppingCharging : Stop condition
StoppingCharging --> Finished : Transaction end
Finished --> Idle : EV unplugged
%% Early exit / Errors
WaitingForAuthentication --> Finished : Fatal error, stop requested, or EV unplugged
PrepareCharging --> StoppingCharging : Fatal error, deauth, or EV unplugged
%% Pauses
Charging --> ChargingPausedEV : EV moves to state B
ChargingPausedEV --> PrepareCharging : Power requested (BCB/Car)
ChargingPausedEV --> ChargingPausedEVSE : No power (AC BASIC)
ChargingPausedEV --> StoppingCharging : Deauth or unplugged
ChargingPausedEVSE --> PrepareCharging : Power available / Errors cleared
ChargingPausedEVSE --> StoppingCharging : Deauth or unplugged
%% Post-Stop logic
StoppingCharging --> ChargingPausedEV : EV-initiated pause
State Transitions¶
Basic Flow
Idle->WaitingForAuthentication: EV plugged in.WaitingForAuthentication->PrepareCharging: Authorized by EIM or PnC.WaitingForAuthentication->Finished: Fatal error, stop requested (e.g. viarequest_stop_transactionordisable), or EV unplugged.PrepareCharging->Charging: Contactor close allowed.Charging->StoppingCharging: Triggered by any Stop Condition (see below).StoppingCharging->Finished: No transaction, EV unplugged, or not authorized.Finished->Idle: EV unplugged.
Pause & Resume
ChargingPausedEV->PrepareCharging: BCB toggle orCarRequestedPower.ChargingPausedEV->ChargingPausedEVSE: No power available (AC BASIC only).ChargingPausedEVSE->PrepareCharging: Power available, no EVSE pause and errors cleared.StoppingCharging->ChargingPausedEV: EV-initiated pause after stop sequence.
ISO 15118-20 EVSE pause
An EVSE pause of an ISO 15118-20 session follows the control mode the EV selected:
Dynamic control mode: the SECC may only ask for a pause at 0 kW ([V2G20-2115]).
StoppingChargingramps the DC setpoint down at 100 A/s while the charge loop continues, requests the pause once the measured output current is below 1 A and keeps the setpoint at 0 A until the EV has paused. A ramp that does not reach 0 A within 35 s ends in the hard stop.Scheduled control mode: a pause may only be notified while the applied entry of the EV’s power profile is 0 kW ([V2G20-1198]). The pause is requested from
Charging, the HLC stack holds the notification back and publishespause_notifiedonce it has gone out; charging continues until then. A resume in between withdraws the request.
Once notified the EV has NotificationMaxDelay, fixed at 60 s ([V2G20-1850]), to
pause; StoppingCharging waits 65 s before the hard stop.
Stop Conditions
- The transition
Charging->StoppingChargingoccurs if: Fatal error
Deauthorization
EVSE pause requested (ISO 15118-20 scheduled control mode: once notified to the EV)
EV unplugged
IEC contactor opened
No power available (Immediate for AC BASIC; timeout for HLC).
Note
Transient helper states (T_step_EF, T_step_X1, and SwitchPhases) are omitted
for readability. Transitions passing through these are shown as direct arrows.
Session Events¶
These are the SessionEvent values published by the EvseManager with respect to the state machine
states and transitions.
State / Transition |
Event |
Trigger |
|---|---|---|
|
|
On entry |
|
|
When EVSE is enabled via |
|
|
On entry (new session) |
|
|
On entry |
|
|
When |
|
|
After auth is accepted, just before leaving state |
|
|
On entry |
|
|
On entry |
|
|
On entry |
|
|
When the set of pause reasons changes |
|
|
On entry |
|
|
On entry (if transaction was active) |
|
|
On entry (if transaction was active) |
|
|
When EV unplugs and |
Authentication¶
The Auth modules validates tokens and assignes tokens to EvseManagers, see Auth
documentation. It will call Authorize(id_tag, pnc) on EvseManager to
indicated that the EvseManager may start the charging session.
Auth module may revoke authorization (withdraw_authorization command) if
the charging session has not begun yet (typically due to timeout), but not once
charging has started.
Autocharge / PnC¶
Autocharge is fully supported, PnC support is coming soon and will use the same
logic. The car itself is a token provider that can provide an auth token to be
validated by the Auth system (see Auth documentation for more details).
EvseManager provides a token_provider interface for that purpose.
If external identification (EIM) is used in HLC (no PnC) then Autocharge is
enabled by connecting the token_provider interface to Auth module. When the
car sends its EVCCID in the HLC protocol it is converted to Autocharge format
and published as Auth token. It is based on the following specification:
To enable PnC the config option payment_enable_contract must be set to
true. If the car selects Contract instead of EIM PnC will be used instead of
Autocharge.
Some EVs use PnC for the authorization only and never enter the HLC charging
loop: they close the TCP connection or send a SessionStop afterwards and expect
basic charging. EvseManager keeps the 5 % duty cycle (or X1 after an X1 start)
and the session until the data link ends, which the ISO 15118 stack bounds with
V2G_SECC_Sequence_Timeout. The end of the link then switches to the nominal
duty cycle with the authorization kept: through X1 and E/F for a lost link
(D-LINK_ERROR, [V2G3-M07-04], [V2G3-M07-05]), through E/F for a
SessionStop(Terminate).
In X1 without a data link, e.g. once the matching retries are exhausted, a PnC
authorization switches to the nominal duty cycle directly.
Reservation¶
Reservation handling logic is implemented in the Auth module. If the Auth module wants to reserve a specific EvseManager (or cancel the reservation) it needs to call the reserve/cancel_reservation commands. EvseManager does not check reservation id against the token id when it should start charging, this must be handled in Auth module. EvseManager only needs to know whether it is reserved or not to emit an ReservatonStart/ReservationEnd event to notify other modules such as OCPP and API or e.g. switch on a specific LED signal on the charging port.
Energy Management¶
EvseManager seamlessly intergrates into the EVerest Energy Management. For further details refer to the documentation of the EnergyManager module.
EvseManager has a grid facing Energy interface which the energy tree uses to provide energy for the charging sessions. New energy needs to be provided on regular intervals (with a timeout).
If the supplied energy limits time out, EvseManager will stop charging. This prevents e.g. overload conditions when the network connection drops between the energy tree and EvseManager.
EvseManager will send out its wishes at regular intervals: It sends a
requested energy schedule into the energy tree that is merged from hardware
capabilities (as reported by board_support module), EvseManager module
configuration settings
(max_current, three_phases) and external limts (via set_external_limits
command) e.g. set by OCPP module.
Note that the set_external_limits should not be used by multiple modules,
as the last one always wins. If you have multiple sources of exernal limits
that you want to combine, add extra EnergyNode modules in the chain and
feed in limits via those.
The combined schedule sent to the energy tree is the minimum of all energy limits.
After traversing the energy tree the EnergyManager will use this information to assign limits (and a schedule) for this EvseManager and will call enforce_limits on the energy interface. These values will then be used to configure PWM/DC power supplies to actually charge the car and must not be confused with the original wishes that were sent to the energy tree.
The EvseManager will never assign energy to itself, it always requests energy from the energy manager and only charges if the energy manager responds with an assignment.
Limits in the energy object can be specified in ampere (per phase) and/or watt. Currently watt limits are unsupported, but it should behave according to that logic:
If both are specified also both limits will be applied, whichever is lower. With DC charging, ampere limits apply to the AC side and watt limits apply to both AC and DC side.
Energy Management: 1ph/3ph switching¶
EVerest has support for switching between 1ph and 3ph configurations during AC charging (e.g. for solar charging when sometimes charging with less then 4.2kW (6A*230V*3ph) if desired).
Be warned: Some vehicles (such as first generation of Renault Zoe) may be permanently damaged when switching from 1ph to 3ph during charging. Use at your own risk!
To use this feature several things need to be enabled:
In EvseManager, adjust two config options to your needs:
switch_3ph1ph_delay_s,switch_3ph1ph_cp_stateIn the BSP driver, set
supports_changing_phases_during_chargingto true in the reported capabilities. If your bsp hardware detects e.g. the Zoe, you can set that flag to false and publish updated capabilities any time.BSP driver capabilities: Also make sure that minimum phases are set to one and maximum phases to 3
BSP driver: make sure the
ac_switch_three_phases_while_chargingcommand is correctly implementedEnergyManager: Adjust
switch_3ph1ph_while_charging_mode,switch_3ph1ph_max_nr_of_switches_per_session,switch_3ph1ph_switch_limit_stickyness,switch_3ph1ph_power_hysteresis_W,switch_3ph1ph_time_hysteresis_sconfig options to your needs
If all of this is properly set up, the EnergyManager will drive the 1ph/3ph switching. In order to do so, it needs an (external) limit to be set. There are two options: The external limit can be in Watt (not in Ampere), even though we are AC charging. This is the preferred option as it gives the freedom to the EnergyManager to decide when to switch. The limit can come from OCPP schedule or e.g. via an additional EnergyNode.
The second option is to set a limit in Ampere and set a limitation on the number of phases (e.g. min_phase=1, max_phase=1). This will enforce switching and can be used to decide the switching time externally. EnergyManager does not have the freedom to make the choice in this case.
Take care especially with the power(watt) and time based hysteresis settings. They should be adjusted to the actual use case to avoid relays wearing due too a lot of switching cycles. Consider also to limit the maximum number of switching cycles per charging session.
DER (grid support) advertising¶
EvseManager exposes a set_der_available command that records, per EVSE, whether DER directive support
(a grid_support provider) is wired for that EVSE. This is a boot-time fact asserted by whichever module
provides the grid_support connection (the OCPP module is one such provider, asserting it from the presence
of a grid_support connection); the EV’s runtime DER capability is never sent here.
Whether DER is available and which ISO 15118-20 AC DER annex the EVSE speaks are separate axes. The annex is a
static per-EVSE choice made with the iso15118_der_flavor config option: NONE (the default, no AC DER
advertised), IEC (Annex L, AC_DER_IEC) or SAE (Annex M, AC_DER_SAE). The two annexes are
mutually exclusive per EVSE, so AC DER is opt-in even where DER availability is asserted.
When DER is available, the EVSE is export-capable (its hardware capabilities report a non-zero export current
and at least one export phase) and a flavor is configured, EvseManager folds that one AC DER energy transfer
mode into the set it advertises, never both. This is in addition to AC_BPT (advertised whenever
supported_iso_ac_bpt is set and the EVSE is export-capable). ISO 15118-20 has no combined AC_BPT_DER
service category, so “AC_BPT_DER supported” is conveyed by advertising both AC_BPT and the configured AC
DER mode as separate energy transfer modes; the EV selects one per session.
The flavor is matched exactly. An unrecognized value advertises no AC DER and logs a warning naming it, a branch normally unreachable because the manifest enum is validated at config load.
Configuring SAE is necessary but not sufficient. The Evse15118D20
module withholds the SAE DER limits until AC parameters carrying a positive nominal frequency and a positive
nominal voltage arrive, and the library then strips AC_DER_SAE from the advertised services. Neither value
has a fallback. It is self-correcting, since the limits are derived again on every change to the energy
services, the AC limits or the AC parameters, so an operator configuring SAE may briefly see no DER
service advertised.
The command returns NoHlc when no HLC is enabled for the EVSE (and does nothing), and Accepted otherwise.
Nominal grid frequency¶
ac_nominal_frequency (default 50) is passed to the HLC stack on every AC parameters update.
Informational for plain AC and AC_BPT. For AC DER it is advertised at ChargeParameterDiscovery as the
mandatory GridNominalFrequency the EV adopts as the frequency of the grid it is connecting to, so it must
match the installation.
It is not a denormalization base. The frequency-trip curves and the enter-service band are in absolute Hz and
are not scaled by it, unlike the voltage curves, which are a percentage of the nominal voltage. Changing it
from 50 to 60 moves no frequency threshold; the default grid code carries 50 Hz-family constants, so a
60 Hz operator supplying a real setup config must supply 60 Hz curve values with it.
It is also load-bearing: the SAE DER limits are only derived once a positive nominal frequency and a positive nominal voltage have arrived, as described above.
CP state in packet captures¶
debug_emit_cp_state_hpav_frames is a debugging aid, off by default. When set to true, the
EvseManager sends a HomePlug AV STP_CPSTATE.IND vendor MME (ethertype 0x88E1, ST/IoTecha OUI
00:80:E1) on debug_cp_state_hpav_device each time the CP state reported by the board support
module or the PWM duty cycle commanded to it changes. Wireshark decodes the frame natively as
CP State Change: B, 5%. The dsV2Gshark plugin additionally derives the X1/X2 sub-state and the
AC current limit from it and plots the CP state in its I/O graph. Capturing on the PLC modem
interface therefore shows CP transitions interleaved with the SLAC and ISO 15118 traffic.
The frame carries the CP state, the duty cycle in percent (100 while no PWM is generated, i.e. in
X1 and in states E and F), 1000 Hz while PWM is active and a nominal CP voltage for the state
(12, 9, 6 and 3 V for A to D, 0 V for E and F). It is sent unicast from the interface’s own MAC address to the local
modem address 00:b0:52:00:00:01, the destination used by the dSPACE reference captures shipped
with dsV2Gshark.
Sending raw Ethernet frames requires the CAP_NET_RAW capability. Without it the module logs a
warning at startup and charges normally, but no frames are sent. Grant it in the configuration:
evse_manager:
module: EvseManager
capabilities:
- CAP_NET_RAW
config_module:
debug_emit_cp_state_hpav_frames: true
debug_cp_state_hpav_device: eth1
Do not enable this option in production.
Error Handling¶
The control flow of this module can be influenced by the error implementation of its requirements. This section documents the side effects that can be caused by errors raised by a requirement.
This module subscribes to all errors of the following requirements:
evse_manager
evse_board_support
connector_lock
ac_rcd
isolation_monitor
power_supply_DC
powermeter (if the config option fail_on_powermeter_errors is set true)
A raised error can cause the EvseManager to stop the charging session and become inoperative. Charging is not possible until the error is cleared. If no charging session is currently running, it will prevent sessions from being started. If a charging session is currently running and an error is raised this will interrupt the charging session.
Almost all errors that are reported from the requirements of this module cause the EvseManager to become Inoperative until the error is cleared. The following sections provide an overview of the errors that do not cause the EvseManager to become Inoperative.
evse_manager¶
evse_manager/Inoperative
evse_manager/MREC11CableCheckFault
evse_board_support¶
evse_board_support/MREC3HighTemperature
evse_board_support/MREC18CableOverTempDerate
evse_board_support/VendorWarning
connector_lock¶
connector_lock/VendorWarning
ac_rcd¶
ac_rcd/VendorWarning
isolation_monitor¶
isolation_monitor/VendorWarning
power_supply_DC¶
power_supply_DC/VendorWarning
powermeter¶
Powermeter errors cause the EvseManager to become Inoperative, if fail_on_powermeter_errors is configured to true. If it is configured to false, errors from the powermeter will not cause the EvseManager to become Inoperative.
powermeter/CommunicationFault
powermeter/VendorError
Note that powermeter/VendorWarning is explicitly ignored by the EvseManager’s inoperative logic (similar to other VendorWarning errors)
and will not block charging even if fail_on_powermeter_errors is set to true. It should be used to signal non-fatal conditions such as
high temperature warnings from the powermeter.
When a charging session is stopped because of an error, the EvseManager differentiates between Emergency Shutdowns and Error Shutdowns. The severity of the error influences the type of the shudown. Emergency shutdowns are caused by errors with Severity::High and error shutdowns are caused by errors with Severity::Medium or Severity::Low.
In case of an Emergency Shutdown the EvseManager will immediately:
Signal PWM state F if HLC is not active
Turn off the PWM
Turn off the DC power supply in case of DC
Signal to open the contactor
In case of an Error Shutdown the EvseManager will:
Signal PWM state F if HLC is not active
Keep the PWM on if HLC is active
Turn off the DC power supply in case of DC
Signal to open the contactor
Report the error via HLC to the EV (if HLC active)