GridBox Binding

The Viessmann GridBox (opens new window) is a energy management device which gathers information about produced and consumed electrical power from compatible energy meters, photovoltaic inverters, batteries, heat pumps, EV charging stations etc. and steers the connected components to increase the self consumption rate and efficiency of the system.

The Viessmann GridBox is a variety of the gridX Gateway (opens new window) and uses the gridX Xenon cloud service to upload the fetched data and deliver the data to the GridBox app and web service. The measured data (energy production, consumptions, etc.) cannot be accessed locally. However, thanks to the pioneer work in the unl0ck/viessmann-gridbox-connector (opens new window) repository, we can retrieve the data from the gridX cloud service using Rest-API calls. The API is documented here (opens new window).

This binding polls the "live data" API endpoint to gather the available data from the GridBox. It creates a GridBox thing with the channels representing the data points of the live data API call.

For connection to the cloud service, account E-Mail and password used to connect to the GridBox web service (opens new window) are required. Authentication is handled by a OAuth call generating a ID Token which is required as a bearer token for subsequent calls to the gridX API.

At the moment, only one API-"system" per account is supported by this binding. A "system" is the representation of a GridBox together with its connected appliances (PV inverter, heat pump etc.). The binding will use the first system ID retrieved by a call to the https://api.gridx.de/systems (opens new window) API.

Also, only the live data API endpoint is supported by the binding as it is the most interesting for openHAB use cases. There is another API endpoint for fetching aggregated measurement data which could be added in the future. Only the Viessmann GridBox variant is supported, other variants would need adaptions to the OAuth mechanism.

This binding is not endorsed or supported by Viessmann or gridX. Arbitrary breaking changes to the API can happen at any time, resulting in this binding failing to retrieve the data.

Supported Things

The following thing can be created with the binding:

• gridbox: A thing representing the GridBox, tied to an account of the Viessmann GridBox.

Discovery

No support for auto discovery at the moment.

Thing Configuration

The following configuration parameters are available on the GridBox thing:

gridbox Thing Configuration

Name	Type	Description	Default	Required	Advanced
email	text	E-Mail address used to log in to the GridBox API	N/A	yes	no
password	text	Password to access the GridBox API	N/A	yes	no
refreshInterval	integer	Interval the device is polled in sec.	60	no	yes

Channels

The following channels are supplied by the GridBox thing (descriptions taken from the API documentation):

Channel	Type	Read/Write	Description
battery-capacity	Number	R	Maximum energy the battery can provide in Wh.
battery-nominal-capacity	Number	R
battery-power	Number	R	Power is the measured power used to charge/discharge the battery. Unit W, Meaning, Positive values indicate discharging. Negative values indicate charging.
battery-remaining-charge	Number	R	Remaining Charge is the amount of energy left.
battery-state-of-charge	Number	R	State of Charge indicates how full a battery is. Unit Percentage points 0.0-1.0.
battery-level	Number	R	Battery level, ratio of remaining charge to capacity.
consumption	Number	R	Adjusted power/energy of the system.
direct-consumption	Number	R	Power/energy consumed through production directly.
direct-consumption-ev	Number	R	Power/energy consumed by the EV through production directly.
direct-consumption-heat-pump	Number	R	Power/energy consumed by the heat pump through production directly.
direct-consumption-heater	Number	R	Power/energy consumed by the heater through production directly.
direct-consumption-household	Number	R	Power/energy consumed by the household through production directly.
direct-consumption-rate	Number	R	Ratio of direct consumption vs production (0.0-1.0).
ev-charging-station-power	Number	R	Measured power used to charge/discharge via EV station, positive values indicate charging, negatives discharging.
heat-pump-power	Number	R	Aggregated measured power/energy for heat pumps.
photovoltaic-production	Number	R	Photovoltaic is the measured power/energy in front of the photovoltaic systems.
production	Number	R	Sum of all energy producing appliances (e.g. PV).
self-consumption	Number	R	Power/Energy consumed through production and charged into battery.
self-consumption-rate	Number	R	Ratio of self consumption vs production (0.0-1.0).
self-sufficiency-rate	Number	R	Ratio of produced energy vs total consumed energy (0.0-1.0).
self-supply	Number	R	Power/energy consumed through storage and production.
total-consumption	Number	R	Adjusted power/energy of the system including heatpumps and EV charging stations.

Full Example

Thing Configuration

Thing gridbox:gridbox:901b4766e2 "GridBox" [email="[email protected]",password="mypassword",refreshInterval=120]                                                                                                               

Item Configuration

Number GridBox_PhotovoltaicProduction "PV Production [%.0f W]" {channel="gridbox:gridbox:901b4766e2:photovoltaicProduction"}

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)