Services

Josev API

Josev API defines the messages and communication between services within Josev and with any third party services on the station operated by the OEM.

Messages can either be of type request, response, or update and are communicated over an MQTT message bus. Topics are organised by service, so to send from service A to service B the topic A/B should be used.


OCPP

OCPP is a core service in Josev which controls much of the logic and the communication between the station and the Charging Station Management System (CSMS). The currently supported version is OCPP 2.0.1.

Josev is certified for OCPP 2.0.1 by the OCA for the Core and Advanced Security profiles.

Supported use cases

Functional Block

Use Case ID

Use Case Name

Supported

Observation

A - Security

A01

Update Charging Station Password for HTTP Basic Authentication

A02

Update Charging Station Certificate by request of CSMS

A03

Update Charging Station Certificate initiated by the Charging Station

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 Behavior Idle Charging Station

B05

Set Variables

B06

Get Variables

B07

Get Base Report

B08

Get Custom 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

C02

Authorization using a start button

C03

Authorization using credit/debit card

TBD

C04

Authorization using PIN-code

C05

Authorization for CSMS initiated transactions

C06

Authorization using local id type

C07

Authorization using Contract Certificates

C08

Authorization at EVSE using ISO 15118 External Identification Means (EIM)

C09

Authorization by GroupId

C10

Store Authorization Data in the Authorization Cache

TBD

C11

Clear Authorization Data in Authorization Cache

TBD

C12

Start Transaction - Cached Id

TBD

C13

Offline Authorization through Local Authorization List

C14

Online Authorization through Local Authorization List

C15

Offline Authorization of unknown Id

C16

Stop Transaction with a Master Pass

D - LocalAuthorizationList Management

D01

Send Local Authorization List

D02

Get Local List Version

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

E10

When cable disconnected on EV-side: Suspend Transaction

TBD

E11

Connection Loss During Transaction

E12

Inform CSMS of an Offline Occurred Transaction

E13

Transaction related message not accepted by CSMS

E14

Check transaction status

E15

End of charging process

F - Remote Control

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

G04

Change Availability Charging Station

G05

Lock Failure

H - Reservation

H01

Reservation

TBD

H02

Cancel Reservation

TBD

H03

Use a reserved EVSE

TBD

H04

Reservation Ended, not used

TBD

I - Tariff and Cost

I01

Show EV Driver-specific tariff information

I02

Show EV Driver running total cost during charging

I03

Show EV Driver final total cost after charging

I04

Show fallback tariff information

Q2 2024

I05

Show fallback total cost message

Q2 2024

I06

Update Tariff Information During Transaction

Q2 2024

J - Meter Values

J01

Sending Meter Values not related to a transaction

J02

Sending transaction related Meter Values

J03

Charging Loop with metering information exchange

TBD

K - SmartCharging [1]

K01

SetChargingProfile

K02

Central Smart Charging

K03

Local Smart Charging

K04

Internal Load Balancing

K05

Remote Start Transaction with Charging Profile

TBD

K06

Offline Behavior Smart Charging During Transaction

K07

Offline Behavior Smart Charging at Start of Transaction

K08

Get Composite Schedule

TBD

K09

Get Charging Profiles

TBD

K10

Clear Charging Profile

K11

Set / Update External Charging Limit With Ongoing Transaction

TBD

K12

Set / Update External Charging Limit Without Ongoing Transaction

TBD

K13

Reset / release external charging limit

TBD

K14

External Charging Limit with Local Controller

TBD

K15

Charging with load leveling based on High Level Communication

⚠️

Partially supported

K16

Optimized charging with scheduling to the CSMS

⚠️

Partially supported

K17

Renegotiating a Charging Schedule

⚠️

Partially supported

L - FirmwareManagement

L01

Secure Firmware Update

L02

Non-Secure Firmware Update

L03

Publish Firmware file on Local Controller

TBD

L04

Unpublish Firmware file on Local Controller

TBD

M - ISO 15118 Certificate Management

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

M06

Get Charging Station Certificate status

TBD

N - Diagnostics

N01

Retrieve Log Information

N02

Get Monitoring report

TBD

N03

Set Monitoring Base

TBD

N04

Set Variable Monitoring

TBD

N05

