Introduction

The Jedlix Smart Charging platform continually fine-tunes the best charging schedule based on real-time grid conditions, electricity pricing, and individual user settings. Accurate charger data is crucial for generating these optimized profiles.

Developed in alignment with the OCPI Sessions Module (view documentation), our API ensures seamless data exchange between Charge Point Operators (CPOs) and the Jedlix platform.

This guide provides Charge Point Operators with detailed instructions on when and how to transmit data points to the Jedlix platform using the OCPI Sessions API, thereby maximizing the efficacy of the Smart Charging solution.

Available Environments

Once you complete the initial setup, Jedlix will grant you access to two distinct API environments:

• Production Environment: Base URL ocpi.jedlix.com
• QA Environment: Base URL qa-ocpi.jedlix.com

Authorization methods

Jedlix uses two main authorization methods to secure data access to the OCPI Sessions API:

1. OAuth 2.0 and API Key Authentication

This method combines OAuth2 token-based authentication and an API Key for an extra layer of security.

For each environment, you'll receive a pair of client credentials (client_id and client_secret). These credentials don't access resources directly; instead, they're used to get tokens that do. Secure these tokens as they carry the API access permissions.

To request a token, use the OAuth2 client credentials flow from our Identity Provider, Auth0.

Token Retrieval Example:

curl -X POST 'https://jedlix-b2e.eu.auth0.com/oauth/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_id={your client_id}' \
    --data-urlencode 'client_secret={your client_secret}' \
    --data-urlencode 'audience=https://ocpi.jedlix.com'

Upon successful request, you'll receive an access_token. Include this token in the Authorization header for subsequent API requests.

📘

Note: The credentials for OCPI API differ from those for the Smart Charging API.

Refreshing Tokens: Your access token remains valid for 14 days. Make sure to request a new one before it expires.

API Call Example

curl --request PUT \
     --url 'https://ocpi.jedlix.com/api/ocpi/emsp/2.2.1/sessions/NL/ABC/12345' \
     --header 'authorization: Bearer {access_token}' \
     --header 'ApiKey: {YOUR API KEY}'

2. OCPI Credentials Module

Jedlix also accommodates authorization via the OCPI Credentials Module, which you can read about in detail here.

Initiating the Handshake

The Credentials Module necessitates a starting handshake between Jedlix and the CPO. One party acts as the SENDER and the other as the RECEIVER. Jedlix generally prefers to be the RECEIVER.

• If Jedlix is the RECEIVER
  1. Send the offline token and CPO base URL to Jedlix.
  2. Trigger the registration request to the appropriate OCPI API endpoint.
  3. The registration process will confirm if the handshake was successful.
• If Jedlix is the SENDER
  1. Start the handshake by making a request to the appropriate OCPI API endpoint.
  2. The response will contain a jedlix_token to be shared with the RECEIVER for completing the registration.

For detailed technical steps and code examples on initiating the handshake, please consult the official OCPI credentials documentation.

Data requirements

Fields

Your data payload should conform to the OCPI Sessions Object (documentation) and include the fields:

• start_date_time : The timestamp when the session became ACTIVE in the Charge Point.
• end_date_time : The timestamp when the session was completed (the moment the session was ended)
• last_updated: Timestamp when this Session was last updated (or created).
• kwh : How many kWh were charged.
• status: The status of the session.
• charging_periods, as defined here, including:
  • start_date_time :
  • dimensions, as defined here, including at least the Types:
    • ENERGY: Total amount of energy (dis-)charged during this ChargingPeriod: defined in kWh. When negative, more energy was feed into the grid then charged into the EV. Default step_size is 1.
    • ENERGY_EXPORT: Total amount of energy feed back into the grid: defined in kWh.
    • ENERGY_IMPORT: Total amount of energy charged, defined in kWh.
    • POWER: Average power during this ChargingPeriod: defined in kW (Kilowatt). When negative, the power is flowing from the EV to the grid.
    • MIN_POWER: Minimum power reached during this ChargingPeriod: defined in kW (Kilowatt), when negative, the power has flowed from the EV to the grid.
    • MAX_POWER: Maximum power reached during this ChargingPeriod: defined in kW (Kilowatt).
    • PARKING_TIME: Time during this ChargingPeriod not charging: defined in hours, default step_size multiplier is 1 second.
    • STATE_OF_CHARGE (if available): Current state of charge of the EV, in percentage, values allowed: 0 to 100. See note below.

