CSMS API Endpoints

The HTTP endpoints below are described in the OpenAPI 3 (Swagger) API documentation.

Conventions :

Date-Time: ISO 8601 Date Time format.
Durations: ISO 8601 Duration format.
Periods :
- Start date included.
- End date excluded. A null value means "infinite".
The charging commands provided by Dreev are in Watts (W).
EVSEs, Vehicles and Transactions unique identifiers used by the API are CSMS identifiers.
Endpoints using CSMS identifiers above are prefixed with /csms/{csmsId}, with the csmsId provided by Dreev.
The charging command identifiers are Dreev identifiers.

Note: The CSMS must send Dreev only the data from the EVSEs and vehicles included in the scope of the project.

Monitoring of EVSE communications

Dreev must be able to determine whether the EVSEs are communicating and therefore controllable. When an EVSE is no longer communicating, Dreev knows the latest commands assigned to the EVSE, and continues to distribute the remaining power to the rest of the fleet while preserving the electrical installation.

In order to determine whether an EVSE is communicating, Dreev relies on receiving heartbeat messages every 5 minutes (in addition to the other expected OCPP messages).

To save bandwidth, CSMS can also use the WebSocket ping/pong instead of the Heartbeat message. Any packet/message works as long as Dreev can determine that each EVSE has generated traffic in a given time interval.

`POST /csms/{csmsId}/evse-heartbeats`

Heartbeats allow Dreev to determine the communication status of the EVSE. This endpoint can handle batches of heartbeats from multiple EVSEs at once.

OCPP Message Example : `Heartbeat` Request

{}

Note : The Charging Station concerned by this message is identified when opening the WebSocket connection.

Corresponding CSMS API call

{
  "evses":[
    {
      "evseId":"CSMS-EVSE-1337",
      "heartbeats":[
        {
          "timestamp":"2023-01-01T10:00:00Z"
        }
      ]
    }
  ]
}

Transactions

The most important for Dreev is to track ongoing transactions in real-time. The Dreev platform builds a "snapshot" of all transactions on the field, so that optimal charging commands can be assigned.

`POST /csms/{csmsId}/transaction-events`

Sending transaction start & stop events. This endpoint can handle batches of transaction start & stop events for multiple EVSEs at once.

In order to be as close as possible to real time, the start and end of the transaction events should be sent to Dreev at least every minute.

It is possible to specify a connector for each transaction start. To keep backwards compatibility, a default connector is chosen by Dreev for each EVSE model, whenever this information is not supplied in the request.

The charging state can also be supplied in the start transaction event (cf. endpoint charging-states below). Default charging state to keep backwards compatibility is CHARGING.

OCPP 1.6 Messages Examples

StartTransaction Request - EVSE ID : CSMS-EVSE-1337

{
  "connectorId":1,
  "idTag":"72f1ba11",
  "meterStart":0,
  "timestamp":"2023-01-01T00:00:00Z"
}

StartTransaction Response - EVSE ID : CSMS-EVSE-1337

{
  "transactionId":33,
  "idTagInfo":{
    "status":"Accepted",
    "expiryDate":"2023-01-01T00:00:05Z"
  }
}

StopTransaction Request - EVSE ID : CSMS-EVSE-2000

{
  "transactionId":99,
  "timestamp":"2023-01-01T00:00:07Z",
  "meterStop":33000,
  "idTag":"badge_999",
  "reason":"Other"
}

OCPP 2.0 Messages Examples

TransactionEvent Request - Start - EVSE ID : CSMS-EVSE-1337

