Control Connector Availability During a Firmware Update¶
This guide shows how an update mechanism decides whether a firmware update takes the connectors out of service,
how it can defer that decision until the downloaded package has been inspected, and how an update is installed
while the charging station has no connection to the CSMS. It is written for anyone integrating an update mechanism
with EVerest through the system_API module, as an API client of the
EVerest System API.
Without any of this, every firmware update delivered over OCPP makes the OCPP module disable all connectors, wait for running transactions to finish, and only then tell the update mechanism that the install may proceed. That is the right behaviour for a system image that reboots the station. It is unnecessary for a package that only replaces configuration, images or other content, and operators who ship both kinds want to choose per update.
How the pieces fit together¶
A firmware update is a conversation between three parties, with the system_API module connecting the OCPP
module to the update mechanism over MQTT. Its topics are below everest_api/1/system/<module_id>/, where
<module_id> is the module’s id in the EVerest configuration.
The CSMS sends
UpdateFirmware(orSignedUpdateFirmwarein OCPP 1.6 with the Security Whitepaper).The OCPP module forwards the request to the API client as an
e2m/update_firmwarerequest, sends each reported status to the CSMS as aFirmwareStatusNotification, and manages connector availability for the install.The API client downloads and installs the package. It reports progress by publishing to
m2e/firmware_update_statusand waits fore2m/allow_firmware_installationbefore it installs anything that needs the connectors out of service.
Each m2e/firmware_update_status message carries the status itself, the request id (-1 for an unsigned OCPP
1.6 update) and an optional firmware_update_metadata object with one field:
{
"firmware_update_status": "Downloaded",
"request_id": -1,
"firmware_update_metadata": {"disable_connectors_during_install": false}
}
The OCPP module reads disable_connectors_during_install at two points of the cycle. The first is the status
right before the install, which is Downloaded for an unsigned update and SignatureVerified for a signed
one. The second is InstallScheduled.
Status |
Flag unset |
Flag |
Flag |
|---|---|---|---|
|
Connectors are disabled |
Connectors are disabled |
Connectors stay available |
|
No change |
Connectors are disabled |
No change |
Any other status |
No change |
No change |
No change |
“Connectors are disabled” means the OCPP module makes every connector without a running transaction unavailable,
queues the same change for connectors that are still charging so it applies once their transaction ends, and
sends allow_firmware_installation to the API client once no connector is available any more. That message is
sent once per update cycle, and only for an install that disables the connectors: connectors that become
unavailable for another reason earlier in the cycle, during the download for example, do not trigger it. The
connectors are restored to their stored availability when the cycle ends with Installed,
InstallationFailed, InstallVerificationFailed, InvalidSignature, DownloadFailed or Idle. A
status after Idle starts a new cycle, and so does a newly accepted update request (in OCPP 1.6 the
Downloading status of an unsigned update); connectors that an update which never reported its end left
unavailable are restored at that point. A change the CSMS scheduled with ChangeAvailability for a connector
that is still charging is queued alongside the one for the update: it applies when the transaction ends, whether
or not the update cycle has ended by then.
Connector availability never depends on the CSMS connection. The connectors are disabled and
allow_firmware_installation is sent as soon as the status arrives, whether or not the BootNotification has
been accepted. Only the FirmwareStatusNotification message to the CSMS waits for registration; the latest
status is sent once the CSMS accepts the station.
Keep the connectors available for an update¶
When the API client already knows that a package does not need the connectors out of service, it reports the
status before the install with the flag set to false.
Unsigned update (OCPP 1.6 without the Security Whitepaper):
{
"firmware_update_status": "Downloaded",
"request_id": -1,
"firmware_update_metadata": {"disable_connectors_during_install": false}
}
Signed update (OCPP 1.6 Security Whitepaper, OCPP 2.0.1 and 2.1):
{
"firmware_update_status": "SignatureVerified",
"request_id": 42,
"firmware_update_metadata": {"disable_connectors_during_install": false}
}
The OCPP module forwards the status to the CSMS and leaves the connectors as they are. The API client does not
receive allow_firmware_installation in this case and continues with Installing and Installed on its
own.
Decide after inspecting the package¶
Often the API client only knows what kind of package it has once it has downloaded it and read its manifest. The cycle then looks like this:
Report
DownloadedorSignatureVerifiedwith the flag set tofalse. The connectors stay available while the package is inspected.Inspect the package. If it can be installed without taking the connectors out of service, continue with
Installing; the rest of this list does not apply.Otherwise report
InstallScheduledwith the flag set totrue:{ "firmware_update_status": "InstallScheduled", "request_id": 42, "firmware_update_metadata": {"disable_connectors_during_install": true} }
The OCPP module disables the idle connectors at once and queues the change for connectors with a running transaction.
Wait for
e2m/allow_firmware_installation. It arrives as soon as every connector is unavailable, which may be immediately or after the last transaction has finished.Install the package and report
InstallingandInstalledas usual.
An InstallScheduled status without the flag, or with the flag set to false, changes nothing. That keeps
existing update mechanisms that report InstallScheduled for a timed install behaving as before.
Repeating InstallScheduled with the flag does not send allow_firmware_installation a second time within
the same cycle. A new cycle starts when the CSMS sends the next UpdateFirmware request that the API client
accepts.
Install while the station is offline¶
Nothing extra is needed. Because connector availability and allow_firmware_installation do not wait for the
CSMS, an API client that has the package already (for example from a local USB stick, or because the connection
was lost after the download) can report the statuses above and will be told to install even when the station is
unregistered. The FirmwareStatusNotification for the latest status is held by the OCPP module and sent once
the CSMS accepts the BootNotification. A session that ends while the station is offline counts as ended for the
install, although the CSMS has not confirmed the stop of its transaction yet.
For an update the CSMS did not request, OCPP 2.x cannot tell from a request whether the package is signed. The
status right before the install is then Downloaded when the status is reported with request id -1 and
SignatureVerified for any other request id. Set the flag explicitly to decide otherwise.