The ocpp::v201 namespace exposes a ChargePoint class capable of client-side OCPP 2.0.1 communications. It enables charging stations to communicate with a cloud backend over a websocket for the remote control of charging stations and administration of charging sessions.
Note
For more information about the differences between versions of the Open Charge Point Protocol, please refer to the Open Charge Alliance's website.
The OCPP 2.0.1 implementation in libocpp is nearing completion, but there remain areas of active development. The OCA also does not currently plan to provide an official validation tool for all functionality within the protocol until the end of 2024. A high-level overview of supported functionality is provided below. For a more granular and up-to-date analysis of available OCPP 2.0.1 features in libocpp, please refer to the OCPP 2.0.1 Status document.
- Supported Certification Profiles
- CSMS Compatibility
- Integration with EVerest
- Standalone Integration
- OCPP 2.0.1 Use Cases in
libocpp - Quickstart for OCPP 2.0.1
- Building with FetchContent Instead of EDM
- Unit Testing
- Building the Doxygen Documentation
- Support for TPM Keys
- Support for
websocket++ - Support for
iface
Some optional OCPP 2.0.1 features are still being actively developed by the libocpp community. The following table shows which portions of the OCPP 2.0.1 implementation within libocpp are still being built out, broken down by OCPP 2.0.1 Certification Profile:
| OCPP 2.0.1 Functionality | Supported |
|---|---|
| Core | ✔️ Yes |
| Advanced Security | 🚧 In Progress |
| Local Auth List Management | ⌛ Planned |
| Smart Charging | 🚧 In Progress |
| Advanced Device Management | ⌛ Planned |
| Advanced User Interface | ⌛ Planned |
| Reservation | ⌛ Planned |
| ISO 15118 Support | 🚧 In Progress |
| Whitepapers & Application Notes | Supported |
|---|---|
| OCPP & California Pricing Requirements | 🚧 In Progress |
The ongoing development of OCPP 2.0.1 implementation is continuously tested against OCTT2 (OCPP Compliance Testing Tool 2), and has been tested against the following Charging Station Management Systems (CSMS):
| CSMS |
|---|
| ChargePoint |
| CitrineOS |
| Current |
| ihomer (Infuse CPMS) |
| Instituto Tecnológico de la Energía (ITE) HySGrid+ |
| MaEVe (Thoughtworks) |
| Monta |
| Open Charging Cloud (GraphDefined) |
| Switch EV |
| SWTCH Energy |
EVerest provides a simplified OCPP 2.0.1 integration path through its OCPP201 module.
When setting up a development environment (or building) EVerest through the everest-core project, a version of libocpp will be pulled down as a dependency. If you wish to use the OCPP201 module, you will want to defined your charging station's Device Model in the config.json file for the libocpp repository pulled in by everest-core as a dependency. This configuration will be incorporated into everest-core during the latter's build process.
Once everest-core has been built with your station-specific libocpp configuration, you can then specify and configure OCPP201 as a module in the runtime configuration of your EVerest deployment.
OCPP is a protocol that affects, controls, and monitors many areas of a charging station's operation. The libocpp library is just the messenger for this protocol. It is intended to provide mechanisms for connecting to and authenticating with a CSMS, sending and receiving the OCPP messages that govern behaviors in the standard, and to the track state required for a charging station to conform to the protocol all while minimizing hardware- or implementation-specific functionality.
The actual substance of how a charging station reacts to an OCPP command (such as ResetRequest) or when it should consider sending a command to the CSMS (such as NotifyChargingLimitRequest) is left to the rest of the charging station's systems. This is done by providing means of (a) registering callbacks that can be triggered by a libocpp ChargePoint in response to certain events and (b) reacting to various event handlers defined on a ChargePoint in other areas of the charging station's codebase.
Important
Integrating this library with your charging station requires both (a) defining callbacks that enable control of your station by libocpp and (b) calling libocpp event handlers in your charging station's systems in response to new events and data in order to keep libocpp up to date on station information.
Throughout this document and the libocpp codebase, the following conventions are followed:
-
A callback is a function providing the actual station-specific implementation of an OCPP command. It allows a
libocppChargePointto control other systems within a charging station. By convention, each callback on aChargePointhas a name suffixed with_callback(for instance,unlock_connector_callback). ACallbacksstructcontaining a complete set of desired callback implementations (as suitablestd::functioninstances) should be provided to a 2.0.1ChargePointat construction time. -
An event handler is a public function defined on a
ChargePointthat allows a charging station to update the state being tracked by theChargePointbased on new information (meter values, charging session events, etc.) and (indirectly) send messages to a CSMS. By convention, the names of event handlers on theChargePointare each prefixed withon_(for instance,on_meter_value).
The complete set of callbacks and event handlers defined on an OCPP 2.0.1 ChargePoint can be viewed in the latter's header file. Please use the Doxygen documentation as an additional source of information about the ChargePoint API.
| Callbacks | Description |
|---|---|
all_connectors_unavailable_callback |
Notifies that all connectors are unavailable. Used to handle charge availability requests and firmware updates. |
boot_notification_callback |
Callback to notify of a system boot |
clear_customer_information_callback |
Called to clear customer information based on passed in Customer Certificate, the IdToken for this request, and the Customer Identified that the request refers to. If IdToken is passed in will delete authorization cache entry from database. |
configure_network_connection_profile_callback |
Called to configure a network connection profile when none is configured. |
connector_effective_operative_status_changed_callback |
Notifies the user of liboccp that the Operative/Inoperative state of a specific EVSE has changed. |
cs_effective_operative_status_changed_callback |
Used to notify the user of libocpp that the Operative/Inoperative state of the charging station itself has changed. Will also call evse_effective_operative_status_changed_callback for each EVSE, and connector_effective_operative_status_changed_callback for each connector whose status has changed. |
data_transfer_callback |
Used to handle arbitrary data transfers. |
evse_effective_operative_status_changed_callback |
Notifies the user of libocpp that the Operative/Inoperative state of an EVSE has changed. If as a result the state of connectors changed as well, libocpp will additionally call the connector_effective_operative_status_changed_callback for each connector. |
get_customer_information_callback |
Returns human readable customer information based on the CertificateHashDataType, IdToken and Customer Identifier passed in. |
get_log_request_callback |
Callback to return logs |
is_reservation_for_token_callback |
Check if the current reservation for the given evse id is made for the id token / group id token. |
is_reset_allowed_callback |
Callback if reset is allowed. If evse_id has a value, reset only applies to the given evse id. If it has no value, applies to complete charging station. |
ocpp_messages_callback |
Callback to congfigure ocpp message logging. |
pause_charging_callback |
Used to request pausing of charging, the "connector" parameter instructing which connector/EVSE to pause. |
remote_start_transaction_callback |
Called when the request can be accepted. The boolean authorize_remote_start indicates if Authorize.req needs to follow or not |
reset_callback |
Performs a reset of the requested type |
security_event_callback |
Used to react to a security event callback. This callback is called only if the SecurityEvent occured internally within libocpp. Typically this callback is used to log security events in the security log. |
set_charging_profiles_callback |
Indicates when a charging profile is received and accepted. |
stop_transaction_callback |
Used to stop a transaction. Called when the idTagInfo.status of a StartTransaction.conf is not Accepted, when a RemoteStopTransaction.req is received, or when an UnlockConnector.req is received. |
time_sync_callback |
Called on boot notification if the TimeSource ControllerComponent contains Heartbeat. |
transaction_event_callback |
Called when a transaction_event was sent to the CSMS. |
transaction_event_response_callback |
Called when a transaction_event_response was received from the CSMS. |
unlock_connector_callback |
Used by libocpp to force unlock a connector |
update_firmware_request_callback |
Initiates a firmware update request. Triggers a security event notification if the certificate is Invalid or Revoked. |
validate_network_profile_callback |
Validates the submitted Network Profile. Is Rejected if: • No callback registered to validate network profile • CSMS attempted to set a network profile with a lower securityProfile • CSMS attempted to set a network profile that could not be validated • Network profile could not be written to the device model storage |
variable_changed_callback |
Called when a variable has been changed by the CSMS |
The complete set of event handlers defined on an OCPP 2.0.1 ChargePoint can be viewed in the latter's header file. Please use the Doxygen documentation as an additional source of information about the ChargePoint API.
To initialize the database where a ChargePoint will persist state, please use the provided SQLite database or implement your own storage drive.
For an in-depth guide to use cases from the OCPP 2.0.1 standard and how these use cases are implemented in libocpp, please see this guide.
This section walks you through how to sanity check that your libocpp development environment is set up effectively. The process will involve the following:
- Download
libocppfrom GitHub - Ensuring you've installed
libocpp's system dependencies - Running unit tests
This approach can also be used later in development for testing an actual station's device model and configuration is valid in the eyes of a CSMS.
You'll first want to download the source code for libocpp from this repository:
git clone https://github.com/EVerest/libocpp.gitTo be able to build libocpp, your system needs a compatible compiler, build tools, and development libraries and headers for several dependencies installed. For instance, on Debian GNU/Linux 11, these can be installed as follows:
sudo apt install build-essential \
cmake \
ninja-build \
libboost-all-dev \
libsqlite3-dev \
libssl-dev \
python3-pipWarning
OpenSSL version 3.0 or above is required.
GTest is required for building the test cases target.
To build the target and run the tests you can reference the script .ci/build-kit/install_and_test.sh.
The script allows the GitHub Actions runner to execute.
Local testing:
mkdir build
cmake -B build -DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX="./dist"
cd build
make -j$(nproc) installIn doc/build-with-fetchcontent you can find an example how to build libocpp with FetchContent instead of EDM.
Run any required tests from build/tests.
cmake -S . -B build
cmake --build build --target doxygen-ocppYou will find the generated Doxygen documentation at:
build/dist/docs/html/index.html
The main reference for the integration of libocpp for OCPP2.0.1 is the ocpp::v201::ChargePoint class defined in libocpp/include/ocpp/v201/charge_point.hpp.
In order to use the TPM keys, it is mandatory to use the default libwebsocket implementation.
The old websocket++ implementation has been deprecated. For enabling websocket++ support use the following cmake option:
cmake .. -DLIBOCPP_ENABLE_DEPRECATED_WEBSOCKETPP=ONIn order to connect through a custom network iface, a custom internal config variable 'IFace' can be used.
"Internal": {
"IFace" : "enp43s0"
}