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.

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:

  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.

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.

Indices and tables