{
  "eventType":"Started",
  "timestamp":"2023-01-01T00:00:05Z",
  "triggerReason":"Authorized",
  "seqNo":1,
  "transactionInfo":{
    "transactionId":"CSMS-EVSE-1337-TX-0033",
    "chargingState":"Charging"
  },
  "evse":{
    "id":1,
    "connectorId":1
  },
  "idToken":{
    "idToken":"72f1ba11",
    "type":"ISO14443",
    "additionalInfo":[
      {
        "additionalIdToken":"72:c7:06:79:3f:dc",
        "type":"eMAID"
      }
    ]
  },
  "meterValue":[
    {
      "timestamp":"2023-01-01T00:00:05Z",
      "sampledValue":[
        {
          "value":0.0,
          "context":"Transaction.Begin",
          "measurand":"Energy.Active.Import.Register",
          "unitOfMeasure":{
            "unit":"Wh"
          }
        }
      ]
    }
  ]
}

TransactionEvent Response - Start - EVSE ID : CSMS-EVSE-1337

{
  "idTokenInfo":{
    "status":"Accepted"
  }
}

TransactionEvent Request - Stop - EVSE ID : CSMS-EVSE-2000

{
  "eventType":"Stopped",
  "timestamp":"2023-01-01T00:00:07Z",
  "triggerReason":"RemoteStop",
  "seqNo":90,
  "transactionInfo":{
    "transactionId":"CSMS-EVSE-2000-TX-0099"
  },
  "idToken":{
    "idToken":"some_badge_1234",
    "type":"ISO14443"
  },
  "meterValue":[
    {
      "timestamp":"2023-01-01T00:00:07Z",
      "sampledValue":[
        {
          "value":33000.0,
          "context":"Transaction.End",
          "measurand":"Energy.Active.Import.Register",
          "unitOfMeasure":{
            "unit":"Wh"
          }
        }
      ]
    }
  ]
}

Corresponding CSMS API call

{
  "evses":[
    {
      "evseId":"CSMS-EVSE-1337",
      "transactionStarts":[
        {
          "transactionId":"CSMS-EVSE-1337-TX-0033",
          "connectorId":"1",
          "vehicleId":"72:c7:06:79:3f:dc",
          "badgeId":"72f1ba11",
          "meterStart":{
            "unit":"kWh",
            "value":0
          },
          "startedAt":"2023-01-01T00:00:05Z",
          "chargingState":"CHARGING"
        }
      ],
      "transactionStops":[]
    },
    {
      "evseId":"CSMS-EVSE-2000",
      "transactionStarts":[],
      "transactionStops":[
        {
          "transactionId":"CSMS-EVSE-2000-TX-0099",
          "badgeId":"some_badge_1234",
          "meterStop":{
            "unit":"kWh",
            "value":33
          },
          "stoppedAt":"2023-01-01T00:00:07Z"
        }
      ]
    }
  ]
}

Notes :

Transaction IDs must be unique across all EVSEs for a given CSMS.
In OCPP 1.6, Transaction IDs are relative to a given EVSE. In order to provide Dreev a unique ID, the CSMS may have to concatenate the EVSE ID with the Transaction ID, or to generate a unique identifier (like a UUID) and keep a mapping internally.
The API endpoint can be used to send each transaction event separately or in batches, as long as the CSMS sends events as fast as possible.

`POST /csms/{csmsId}/transactions/{transactionId}/charging-states`

Charging State enables Dreev to :

free power for other transactions in case of a charge being suspended
increase power for a transaction whenever a vehicle starts charging again.

Find below the mapping between OCPP 2.0 TransactionEvent.chargingState and Dreev Charging State :

OCPP 2.x TransactionEvent.charging State	Dreev Charging State
`Charging`	`CHARGING`
`EVConnected`	`SUSPENDED_OTHER`
`SuspendedEV`	`SUSPENDED_BY_VEHICLE`
`SuspendedEVSE`	`SUSPENDED_BY_EVSE`
`Idle`	`SUSPENDED_OTHER`

In OCPP 1.6 the status attribute of StatusNotification message mixes the EVSE availability, its operating status and its charging state.

Find below the mapping between OCPP 1.6 StatusNotification.status and Dreev Charging State.

