user guide
Follow the steps listed in README.md to get started. Below are some additional notes which may save you some time.
Installation of the HACS integration is a pre-requisite before you can install OCPP. However, it's worth noting that HACS brings a lot of baggage along with it, which is annoying, but this is the price to pay for using a 3rd party repository installer such as HACS. Having said that, once it's up and running, HACS stays out of the way unless you need to Redownload or Remove OCPP.
The 'baggage' referred to above, is every single repository available through HACS. As you can imagine, this adds up to a huge amount of data being downloaded from the Github servers, and they get upset about it, displaying Rate Limit error messages. You will see these error messages whenever you install HACS, but don't worry, the rate limit will reset after a few hours and HACS will be installed. It's worth remembering never to remove HACS unless there is no other way to achieve whatever it is you're wanting to do. Each time you reinstall, you'll be in for a wait of several hours so it's best avoided unless there is no other alternative.
The Central system identity shown above with a default of central can be anything you like up to a maximum of 20 characters. Whatever is entered in that field will be used as a device identifier in Home Assistant (HA), so it's probably best to avoid spaces and punctuation symbols, but otherwise, enter anything you like.
The Charge point identity shown above with a default of charger is a little different. Whatever you enter in that field will determine the prefix of all Charger entities added to Home Assistant (HA). My recommendation is that it's best left at the default of charger. If you put anything else in that field, it will be used as the prefix for all Charger entities added to HA during installation, however, new entities subsequently added in later version releases sometimes revert to the default prefix, regardless of what was entered during installation. So you end up with a mixture of different prefixes which can be avoided simply by leaving Charge point identity set to the default of charger.
Measurands (according to OCPP terminology) are actually metrics provided by the charger. Each charger supports a subset of the available metrics and for each one supported, a sensor entity is available in HA. Some of these sensor entities will give erroneous readings whilst others give no readings at all. Sensor entities not supported by the charger will show as Unknown if you try to create a sensor entity for them. Below is a table of the metrics I've found useful for the Wallbox Pulsar Plus. Tables for other chargers will follow as contributions come in from owners of each supported charger.
OCPP integration can automatically detect supported measurands. However, some chargers have faulty firmware that causes the detection mechanism to fail. For such chargers, it is possible to disable automatic measurand detection and manually set the measurands to those supported by the charger. When set manually, selected measurands are not checked for compatibility with the charger and are requested from it. See below for OCPP compliance notes and charger-specific instructions in supported devices.
For chargers with multiple connectors (outlets), the OCPP integration will create one device per connector, named charger Connector 1, charger Connector 2 etc. All measurands and other entities (buttons, numbers, switches, diagnostics sensors) that are connector-specific per the OCPP standard will be found on these devices.
Your charger exposes a connector status sensor:
- Single-connector:
sensor.<charger_id>_status_connector - Multi-connector:
sensor.<charger_id>_connector_<connector_number>_status_connector
For OCPP 1.6, the sensor can show these values:
- Available – No EV is connected; the connector is free.
- Preparing – EV is connected and/or authenticated but charging hasn’t started yet (handshake, cable lock, internal checks).
- Charging – Energy is being delivered.
- SuspendedEV – The EV has paused energy transfer (e.g., target SoC reached, schedule, thermal limit).
- SuspendedEVSE – The charger has paused energy transfer (e.g., power limit, smart charging profile, grid signal).
- Finishing – Charging has stopped, but the session isn’t fully closed yet (typically waiting for the cable to be unplugged).
- Reserved – The connector is reserved (via ReserveNow); only the intended user/ID may start. This is not supported by the OCPP integration yet.
- Unavailable – Intentionally set out of service (e.g., ChangeAvailability(Inoperative)) or temporarily not usable. (Entities remain available in Home Assistant.)
- Faulted – A fault prevents charging (e.g., ground fault, over-temp, lock error). Check the sensor errorCode for details.
Note
In OCPP 1.6, connectorId = 0 (station level) only uses Available, Unavailable, or Faulted.
In OCPP 2.0.1, connector status is simplified to Available / Occupied / Reserved / Unavailable / Faulted; “Preparing/Finishing” are reflected in TransactionEvent rather than as connector statuses.
If your integration shows extra attributes on the connector status sensor like availability_change or availability_pending, they indicate that a status change (e.g., after ChangeAvailability) has been accepted or scheduled and will take effect once current conditions allow (e.g., after an active session ends).
-
Availability (charger-level) switch
Sets the entire charger toUnavailable(station-level). All idle connectors switch toUnavailableimmediately. Any connector with an ongoing session is marked as scheduled and will switch toUnavailableafter the session ends. -
Availability (per-connector) switches
Set a specific connector toUnavailable. If that connector currently has an ongoing session, the change is scheduled and will take effect once the session ends. -
Charge Control switch
Turning off ends the ongoing charging session (remote stop). The connector typically transitions toFinishingand then back to its normal idle state once the cable is unplugged. Turning the switch on again resets the session metrics; the charger returns to its previous state (this does not force a new session to start).
-
Energy Active Import RegisterorEnergy Session(they give the same readings) -
Power Active Import(instantaneous charging power) -
Current Offered(maximum charging current available) -
Voltage(single phase models only, doesn't work on 3-phase) -
Frequency(single phase models only, doesn't work on 3-phase) -
Time Session(elapsed time from start of charging session)
-
Status Connector(shows the current state of available/preparing/charging/finishing/suspended etc) -
Stop Reason(reason the charging session was stopped)
Charge Control-
Availability(must be set to ON before EV is plugged in) -
Maximum Current(sets maximum charging current available) Reset
-
Current.Import(instantaneous current flow to EV) -
Energy.Active.Import.Register(active energy imported from the grid) -
Power.Active.Import(instantaneous active power imported by EV) -
Voltage(instantaneous AC RMS supply voltage)
-
Current Offered(maximum charging current available) -
Time Session(elapsed time from start of charging session) -
Temperature(internal charger temperature)
-
Status Connector(shows the current state of available/preparing/charging/finishing/suspended etc) -
Stop Reason(reason the charging session was stopped)
Charge Control-
Availability(OFF when something causes a problem or during a reboot etc) -
Maximum Current(sets maximum charging current available) Reset
Comments below relate to Grizzl-E firmware version 5.633, tested Oct-Nov 2022.
The Grizzl-E updates these metrics every 30s during charging sessions:
-
Current Import(current flowing into EV) -
Power Active Import(power flowing into EV) -
Energy Active Import Register(cumulative energy supplied to EV during charging session. Resets to zero at start of each session) -
Time Session(elapsed time from start of charging session)
-
Status Connector(current charger state: available/preparing/charging/finishing/suspended etc) -
Stop Reason(reason the charging session was stopped) -
Latency Pong(elapsed time for charger's response to internet ping. Good for diagnosing connectivity issues. Usually less than 1000ms) -
Version Firmware(charger firmware version and build)
-
Charge Control(User switches to ON to start charging session, once charger is in Preparing state. Can be automated in HA - see this comment in Issue #442 for details) -
Availability(ON when charger is idle. OFF during active charging session, or when something causes a problem) -
Maximum Current(sets maximum charging current available. Reverts to value set by charger's internal DIP switch following reboots; tweak slider to reload)
-
Energy Active Import Register(cumulative energy supplied to EV during charging session. Resets to zero at start of each session) -
Energy Active Import Interval(in case you need the energy spent in total for the current charging session) -
Power Active Import(instantaneous charging power) Current Import-
Time Session(elapsed time from start of charging session)
-
Status Connector(shows the current state of available/preparing/charging/finishing/suspended etc) -
Stop Reason(reason the charging session was stopped)
Charge Control-
Availability(must be set to ON before EV is plugged in) -
Maximum Current(sets maximum charging current available) Reset
Current Import-
Current Offered(may be limited by the settings on the charger itself, check the EVO app) -
Energy Session(charge for present/last session - kWh) -
Power Active Import(active charging power - kW) -
Temperature(internal temperature - degrees C) -
Time Session(duration of active/last charging session) -
Voltage(seems to report a little higher than expected)
There are several other metrics too, I'm not sure what they mean, and also Export variants of some of the Import entities, but they seem to always be zero for me.
-
Status Connector(Available, Preparing, Charging, etc)
There are many other diagnostic entities about the features, ids, model, firmware etc, not sure if they'd be much practical use.
-
Availability(turning off switches the halo from flashing blue to constant red) Charge Control-
Maximum Current(ifCurrent Offereddoesn't reach this when charging, raise the current to the max in the EVO app itself, connect via Bluetooth) -
Reset(reboot the charger) -
Unlock(I think this will unlock the charging cable, if permanent lock is enabled from the app)
ABB Terra AC firmware 1.8.21 and earlier versions fail to respond correctly when OCPP measurands are automatically detected by the OCPP integration. As of this writing, ABB has been notified, but no corresponding firmware fix is available. As a result, users must configure measurands manually. See the suggested ABB Terra AC configuration in supported devices.
Grizzl-E firmware 5.x has a few OCPP-compliance defects, including responding to certain OCPP server messages with invalid JSON. Firmware 3.x.x on chargers such as the Mini Connect and Ultimate does not seem to have these issues. Symptoms of this problem include repeated reboots of the charger. By editing the OCPP server source code, one can avoid these problematic messages and obtain useful charger behaviour. ChargeLabs (the company working on the Grizzl-E firmware) expects to release version 6 of the firmware in early 2023, which may fix these problems.
The workaround consists of:
- checking the Skip OCPP schema validation checkbox during OCPP server configuration
- commenting-out several lines in
/config/custom_components/ocpp/api.pyand adding a few default values to the OCPP server source code. Details are in this comment in Issue #442