Load Balancing (v1)

Download OpenAPI specification:Download

Cloud-based charging station Load Balancing

Some locations may have variable electrical load, which means that the total current can rise above the nominal rate of the location's switchboard fuse and lead to a power failure.

"Power Groups" feature in ChargEye allows setting a limit how much power a group of charging station is allowed to consume at any given time. Limiting the load not only protects the switchboard fuse, but can also help avoid additional investments in grid connection and cabling.

A power group may consist of subgroups and multiple charging stations. All charging stations in the same group/subgroup share a common limit. The limit is set in either AC amperes (input current) or DC kilowatts (output power). The available power is distributed between the chargers based on the demand and usage at the chargers.

Load balancing can be static or dynamic. In static load balancing, the used electric current measurement data is non real-time data. while dynamic load balancing is based on real-time electric current usage data provided by Kempower Load Manager Kit hardware.

Update a Power Group

patch/loadBalancing/powerGroup/{powerGroupId}

Modify parameters of the given Power Group. With this endpoint, you may give just a partial object.

To change the maximum amperage a power group,

SecuritybearerAuth
Request
path Parameters
powerGroupId
required
string
Request Body schema: application/json
required
required
object (PatchPowerGroup)
actualSiteFuseSize
number

Actual site fuse size in amperes. For information purposes only.

algorithm
string

Algorithm version

Value: "AdjustLimitBasedOnMeterAndApproximateUsage"
allocateFullCapacity
boolean

When enabled, allocates all available capacity (power or current) to the chargers.

defaultMinPowerReservationKw
number

Reserve at least this much power at all times. May be overriden at station level.

defaultOfflinePowerKw
number

If charger is offline, assume used power is this. May be overriden at station level.

dynamicDefaultMinCurrentReservationPerChargerA
number

Dynamically calculated minimum current reservation for per charger under this power group

dynamicMaxCurrentA
number

Maximum electric current (amperes) this power group is allowed to use currently (dynamic value). Applicable only if limitationType is 'InputCurrent'. If so, "maxPowerKw" should not be set.

This value is typically adjusted automatically based on measured current (external measurement device).

The actual effective maximum current for this power group is calculated as such: Min(maxCurrentA, dynamicMaxCurrentA)

dynamicMaxCurrentADivisibleBy
number or null

Divider for limit to be floored to nearest whole number given. E.g. dynamicMaxCurrentADivisibleBy = 50, limit: 270A -> 250A Default 10

dynamicMaxCurrentAIncreaseThresholdMinutes
number or null

How many minutes until limit can be increased after last update to dynamicMaxCurrentA Default 1 minute

dynamicMaxCurrentAUpdatedTimestamp
string

Timestamp when dynamicMaxCurrentA was updated

groupId
string

Group UUID

groupName
string
limitationType
string

Is this power group limiting output power (unit kW), or input current (unit A)?

If not set, defaults to OutputPower

Enum: "InputCurrent" "OutputPower"
loadBalancingEnabled
boolean

Is the load balancing algorithm enabled

maxCurrentA
number

Maximum electric current (amperes) this power group is allowed to use. Applicable only if limitationType is 'InputCurrent'. If so, "maxPowerKw" should not be set.

This should be regarded as the normal maximum if no external limits, and set in commissioning phase.

The actual effective maximum current for this power group is calculated as such: Min(maxCurrentA, dynamicMaxCurrentA)

maxPowerKw
number

Maximum output power of the group, applicable only if limitationType is undefined or 'OutputPower'. If so, maxCurrentA and dynamicMaxCurrentA should not be set.

object

Latest 10 history items of the site measurement samples from the site meter. Contains ~30 seconds of history.

meterId
string or null

If power metering based control is enabled, this is the meter id

meteredCurrentUsageA
number

Current metered usage (amperes) from the meter (see meterId field)

parentPath
Array of strings

Array of parent groupIds, empty if "root"

reservationMarginForActiveChargersKw
number or null

Margin added to power reservation when charger is active. E.g. reservationMarginForActiveChargers = 10 -> Charger using 12kW, power reservation for charger = 12kw + 10kw.

safeModeMaxLimitA
number or null

Fall back limit if latest measurement at meteredCurrentUsageA is older than duration determined at safeModeTriggerDurationS defaults to maxCurrentA

safeModeTriggerDurationSeconds
number or null

Duration how old can latest measurement at meteredCurrentUsageA be, if older than duration here, set fall back for dynamicMaxCurrentA, determined at safeModeSiteLimitA defaults to 30 seconds

strategy
string

Which strategy to use for load balancing? As of 2024-03-25, the default is lb2021, but it's possible to switch to lb2024 for the new strategy ("fair load balancing"). Later on we will consider changing the default strategy to lb2024.

Enum: "lb2021" "lb2024"
testingOnlyUseChargerMaxForEvse
boolean