OCPP 1.6 StatusNotification.status	Dreev Charging State
`Available`	❌
`Charging`	`CHARGING`
`Preparing`	`SUSPENDED_OTHER`
`SuspendedEV`	`SUSPENDED_BY_VEHICLE`
`SuspendedEVSE`	`SUSPENDED_BY_EVSE`
`Finishing`	`SUSPENDED_OTHER`
`Reserved`	❌
`Unavailable`	❌
`Faulted`	❌

Example OCPP 1.6 Message - `StatusNotification`

{
  "connectorId":1,
  "errorCode":"EVCommunicationError",
  "status":"SuspendedEV",
  "timestamp":"2023-01-01T01:01:01Z"
}

Example OCPP 2.0 Message - `TransactionEvent (updated)`

{
  "eventType":"Updated",
  "timestamp":"2023-01-01T01:01:01Z",
  "triggerReason":"EVCommunicationLost",
  "seqNo":10,
  "transactionInfo":{
    "transactionId":"CSMS-EVSE-1337-TX-0033",
    "chargingState":"SuspendedEV"
  }
}

Corresponding CSMS API call

{
  "state":"SUSPENDED_BY_VEHICLE",
  "timestamp":"2023-01-01T01:01:01Z"
}

`POST /csms/{csmsId}/transaction-measurements`

Sending measurements. This endpoint can handle batches of measurements for multiple EVSEs at once.

The measurements taken during the transaction serve two main functions:

Knowing the vehicle's state of charge (SoC): if a vehicle is fully charged, Dreev can assign power to other EVSEs.
Monitoring (Energy and Power) the smart charging process and the proper application of the commands by the EVSE.

Measurements should be taken by the EVSEs and sent to Dreev at a minimum frequency of 5 minutes.

Ideally, these measurements should be taken at a fixed time (Clock Aligned), but this is not a blocker unless services are to be provided to the grid.

OCPP Measurand	Dreev Measurement Type	Units
`Energy.Active.Import.Register`	`ENERGY_IMPORT`	`Wh` or `kWh`
`Energy.Active.Export.Register`	`ENERGY_EXPORT`	`Wh` or `kWh`
`Power.Active.Import` `Power.Active.Export`	`POWER`	`W` or `kW`
`SoC`	`SOC`	`%`
`Current.Import` `Current.Export`	`CURRENT`	`A`
`Frequency`	`FREQUENCY`	`Hz or mHz`

Note:

Power and energy measurements should come from the Inlet interface. In OCPP, measurements with location = Inlet should be retained.
Frequency measurements are only necessary to provide certain system services in V2G.
If no phase is supplied, then Dreev assumes that the measurand applies to all phases (ALL).
OCPP has Import & Export values for Current and Active Power.
An EVSE can only be charging or discharging at a specific instant, so Dreev only has one value for POWER and CURRENT that can be either positive or netgative.
Because an EVSE can charge and discharge during a given period, Dreev has different values for energy import and export indexes.

Example OCPP 1.6 Message - `MeterValues`

EVSE ID : CSMS-EVSE-1337

{
  "connectorId":1,
  "transactionId":33,
  "meterValue":[
    {
      "timestamp":"2023-01-01T00:15:00",
      "sampledValue":[
        {
          "value":"80.0",
          "measurand":"SoC",
          "location":"EV",
          "unit":"Percent"
        },
        {
          "value":"6.0",
          "measurand":"Power.Active.Import",
          "location":"Inlet",
          "unit":"kW"
        },
        {
          "value":"1.2",
          "measurand":"Energy.Active.Import.Register",
          "location":"Inlet",
          "unit":"kWh"
        },
        {
          "value":"50.0",
          "measurand":"Current.Import",
          "location":"Inlet",
          "unit":"A"
        }
      ]
    }
  ]
}

Example OCPP 2.0 Message - `TransactionEvent (updated)`

