{"id":50736701,"url":"https://github.com/chargee-energy/chargee-homeassistant","last_synced_at":"2026-06-10T14:30:20.370Z","repository":{"id":362768209,"uuid":"1260650067","full_name":"chargee-energy/chargee-homeassistant","owner":"chargee-energy","description":"Official Chargee Home Assistant integration","archived":false,"fork":false,"pushed_at":"2026-06-05T20:18:10.000Z","size":245,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T21:15:49.228Z","etag":null,"topics":["chargee","dsmr","energy","flint","hacs","home-assistant","homeassistant","homeassistant-integration","p1-meter","sparky"],"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/chargee-energy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2026-06-05T18:10:43.000Z","updated_at":"2026-06-05T20:18:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chargee-energy/chargee-homeassistant","commit_stats":null,"previous_names":["chargee-energy/chargee-homeassistant"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chargee-energy/chargee-homeassistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargee-energy%2Fchargee-homeassistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargee-energy%2Fchargee-homeassistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargee-energy%2Fchargee-homeassistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargee-energy%2Fchargee-homeassistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chargee-energy","download_url":"https://codeload.github.com/chargee-energy/chargee-homeassistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargee-energy%2Fchargee-homeassistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34157453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["chargee","dsmr","energy","flint","hacs","home-assistant","homeassistant","homeassistant-integration","p1-meter","sparky"],"created_at":"2026-06-10T14:30:18.840Z","updated_at":"2026-06-10T14:30:20.365Z","avatar_url":"https://github.com/chargee-energy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chargee P1 for Home Assistant\n\n[![Validate](https://github.com/chargee-energy/chargee-homeassistant/actions/workflows/validate.yml/badge.svg)](https://github.com/chargee-energy/chargee-homeassistant/actions/workflows/validate.yml)\n[![Tests](https://github.com/chargee-energy/chargee-homeassistant/actions/workflows/tests.yml/badge.svg)](https://github.com/chargee-energy/chargee-homeassistant/actions/workflows/tests.yml)\n[![hacs](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://hacs.xyz)\n\nA custom [Home Assistant](https://www.home-assistant.io/) integration for the\n**Chargee P1 dongle** (**Sparky** and **Flint**). It reads your smart meter data\ndirectly from the dongle over its **Local API** and feeds it straight into the\nHome Assistant **Energy dashboard** - no cloud account required.\n\nThe integration is built from scratch, taking inspiration from the HomeWizard\nEnergy integration's structure and UX, but implemented specifically for the\nChargee Local API.\n\n\u003e **Note:** A future release will optionally support connecting through the\n\u003e Chargee Web API. That option is not available yet; today the integration\n\u003e talks to your device **locally only**. See [Roadmap](#roadmap).\n\n---\n\n## Features\n\n- Automatic discovery of Sparky and Flint devices on your network via **mDNS**.\n- 100% local polling - your data never leaves your network.\n- Full mapping to the **Home Assistant Energy dashboard** (grid import, grid\n  export, and gas).\n- Per-phase power, voltage and current sensors for three-phase meters.\n- Tariff, Wi-Fi and meter diagnostics.\n- An **Identify** button that blinks the device status light.\n- Diagnostics download support for troubleshooting.\n\n## Supported devices\n\n| Device | Minimum firmware | Notes |\n| ------ | ---------------- | ----- |\n| Sparky | 95               | Local API enabled by default from this version |\n| Flint  | 105              | Local API enabled by default from this version |\n\nThe integration uses **Local API v1** (`api_version: \"v1\"`), served over HTTP on\nport 80, and advertised on the network as the `_chargee_p1._tcp` mDNS service.\n\n---\n\n## Before you start: enable the Local API\n\nThe Local API is enabled by default on supported firmware, but you can verify it\nin the Chargee app:\n\n1. Open the **Chargee app**.\n2. Go to **Profile -\u003e your Address -\u003e My House -\u003e Local API**.\n3. Make sure the Local API is enabled.\n\n\u003e Optional: enabling **\"Previous P1 meters\"** turns on *compatibility mode*,\n\u003e which additionally broadcasts the legacy P1 service on port 3602. This\n\u003e integration does **not** require compatibility mode - it uses the modern\n\u003e Local API v1.\n\n---\n\n## Installation\n\n### HACS (recommended)\n\n1. In Home Assistant, go to **HACS -\u003e Integrations**.\n2. Open the overflow menu (top right) and choose **Custom repositories**.\n3. Add `https://github.com/chargee-energy/chargee-homeassistant` with category\n   **Integration**.\n4. Search for **Chargee P1** and install it.\n5. Restart Home Assistant.\n\n### Manual\n\n1. Copy the `custom_components/chargee` folder into your Home Assistant\n   `config/custom_components/` directory.\n2. Restart Home Assistant.\n\n---\n\n## Setup\n\n### Automatic discovery\n\nOnce your Sparky or Flint is online, Home Assistant will discover it\nautomatically. You'll see a **\"Discovered\"** card under\n**Settings -\u003e Devices \u0026 Services**. Click **Configure** and confirm.\n\n### Manual setup\n\nIf discovery doesn't find your device (e.g. mDNS is blocked between VLANs):\n\n1. Go to **Settings -\u003e Devices \u0026 Services -\u003e Add Integration**.\n2. Search for **Chargee P1**.\n3. Enter the **IP address** of your dongle (and port, if not 80).\n\nThe integration validates the connection by calling `/api` and uses the device\n**serial number** as its unique identifier, so a device is never added twice.\n\n---\n\n## Entities\n\nEntities are created only for the data points your meter actually reports, so a\nsingle-phase Flint without gas will expose fewer entities than a three-phase\nSparky with gas. Some less-common sensors are disabled by default; enable them\nfrom the entity settings if you need them.\n\n### Energy (for the Energy dashboard)\n\n| Entity | Unit | Device class | State class | Enabled by default |\n| ------ | ---- | ------------ | ----------- | ------------------ |\n| Energy import | kWh | energy | total_increasing | Yes |\n| Energy import tariff 1 | kWh | energy | total_increasing | No |\n| Energy import tariff 2 | kWh | energy | total_increasing | No |\n| Energy export | kWh | energy | total_increasing | Yes |\n| Energy export tariff 1 | kWh | energy | total_increasing | No |\n| Energy export tariff 2 | kWh | energy | total_increasing | No |\n| Gas | m3 | gas | total_increasing | Yes |\n\n### Power, voltage and current\n\n| Entity | Unit | Device class | Enabled by default |\n| ------ | ---- | ------------ | ------------------ |\n| Active power | W | power | Yes |\n| Active power phase 1/2/3 | W | power | Yes |\n| Voltage phase 1/2/3 | V | voltage | No |\n| Current | A | current | Yes |\n| Current phase 1/2/3 | A | current | No |\n\n### Diagnostics\n\n| Entity | Description |\n| ------ | ----------- |\n| Active tariff | Current tariff (1 or 2) |\n| Wi-Fi strength | Signal strength in % |\n| Wi-Fi SSID | Network the dongle is connected to |\n| Smart meter model | Brand/model reported by the meter |\n| DSMR version | Smart meter DSMR/SMR version |\n| Gas timestamp | Timestamp of the most recent gas reading |\n\n### Controls\n\n| Entity | Description |\n| ------ | ----------- |\n| Identify (button) | Blinks the status light green for 5 seconds |\n\n---\n\n## Configuring the Energy dashboard\n\n1. Go to **Settings -\u003e Dashboards -\u003e Energy**.\n2. Under **Electricity grid**:\n   - **Grid consumption** -\u003e select **Energy import**.\n   - **Return to grid** -\u003e select **Energy export**.\n   - (Optional) Add your energy tariffs / costs.\n3. Under **Gas consumption** (if your meter reports gas) -\u003e select **Gas**.\n4. Save. Home Assistant starts building long-term statistics on the next cycle.\n\n\u003e If you want tariff-split statistics, enable the **tariff 1/2** import and\n\u003e export sensors first, then add them instead of the combined sensors.\n\n---\n\n## How it works\n\n```\nmDNS (_chargee_p1._tcp)            HTTP (port 80)\n        |                                 |\n        v                                 v\n  Config flow  -\u003e  Config entry  -\u003e  Coordinator  -\u003e  Local API client\n                                          |                  |\n                                          v                  v\n                                    Sensors / Button    /api, /api/v1/data,\n                                                        /api/v1/telegram,\n                                                        /api/v1/identify\n```\n\nThe integration polls `/api/v1/data` every few seconds through a\n`DataUpdateCoordinator`, and reads static device information from `/api` once.\nThe bundled async API client lives in\n[`custom_components/chargee/api/`](custom_components/chargee/api) and has no\nHome Assistant dependencies, so it can be unit-tested in isolation and reused\nlater for the Web API.\n\n---\n\n## Troubleshooting\n\n- **Device not discovered:** Ensure the dongle and Home Assistant are on the\n  same network/VLAN and that mDNS (UDP 5353) is allowed. Use **manual setup**\n  with the device IP as a fallback.\n- **Cannot connect:** Confirm the Local API is enabled in the Chargee app and\n  that you can reach `http://\u003cdevice-ip\u003e/api` from a browser or with\n  `curl http://\u003cdevice-ip\u003e/api`.\n- **Some sensors are missing:** This is expected - the API only sends data\n  points your meter actually provides. Single-phase meters won't have L2/L3\n  sensors, and meters without gas won't have a gas sensor.\n- **Statistics not showing in Energy dashboard:** Long-term statistics are\n  generated on a schedule; allow up to an hour after adding the sensors.\n\n### Diagnostics\n\nFor bug reports, download diagnostics from the device page\n(**Settings -\u003e Devices \u0026 Services -\u003e Chargee P1 -\u003e Download diagnostics**).\nSensitive values (host, serial, gas/meter IDs, Wi-Fi SSID) are redacted.\n\n---\n\n## Local API reference\n\nThe integration uses the following endpoints (Local API v1):\n\n| Endpoint | Method | Description |\n| -------- | ------ | ----------- |\n| `/api` | GET | Device info: `product_type`, `product_name`, `serial`, `firmware_version`, `api_version` |\n| `/api/v1/data` | GET | Most recent measurement (JSON, optional fields) |\n| `/api/v1/telegram` | GET | Most recent raw, validated DSMR telegram (text) |\n| `/api/v1/identify` | GET | Blinks the status light |\n\n---\n\n## Roadmap\n\n- [ ] **Web API connection** - connect to your device through the Chargee Web\n      API for access outside your local network. The client layer is already\n      structured so a cloud client can return the same data models, but the Web\n      API is not publicly available yet.\n- [ ] Expose the raw DSMR telegram as a service/diagnostic.\n- [ ] Additional translations.\n\n---\n\n## Development\n\n```bash\npython3.12 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements_test.txt\npytest\n```\n\nThe test suite uses\n[`pytest-homeassistant-custom-component`](https://github.com/MatthewFlamm/pytest-homeassistant-custom-component)\nand mocks all network traffic; no device is required.\n\n## License\n\n[MIT](LICENSE)\n\n\u003e Chargee, Sparky and Flint are trademarks of their respective owner. This is a\n\u003e community integration.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchargee-energy%2Fchargee-homeassistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchargee-energy%2Fchargee-homeassistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchargee-energy%2Fchargee-homeassistant/lists"}