A gateway manages appliances in the local network and establishes the connection to our cloud (API server). Every gridBox is a gateway.


A system belongs to an account and contains a single gateway. It represents a physical installation site such as households or an office (XENON Home), or simply a collection of charging stations (XENON Charge).


Devices that produce or consume energy and can be monitored and/or controlled by a gridBox. Appliances are charging stations, batteries, inverter, meters, etc... They are also called DERs (Distributed Energy Resources).


As shown in the diagram, our organizational structure consists of accounts, users, customers and systems. It allows to manage users in a flexible way as well as controlling system access rights. In the following, each term is briefly defined.


An account is an organizational unit for managing access to systems/gateways/appliances for multiple users. It is built as a tree structure, thus allowing multiple levels of organization via sub-accounts.


A customer is a special kind of account that is directly associated with the end-user owning the gridBox. A customer account is the intermediary to manage which users have access to the system. When thinking of an organizational tree structure (see Account), it is always the leaf account which directly sits above the end-user.


A user contains information required to authenticate with gridX cloud services, such as name, email address and contract information. Users are directly bound to an associated account or if it is an end-user, the customer account.

Raw Measurement

Raw measurements are data points of appliances monitored by the gridBox (e.g. meter readings ... ).

System Measurement

A measurement contains power/energy values associated with appliances that belong to a system. Measurements consist of integrated data points for a specified time interval and are derived by calculating the combined meter readings of all appliances.


The resolution is the time interval in which measurements are aggregated. The result is a downsampled measurement.

  • The raw measurements we receive from the appliances are periodically aggregated in specific resolutions, e.g. 15 minutes, 1 day, 1 month etc.
  • The resolution of the raw measurements themselves depends on the appliance.
  • Resolutions offer the possibility to get a broader view on measurements.
  • For example, how the energy consumption changed month over month, or day by day, etc.
  • The different resolutions are accessible through the usual measurement endpoints by specifying the desired resolution as a query parameter.


The inventory is a collection of all metadata about systems, systempools, clusters, gateways and appliances that are owned by an account.

System Pool

Systempool is a collection of systems to build:

  • Communities
  • Virtual power plants

The measurements of systems in a system pool are aggregated and can be accessed through the API.


A cluster is a group of appliances belonging to the same system. It is possible to have nested clusters.


Reflects the current state of an appliance, which includes

  • The latest measurement update: power, state-of-charge, etc.
  • The resulting operating boundaries: a summary of all constraints applied to the appliance and defining its operating boundaries. For example, to preserve a certain energy level, the minEnergy/maxEnergy values returned by the flexibilities may differ from their physical counterparts.
  • The latest set point applied to the appliance

Flexibility is not set by the API user, they can only be read. The concept of flexibility is general to all appliances.

  • In the case of an EVCS, the minPower and maxPower values reflect the min and max total operating power range of the EVCS; the power is the latest power value
  • In the case of a meter at the global coupling point with the grid, the minPower (negative value) is the total feedin power limit, and the max power (positive value) is the total import limit. The power, if negative, reflects power being exported to the grid, whereas if positive, reflects the power being imported from the grid
  • In the case of a battery, the min power (negative value) represents the max discharging power, whereas the max power (positive value) represents the max charging power. The power, when negative, reflects the fact that the battery is discharging, whereas when positive, reflects the power being charged by the battery.


Appliance constraints allow setting operational constraints to an appliance. Constraints can consist of:

  • Operational ranges, i.e min/max values. For example, the minimum power that an EV can charge is 4.14kW and the maximum power is 22kW. The maximum capacity of a battery is 5000Wh.
  • Set points, i.e. the control value directly expected to be applied to an appliance. For example, to charge an EV with 15kW.

To each constraint is associated:

  • A date after which the constraint expires (invalidAt)
  • A priority level: 0-low, infinity-high. In case multiple constraints are set to a same field, or if conflicting constraints are set, the priority level allows to determine the final operating constraint.

The constraint with priority 1 is considered first. In this case, the constraint with priority 0 will be discarded.
They can be set by a user or by the appliance’s driver themselves (physical limits).

  • The physical operation limits of the appliance are always associated to the highest priority level
  • A local-user specific input may also trigger additional constraints. For example, if the manager of an EV fleet would like the fleet to charge only with PV surplus, but the car owner needs his car to charge faster, there might be conflicting constraints.

The priority of each constraint will therefore also depend on the priority associated with the emitter of the constraint.

Multiple constraints can therefore coexist for the same property, and are summarized into a single operational boundary in the flexibility.