Gridx Connector

This is not an Official GridX Library

⚠️ Deprecation Notice — Viessmann realm The Viessmann realm was shut down at the end of 2025. The viessmann OEM is deprecated and will be removed in a future major release. Please switch to eon Home.

Harness the power of your photovoltaic system with the GridboxConnector library. This versatile tool taps into the same REST API as the official dashboard and app, providing you with direct access to your data from the cloud.

Whether you're a developer looking to integrate solar data into your own project, or a power user seeking command-line access, GridboxConnector has you covered.

Take control of your solar data with GridboxConnector, and unlock the full potential of your photovoltaic system.

Supported Realms

Installation

pip install gridx-connector
# or with uv
uv add gridx-connector

Usage

Use your login credentials from the app or from https://company.gridx.de/login.

CLI

The gridx command authenticates with your credentials, discovers all energy systems linked to your account, and prints their current live measurements to stdout as JSON.

usage: gridx [-h] -u USERNAME -p PASSWORD [-o {eon-home}]

options:
  -h, --help            show this help message and exit
  -u, --username        Login username (e-mail address from the app)
  -p, --password        Login password
  -o, --oem             OEM configuration to use (default: eon-home)

Examples

# Minimal — prints live data for all systems on your account
gridx -u your@email.com -p yourpassword

# Explicit OEM (currently only eon-home is supported)
gridx -u your@email.com -p yourpassword -o eon-home

# Pretty-print with jq
gridx -u your@email.com -p yourpassword | jq .

# Store the result in a file
gridx -u your@email.com -p yourpassword > live.json

What the command does internally

1. Loads eon-home.config.json bundled with the package.
2. Exchanges your credentials for an OAuth2 token via Auth0.
3. Calls GET /systems to discover all energy systems on your account.
4. Calls GET /systems/{id}/live for each system.
5. Prints the combined list of measurement dicts as JSON to stdout.

As a library

from gridx_connector import GridboxConnector, build_login_config

# Realm, client id and audience for the OEM are defined in the library.
config = build_login_config("your@email.com", "yourpassword")

connector = GridboxConnector(config)

# Live data (all systems)
live_data = connector.retrieve_live_data()

# Historical data
historical = connector.retrieve_historical_data(
    start="2024-01-01T00:00:00+01:00",
    end="2024-01-02T00:00:00+01:00",
    resolution="1h",  # 15m | 1h | 1d | 1w | 1M
)

Example Output

{
    "consumption": 496,
    "directConsumption": 413,
    "directConsumptionEV": 0,
    "directConsumptionHeatPump": 0,
    "directConsumptionHeater": 0,
    "directConsumptionHousehold": 413,
    "directConsumptionRate": 1,
    "grid": 83,
    "gridMeterReadingNegative": 4318200000,
    "gridMeterReadingPositive": 14499360000,
    "measuredAt": "2023-08-04T11:29:43Z",
    "photovoltaic": 413,
    "production": 413,
    "selfConsumption": 413,
    "selfConsumptionRate": 1,
    "selfSufficiencyRate": 0.8326612903225806,
    "selfSupply": 413,
    "totalConsumption": 496
}

How it works — Getting your data step by step

The diagram below shows the full journey from credentials to measurements.

┌─────────────────────────────────────────────────────────────┐
│  1. Load config                                             │
│     Read eon-home.config.json (or set GRIDX_USERNAME /      │
│     GRIDX_PASSWORD env vars to avoid credentials in a file).│
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  2. Authenticate  (OAuth2 / Auth0)                          │
│     GridboxConnector calls POST /oauth/token on the login   │
│     URL with your credentials and receives an access_token. │
│     The token is refreshed automatically when it expires.   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  3. Discover systems  (GET /systems)                        │
│     The connector fetches all energy systems linked to your │
│     account and stores their UUIDs in connector.gateways.   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  4a. Live data  (GET /systems/{id}/live)                    │
│      Returns the latest snapshot: PV production, grid feed- │
│      in/draw, battery state, household consumption, etc.    │
├─────────────────────────────────────────────────────────────┤
│  4b. Historical data  (GET /systems/{id}/historical)        │
│      Returns measurements aggregated over a time interval   │
│      and a chosen resolution (15m / 1h / 1d / 1w / 1M).    │
└─────────────────────────────────────────────────────────────┘

