CSMS API Specifications

CSMS API Specifications

Revisions

VersionDateAuthor(s)Description
1.0.02021-04-08Michael TécourtInitial version
1.1.02021-05-04Michael TécourtCSMS API v0.3.0
Added prefix /csms/{csmsId}`
1.2.02021-06-16Michael TécourtOCPP server prerequisite: Limit concurrent transactions per badge.
1.3.0-draft2021-07-23Michael TécourtV2G draft
1.4.0-draft2021-12-07Michael TécourtAuthorization/token URL Change
1.4.12022-04-13Michael TécourtAdd the V2G section
1.5.02022-04-14Michael TécourtAdd aFRR activation signal
1.6.02022-12-13Michael TécourtOCPP V2G Requirements - ABB Chargers
1.6.22023-05-22Eric MévellecEnglish translation
1.7.12023-10-25Chloé EnjolrasAdding Charging States, measurement by phase and connector
1.7.22023-11-28Michaël TécourtFix URLs.
1.8.02023-12-08Michaël TécourtOCPP ↔️ CSMS API mapping examples.
1.9.02023-12-25Michaël TécourtAdd sequence diagrams for different integration scenarios (pull, push, batch).
2.0.02024-04-17Michaël TécourtMarkdown, fixes and moved V2G to separate document

Glossary

TermDefinition
CSMSCharging Station Management System.
The information system responsible for managing the charging stations.
SCSPThe Smart Charging Service Provider (Dreev).
EVSEElectric Vehicle Supply Equipment. Equivalent to a Charge Point or Charge Box, in OCPP 1.x terminology.
Roughly equivalent to a physical charging station.
TransactionCharging Session in OCPP terminology.
Charging CommandCharging instructions to be applied during a transaction.
Dreev equivalent of the OCPP SetChargingProfile message, with purpose=TxProfile.
Default Charging CommandDefault command configured per EVSE regardless of the transaction.
These commands are persisted on the device. Dreev equivalent of the OCPP SetChargingProfile message, with purpose=TxDefaultProfile.
SoCThe State of Charge of a vehicle in %.
Local constraintsPower constraints of the electrical installation.
ISInformation System.
V2GVehicle-to-Grid. Bi-directional charging.
InletThe EVSE’s “power input" interface connected to the electrical network.
OutletThe EVSE’s “power output" interface connected to the vehicle.

Overview

Information systems responsibilities

CSMS

Charging Station Management System :

  • Connect to OCPP EVSEs
  • Acquire transactions, measurements and heartbeats from the EVSEs
  • Send transactions to Dreev
  • Send measurements to Dreev :
    • Active energy import (Wh or kWh)
    • Active power (W or kW)
    • Current (A)
    • SoC (%)
  • (Optional) Send Trips to Dreev, including :
    • Theoretical departure date
    • Theoretical return date
    • Energy requirement (Wh) to make the trip
  • Receive or Fetch charging commands calculated by Dreev
  • Translate charging commands into OCPP messages sent to EVSEs
  • Send the acknowledgements received for each charging command
  • Resend data after recovering from connection losses between systems

Dreev

Smart Charging Service Provider :

  • Receive data from the CSMS
  • Optimize charging : Charging Commands computation
  • Provide Charging Commands to the CSMS

Prerequisites

Charging Stations Requirements

  • OCPP 1.6-J
  • Smart Charging Profile
  • Type of measurements required (measurands) in the MeterValues message :
    • Energy.Active.Import (location = Inlet)
    • Power.Active.Import (location = Inlet)
    • SoC
  • « Clock Aligned » measurement readings
  • Required features of the SetChargingProfile message
    • purpose : TxProfile, TxDefaultProfile
    • kind : Absolute, Relative
    • One stackLevel per purpose is sufficient
    • Ability to replace an existing profile if a new one is sent with the same purpose + stackLevel combination, according to the OCPP 1.6 specification (section 5.16.3)
    • chargingRateUnit : W or A
    • startSchedule :
      • Must be defined when kind=Absolute, the startPeriod offsets are interpreted as : startSchedule + startPeriod.
      • Not defined when kind=Relative, startPeriod offsets are interpreted as : transaction start date + startPeriod.
  • The power setpoints of the SetChargingProfile messages are applied on the "AC" Inlet interface. This constraint is mandatory for system services (V2G). Dreev can also control unidirectional EVSEs on the Outlet ("DC") interface if required.

In summary, the following two typical profiles must be supported by EVSEs. The profile selection mechanisms must also be implemented according to OCPP 1.6 (or using Stack Level, or using profile IDs according to OCPP 1.6 paragraph 5.16.3).

Charging profiles requiredDefaultChargingCommandChargingCommand
chargingProfilePurposeTxDefaultProfileTxProfile
chargingProfileKindRelativeAbsolute
recurrencyKindemptyempty
validFromemptyempty
validToemptyempty
durationemptyempty
startScheduleemptydefined
chargingRateUnitW or AW or A
minChargingRateemptyempty
Other chargingSchedule parameters (added by Dreev)DefaultChargingCommand ChargingCommand
startPerioddefineddefined
limitdefineddefined
numberPhasesemptyempty

OCPP Server Requirements

Limit on the number of concurrent transactions per badge

It is not possible for Dreev to have multiple transactions for the same vehicle or EVSE.
Until the protocols implement strong vehicle identification, Dreev associates a badge (OCPP idTag) with a single vehicle. In principle, each user will receive a single badge for each vehicle. However, the CSMS must prevent the simultaneous presence of several transactions for the same badge.

For example, the OCPP SteVe server allows users to define the number of concurrent transactions for a given idTag. If a user tries to start a new transaction with their badge while a transaction is already in progress, the server will reject the second transaction.

Dreev assumes that the CSMS guarantees a maximum of one live transaction per vehicle. If Dreev receives a new transaction with a given badge, Dreev will assume that the previous open transactions are stopped.

Provisioning static data

The following information is relatively static, and can be provisioned in Dreev’s system before the project starts.

To scale up, Dreev could set up endpoints to automate these exchanges.

Site topology

Dreev needs to know the topology of the site's electrical network to take into account power constraints. Some circuits are constrained to a maximum power lower than the sum of the maximum power of all the EVSEs on that circuit. In this context, Dreev must sometimes anticipate the charging of vehicles in order to respect the constraints of the electrical installation and the drivers mobility needs.

In addition to the electrical installation, Dreev also needs to know whether certain parking spots block others.

Data needed:

  • Delivery Points, also known as : Grid connection, Service Drop, Meter Point Administration Number (MPAN), PDL...
  • Power constraints at the delivery point level
  • Electrical installation topologies
    • Circuits with their hierarchy
    • Power constraints of each circuit
    • EVSEs connected to each circuit
  • Priority : Parking/exit order

EVSE registry

The list of controlled EVSEs. Dreev needs to know the technical characteristics of the EVSEs in order to be able to properly control the charging.

Data needed:

  • Unique identifier (UUID, mac address, ...)
  • Name of the EVSE (user friendly)
  • Name of the manufacturer
  • Serial number
  • Technical characteristics of the model :
    • Maximum charging power
    • Minimum charging power (can be 0)
    • Stand-by losses
    • Variable losses while charging

Vehicles registry

The list of vehicles with their technical characteristics.

Data needed:

  • Unique identifier (UUID, mac address, ...)
  • Vehicle name (user friendly)
  • Name of the manufacturer
  • Technical characteristics of the model :
    • Battery capacity
    • Maximum power
    • Minimum power when charging (can be 0)

Note: The vehicle list can be dynamically provisioned by the CSMS depending on the project.

Charging Requirements - SoC Targets

Dreev can set SoC requirements for each vehicle following a weekly schedule. 
This functionality is also available dynamically by the CSMS depending on the project, see section Charging Requirements.

Data flows

General dynamics

Dreev can send charging commands to the CSMS in real time after each optimization.

If it is not possible to allow Dreev → CSMS calls for security reasons, Dreev also provides an API that allows the CSMS to poll the latest charging commands.

If the CSMS architecture cannot react in real-time to OCPP messages, it is possible to trigger periodic batch processing to extract the accumulated OCPP data and send it to the Dreev API.

Periodicity

CSMS receives and records the following OCPP messages continuously:

  • StartTransaction
  • StopTransaction
  • MeterValues
  • Heartbeats
  • ...

CSMS sends a near-real-time message to Dreev :

  • Transaction Start & Stop events
  • Charging command acknowledgements : SetChargingProfile.respChargingCommand status
  • Heartbeat messages
  • Measurements (see description of flows)

Dreev sends the charging commands to the CSMS in real time after each optimization.

If this is not possible, the CSMS can also retrieve the charging commands every minute from Dreev. However, it is preferable to aim for real time, rather than batch processing.

Integration flows

Below are descriptions of different integration flows depending on the CSMS capabilities.

a) Real time Events + Push Charging Commands (optimal)

  • The CSMS can react to transaction events in real time
  • The CSMS can receive charging commands pushed by Dreev whenever they are computed

b) Real time Events + Pull Charging Commands

  • The CSMS can react to transaction events in real time
  • The CSMS polls Charging Commands frequently. This decision could be made for :
    • security reasons : impossible to open bidirectional communication between systems, prefering to keep the CSMS internal, etc.
    • convenience : it is easier to only call Dreev’s server than having to build and operate one.

c) Batch Events + Pull Charging Commands

  • The CSMS cannot send transaction events in real-time, and has to send events in batch periodically. The CSMS could also choose this option for performance reasons (limiting HTTP calls).

  • The CSMS cannot receive calls from Dreev, and has to rely on polling Charging Commands frequently.

Dreev CSMS HTTP API

Dreev’s CSMS API allows a CSMS to :

  • Send transactions, measurements and heartbeats received via OCPP.
  • Retrieve charging commands for each transaction.
  • Acknowledge the status of each charging command.
  • Report vehicle trips and energy requirements.

See CSMS API Authentication and CSMS API Endpoints.