If true, use charger's maxPowerACW for EVSEs instead of connector's maxPowerKwActual. Only meant to be used with virtual chargers where connector's maxPowerKwActual gets altered when charger limit is set.

timeThresholdToIncreasePowerSeconds
number or null

Time threshold in seconds to increase power for charger while EV is charging.

Responses
200

OK

Response Schema: application/json
success
required
boolean
401

Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission

Request samples
application/json
{
  • "group": {
    }
}
Response samples
application/json
{
  • "success": true
}

List Power Groups

get/loadBalancing/powerGroups

Get a list of top-level Power Groups defined in the system.

There can be sub-groups, such as for dividing a location's total electricity supply into different transforms, each with distinct maximum allowed load.

SecuritybearerAuth
Responses
200

OK

Response Schema: application/json
required
object
additional property
object (LBPowerGroup)
actualSiteFuseSize
number

Actual site fuse size in amperes. For information purposes only.

algorithm
string

Algorithm version

Value: "AdjustLimitBasedOnMeterAndApproximateUsage"
allocateFullCapacity
boolean

When enabled, allocates all available capacity (power or current) to the chargers.

defaultMinPowerReservationKw
number

Reserve at least this much power at all times. May be overriden at station level.

defaultOfflinePowerKw
number

If charger is offline, assume used power is this. May be overriden at station level.

dynamicDefaultMinCurrentReservationPerChargerA
number

Dynamically calculated minimum current reservation for per charger under this power group

dynamicMaxCurrentA
number

Maximum electric current (amperes) this power group is allowed to use currently (dynamic value). Applicable only if limitationType is 'InputCurrent'. If so, "maxPowerKw" should not be set.

This value is typically adjusted automatically based on measured current (external measurement device).

The actual effective maximum current for this power group is calculated as such: Min(maxCurrentA, dynamicMaxCurrentA)

dynamicMaxCurrentADivisibleBy
number or null

Divider for limit to be floored to nearest whole number given. E.g. dynamicMaxCurrentADivisibleBy = 50, limit: 270A -> 250A Default 10

dynamicMaxCurrentAIncreaseThresholdMinutes
number or null

How many minutes until limit can be increased after last update to dynamicMaxCurrentA Default 1 minute

dynamicMaxCurrentAUpdatedTimestamp
string

Timestamp when dynamicMaxCurrentA was updated

groupId
required
string

Group UUID

groupName
required
string
limitationType
string

Is this power group limiting output power (unit kW), or input current (unit A)?

If not set, defaults to OutputPower

Enum: "InputCurrent" "OutputPower"
loadBalancingEnabled
required
boolean

Is the load balancing algorithm enabled

maxCurrentA
number

Maximum electric current (amperes) this power group is allowed to use. Applicable only if limitationType is 'InputCurrent'. If so, "maxPowerKw" should not be set.

This should be regarded as the normal maximum if no external limits, and set in commissioning phase.

The actual effective maximum current for this power group is calculated as such: Min(maxCurrentA, dynamicMaxCurrentA)

maxPowerKw
number

Maximum output power of the group, applicable only if limitationType is undefined or 'OutputPower'. If so, maxCurrentA and dynamicMaxCurrentA should not be set.

object

Latest 10 history items of the site measurement samples from the site meter. Contains ~30 seconds of history.

meterId
string or null

If power metering based control is enabled, this is the meter id

meteredCurrentUsageA
number

Current metered usage (amperes) from the meter (see meterId field)

oadrId
string

Oadr ID mapping of the power group

parentPath
required
Array of strings

Array of parent groupIds, empty if "root"

reservationMarginForActiveChargersKw
number or null

Margin added to power reservation when charger is active. E.g. reservationMarginForActiveChargers = 10 -> Charger using 12kW, power reservation for charger = 12kw + 10kw.

safeModeMaxLimitA
number or null

Fall back limit if latest measurement at meteredCurrentUsageA is older than duration determined at safeModeTriggerDurationS defaults to maxCurrentA

safeModeTriggerDurationSeconds
number or null

Duration how old can latest measurement at meteredCurrentUsageA be, if older than duration here, set fall back for dynamicMaxCurrentA, determined at safeModeSiteLimitA defaults to 30 seconds

strategy
string

Which strategy to use for load balancing? As of 2024-03-25, the default is lb2021, but it's possible to switch to lb2024 for the new strategy ("fair load balancing"). Later on we will consider changing the default strategy to lb2024.

Enum: "lb2021" "lb2024"
object (LBSubNodes)
testingOnlyUseChargerMaxForEvse
boolean

If true, use charger's maxPowerACW for EVSEs instead of connector's maxPowerKwActual. Only meant to be used with virtual chargers where connector's maxPowerKwActual gets altered when charger limit is set.

timeThresholdToIncreasePowerSeconds
number or null

Time threshold in seconds to increase power for charger while EV is charging.

versionCreatedTimestamp
string
401

Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission

Request samples 
Response samples 
application/json
{
  • "tree": {
    }
}