Set Monitoring Level

TBD

N06

Clear / Remove Monitoring

TBD

N07

Alert Event

TBD

N08

Periodic Event

TBD

N09

Get Customer Information

TBD

N10

Clear Customer Information

TBD

O - Display Message

O01

Set DisplayMessage

O02

Set DisplayMessage for Transaction

O03

Get All DisplayMessages

TBD

O04

Get Specific DisplayMessages

TBD

O05

Clear a DisplayMessage

T

O06

Replace DisplayMessage

P - Data Transfer

P01

Data Transfer to the Charging Station

P02

Data Transfer to the CSMS

Relevant Josev API Messages

Required

Optional


ISO 15118

Switch provides an open source Python based ISO15118 implementation which can be found here. This package is combined with a Rust EXI encoder and used in the main Josev Pro project as the foundation of the iso15118 service.

The ISO15118 service contains support for the following protocols:

  • DIN 70121

  • ISO 15118-2

  • ISO 15118-20

Supported use cases

Features

DIN
70121

ISO
15118-2

ISO
15118-20

Observation

SLAC

Performed by our rslac application.

SDP

TCP

TLS 1.2

-

TLS 1.3 (with mTLS)

-

⚠️

This feature is supported and was already successfully tested in our development environment, but is not yet in production. Expected to be released by 2024.

SupportedAppProtocol

CertificateInstallation

PnC Contract CertificateUpdate is not something OEMs perform, so it is not used in the stack, only CertificateInstallation. CertificateInstallation is achieved by fetching the certificate via Hubject services.

EIM Authorization

PnC Authorization

-

AC

-

DC

-

AC_BPT

-

-

AC_BPT_DER

-

-

Distributed Energy Resource (DER) use case is being drafted. Switch is leading the task force to add support for this use case in ISO 15118-20. An amendment to the standard shall be expected in Q3 2024.

DC_BPT

ACDP

Automated Connection Device-Pantograph feature will come in a future release

WPT

Wireless Power Transfer will come in a future release.

Pause

Stand-By

Wake-up

Performed by our rslac application.

Fallback Mechanism

For the AC communication, if the ISO 15118 communication initial setup fails (during SLAC or before PowerDelivery), rslac does an E/F transition and sets a nominal PWM to force the EV to start basic AC charging.

Multiplexed Communication

Will come in a future release.

Dynamic Mode

Neither the DIN 70121 or the ISO 15118-2 have the concept of Dynamic mode, defined by the ISO 15118-20, however, the DIN 70121 is by design a dynamic charging protocol. The ISO 15118-2 has also a workaround to emulate a dynamic charging session by using the fields:
-EVSEMaxCurrent [AC]
-EVSEMaximumPowerLimit [DC]
-EVSEMaximumCurrentLimit [DC]
Josev makes use of these fields.

Scheduled Mode

-

The ISO 15118-2 does not have the concept of scheduled charging mode, but, by design, the protocol behaves as the Scheduled mode defined by the ISO 15118-20.

Certificate Management

⚠️

This relates to the EVSE Certificate chain, V2G root and MO root installation and update. The stack is ready to validate and to get these certificates by interacting with Hubject. The certificates needed for the ISO 15118-20 must be based on the ecdsa_secp521r_sha512 or ed448 signature algorithms, but these are not yet supported by Hubject.

Relevant Josev API Messages


SLAC

The slac service corresponds directly to the protocol defined in ISO 15118-3, which defines the usage of the HomePlug GreenPHY SLAC (Signal Level Attenuation Characterisation) mechanism to ensure a direct communication between the station and the EV that is electrically connected to it. SLAC acts on layer 2 of the OSI model.

RSlac is an implementation of the SLAC matching protocol, written in Rust (hence the R). It is exclusive to Josev Pro customers, where Josev Community uses the Python version PySlac.

