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 end. Information like EVSE charge parameters, EVSE power relays state and control pilot 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).

Details on this MQTT interface can be found in Josev API documentation.

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:

  1. 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.

  2. 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.

  3. In case any status or limit changes on the CS, an update message will be sent on the same topic as the response.

Josev MQTT API example (cs_status_and_limits)

%%{init: {"theme":"light", "sequenceDiagram": {"htmlLabels": false}} }%% sequenceDiagram participant J as Josev participant CS as Charging Station J-)+CS: 4. cs_status_and_limits_request Note right of CS: channel/topic: josev/cs CS-)-J: 5. cs_status_and_limits_response Note right of CS: channel/topic: cs/josev CS--)J: 16. cp_status_update Note right of CS: channel/topic: cs/josev

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 the previous table, 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.

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": {}
    }

  1. 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

N/A

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

Transactions related messages

L

Firmware Management

Update Firmware

Firmware Status

Reset

M

ISO 15118 Certificate Management

N/A

N

Diagnostics

Upload Logs

Log status

O

Display Message

Display and Personal Message

P

Data Transfer

Data Transfer

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.

%%{init: {"theme":"light", "sequenceDiagram": {"htmlLabels": false}} }%% sequenceDiagram participant J as Josev participant CS as Charging Station rect rgb(0,128,145) Note over J,CS: Boot Sequence CS-)CS: 1. HW and SW boot J-)+CS: 2. device_model_request CS-)-J: 3. device_model_response J-)+CS: 4. cs_status_and_limits_request CS-)-J: 5. cs_status_and_limits_response J-)+CS: 6. cs_parameters_request CS-)-J: 7. cs_parameters_response(max_current, status_code, ..) end rect rgb(15,128,2) Note over J,CS: Charging Session CS-)CS: 8. Vehicle Plugged (State B) CS--)J: 9. cp_status_update(state="B1"...) CS--)J: 10. meter_values_update(total_active_energy_exported...) Note right of CS: can be sent at any time J--)CS: 11. hlc_charging_update(evse_id...) Note right of CS: HLC means High Level Communication alt authorization triggered by iso15118 or CSMS J--)CS: 12. external_authorization_update(evse_id...) end alt EIM (ie.Card reader) CS-)+J: 13. cs_authorization_request(evse_id, idToken...) J-)-CS: 14. cs_authorization_response(status: "Accepted"...) end loop Charging Loop CS-)CS: 15. Vehicle Charging (State C) CS--)J: 16. cp_status_update(state="C2"...) end rect rgb(0,90,2) Note over J,CS: End of Charging Session alt EIM triggers stop_charge on CS side CS-)CS: 17. EIM detected CS-)+J: 18. cs_authorization_request(evse_id, idToken...) J-)-CS: 19. cs_authorization_response(status: "Accepted") end alt Remote stop from CSMS J-)+CS: 20. stop_charging_request(evse_id...) CS-)-J: 21. stop_charging_response(status:"accepted") end CS--)J: 22.cp_status_update(state="C1"...) CS-)CS: 23. Vehicle Stop Charging(State B1) CS--)J: 24.cp_status_update(state="B1"...) CS-)CS: 25. Vehicle Unplugged (State A) CS--)J: 26.cp_status_update(state="A1"...) end end rect rgb(0,102,153) Note over J,CS: Reset Sequence J-)+CS: 27. reset_request(id...) CS-)-J: 28. reset_response(status:"accepted") CS-)CS: 29. HW and SW Boot end

ISO15118 specific API messages

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