Josev API ========= This is an introductory document for any Charging Station (CS) manufacturer that would like to start integrating Josev to their system. Introduction ------------ Josev is a stack of software including ISO15118, OCPP 2.0.1, and Slac. The goal is to enable CS manufacturers an easy integration of these protocols to their final product with minimal development effort. Integrating Josev ----------------- In order to enable Josev’s services integration, there is the need to exchange specific information that allows a seamless charging session from start to the end of it. Information like EVSE charge parameters, EVSE power relays state and CP state are a few examples of such data. This exchange of data is made by means of an MQTT Broker ruled by a specific contract (API). An MQTT broker will have to be spawned in order to establish a way of communicating between the CS and Josev (think of the broker like the mailing service in charge of transporting and delivering messages from one end to the other). The messages between the charging station (CS) and Josev are exchanged through specific channels called “topics”. The naming of the topics follow the rule sender/receiver. The aforementioned naming convention is better understood with the following example, illustrated in the following sequence and its diagram: a) Once Josev starts, in order to initiate its services, the CS status and limits must be known first. To get this info, Josev will publish a request message on the josev/cs topic while the CS will be listening (subscribed) to it. b) After the CS receives and process the request, it will reply to Josev with a response but it will be sent on a different topic, in this case cs/josev and Josev will be subscribed to it. c) In case any status or limit changes on the CS, an update message will be sent on the same topic as the response. .. image:: images/cs_status_and_limits_sequence_diag.svg :width: 400 :alt: CS status and limits example message exchange The same approach is followed for the rest of the messages. +----------------------+----------+----------------+-----------------+ | Message Name | Type | Sub (listener) | Pub (publisher) | +======================+==========+================+=================+ | cs_status_and_limits | request | cs | josev | +----------------------+----------+----------------+-----------------+ | cs_status_and_limits | response | josev | cs | +----------------------+----------+----------------+-----------------+ | cs_status_and_limits | update | josev | cs | +----------------------+----------+----------------+-----------------+ After having a look at Table 1 you might have noticed there are certain messages that do not allow the "request" type message, hence the following clarification: - Request: is issued in order to force an answer from the counter party. - Update: is used as a form of "push" notification even without a previous request. Message structure ----------------- The format of the messages is in JSON and the schemas for each message type ensure this contract is strictly respected. https://github.com/SwitchEV/josev-api/tree/main/schemas Continuing the example with cs_status_and_limits, the sequence of payloads exchanged would be: a) Request by Josev (on topic josev/cs):: { "id": "6c1f594a-3dfe-409b-8251-bceb68ad0812", "name": "cs_status_and_limits", "type": "request", "data": {} } b) Response from CS (on topic cs/josev):: { "id": "6c1f594a-3dfe-409b-8251-bceb68ad0812", "name": "cs_status_and_limits", "type": "response", "data": { "GB*SEV*E123456789" : { "ac": { "max_current": {"l1": 16.0, "l2": 16.0, "l3": 16.0}, "nominal_voltage": 230, "rcd_error": False } } } Map of OCPP sections and relevant API messages ---------------------------------------------- The following table aims to give the CS manufacturer a guide of what are the API messages that need to be supported for the different sections of the OCPP specification use cases. +------------------+----------------------------------+-----------------------------------------------------+ | OCPP Section | Name | Relevant API message for the CS manufacturer | +==================+==================================+=====================================================+ | A | Security | | +------------------+----------------------------------+-----------------------------------------------------+ | B | Provisioning | :doc:`external_messages/service_status` | | | | | | | | :doc:`external_messages/websocket_status` | | | | | | | | :doc:`external_messages/boot_status` | | | | | | | | :doc:`external_messages/device_model` | | | | | | | | :doc:`external_messages/reset` | +------------------+----------------------------------+-----------------------------------------------------+ | C | Authorization | :doc:`external_messages/authorization` | | | | | | | | | +------------------+----------------------------------+-----------------------------------------------------+ | D | Local Auth List Mgmt | Not implemented yet | +------------------+----------------------------------+-----------------------------------------------------+ | E | Transactions | :doc:`external_messages/authorization` | | | | | | | | :doc:`external_messages/cable_info` | | | | | | | | :doc:`external_messages/cp_status` | | | | | | | | :doc:`external_messages/stop_charging` | | | | | | | | :doc:`external_messages/parking_bay` | +------------------+----------------------------------+-----------------------------------------------------+ | F | Remote Control | | | | | :doc:`external_messages/cs_connector` | | | | | | | | :doc:`external_messages/boot_status` | | | | | | | | :doc:`external_messages/stop_charging` | | | | | | | | :doc:`external_messages/logs_status` | | | | | | | | :doc:`external_messages/cp_status` | +------------------+----------------------------------+-----------------------------------------------------+ | G | Availability | :doc:`external_messages/change_availability` | | | | | | | | :doc:`external_messages/cs_connector` | | | | | | | | :doc:`external_messages/hardware_fault` | +------------------+----------------------------------+-----------------------------------------------------+ | H | Reservation | Not implemented yet | +------------------+----------------------------------+-----------------------------------------------------+ | I | Tariff and Cost | Not implemented yet | +------------------+----------------------------------+-----------------------------------------------------+ | J | Meter Values | :doc:`external_messages/meter_values` | +------------------+----------------------------------+-----------------------------------------------------+ | K | Smart Charging | Not implemented yet | +------------------+----------------------------------+-----------------------------------------------------+ | L | Firmware Management | :doc:`external_messages/update_firmware` | | | | | | | | :doc:`external_messages/firmware_status` | | | | | | | | :doc:`external_messages/reset` | +------------------+----------------------------------+-----------------------------------------------------+ | M | ISO 15118 Certificate Management | Not implemented yet | +------------------+----------------------------------+-----------------------------------------------------+ | | | :doc:`external_messages/upload_logs` | | | | | | | | :doc:`external_messages/logs_status` | | | | | | N | Diagnostics | | +------------------+----------------------------------+-----------------------------------------------------+ | O | Display Message | Not implemented yet | +------------------+----------------------------------+-----------------------------------------------------+ | P | Data Transfer | :doc:`external_messages/data_transfer` | +------------------+----------------------------------+-----------------------------------------------------+ Use cases covered by the latest by the latest version of JOSEV -------------------------------------------------------------- +------------------+----------------------------------+-------------------------------------------------------------------------+ | OCPP Section | Name | Use cases covered | +==================+==================================+=========================================================================+ | A | Security |A01 - Update Charging Station Password for HTTP Basic Authentication | | | | | | | |A02 - Update CS Certificate by request of CSMS | | | | | | | |A04 - Security Event Notification | | | | | | | |A05 - Upgrade Charging Station Security Profile | | | | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | B | Provisioning |B01 - Cold Boot Charging Station | | | | | | | |B02 - Cold Boot Charging Station – Pending | | | | | | | |B03 - Cold Boot Charging Station – Rejected | | | | | | | |B04 - Offline Behaviour Idle Charging Station | | | | | | | |B05 - Set Variables | | | | | | | |B06 - Get Variables | | | | | | | |B07 - Get Base Report | | | | | | | |B09 - Setting a new NetworkConnectionProfile | | | | | | | |B10 - Migrate to new CSMS | | | | | | | |B11 - Reset - Without Ongoing Transaction | | | | | | | |B12 - Reset - With Ongoing Transaction | | | | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | C | Authorization |C01 - EV Driver Authorization using RFID | | | | | | | |C04 - Authorization using PIN-code | | | | | | | |C05 - Authorization for CSMS initiated transactions | | | | | | | |C07 - Authorization using Contract Certificates | | | | | | | |C08 - Authorization at EVSE using ISO 15118 External Identification Means| | | | | | | | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | D | Local Auth. List | | | | | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | E | Transactions |E01 - Start Transaction options | | | | | | | |E02 - Start Transaction - Cable Plugin First | | | | | | | |E03 - Start Transaction - IdToken First | | | | | | | |E04 - Transaction started while Charging Station is offline | | | | | | | |E05 - Start Transaction - ID not accepted | | | | | | | |E06 - Stop Transaction options | | | | | | | |E07 - Transaction locally stopped by IdToken | | | | | | | |E08 - Transaction stopped while Charging Station is offline | | | | | | | |E09 - When cable disconnected on EV side: Stop Transaction | | | | | | | |E11 - Connection Loss during transaction | | | | | | | |E12 - Inform CSMS of an Offline Occurred Transaction | | | | | | | |E14 - Get Transaction Status | | | | | | | |E15 - End of charging process | +------------------+----------------------------------+-------------------------------------------------------------------------+ | F | RemoteControl |F01 - Remote Start Transaction - Cable Plugin First | | | | | | | |F02 - Remote Start Transaction - Remote Start First | | | | | | | |F03 - Remote Stop Transaction | | | | | | | |F04 - Remote Stop ISO 15118 Charging from CSMS | | | | | | | |F05 - Remotely Unlock Connector | | | | | | | |F06 - Trigger Message | | | | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | G | Availability |G01 - Status Notification | | | | | | | |G02 - Heartbeat | | | | | | | |G03 - Change Availability EVSE/Connector | | | | | | | |G04 - Change Availability Charging Station | | | | | | | |G05 - Lock failure | | | | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | H | Reservation | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | I | TariffAndCost | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | J | |J01 - Sending Meter Values not related to a transaction | | | | | | | MeterValues |J02 - Sending Transaction Related Meter Values | +------------------+----------------------------------+-------------------------------------------------------------------------+ | K | SmartCharging | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | | |L01 - Secure Firmware Update | | L | FirmwareManagement | | | | |L02 - Non-Secure Firmware Update | +------------------+----------------------------------+-------------------------------------------------------------------------+ | | |M01 - Certificate installation EV | | M | ISO 15118 | | | | |M02 - Certificate Update EV | | | CertificateManagement | | | | |M03 - Retrieve list of available certificates from a Charging Station | | | | | | | |M04 - Delete a specific certificate from a Charging Station | | | | | | | |M05 - Install CA certificate in a Charging Station | +------------------+----------------------------------+-------------------------------------------------------------------------+ | N |Diagnostics |N01 - Retrieve Log Information | | | | | | | |N09 - Get Customer Information | | | | | | | |N10 - Clear Customer Information | | | | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | O |DisplayMessage | | | | | | | | | | | | | | | | | | +------------------+----------------------------------+-------------------------------------------------------------------------+ | P |DataTransfer |P01 - Data Transfer to the Charging Station | | | | | | | |P02 - Data Transfer to the CSMS | | | | | +------------------+----------------------------------+-------------------------------------------------------------------------+ Message sequence for a charging session --------------------------------------- The sequence diagram below shows an example of the exchanged MQTT messages between Josev and the charging station CS, that might take place during the operation of a charging station and a typical charging session. Note that some of the messages, like meter_values, can be sent at any time depending on the situation. .. image:: images/charging_session_sequence_diag.svg :width: 400 :alt: Example message exchange for a charging session ISO15118 specific API messages ------------------------------ In order to integrate the ISO15118 protocol, the following API messages must be supported by the CS manufacturer. * :doc:`external_messages/slac_status` * :doc:`external_messages/cs_parameters` * :doc:`external_messages/cs_status_and_limits` * :doc:`external_messages/service_status` * :doc:`external_messages/cp_status` * :doc:`external_messages/stop_charging` * :doc:`external_messages/nw_info` * :doc:`external_messages/hlc_charging` * :doc:`external_messages/iso15118_state_info` * :doc:`external_messages/cs_contactor_status` * :doc:`external_messages/cp_pwm` (Only if using RSLAC) * :doc:`external_messages/cable_check` (DC only) * :doc:`external_messages/power_electronics_setpoint` (DC only) * :doc:`external_messages/sdp` (If UDP server is disabled) .. toctree:: :hidden: :maxdepth: 2 :caption: External Messages: external_messages/authorization external_messages/cable_check external_messages/cable_info external_messages/boot_status external_messages/change_availability external_messages/clock_sync external_messages/cp_pwm external_messages/cp_status external_messages/cs_connector external_messages/cs_contactor_status external_messages/cs_parameters external_messages/cs_status_and_limits external_messages/data_transfer external_messages/device_model external_messages/firmware_status external_messages/hardware_fault external_messages/hlc_charging external_messages/iso15118_state_info external_messages/logs_status external_messages/meter_values external_messages/nw_info external_messages/parking_bay external_messages/power_electronics_setpoint external_messages/reset external_messages/sdp external_messages/service_status external_messages/slac_status external_messages/stop_charging external_messages/update_firmware external_messages/upload_logs external_messages/websocket_status .. toctree:: :hidden: :maxdepth: 2 :caption: Internal Messages: internal_messages/connector_and_charging internal_messages/charging_setpoint internal_messages/set_charging_profile internal_messages/clear_charging_profile internal_messages/gridcode_settings internal_messages/iso15118_authorization internal_messages/iso15118_get_ev_certificate internal_messages/iso15118_message internal_messages/iso15118_charging_loop_power_limits internal_messages/limit_energy_flow internal_messages/remote_gridcode_operation internal_messages/slac_data_link .. only:: wheeldocs .. toctree:: :maxdepth: 2 :caption: Python modules python_docs/root Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`