Smartgrid Services

These web services are used to manage the smartgrid. They require the id of a charging station as managed by the smartgrid.

This API uses SI units: powers values are always expressed in watt (W), energy is expressed in joules (J).

Power curve

The power curve is represented as following:

{
    timestamp: power,
    ...
}

Each timestamp is a Unix UTC timestamp (seconds since midnight UTC, 1 January 1970), rounded to fifteen minutes (:00, :15, :30, :45). The value \(\mathrm{power}_i\) is only valid in the half open interval \([\mathrm{stamp}_{(i-1)}, \mathrm{stamp}_i[\).

Power is specified in watt.

Charging modes

There are currently two charging modes implemented:
  1. Balanced Charging: try to spread the power consumption over time.
  2. Maximum Charging: consume all available power and charge vehicles as quickly as possible.

Smartgrid control

POST /smartgrid/(chargingStationId)

Enable the smartgrid for this charging station.

Status Codes:
  • 204 – Unknown charging station.
DELETE /smartgrid/(chargingStationId)

Disable the smartgrid for this charging station.

Status Codes:
  • 204 – Unknown charging station.
GET /smartgrid/(chargingStationId)

Check whether the smartgrid is enabled for this station.

Returns

{
    "enabled": bool
}
Status Codes:
  • 204 – Unknown charging station.

Smartgrid functions

PUT /smartgrid/(chargingStationId)/power/curve

Set the maximum power curve, overwrite all previous values between the first and last timestamp of the new curve. This will not add nor erase values from the past.

Query Parameters:
 
  • powerCurve – the power curve in JSON format as described in the Power curve section.
Status Codes:
  • 204 – Unknown charging station.
  • 1001 – Smartgrid is not enabled on this station.
GET /smartgrid/(chargingStationId)/power/curve

Get values from the maximum power curve. If timeFrom or timeTo is not specified, then all values will be returned.

Returns a Power curve.

Query Parameters:
 
  • timeFrom? – Start of the period.
  • timeTo? – End of the period.
Status Codes:
  • 204 – Unknown charging station.
  • 1001 – Smartgrid is not enabled on this station.
DELETE /smartgrid/(chargingStationId)/power/curve

Delete values from the maximum power curve between timeFrom and timeTo. This will not erase values from the past.

Query Parameters:
 
  • timeFrom? – Start of the period.
  • timeTo? – End of the period.
Status Codes:
  • 204 – Unknown charging station.
  • 1001 – Smartgrid is not enabled on this station.
GET /smartgrid/(chargingStationId)/power/log

Get the maximum power curve that was used to control the charging station.

Returns a Power curve.

Query Parameters:
 
  • timeFrom? – Start of the period.
  • timeTo? – End of the period.
Status Codes:
  • 204 – Unknown charging station.
  • 1001 – Smartgrid is not enabled on this station.
PUT /smartgrid/(chargingStationId)/power/mode

Change the charging mode.

Query Parameters:
 
  • mode – the index of the new charging mode as described in the Charging modes section.
Status Codes:
  • 204 – Unknown charging station.
  • 1001 – Smartgrid is not enabled on this station.
GET /smartgrid/(chargingStationId)/power/mode

Get the charging mode as described in the Charging modes section.

{
    "mode": int,
}
Status Codes:
  • 204 – Unknown charging station.
  • 1001 – Smartgrid is not enabled on this station.
PUT /smartgrid/(chargingStationId)/power/override

Set a maximum value (W) that overrides the power curve. Note that the power curve will be completely ignored while this value is set.

Query Parameters:
 
  • powerValue – an integer in watt
Status Codes:
  • 204 – Unknown charging station.
DELETE /smartgrid/(chargingStationId)/power/override

Stop overriding the power curve.

Status Codes:
  • 204 – Unknown charging station.
GET /smartgrid/(chargingStationId)/power/override

If set, get the overruling maximum value, otherwise null.

{
    "powerValue": int
}
Status Codes:
  • 204 – Unknown charging station.
GET /smartgrid/(chargingStationId)/power

Get information about the station’s power situation.

Returns the following object:

{
    "mode": int,            // smartgrid mode
    "limit": int,           // current power limit (W), this may be null if the smartgrid has never run yet.
    "physicalLimit": int,   // the physical limit (W) for this station, may be null.
    "overridingLimit": int, // the overriding limit (W) for this station, may be null.
    "overriding": boolean,  // true if the power curve is being overrided by a constant value
    "allocated": int,       // total allocated power (W)
    "sessions": {
        sessionId: int,     // allocated power per active session (W)
        ...
    },

    "minimum": int,         // Get the minimum power (W) to guarantee that all
                            // cars are charged in time. The returned value is an
                            // upper bound estimation of the actual required
                            // minimum power.

    "maximum": int          // Get the total power (W) if all cars of which the
                            // battery is not yet completely charged would charge
                            // at their maximum power (or the socket's maximum).
}
Status Codes:
  • 204 – Unknown charging station.
  • 1001 – Smartgrid is not enabled on this station.
GET /smartgrid/(chargingStationId)/sessions

Get information about the active sessions for the given charging station.

{
    "chargingSessionId": int,
    "socketId": int,
    "kiloWattHour": double,                 // kWh
    "batteryCapacity": double,              // kWh
    "estimatedBatteryPercentage": double,
    "powerValue": int,                      // W
    "timeStarted" int,                      // Unix timestamp
    "requestedDurationSeconds": int,
}
GET /smartgrid/(chargingStationId)/simulation

Run a simulation over a defined period. Optionally a power curve or a power value can be set to override the current curve without replacing it.

The optional power curve can be sent as a JSON object (formatted as described above) in the body of the HTTP request.

If the powerValue parameter is set then this is the only value that is used in the simulation., otherwise the optional power curve is used.

When the optional curve does not supply a power value (either because there is no curve or it is not defined at a given timestamp) then values are taken from the existing smartgrid configuration. That means either the currently overriding value or a value from the current power curve.

Returns a mapping of all sessions and their status after the simulation. Note that all fields may be null if the vehicle type and/or scheduled departure are unknown.

{
    "success": boolean,
    "status": {
        "sessionId": {
            "chargingSession": ChargingSession,  // ChargingSession object
            "maximumBatteryCapacity": double,    // Capacity of a full battery (kWh)
            "currentBatteryCapacity": double,    // Battery capacity before the simulation (kWh)
            "expectedBatteryCapacity": double,   // Expected battery capacity when the car departs (kWh)
            "potentialBatteryCapacity": double,  // Potential battery capacity if the car
                                                 //   could charge at full power (kWh)
            "departure": long,                   // Expected departure (unix timestamp in seconds)
            "extraEnergyNeeded": long,           // Extra energy needed to achieve a battery status
                                                 //   of x% when the vehicle departs (kWh)
                                                 //   where `x` is the threshold property.
        },
        ...
    }
}
Query Parameters:
 
  • until? – end of the simulation period (default: last known scheduled departure of the cars)
  • mode? – the charging mode (default: the currently used charging mode)
  • powerValue? – a power value that overrides the power curve.
Status Codes:
  • 204 – Unknown charging station.
  • 1001 – Smartgrid is not enabled on this station.