{"id":36936987,"url":"https://github.com/unl0ck/gridx-connector","last_synced_at":"2026-04-06T15:01:35.311Z","repository":{"id":326177860,"uuid":"1101119277","full_name":"unl0ck/gridx-connector","owner":"unl0ck","description":"a small gridx connector, based of the viessmann connector, you can use it to fetch historical and live data from gridx gridbox, will support eon, viessmann","archived":false,"fork":false,"pushed_at":"2026-04-02T20:23:03.000Z","size":1939,"stargazers_count":0,"open_issues_count":6,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-03T03:57:56.990Z","etag":null,"topics":["eon","eon-gridbox","gridbox","gridx","viessmann-gridbox"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unl0ck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T08:12:15.000Z","updated_at":"2026-04-02T20:22:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/unl0ck/gridx-connector","commit_stats":null,"previous_names":["unl0ck/gridx-connector"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/unl0ck/gridx-connector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unl0ck%2Fgridx-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unl0ck%2Fgridx-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unl0ck%2Fgridx-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unl0ck%2Fgridx-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unl0ck","download_url":"https://codeload.github.com/unl0ck/gridx-connector/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unl0ck%2Fgridx-connector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31477013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T14:34:32.243Z","status":"ssl_error","status_checked_at":"2026-04-06T14:34:31.723Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eon","eon-gridbox","gridbox","gridx","viessmann-gridbox"],"created_at":"2026-01-13T10:02:09.684Z","updated_at":"2026-04-06T15:01:35.295Z","avatar_url":"https://github.com/unl0ck.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gridx Connector\n\n\u003ch3 align=\"center\"\u003eThis is not an Official GridX Library\u003c/h3\u003e\n\n\u003e **⚠️ Deprecation Notice — Viessmann realm**\n\u003e The Viessmann realm was shut down at the end of 2025. The `viessmann` OEM is deprecated\n\u003e and will be removed in a future major release. Please switch to **eon Home**.\n\nHarness 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.\n\nWhether 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.\n\n**Take control of your solar data with GridboxConnector, and unlock the full potential of your photovoltaic system.**\n\n![Screenshot vom mygridbox](images/screenshot.png)\n\n## Supported Realms\n\n| Realm | Status |\n|---|---|\n| **eon Home** | ✅ Active |\n| Viessmann | ⚠️ Deprecated — shut down end of 2025 |\n\n## Installation\n\n```shell\npip install gridx-connector\n# or with uv\nuv add gridx-connector\n```\n\n## Usage\n\nUse your login credentials from the app or from \u003chttps://company.gridx.de/login\u003e.\n\n### CLI\n\nThe `gridx` command authenticates with your credentials, discovers all energy systems\nlinked to your account, and prints their current live measurements to stdout as JSON.\n\n```\nusage: gridx [-h] -u USERNAME -p PASSWORD [-o {eon-home}]\n\noptions:\n  -h, --help            show this help message and exit\n  -u, --username        Login username (e-mail address from the app)\n  -p, --password        Login password\n  -o, --oem             OEM configuration to use (default: eon-home)\n```\n\n**Examples**\n\n```shell\n# Minimal — prints live data for all systems on your account\ngridx -u your@email.com -p yourpassword\n\n# Explicit OEM (currently only eon-home is supported)\ngridx -u your@email.com -p yourpassword -o eon-home\n\n# Pretty-print with jq\ngridx -u your@email.com -p yourpassword | jq .\n\n# Store the result in a file\ngridx -u your@email.com -p yourpassword \u003e live.json\n```\n\n**What the command does internally**\n\n1. Loads `eon-home.config.json` bundled with the package.\n2. Exchanges your credentials for an OAuth2 token via Auth0.\n3. Calls `GET /systems` to discover all energy systems on your account.\n4. Calls `GET /systems/{id}/live` for each system.\n5. Prints the combined list of measurement dicts as JSON to stdout.\n\n### As a library\n\n```python\nfrom gridx_connector import GridboxConnector, SupportedOEM\nfrom importlib.resources import files\nimport json\n\nconfig_file = files(\"gridx_connector\").joinpath(\"config\", f\"{SupportedOEM.EON_HOME}.config.json\")\nwith open(config_file) as f:\n    config = json.load(f)\n\nconfig[\"login\"][\"username\"] = \"your@email.com\"\nconfig[\"login\"][\"password\"] = \"yourpassword\"\n\nconnector = GridboxConnector(config)\n\n# Live data (all systems)\nlive_data = connector.retrieve_live_data()\n\n# Historical data\nhistorical = connector.retrieve_historical_data(\n    start=\"2024-01-01T00:00:00+01:00\",\n    end=\"2024-01-02T00:00:00+01:00\",\n    resolution=\"1h\",  # 15m | 1h | 1d | 1w | 1M\n)\n```\n\n### Example Output\n\n```json\n{\n    \"consumption\": 496,\n    \"directConsumption\": 413,\n    \"directConsumptionEV\": 0,\n    \"directConsumptionHeatPump\": 0,\n    \"directConsumptionHeater\": 0,\n    \"directConsumptionHousehold\": 413,\n    \"directConsumptionRate\": 1,\n    \"grid\": 83,\n    \"gridMeterReadingNegative\": 4318200000,\n    \"gridMeterReadingPositive\": 14499360000,\n    \"measuredAt\": \"2023-08-04T11:29:43Z\",\n    \"photovoltaic\": 413,\n    \"production\": 413,\n    \"selfConsumption\": 413,\n    \"selfConsumptionRate\": 1,\n    \"selfSufficiencyRate\": 0.8326612903225806,\n    \"selfSupply\": 413,\n    \"totalConsumption\": 496\n}\n```\n\n## How it works — Getting your data step by step\n\nThe diagram below shows the full journey from credentials to measurements.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  1. Load config                                             │\n│     Read eon-home.config.json (or set USERNAME / PASSWORD   │\n│     env vars to avoid storing credentials in a file).       │\n└────────────────────────┬────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────────┐\n│  2. Authenticate  (OAuth2 / Auth0)                          │\n│     GridboxConnector calls POST /oauth/token on the login   │\n│     URL with your credentials and receives an id_token.     │\n│     The token is refreshed automatically when it expires.   │\n└────────────────────────┬────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────────┐\n│  3. Discover systems  (GET /systems)                        │\n│     The connector fetches all energy systems linked to your │\n│     account and stores their UUIDs in connector.gateways.   │\n└────────────────────────┬────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────────┐\n│  4a. Live data  (GET /systems/{id}/live)                    │\n│      Returns the latest snapshot: PV production, grid feed- │\n│      in/draw, battery state, household consumption, etc.    │\n├─────────────────────────────────────────────────────────────┤\n│  4b. Historical data  (GET /systems/{id}/historical)        │\n│      Returns measurements aggregated over a time interval   │\n│      and a chosen resolution (15m / 1h / 1d / 1w / 1M).    │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Minimal working example\n\n```python\nimport json\nfrom importlib.resources import files\nfrom gridx_connector import GridboxConnector, SupportedOEM\n\n# 1. Load config\nconfig_path = files(\"gridx_connector\").joinpath(\"config\", f\"{SupportedOEM.EON_HOME}.config.json\")\nconfig = json.loads(config_path.read_text())\n\n# Inject credentials (or set USERNAME / PASSWORD env vars instead)\nconfig[\"login\"][\"username\"] = \"your@email.com\"\nconfig[\"login\"][\"password\"] = \"yourpassword\"\n\n# 2+3. Authenticate and discover systems automatically\nconnector = GridboxConnector(config)\nprint(\"Systems found:\", connector.get_gateways())\n\n# 4a. Live snapshot for all systems\nfor measurement in connector.retrieve_live_data():\n    print(f\"PV: {measurement['photovoltaic']} W  \"\n          f\"Grid: {measurement['grid']} W  \"\n          f\"Consumption: {measurement['consumption']} W\")\n\n# 4b. Yesterday's data in 1-hour buckets\nfrom datetime import date, timedelta\nyesterday = date.today() - timedelta(days=1)\nhistorical = connector.retrieve_historical_data(\n    start=f\"{yesterday}T00:00:00+01:00\",\n    end=f\"{yesterday}T23:59:59+01:00\",\n    resolution=\"1h\",   # 15m | 1h | 1d | 1w | 1M\n)\nfor entry in historical:\n    for bucket in entry.get(\"measurements\", []):\n        print(bucket[\"measuredAt\"], \"→\", bucket[\"photovoltaic\"], \"W\")\n```\n\n### Credential handling\n\n| Option | How |\n|---|---|\n| Config file | Set `login.username` / `login.password` in `eon-home.config.json` |\n| Environment variables | Export `USERNAME=...` and `PASSWORD=...` — these override the config file |\n| CLI | Pass `-u \u003cuser\u003e -p \u003cpass\u003e` on the command line |\n\n### Discover OAuth config automatically\n\nIf you only know your website URL plus username/password, use the helper script to discover\n`client_id`, `realm`, `scope`, `audience`, and the token endpoint from the login page and JS bundles.\n\n```shell\n# Discovery only (prints candidates as JSON)\npython scripts/discover_oauth_config.py --site-url https://eon.gridx.de\n\n# Discovery + token validation + config file output (credentials redacted by default)\npython scripts/discover_oauth_config.py \\\n    --site-url https://eon.gridx.de \\\n    -u your@email.com \\\n    -p yourpassword \\\n    --validate \\\n    --output eon.config.json\n```\n\nNotes:\n\n- Add `--include-credentials` to store username/password in the output file.\n- The generated JSON matches this project's config structure and can be used with `--config`.\n\n## Examples\n\nReady-to-run scripts are in the [`examples/`](examples/) directory:\n\n| Script | Description |\n|---|---|\n| [`read_live_data.py`](examples/read_live_data.py) | Poll live data every 60 s |\n| [`historical_data.py`](examples/historical_data.py) | Fetch today's historical data |\n| [`openapi_test.py`](examples/openapi_test.py) | Use the low-level `gridx_connector_api` client directly |\n\n## Generated API Client\n\n`gridx_connector_api/` is an auto-generated Python client derived directly from\n[`APIDefinition/openapi.json`](APIDefinition/openapi.json) using\n[openapi-python-client](https://github.com/openapi-generators/openapi-python-client).\n\nThe client is regenerated automatically via GitHub Actions whenever `openapi.json` changes.\nTo regenerate locally after replacing `openapi.json`:\n\n```shell\nuv sync --dev\nbash scripts/generate_client.sh\n```\n\n## Dependencies\n\n- `requests` — HTTP client\n- `authlib` — OAuth2 authentication\n\n## License\n\nMIT\n\n\n## Contributing\n\nIf you'd like to contribute to gridx-connector, please follow these steps:\n\nFork the repository.\nCreate a new branch for your feature or bug fix.\nMake your changes and write tests if possible.\nRun tests and ensure they pass.\nSubmit a pull request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funl0ck%2Fgridx-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funl0ck%2Fgridx-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funl0ck%2Fgridx-connector/lists"}