Minimal working example

import json
from importlib.resources import files
from gridx_connector import GridboxConnector, SupportedOEM

# 1. Load config
config_path = files("gridx_connector").joinpath("config", f"{SupportedOEM.EON_HOME}.config.json")
config = json.loads(config_path.read_text())

# Inject credentials (or set GRIDX_USERNAME / GRIDX_PASSWORD env vars instead)
config["login"]["username"] = "your@email.com"
config["login"]["password"] = "yourpassword"

# 2+3. Authenticate and discover systems automatically
connector = GridboxConnector(config)
print("Systems found:", connector.get_gateways())

# 4a. Live snapshot for all systems
for measurement in connector.retrieve_live_data():
    print(f"PV: {measurement['photovoltaic']} W  "
          f"Grid: {measurement['grid']} W  "
          f"Consumption: {measurement['consumption']} W")

# 4b. Yesterday's data in 1-hour buckets
from datetime import date, timedelta
yesterday = date.today() - timedelta(days=1)
historical = connector.retrieve_historical_data(
    start=f"{yesterday}T00:00:00+01:00",
    end=f"{yesterday}T23:59:59+01:00",
    resolution="1h",   # 15m | 1h | 1d | 1w | 1M
)
for entry in historical:
    for bucket in entry.get("measurements", []):
        print(bucket["measuredAt"], "→", bucket["photovoltaic"], "W")

Async usage and errors

from gridx_connector import (
    AsyncGridboxConnector,
    GridXAuthenticationError,
    GridXConnectionError,
    GridXError,
    build_login_config,
)

async with AsyncGridboxConnector(build_login_config("your@email.com", "yourpassword")) as connector:
    try:
        live = await connector.get_live_data()  # {system_id: measurement}, fails if any system fails
    except GridXAuthenticationError:
        ...  # wrong credentials or token rejected (HTTP 401/403)
    except GridXConnectionError:
        ...  # network problem or timeout
    except GridXError:
        ...  # unexpected status or payload (GridXResponseError)
    for system_id, measurement in live.items():
        print(connector.systems[system_id].name, measurement["photovoltaic"])

retrieve_live_data() keeps the old list-based, partial-failure-tolerant behaviour. The bearer token is sent per request, so an injected httpx.AsyncClient is never modified.

Credential handling

Discover OAuth config automatically

If you only know your website URL plus username/password, use the helper script to discover client_id, realm, scope, audience, and the token endpoint from the login page and JS bundles.

# Discovery only (prints candidates as JSON)
python scripts/discover_oauth_config.py --site-url https://eon.gridx.de

# Discovery + token validation + config file output (credentials redacted by default)
python scripts/discover_oauth_config.py \
    --site-url https://eon.gridx.de \
    -u your@email.com \
    -p yourpassword \
    --validate \
    --output eon.config.json

Notes:

• Add --include-credentials to store username/password in the output file.
• The generated JSON matches this project's config structure and can be used with --config.

Examples

Ready-to-run scripts are in the examples/ directory:

Generated API Client

gridx_connector_api/ is an auto-generated Python client derived directly from APIDefinition/openapi.json using openapi-python-client.

The client is regenerated automatically via GitHub Actions whenever openapi.json changes. To regenerate locally after replacing openapi.json:

uv sync --dev
bash scripts/generate_client.sh

Dependencies

• requests — HTTP client
• authlib — OAuth2 authentication

License

MIT

Contributing

If you'd like to contribute to gridx-connector, please follow these steps:

Fork the repository. Create a new branch for your feature or bug fix. Make your changes and write tests if possible. Run tests and ensure they pass. Submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.