# 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 |
|---|---|---|---|---|---|
| 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"}
← GREE GROHE ONDUS →