Skip to main content

Site and Site Configuration

Site​

A site in our EMS system represents an entity such as a factory, business office, or apartment building. Typically, a site is defined by a single connection to the electrical grid. Each site operates as an independent entity, managing energy flow, monitoring devices, and optimizing operations for its designated grid connection.

Site Configuration​

The site configuration defines the topology of the site that requires optimization. Without a proper configuration, the system cannot generate accurate optimization recommendations.

This section provides an overview of the key components of a typical site configuration, which consists of two main elements: the collector list and the device list.

Collector List​

The collector list defines the relevant collectors within the electrical grid being optimized. Future updates will support multiple collectors with different commodities (e.g., electricity, gas, hot water), but currently, only electricity collectors are supported.

Collectors are organized in a parent-child hierarchy, where different attributes may be required depending on their role.

Collector​

The collector schema applies to both parent (main) and child (sub) collectors. Child collectors can additionally specify phase and phase_permutations fields.

{
  "name": "main_collector",
  "children": [
    null
  ],
  "line_current": 400,
  "safe_line_current": 300,
  "min_phase_current": 0,
  "phase_voltage": 230,
  "commodity": "electricity",
  "nb_of_phases": 0
}

Collector

    phase_permutations object

    Specify the phase mapping between this asset (child) and its parent collector (parent). Leave unset when the wiring is unknown; phase-aware control (use_topology) requires every asset's mapping to be declared, so a single unset mapping makes the controller fall back to the worst case. The root collector is exempt: it is the grid connection, whose phases are the reference frame every other mapping is expressed against, so the controller always treats it as the identity and it may only be left unset or declared as the identity.

    anyOf
    nameName (string)required
    children object

    The children of this collector. This is used to create a tree structure.

    anyOf
  • Array [
    • $ref
  • ]
    • line_currentLine Current (integer)required

    The line current in Ampere.

    safe_line_current object

    An optional, safer line current in Ampere used by the optimizer instead of line_current when set.

    anyOf
    integer
    min_phase_current object

    An optional lower bound in Ampere per phase. Set it to 0 on the main collector to forbid injection into the grid.

    anyOf
    number
    phase_voltagePhase Voltage (integer)required

    The phase voltage is in Volt.

    commodityCommodity (string)
    Default value: electricity
    1P_3P

    Specifies whether the collector is single-phase (1P) or three-phase (3P).

    Default value: 3P
info

Setting a different line voltage in a child collector allows the inclusion of transformers, but transformer losses are not accounted for.

Device List​

3-Phase Charging Station​

{
  "name": "LR34_001",
  "collector": "main_collector",
  "type": "charging_pole_3phase",
  "line_current": 32
}

AC Charging Pole (3-Phase)

    nameName (string)required

    The name of the device itself. This value will be used as the asset ID in the rest of the API.

    collectorCollector (string)required

    The name of the collector to which this device is connected.

    ingress_validation object

    Overrides the site-level ingress validation config for this asset. When set, controls how often measurements are expected during active and inactive transactions. When null, the site-level configuration is used.

    anyOf
    typeType (string)
    Constant value: charging_pole_3phase
    Default value: charging_pole_3phase
    line_currentLine Current (integer)required

    The line current in Ampere.

    pin_to_phase_mappingrequired

    Defines how charging pole pins map to the collectors' phases. For more information see the 'Key Concepts - Site configuration' section in the documentation.

pin_to_phase_mapping

In order to balance power over the phases when lots of single phase charging sessions are ongoing, it is common practice to rotate the phases of the charging stations. In order to make sure that the optimization software calculates the power on each phase correctly, it is important that phase mapping of each individual charging pole is correctly configured. The figure below shows the pinning of a CCS type 2 connector, having 3 pins connecting the phases of the grid to the car. On the connector they are referred to as L1, L2 and L3 but that does not mean that they are actually connected to the L1, L2 and L3 phases of the grid. In the terminology below, pins refer to the pins of the connector.

Image

The figure below shows how rotating phases should be configured in the pin_to_phase_mapping field of a three-phase charging pole. The pin_list refers to the physical pins on the connector, the phase_list refers to the phases of the grid.

Image

Single-Phase Charging​

Single-phase charging is handled using the same charging_pole_3phase device type. To configure a charging pole for single-phase operation, set up the pin_to_phase_mapping with only the pin that will be used. The number of phases used during a charging session is determined by the usedChargingPins field in the transaction payload.

info

The charging pole inherits the voltage from the collector it is connected to.

3-Phase Forecasted Series​

A forecasted series can be added for any non-controllable three-phase device with predictable energy patterns.

info

We support photovoltaic (PV) and uncontrollable load (UCL) forecasting.

{
  "name": "LR34_001",
  "collector": "main_collector",
  "type": "forecasted_series_3phase",
  "line_current": 32,
  "should_be_aggregated": false
}

Forecasted 3-Phase Device

    phase_permutations object

    Specify the phase mapping between this asset (child) and its parent collector (parent). Leave unset when the wiring is unknown; phase-aware control (use_topology) requires every asset's mapping to be declared, so a single unset mapping makes the controller fall back to the worst case.

    anyOf
    nameName (string)required

    The name of the device itself. This value will be used as the asset ID in the rest of the API.

    collectorCollector (string)required

    The name of the collector to which this device is connected.

    ingress_validation object

    Overrides the site-level ingress validation config for this asset. When set, controls how often measurements are expected during active and inactive transactions. When null, the site-level configuration is used.

    anyOf
    typeType (string)
    Constant value: forecasted_series_3phase
    Default value: forecasted_series_3phase
    line_currentLine Current (integer)required

    The line current in Ampere.

    forecast_typerequired

    Defines the type of forecast to be used for this device.

    should_be_aggregatedShould Be Aggregated (boolean)
    Default value: false
    curtailment_mode

    How the controller may curtail this device's production to respect the grid minimum. NONE never curtails; CONTINUOUS curtails to any level. Only relevant for PV devices.

    Default value: none

This document provides a structured guide to configuring sites within the EMS system, ensuring accurate energy optimization for different setups.