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.

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:

1. Request by Josev (on topic josev/cs):

   {
       "id": "6c1f594a-3dfe-409b-8251-bceb68ad0812",
       "name": "cs_status_and_limits",
       "type": "request",
       "data": {}
   }
   

2. 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	Service Status Websocket Status Boot status Device Model Reset
C	Authorization	Authorization
D	Local Auth List Mgmt	Not implemented yet
E	Transactions	Authorization Cable Info Control Pilot Status Stop Charging Parking Bay
F	Remote Control	Charging Station Connector Boot status Stop Charging Log status Control Pilot Status
G	Availability	Change Availability Charging Station Connector Hardware Fault
H	Reservation	Not implemented yet
I	Tariff and Cost	Not implemented yet
J	Meter Values	Meter Values
K	Smart Charging	Not implemented yet
L	Firmware Management	Update Firmware Firmware Status Reset
M	ISO 15118 Certificate Management	Not implemented yet
N	Diagnostics	Upload Logs Log status
O	Display Message	Not implemented yet
P	Data Transfer	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	MeterValues	J01 - Sending Meter Values not related to a transaction J02 - Sending Transaction Related Meter Values
K	SmartCharging
L	FirmwareManagement	L01 - Secure Firmware Update L02 - Non-Secure Firmware Update
M	ISO 15118 CertificateManagement	M01 - Certificate installation EV M02 - Certificate Update EV 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.

ISO15118 specific API messages

In order to integrate the ISO15118 protocol, the following API messages must be supported by the CS manufacturer.

• SlacStatusUpdate

• Charging Station Parameters

• Charging Station Status and Limits

• Service Status

• Control Pilot Status

• Stop Charging

• HomePlug Network Information

• (HLC) High Level Communication Charging

• ISO15118 State Information

• Charging Station Contactor

• Control Pilot Control (Only if using RSLAC)

• Cable Check (DC only)

• Power Electronics Setpoint (DC only)

• SDP (If UDP server is disabled)

Indices and tables

• Index

• Module Index

• Search Page