{
  "eventType":"Updated",
  "timestamp":"2023-01-01T00:15:00Z",
  "triggerReason":"MeterValueClock",
  "seqNo":8,
  "transactionInfo":{
    "transactionId":"CSMS-EVSE-1337-TX-0033"
  },
  "evse":{
    "id":1,
    "connectorId":1
  },
  "meterValue":[
    {
      "timestamp":"2023-01-01T01:00:00Z",
      "sampledValue":[
        {
          "value":80.0,
          "context":"Sample.Clock",
          "measurand":"SoC",
          "location":"EV",
          "unitOfMeasure":{
            "unit":"Percent"
          }
        },
        {
          "value":6.0,
          "context":"Sample.Clock",
          "measurand":"Power.Active.Import ",
          "location":"Inlet",
          "unitOfMeasure":{
            "unit":"kW"
          }
        },
        {
          "value":1.2,
          "context":"Sample.Clock",
          "measurand":"Energy.Active.Import.Register",
          "location":"Inlet",
          "unitOfMeasure":{
            "unit":"kWh"
          }
        },
        {
          "value":50.0,
          "context":"Sample.Clock",
          "measurand":"Current.Import",
          "location":"Inlet",
          "unitOfMeasure":{
            "unit":"A"
          }
        }
      ]
    }
  ]
}

Corresponding CSMS API call