❗️

Important Note on Session Status and Charging State Limitations

In the OCPI framework, the status field of a Session Object offers limited values such as ACTIVE, COMPLETED, INVALID, PENDING, and RESERVATION. While useful for identifying whether a session is in progress (ACTIVE) or concluded (COMPLETED), these status options fall short of giving Smart Charging Service Providers a clear way to assess the current charging state during an ongoing session.

Though it's feasible to estimate the charging state using parameters like PARKING_TIME, POWER, or the change in ENERGY between charging intervals, these approximations are not foolproof. They can lead to inaccuracies in the calculated charging profiles or display incorrect status to users (e.g., indicating that a car is charging when it is not).

The OCPP 2.0 standard introduces a more nuanced ChargingState field, which includes options like Charging, EVConnected, SuspendedEV, and SuspendedEVSE. Ideally, Smart Charging Service Providers should have access to these more detailed statuses during an active session. Alternatively, the PARKING_TIME value in the Charging Period Dimension should reliably reflect the SuspendedEV and SuspendedEVSE states as specified in OCPP 2.0.

Frequency

For best results:

• Update every 5 minutes during charging/discharging
• Update when chargingState changes

Latency

Though there is no rigid specification for Session Data latency, its timeliness is crucial for verifying the immediate implementation of charging profile requests. If you aim to partake in energy markets, it's essential that the time gap between initiating a Smart Charging profile request, its actual execution, and the subsequent confirmation back to the Smart Charging Service Provider, be limited to a maximum of 10 seconds. Note that this can also be achieved through the Charging Profile Accepted messages.

Optimal Data Exchange Timing

Ensuring timely data exchange is critical for the Jedlix Smart Charging platform to deliver its full potential. Below are the suggested times to send various types of data.

1. Initiating a New Session

• Action: Create a new Session Object
• API Endpoint: Create a Session
• Significance: Upon the start of a new charging session, it's imperative to relay this information to the Jedlix platform. Doing so enables dynamic charge scheduling based on the latest session data.
• Example API Call:

curl --request PUT \\
     --url 'https://ocpi.jedlix.com/api/ocpi/emsp/2.2.1/sessions/{COUNTRY_ID}/{PARTY_ID}/{SESSION_ID}' \\
     --header 'accept: application/json' \\
     --header 'authorization: Bearer {OCPI_ACCESS_TOKEN}' \\
     --header 'content-type: application/json' \\
     --data '
{
     "id": "c1e3aa3f-684b-4f53-b080-785de09e8e21",
     "evse_uid": "1668455",
     "status": "ACTIVE",
     "kwh": 0,
     "start_date_time": "2022-11-14T14:33:19.782Z",
     "last_updated": "2022-11-14T14:33:45.653Z"
}
'

2. Updating an Ongoing Session

• Action: Modify an existing Session Object
• API Endpoint: Update a Session
• Recommended Frequency:
  • At intervals of 5 minutes or less during charging/discharging
  • Triggered by any change in chargingState
• Explanation: Frequent updates enable the platform to adapt to real-time changes effectively. We advise sending updates at intervals not exceeding 5 minutes to ensure detailed and accurate data, thus facilitating the optimization of energy flexibility services.
• Example API Call:

curl --request PATCH \\
     --url 'https://ocpi.jedlix.com/api/ocpi/emsp/2.2.1/sessions/{COUNTRY_ID}/{PARTY_ID}/{SESSION_ID}' \\
     --header 'accept: application/json' \\
     --header 'authorization: Bearer {OCPI_ACCESS_TOKEN}' \\
     --header 'content-type: application/json' \\
     --data '
{
     "charging_periods": [...],
     "id": "c1e3aa3f-684b-4f53-b080-785de09e8e21",
     "start_datetime": "2022-11-14T14:33:19.782Z",
     "status": "ACTIVE",
     "kwh": 34.765,
     "last_updated": "2022-11-15T03:33:19.782Z"
}
'

3. Finalizing a Session

• Action: Update Session Object to COMPLETED
• Significance: When a charging session concludes, it's vital to update the Session Object's status to COMPLETED. Avoid deleting these records; they are useful for future performance enhancements. Jedlix should be capable of fetching this historical data from the Charge Point Operator (CPO) for analysis and subsequent improvements.