%%{init: {"theme":"light", "sequenceDiagram": {"htmlLabels": false}} }%% sequenceDiagram participant CS as Charging Station box Gray RSlac participant SM as Service Manager participant Service as Service(evse_id) end participant PLC Note over CS,Service: Startup SM-)CS: service_status Update(starting) opt if Parameters and Limits cannot be loaded from file SM-)+CS: cs_parameters Request CS-)-SM: cs_parameters Response SM-)+CS: cs_status_and_limits Request CS-)-SM: cs_status_and_limits Response end SM-)Service: spawn(evse_id) Service-)SM: set_hlc SM-)+CS: cp_pwm Request(evse_id, high_level_charging) Note over SM: High Level Charging may be<br/>configured in cs_parameters<br/>or config file CS-)-SM: cp_pwm Response Note over CS,Service: Matching Process CS-)SM: cp_status Update(evse_id, B2) SM-)Service: start PLC-->Service: SLAC matching process alt SLAC match succesful rect rgb(21,128,0) Service-)SM: matching SM-)CS: slac_service_status Update(evse_id, matching) Service-)SM: matched SM-)CS: slac_service_status Update(evse_id, matched) end end alt SLAC match failed rect rgb(153,0,0) Service-)SM: matching SM-)CS: slac_service_status Update(evse_id, matching) Service-)SM: failed SM-)CS: slac_service_status Update(evse_id, failed) end end alt SLAC initialization timeout (Basic Charging fallback) rect rgb(0,102,153) Note over SM, Service: after 20 seconds SM-)CS: slac_service_status Update(evse_id, basic_charging) SM-)+CS: cp_pwm Request(evse_id, F) CS-)-SM: cp_pwm Response Note over SM, Service: wait 5 seconds SM-)+CS: cp_pwm Request(evse_id, X1) CS-)-SM: cp_pwm Response Note over SM, Service: wait 0.5 seconds SM-)+CS: cp_pwm Request(evse_id, X2(nominal_current)) CS-)-SM: cp_pwm Response end end

Supported optional features

  • Match validation using BCB toggling (CM_VALIDATE)

  • EV-side wakeup using BCB toggling

  • HomePlug network inspection (using CM_NW_INFO)

  • HomePlug link status checking (using vendor extension LINK_STATUS_REQ)

Currently unsupported optional features

  • Amplitude mapping

  • EVSE-side wakeup using B1/B2 toggling

Relevant Josev API Messages


Smart Charging

The Smart Charging service is an optional add-on which offers OCPP 2.0.1 based smart charging operation. The service consumes OCPP 2.0.1 SetChargingProfile requests, calculate the right charge limits and apply those limits to any active session. Both basic charging and ISO 15118 sessions are supported.

Charging profile purposes

Supported

Observation

ChargingStationMaxProfile

Only supported for chargers with a single EVSE.

TxProfile

TxDefaultProfile

ChargingStationExternalConstraints

Charging profile recurrency

Supported

Observation

Absolute

Relative

Recurring

When the service is booting, it relies on the Josev API messages Charging Station Parameters and Charging Station Status and Limits to detect the electrical layout of the charger.

sequenceDiagram autonumber title Boot sequence Smart Charging Service participant oem as OEM participant sms as Smart Charging Service participant void as void sms -->> void: ServiceStatusUpdate(status="Starting") sms -->> oem: CsParametersRequest(...) oem ->> sms: CsParamaterResponse(...) sms -->> oem: CsStatusAndLimitsRequest(...) oem ->> sms: CsStatusAndLimitsResponse(...) sms -->> void: ServiceStatusUpdate(status="Ready")

After booting, the service subscribes for the messages Control Pilot Status and SlacStatusUpdate. These messages inform the Smart Charging service when a session has started or ended.

The service also subscribes for api:external_messages/set_charging_profile.

During a charging session, the service produces messages to control the rate of charge. The relevant messages are Control Pilot Control (for a basic charging session) and Iso15118ChargeLimit (for an ISO 15118 session).

sequenceDiagram autonumber title Handle changes in charger's environment participant oem as OEM participant ocpp as OCPP Service participant sms as Smart Charging Service participant rslac participant iso15118 loop par oem -->> sms: CpStatusUpdate(evse_id, connector_id, state, ..) and rslac -->> sms: SlacStatusUpdate(evse_id, status, ...) and ocpp -->> sms: SetChargingProfile(evse_id, ...) and sms -->> oem: CpPwmRequest(evse_id, current, ...) and sms -->> iso15118: Iso15118ChargeLimit(evse_id, limit, unit) end end

Relevant Josev API Messages