{
  "transactions":[
    {
      "transactionId":"CSMS-EVSE-1337-TX-0033",
      "measurements":[
        {
          "type":"SOC",
          "value":80,
          "unit":"%",
          "timestamp":"2023-01-01T00:15:00"
        },
        {
          "type":"POWER",
          "value":6,
          "unit":"kW",
          "timestamp":"2023-01-01T00:15:00"
        },
        {
          "type":"ENERGY_IMPORT",
          "value":1.2,
          "unit":"kWh",
          "timestamp":"2023-01-01T00:15:00"
        },
        {
          "type":"CURRENT",
          "value":50,
          "unit":"A",
          "timestamp":"2023-01-01T00:15:00"
        }
      ]
    }
  ]

Charging Commands (during the transaction)

Dreev calculates charging commands every few minutes. The latest charging command provided by Dreev must override the previous command received by the EVSE.

The charging profile purpose (OCPP Charging Profile purpose = TxProfile) takes priority over the default charging profile purpose (OCPP Charging Profile purpose = TxDefaultProfile).

In order to get as close as possible to real time when using pull mode, the CSMS must retrieve the charging commands calculated by Dreev at least every minute.

`GET /csms/{csmsId}/transactions/{transactionId}/charging-commands/latest`

The latest charging command computed for a given transaction.

Below is a description of the Charging Command attributes.

Attribute	Description
`id`	Unique identifier of the charging command. This attribute must be kept by CSMS in order to update the status of the command after its application by the EVSE.This is the `chargingCommandId` in the endpoint path `/charging-commands/{chargingCommandId}/status`.
`transactionId`	The transaction on which the command is to be applied.
`type`	Command type. Always `CHARGING_PROFILE` for one-way EVSEs implementing a standard "non-V2X" OCPP version.For V2X commands, refer to the V2G (🚧 Work In Progress) section of the documentation.
`command.elements[]`	Ordered table containing the different elements of the charging schedule. Each element contains an application period and a power.
`command.elements[].power`	The power to be applied, in Watts (W).
`command.elements[].from`	Absolute start date of the element.ISO-8601 Date Time format.
`command.elements[].to`	Absolute end date of the element.May be nullable for the last item in the list (command applied until further notice).ISO-8601 Date Time format.
`status`	The status of the command.The commands that have just been calculated by Dreev have the status `PENDING`, which means that they have to be sent to the EVSE.Once the CSMS has obtained an asynchronous response to the `SetChargingProfile` message, this status must be updated via the endpoint `/charging-commands/{chargingCommandId}/status`.

The start date from of the first element corresponds to the startSchedule date of the OCPP profile. The date/time periods in Dreev’s commands must then be translated into offset seconds in the OCPP profile.

The two examples below are equivalent. They show a command containing two elements:

A first period of 5min (300s) from 00:00 to 00:05 with a power limit of 0W
A second period from 00:05 with no end date and a power limit of 10,000 W

Example of Charging Command :

{
  "id": "dreev-7890",
  "evseId": "string",
  "transactionId": "354",
  "requestedAt": "2021-02-01T00:00:00Z",
  "type": "CHARGING_PROFILE",
  "command": {
    "elements": [
      {
        "power": 0,
        "validity": {
          "from": "2021-02-01T00:00:00Z",
          "to": "2021-02-01T00:05:00Z"
        }
      },
      {
        "power": 10000,
        "validity": {
          "from": "2021-02-01T00:05:00Z"
        }
      }
    ]
  },
  "status": "PENDING"
}

Example of the corresponding OCPP 1.6 SetChargingProfile message:

{
  "connectorId": 1,
  "csChargingProfiles": {
    "transactionId": 354,
    "chargingProfileId": 1234,
    "stackLevel": 1,
    "chargingProfilePurpose": "TxProfile",
    "chargingProfileKind": "Absolute",
    "chargingSchedule": {
      "chargingRateUnit": "W",
      "chargingSchedulePeriod": [
        {
          "startPeriod": 0,
          "limit": 0,
        },
        {
          "startPeriod": 300,
          "limit": 10000,
        }
      ],
      "startSchedule": "2021-02-01T00:00:00Z",
    }
  }
}

`POST /charging-commands/{chargingCommandId}/status`

Updating the status of a charging command after transmission to the EVSE.

The message contains the status of the EVSE's response, as well as the date on which the EVSE acknowledged the command.

Once updated, the status of the latest command is changed in the endpoint /csms/{csmsId}/transactions/{transactionId}/charging-commands/latest (until a new command replaces the previous one, with a new ID and the status PENDING).

SetChargingProfile response OCPP	Charging Command status Dreev
`Accepted`	`ACCEPTED`
`Rejected`	`REJECTED`
`NotSupported`	`ERROR`

Default Charging Commands

The default charging commands determine the behavior of the EVSE in the absence of a charging command. They are useful in several cases:

EVSE disconnected.
Before receiving the first charging command at the start of a transaction.

The default charging commands allow all the EVSEs to charge simultaneously. When the electrical installation has local constraints, the default commands are suboptimal: the maximum power supplied by each EVSE may be lower than the "physical" maximum power of the EVSE.

The nominal scenario is that the Dreev platform distributes power in such a way as to maximize the use of all the EVSEs.

The default charging commands are computed each time the electrical installation changes, which should be very rare. However, these commands can be recalculated if the project scope changes.

`GET /csms/{csmsId}/evses/{evseId}/default-charging-commands/latest`

Retrieve the latest default command calculated by Dreev.

The default charging command schedule is to be applied relatively to the start date of the transaction.

Below is a description of the attributes of interest to the CSMS.

Attribute	Description
`id`	Unique identifier of the charging command. This attribute must be kept by the CSMS in order to update the status of the command after its application by the EVSE.This is the `chargingCommandId` in the path of the endpoint `/charging-commands/{chargingCommandId}/status`.
`evseId`	EVSE on which the command is to be applied.
`command.elements[]`	Ordered table containing the different elements of the charging schedule. Each element contains a duration and a power.
`command.elements[].power`	The power to be applied, in Watts (W).
`command.elements[].duration`	Duration of the element. Format : ISO-8601 Duration.
`status`	The status of the default command (same management as `charging-commands`).

The two examples below are equivalent:

A first period from the beginning of the transaction, for a duration of 2min, with a limit of 0W
A second period, from the start of the transaction + 2min, for a duration of one minute, with a limit of 5000W
A third period, from the beginning of the transaction + 3min, for an infinite duration, with a limit of 10000W

Example of a Default Charging Command:

{
  "id": "dreev-7890",
  "evseId": "string",
  "requestedAt": "2021-02-01T00:00:00Z",
  "type": "CHARGING_PROFILE",
  "command": {
    "elements": [
      {
        "power": 0,
        "duration": "PT2M"
      },
      {
        "power": 5000,
        "duration": "PT1M"
      },
      {
        "power": 10000
      }
    ]
  },
  "status": "PENDING"
}

Example of the corresponding OCPP 1.6 SetChargingProfile message:

{
  "connectorId": 1,
  "csChargingProfiles": {
    "transactionId": 354,
    "chargingProfileId": 1234,
    "stackLevel": 1,
    "chargingProfilePurpose": "TxDefaultProfile",
    "chargingProfileKind": "Relative",
    "chargingSchedule": {
      "chargingRateUnit": "W",
      "chargingSchedulePeriod": [
        {
          "startPeriod": 0,
          "limit": 0,
        },
        {
          "startPeriod": 120,
          "limit": 5000,
        },
        {
          "startPeriod": 180,
          "limit": 10000,
        }
      ]
    }
  }
}

`POST /default-charging-commands/{defaultChargingCommandId}/status`

Updating the status of a default charging command after transmission to the EVSE.

Same as /charging-commands/{chargingCommandId}/status.

Charging Requirements (mobility needs)

Depending on the use case, these endpoints are optional :

Dreev provides its mobile application or portal to the end user : the CSMS does not need to implement this functionality
CSMS collects the end user’s charging requirements: CSMS must transmit the charging requirements to Dreev through the API

There are several types of Charging Requirements:

Charging Requirement Type	Description
SoC Requirements	SoC target for a given period. This requirement can be expressed in a one-time or recurring manner. It is the most important objective in Dreev's charging strategy, right after the physical constraints of the electrical installation.
Instant Charge	a.k.a. Emergency charge, Priority charging or Boost. This request reduces the benefits of smart charging, as Dreev will charge the vehicle as quickly as possible. This "charge as soon as possible" mode still takes into account the constraints on the electrical installation.
Trips	For fleet management tools. Allows the definition of vehicle trips, with a precise exit date and an energy requirement to complete a trip. Unlike SoC Requirements which guarantee a state of charge without assuming the end of the transaction, here Dreev anticipates the end of the transaction.

`POST /transactions/{transactionId}/instant-charge`

Instant Charge request from the EVSE or the user.

`DELETE /transactions/{transactionId}/instant-charge`

Stop the Instant Charge.

Identification

Without a vehicle/EVSE protocol that reliably identifies vehicles for each transaction (such as ISO-15118), Dreev allows the CSMS to associate a unique badge identifier (OCPP idTag) with a vehicle.

CSMS API Endpoints

Monitoring of EVSE communications

OCPP Message Example : Heartbeat Request

Corresponding CSMS API call

Transactions

OCPP 1.6 Messages Examples

OCPP 2.0 Messages Examples

Corresponding CSMS API call

Example OCPP 1.6 Message - StatusNotification

Example OCPP 2.0 Message - TransactionEvent (updated)

Corresponding CSMS API call

POST /csms/{csmsId}/transaction-measurements

Example OCPP 1.6 Message - MeterValues

Example OCPP 2.0 Message - TransactionEvent (updated)

Corresponding CSMS API call

Charging Commands (during the transaction)

Default Charging Commands

Charging Requirements (mobility needs)

Identification

OCPP Message Example : `Heartbeat` Request

Example OCPP 1.6 Message - `StatusNotification`

Example OCPP 2.0 Message - `TransactionEvent (updated)`

`POST /csms/{csmsId}/transaction-measurements`

Example OCPP 1.6 Message - `MeterValues`

Example OCPP 2.0 Message - `TransactionEvent (updated)`