************************** How To: OCPP1.6 in EVerest ************************** .. note:: EVerest has an implementation of OCPP 1.6J and 2.0.1. This tutorial is about the 1.6 implementation. To get documentation about all implemented versions, see `the GitHub repository libocpp `_. EVerest provides a complete implementation of Open Charge Point Protocol (OCPP) 1.6J, supporting all feature profiles including Plug&Charge and the Security Extensions. The code of `libocpp` is at https://github.com/EVerest/libocpp This is a tutorial about how to setup and configure OCPP 1.6 in EVerest. This tutorial includes: - How the `libocpp` is integrated into `everest-core` - How to run EVerest with the default OCPP1.6J configuration connecting to SteVe - How to configure OCPP within EVerest - How to connect to different CSMS - What's relevant when configuring the OCPP module - Where to find and how to configure the OCPP logging .. _prerequisites: Prerequisites ============= If you're new to EVerest start with our :ref:`Quick Start Guide ` to get a simulation in EVerest running for the first time. It is important that you have set up the required docker containers for Mosquitto and SteVe, which we will use as an example CSMS. If you have done that successfully, you can move on with this tutorial. .. _integration: Integration of `libocpp` into `everest-core` ============================================ The actual OCPP1.6J implementation is located in https://github.com/EVerest/libocpp . This library is then used within the `OCPP `_ module of `everest-core`. The OCPP module handles the integration of OCPP into the EVerest framework. It registers callbacks that are then triggered by the `libocpp`, like a callback for a pausing charging or unlocking a connector. In addition the module calls the event handlers of the `libocpp` so that it can track the state of the charging station and trigger OCPP messages accordingly (e.g. MeterValues.req , StatusNotification.req). .. _run_with_steve: Run EVerest with SteVe ====================== EVerest's `everest-core` repository provides a configuration that you can use to run EVerest with OCPP. By default this configuration is connecting to the Open Source CSMS `SteVe `_. Simply run .. code-block:: bash ${EVEREST_WORKSPACE:?}/everest-core/build/run-scripts/run-sil-ocpp.sh to start EVerest with OCPP1.6J. Don't forget to add the default chargepoint id *cp001* to SteVe. .. _configure_ocpp: Configuring OCPP ================ In order to connect to a different CSMS, you have to modify the connection details within the ocpp configuration file. The ocpp config is a separate file in which all configuration keys of OCPP1.6 plus some internal parameters can be configured. You can specify the path to this configuration file inside the `everest-core` configuration file using the configuration parameter ChargePointConfigPath of the OCPP module within everest-core. This defaults to *ocpp-config.json*. If this path is relative the default path for the ocpp configuration dist/share/everest/modules/OCPP will be prepended. This here is an example for an ocpp configuration: .. code-block:: json { "Internal": { "ChargePointId": "cp001", "CentralSystemURI": "127.0.0.1:8180/steve/websocket/CentralSystemService/cp001", "ChargeBoxSerialNumber": "cp001", "ChargePointModel": "Yeti", "ChargePointVendor": "Pionix", "FirmwareVersion": "0.1" }, "Core": { "AuthorizeRemoteTxRequests": false, "ClockAlignedDataInterval": 900, "ConnectionTimeOut": 30, "ConnectorPhaseRotation": "0.RST,1.RST", "GetConfigurationMaxKeys": 100, "HeartbeatInterval": 86400, "LocalAuthorizeOffline": false, "LocalPreAuthorize": false, "MeterValuesAlignedData": "Energy.Active.Import.Register", "MeterValuesSampledData": "Energy.Active.Import.Register", "MeterValueSampleInterval": 60, "NumberOfConnectors": 1, "ResetRetries": 1, "StopTransactionOnEVSideDisconnect": true, "StopTransactionOnInvalidId": true, "StopTxnAlignedData": "Energy.Active.Import.Register", "StopTxnSampledData": "Energy.Active.Import.Register", "SupportedFeatureProfiles": "Core,FirmwareManagement,RemoteTrigger,Reservation,LocalAuthListManagement,SmartCharging", "TransactionMessageAttempts": 1, "TransactionMessageRetryInterval": 10, "UnlockConnectorOnEVSideDisconnect": true, "WebsocketPingInterval": 0 }, "FirmwareManagement": { "SupportedFileTransferProtocols": "FTP" }, "Security": { "SecurityProfile": 1, "CpoName": "Pionix", "AuthorizationKey": "DEADBEEFDEADBEEF" }, "LocalAuthListManagement": { "LocalAuthListEnabled": true, "LocalAuthListMaxLength": 42, "SendLocalListMaxLength": 42 }, "SmartCharging": { "ChargeProfileMaxStackLevel": 42, "ChargingScheduleAllowedChargingRateUnit": "Current,Power", "ChargingScheduleMaxPeriods": 42, "MaxChargingProfilesInstalled": 42 }, "PnC": { "ISO15118PnCEnabled": true, "ContractValidationOffline": true } } The configuration keys are split up into the feature profiles that are specified in OCPP1.6 plus the extra profiles *Internal*, *Security* and *PnC*. Here's a short overview of the purpose of each profile in the configuration file: - Internal: Used for internal configuration keys that are not specified in OCPP1.6 - Core: Includes Core configuration keys of OCPP1.6 - FirmwareManagement: Includes configuration keys that apply when the feature profile FirmwareManagement is implemented - Security: Includes configuration parameters that have been introduced within the OCPP1.6J Security Whitepaper - LocalAuthListManagement: Includes configuration parameters that apply when the feature profile LocalAuthListManagement is implemented - SmartCharging: Includes configuration parameters that apply when the feature profile SmartCharging is implemented - PnC: Used for Plug&Charge and includes configuration parameters that have been introduced within the OCPP1.6J Plug&Charge Whitepaper EVerest's `libocpp` supports all configuration parameters that are specified within OCPP 1.6. Despite that, it is possible to omit configuration parameters that are not required and it is even possible to omit a whole feature profile in the configuration file if it is not supported. This means that the configuration of the `libocpp` provides maximum flexibility and can be tailored to your specific charging station. .. _different_csms: Connect to a different CSMS =========================== To connect to a different CSMS, you have to modify the connection details of the ocpp configuration file. This includes the parameter *CentralSystemURI* and it might also include to change the parameters *AuthorizationKey* and *SecurityProfile*. Here's a short overview of the purpose of the parameters: - CentralSystemURI: Specifies the endpoint of the CSMS. - Must not include ws:// or wss:// (this will be prepended based on the SecurityProfile setting) - Must include the ChargePointId in the end - SecurityProfile: Specifies the SecurityProfile which defines type of transport layer connection between ChargePoint and CSMS - Can have the value 0, 1, 2 or 3 - SecurityProfile 0: Unsecure transport without Basic Authentication (ws://) - SecurityProfile 1: Unsecure transport with Basic Authentication (ws://) - SecurityProfile 2: TLS with Basic authentication (wss://) - SecurityProfile 3: TLS with client side certificates (wss://) - AuthorizationKey: Specifies the password used for HTTP Basic Authentication - Must be set if SecurityProfile is 1 or 2, can be omitted if SecurityProfile is 0 or 3 - Minimal length: 16 bytes Modify these parameters according to the connection requirements of the CSMS. Find all available configuration keys and their descriptions in `here `_ .. _configure_ocpp_everest: Configuring OCPP within EVerest =============================== To be able to follow the further explanations, you should be familiar with the configuration of EVerest modules. Take a look into :ref:`EVerest Module Concept ` for that. To configure the OCPP module of everest-core, find the available configuration parameters `in the manifest of the module `_. To start OCPP within EVerest, you have to load the OCPP module by including this in the everest configuration file. As you can see in the manifest of the OCPP module, it provides the following EVerest interfaces: - main: This interface is used to stop and restart the OCPP module - auth_validator: This interface is used to validate authorization requests against the CSMS (e.g. request from RFID-Reader). If an authorization is requested within EVerest, OCPP will validate this request using the OCPP Authorize message - auth_provider: This interface is used when OCPP requests authorization using a RemoteStartTransaction.req by the CSMS To summarize, the OCPP module provides (RemoteStartTransaction.req initiated by CSMS) and validates (Authorize.req initiated by ChargePoint) authorization requests. Take a look at the Auth module of everest-core to dive deeper into how authorization is handled within EVerest. In addtion, OCPP requires connection(s) to the following interfaces: - evse_manager: This connection is used to listen to events and to be able to control the EVSE - connector_zero_sink: This connection is used to report SmartCharging limits set for connector 0 - reservation: This connection is used to handle reservation requests of OCPP - auth: This connection is used to be able to listen to authorization requests and provide authorization requests - system: This connection is used to be able to handle system wide operations like diagnostics uploads, resets, etc. You have to make sure that OCPP is correctly wired with other modules within the everest configuration. This is how the configuration of OCPP and relevant modules could look like. .. code-block:: yaml active_modules: token_provider_rfid: module: JsDummyTokenProviderManual system: module: System ocpp: module: OCPP config_module: ChargePointConfigPath: ocpp-config.json connections: evse_manager: - module_id: evse_manager implementation_id: evse reservation: - module_id: auth implementation_id: reservation auth: - module_id: auth implementation_id: main system: - module_id: system implementation_id: main auth: module: Auth config_module: connection_timeout: 30 selection_algorithm: PlugEvents connections: token_provider: - module_id: ocpp implementation_id: auth_provider - module_id: token_provider_rfid implementation_id: main token_validator: - module_id: ocpp implementation_id: auth_validator evse_manager: - module_id: evse_manager implementation_id: evse Please note that this is not a complete configuration but it is only showing modules that are relevant for OCPP. Let's break this configuration down step by step. We can see the configuration of four modules within the everest configuration file (ocpp, system, auth, token_provider_rfid). The System and the JsDummyTokenProviderManual modules are simply loaded and need no configuration. For OCPP, the ChargePointConfigPath is specified and it has connections to - `evse_manager` (not present in this config for reasons of clarity) - `system` - `auth` - `main`: to provide and validate authorization requests - `reservation`: to handle reservations For the Auth module, the `connection_timeout` and the `selection_algorithm` is configured and it has connections to - `ocpp` - `auth_provider`: to handle RemoteStartTransaction.req - `auth_validator`: to trigger Authorize.req - `token_provider_rfid` - `evse_manager`: to provide authorization when provided token was validated This configuration will start EVerest with OCPP1.6. Authorization requests can be published by OCPP (using RemoteStartTransaction.req) or by a manual token provider (e.g. RFID-Reader). Authorization requests are received and forwarded by the Auth module. The only token validator that is configured is the OCPP module, which will use the Authorize.req as well as AuthorizationCache and LocalAuthListManagement to validate the requests. .. _logging: Logging ======= The implementation allows to log all OCPP messages in different formats The default logging path is /tmp/everest_ocpp_logs but can be set using the configuration parameter *MessageLogPath* of the OCPP module of everest-core. Within the ocpp configuration file, you can configure *LogMessages*, to enable or disable logging and *LogMessagesFormat* to specify to one or more log formats. For the latter, you can specify the following values: - console: Logs all OCPP messages - log: Logs all OCPP messages in a text file - html: Logs all OCPP messages using a html format (recommended) - session_logging: Logs all OCPP messages in html format into a path that is optionally provided by the EvseManager at the start of a session