{"id":23661521,"url":"https://github.com/ssenart/gazpar2haws","last_synced_at":"2026-04-11T13:04:02.924Z","repository":{"id":269193338,"uuid":"904401178","full_name":"ssenart/gazpar2haws","owner":"ssenart","description":"Gazpar2HAWS is a gateway that reads data history from the GrDF (French gas provider) meter and send it to Home Assistant using WebSocket interface","archived":false,"fork":false,"pushed_at":"2025-07-22T18:21:13.000Z","size":326,"stargazers_count":23,"open_issues_count":10,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-27T13:54:02.387Z","etag":null,"topics":["dashboard","energy-consumption","gas","gazpar","grdf","home-assistant","meter"],"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/ssenart.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2024-12-16T20:20:11.000Z","updated_at":"2025-08-08T08:19:04.000Z","dependencies_parsed_at":"2024-12-21T17:21:04.037Z","dependency_job_id":"ec599d78-b1fd-4782-9366-007db07b6894","html_url":"https://github.com/ssenart/gazpar2haws","commit_stats":null,"previous_names":["ssenart/gazpar2haws"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/ssenart/gazpar2haws","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssenart%2Fgazpar2haws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssenart%2Fgazpar2haws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssenart%2Fgazpar2haws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssenart%2Fgazpar2haws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ssenart","download_url":"https://codeload.github.com/ssenart/gazpar2haws/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssenart%2Fgazpar2haws/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273162135,"owners_count":25056416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"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":["dashboard","energy-consumption","gas","gazpar","grdf","home-assistant","meter"],"created_at":"2024-12-29T04:59:21.761Z","updated_at":"2026-04-11T13:04:02.917Z","avatar_url":"https://github.com/ssenart.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gazpar2haws\r\n\r\nGazpar2HAWS is a gateway that reads data history from the GrDF (French gas provider) meter and send it to Home Assistant using WebSocket interface.\r\n\r\nIt is compatible with Home Assistant Energy Dashboard and permits to upload the history and keep it updated with the latest readings.\r\n\r\nIt is a complement to the other available projects:\r\n\r\n- [home-assistant-gazpar](https://github.com/ssenart/home-assistant-gazpar): HA integration that publishes a Gazpar entity with the corresponding meter value.\r\n- [gazpar2mqtt](https://github.com/ssenart/gazpar2mqtt): [home-assistant-gazpar](https://github.com/ssenart/home-assistant-gazpar) alternative but using MQTT events (it reduce coupling with HA).\r\n- [lovelace-gazpar-card](https://github.com/ssenart/lovelace-gazpar-card): HA dashboard card compatible with [home-assistant-gazpar](https://github.com/ssenart/home-assistant-gazpar) and [gazpar2mqtt](https://github.com/ssenart/gazpar2mqtt).\r\n\r\n---\r\n\r\n## 🎉 What's New in v0.5.0\r\n\r\n### Flexible Pricing Components\r\n\r\nDefine **unlimited custom pricing component names** instead of being limited to 4 hardcoded names!\r\n\r\n```yaml\r\npricing:\r\n  # Use any names that match your billing structure\r\n  base_energy_cost: [...]\r\n  peak_surcharge: [...]\r\n  carbon_tax: [...]\r\n  distribution_network: [...]\r\n  # Add as many as you need!\r\n```\r\n\r\n**Key Features:**\r\n- ✅ Unlimited components (not just 4)\r\n- ✅ Custom names (e.g., `carbon_tax`, `peak_rate`)\r\n- ✅ Automatic Home Assistant sensors\r\n- ✅ 100% backward compatible\r\n\r\n**Learn More:**\r\n- 📖 [Flexible Pricing Guide](docs/FLEXIBLE_PRICING_GUIDE.md) - Complete documentation\r\n- 📝 [Example 9](#example-9-flexible-pricing-with-custom-component-names-v050) - See it in action\r\n- 🔄 [CHANGELOG](CHANGELOG.md#050---2026-01-30) - Full release notes\r\n\r\n---\r\n\r\n## Documentation\r\n\r\n### User Documentation\r\n\r\n- **[README.md](README.md)** (this file) - Complete installation, configuration, and usage guide\r\n- **[docs/FAQ.md](docs/FAQ.md)** - Frequently Asked Questions based on GitHub issues and user feedback\r\n  - Common configuration issues\r\n  - Troubleshooting steps\r\n  - Migration guides\r\n  - All known issues and solutions\r\n- **[CHANGELOG.md](CHANGELOG.md)** - Version history with all changes, fixes, and new features\r\n\r\n### Developer Documentation\r\n\r\n- **[docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)** - Comprehensive developer guide\r\n  - Architecture overview and design patterns\r\n  - Development setup and workflow\r\n  - Testing strategies and code quality\r\n  - Contributing guidelines and release process\r\n- **[docs/TODO.md](docs/TODO.md)** - Planned improvements and test coverage tasks\r\n  - Test coverage analysis\r\n  - Missing tests by priority\r\n  - Implementation schedule\r\n  - Known issues requiring tests\r\n\r\n### Quick Links\r\n\r\n- 🐛 Found a bug? → Check [docs/FAQ.md](docs/FAQ.md) first, then open an [issue](https://github.com/ssenart/gazpar2haws/issues)\r\n- 📝 Want to contribute? → Read [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) and [docs/TODO.md](docs/TODO.md)\r\n- 🔄 Upgrading? → Check [CHANGELOG.md](CHANGELOG.md) for breaking changes\r\n- ❓ Have a question? → See [docs/FAQ.md](docs/FAQ.md) or ask in [discussions](https://github.com/ssenart/gazpar2haws/discussions)\r\n\r\n## Installation\r\n\r\nGazpar2HAWS can be installed in many ways.\r\n\r\n### 1. Home Assistant Add-on\r\n\r\nIn the **Add-on store**, click **⋮ → Repositories**, fill in **`https://github.com/ssenart/gazpar2haws`** and click **Add → Close** or click the **Add repository** button below, click **Add → Close** (You might need to enter the **internal IP address** of your Home Assistant instance first).\r\n\r\n[![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fssenart%2Fgazpar2haws)\r\n\r\nFor usage and configuration, read the documentation [here](addons/gazpar2haws/DOCS.md).\r\n\r\n### 2. Using Docker Hub\r\n\r\nThe following steps permits to run a container from an existing image available in the Docker Hub repository.\r\n\r\n1. Copy and save the following docker-compose.yaml file:\r\n\r\n```yaml\r\nservices:\r\n  gazpar2haws:\r\n    image: ssenart/gazpar2haws:latest\r\n    container_name: gazpar2haws\r\n    restart: unless-stopped\r\n    network_mode: bridge\r\n    user: \"1000:1000\"\r\n    volumes:\r\n      - ./gazpar2haws/config:/app/config\r\n      - ./gazpar2haws/log:/app/log\r\n    environment:\r\n      - GRDF_USERNAME=\u003cGrDF account username\u003e\r\n      - GRDF_PASSWORD=\u003cGrDF account password\u003e\r\n      - GRDF_PCE_IDENTIFIER=\u003cGrDF PCE meter identifier\u003e\r\n      - HOMEASSISTANT_HOST=\u003cHome Assistant instance host name\u003e\r\n      - HOMEASSISTANT_TOKEN=\u003cHome Assistant access token\u003e\r\n```\r\n\r\nEdit the environment variable section according to your setup.\r\n\r\n2. Run the container:\r\n\r\n```sh\r\n$ docker compose up -d\r\n```\r\n\r\n### 3. Using PIP package\r\n\r\n```sh\r\n$ cd /path/to/my_install_folder/\r\n\r\n$ mkdir gazpar2haws\r\n\r\n$ cd gazpar2haws\r\n\r\n$ python -m venv .venv\r\n\r\n$ source .venv/bin/activate\r\n\r\n$ pip install gazpar2haws\r\n\r\n```\r\n\r\n### 4. Using Dockerfile\r\n\r\nThe following steps permit to build the Docker image based on the local source files.\r\n\r\n1. Clone the repo locally:\r\n\r\n```sh\r\n$ cd /path/to/my_install_folder/\r\n\r\n$ git clone https://github.com/ssenart/gazpar2haws.git\r\n```\r\n\r\n2. Edit the docker-compose.yaml file by setting the environment variables corresponding to your GrDF account and Home Assistant setup:\r\n\r\n```yaml\r\nenvironment:\r\n  - GRDF_USERNAME=\u003cGrDF account username\u003e\r\n  - GRDF_PASSWORD=\u003cGrDF account password\u003e\r\n  - GRDF_PCE_IDENTIFIER=\u003cGrDF PCE meter identifier\u003e\r\n  - HOMEASSISTANT_HOST=\u003cHome Assistant instance host name\u003e\r\n  - HOMEASSISTANT_PORT=\u003cHome Assistant instance port number\u003e\r\n  - HOMEASSISTANT_TOKEN=\u003cHome Assistant access token\u003e\r\n```\r\n\r\n3. Build the image:\r\n\r\n```sh\r\n$ docker compose -f docker/docker-compose.yaml build\r\n```\r\n\r\n4. Run the container:\r\n\r\n```sh\r\n$ docker compose -f docker/docker-compose.yaml up -d\r\n```\r\n\r\n### 5. Using source files\r\n\r\nThe project requires [Poetry](https://python-poetry.org/) tool for dependency and package management.\r\n\r\n```sh\r\n$ cd /path/to/my_install_folder/\r\n\r\n$ git clone https://github.com/ssenart/gazpar2haws.git\r\n\r\n$ cd gazpar2haws\r\n\r\n$ poetry install\r\n\r\n$ poetry shell\r\n\r\n```\r\n\r\n## Usage\r\n\r\n### Command line\r\n\r\n```sh\r\n$ python -m gazpar2haws --config /path/to/configuration.yaml --secrets /path/to/secrets.yaml\r\n```\r\n\r\n### Configuration file\r\n\r\nThe default configuration file is below.\r\n\r\n```yaml\r\nlogging:\r\n  file: log/gazpar2haws.log\r\n  console: true\r\n  level: debug\r\n  format: \"%(asctime)s %(levelname)s [%(name)s] %(message)s\"\r\n\r\ngrdf:\r\n  scan_interval: 0 # Number of minutes between each data retrieval (0 means no scan: a single data retrieval at startup, then stops).\r\n  devices:\r\n    - name: gazpar2haws # Name of the device in home assistant. It will be used as the entity_id prefix: sensor.${name}_*.\r\n      username: \"!secret grdf.username\"\r\n      password: \"!secret grdf.password\"\r\n      pce_identifier: \"!secret grdf.pce_identifier\"\r\n      timezone: Europe/Paris\r\n      last_days: 365 # Number of days of data to retrieve\r\n      reset: false # If true, the data will be reset before the first data retrieval\r\n\r\nhomeassistant:\r\n  host: \"!secret homeassistant.host\"\r\n  port: \"!secret homeassistant.port\"\r\n  token: \"!secret homeassistant.token\"\r\n```\r\n\r\nThe default secret file:\r\n\r\n```yaml\r\ngrdf.username: ${GRDF_USERNAME}\r\ngrdf.password: ${GRDF_PASSWORD}\r\ngrdf.pce_identifier: ${GRDF_PCE_IDENTIFIER}\r\n\r\nhomeassistant.host: ${HA_HOST}\r\nhomeassistant.port: ${HA_PORT}\r\nhomeassistant.token: ${HA_TOKEN}\r\n```\r\n\r\nThe history is uploaded on the entities with names:\r\n\r\n- sensor.${name}\\_volume: Volume history in m³.\r\n- sensor.${name}\\_energy: Energy history in kWh.\r\n- sensor.${name}\\_consumption_cost: Cost from consumption (if pricing configured).\r\n- sensor.${name}\\_subscription_cost: Cost from subscription (if pricing configured).\r\n- sensor.${name}\\_transport_cost: Cost from transport (if pricing configured).\r\n- sensor.${name}\\_energy_taxes_cost: Cost from energy taxes (if pricing configured).\r\n- sensor.${name}\\_total_cost: Total cost (if pricing configured).\r\n\r\n`${name}` is 'gazpar2haws' defined in the above configuration file. It can be replaced by any other name.\r\n\r\n### Cost configuration\r\n\r\nGazpar2HAWS is able to compute and publish cost history to Home Assistant.\r\n\r\nThe cost computation is based in gas prices defined in the configuration files.\r\n\r\nThe section 'Pricing' is broken into 5 sub-sections:\r\n- vat: Value added tax definition.\r\n- consumption_prices: Gas consumption prices, typically in €/kWh (quantity-based).\r\n- subscription_prices: Fixed subscription prices, typically in €/month or €/year (time-based).\r\n- transport_prices: Transport prices, either fixed (€/month or €/year) or based on consumption (€/kWh).\r\n- energy_taxes: Energy taxes, typically in €/kWh (quantity-based).\r\n\r\nBelow, many examples illustrates how to use pricing configuration for use cases from the simplest to the most complex.\r\n\r\n\r\nExample 1: A fixed consumption price\r\n---\r\n\r\nThe given price applies at the given date, after and before.\r\n\r\nThe default unit is € per kWh.\r\n\r\n**Formula:**\r\n```math\r\ncost[€] = quantity[kWh] * price[€/kWh]\r\n```\r\n\r\n\r\n```yaml\r\npricing:\r\n  consumption_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 0.07790 # Default unit is €/kWh.\r\n```\r\n\r\nExample 2: A fixed consumption price in another unit\r\n---\r\n\r\n*price_unit* is the monetary unit (default: €).\r\n*quantity_unit* is the energy unit (default: kWh).\r\n\r\n**Formula:**\r\n```math\r\ncost[€] = \\frac{quantity[kWh] * price[¢/MWh] * converter\\_factor[¢-\u003e€]} {converter\\_factor[MWh-\u003ekWh]}\r\n```\r\n\r\n\r\n```yaml\r\npricing:\r\n  consumption_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 7790.0 # Unit is now ¢/MWh.\r\n      price_unit: \"¢\"\r\n      quantity_unit: \"MWh\"\r\n```\r\n\r\nExample 3: Multiple prices over time\r\n---\r\n\r\n```yaml\r\npricing:\r\n  consumption_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 0.07790 # Default unit is €/kWh.\r\n    - start_date: \"2024-01-01\"\r\n      quantity_value: 0.06888 # Default unit is €/kWh.\r\n```\r\n\r\nPrice is 0.07790 before 2024-01-01.\r\n\r\nPrice is 0.06888 on 2024-01-01 and after.\r\n\r\n\r\nExample 4: Price is given excluding tax\r\n---\r\n\r\nThe *normal* value added tax (*vat*) rate is 20%.\r\n\r\n```yaml\r\npricing:\r\n  vat:\r\n    - id: normal\r\n      start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      value: 0.20 # It is the tax rate in [0, 1.0] \u003c==\u003e [0% - 100%].\r\n  consumption_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 0.07790 # Default unit is €/kWh.\r\n      vat_id: \"normal\" # Reference to the vat rate that is applied for this period.\r\n```\r\n\r\n**Formula:**\r\n```math\r\ncost[€] = quantity[kWh] * price[€/kWh] * (1 + vat[normal])\r\n```\r\n\r\nExample 5: Subscription price\r\n---\r\n\r\nA fixed montly subscription is due over consumption.\r\n\r\nSubscription *vat* tax may be different than the consumption *vat* tax.\r\n\r\n```yaml\r\npricing:\r\n  vat:\r\n    - id: normal\r\n      start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      value: 0.20 # It is the tax rate in [0, 1.0] \u003c==\u003e [0% - 100%].\r\n    - id: reduced\r\n      start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      value: 0.0550\r\n  consumption_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 0.07790 # Default unit is €/kWh.\r\n      vat_id: \"normal\" # Reference to the vat rate that is applied for this period.\r\n  subscription_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      time_value: 19.83\r\n      price_unit: \"€\"\r\n      time_unit: \"month\"\r\n      vat_id: \"reduced\"\r\n```\r\n\r\n**Formula:**\r\n```math\r\ncost[€] = quantity[kWh] * cons\\_price[€/kWh] * (1 + vat[normal]) + sub\\_price * (1 + vat[reduced])\r\n```\r\n\r\n\r\nExample 6: Transport price (fixed fee)\r\n---\r\n\r\nA fixed yearly transport may be charged as well.\r\n\r\n```yaml\r\npricing:\r\n  vat:\r\n    - id: normal\r\n      start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      value: 0.20 # It is the tax rate in [0, 1.0] \u003c==\u003e [0% - 100%].\r\n    - id: reduced\r\n      start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      value: 0.0550\r\n  consumption_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 0.07790 # Default unit is €/kWh.\r\n      vat_id: \"normal\" # Reference to the vat rate that is applied for this period.\r\n  transport_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      time_value: 34.38\r\n      price_unit: \"€\"\r\n      time_unit: \"year\"\r\n      vat_id: reduced\r\n```\r\n**Formula:**\r\n```math\r\ncost[€] = quantity[kWh] * cons\\_price[€/kWh] * (1 + vat[normal]) + trans\\_price[€/year] * (1 + vat[reduced])\r\n```\r\n\r\nExample 6bis: Transport price (based on consumption)\r\n---\r\n\r\nTransport can also be charged per kWh consumed.\r\n\r\n```yaml\r\npricing:\r\n  vat:\r\n    - id: normal\r\n      start_date: \"2023-06-01\"\r\n      value: 0.20\r\n    - id: reduced\r\n      start_date: \"2023-06-01\"\r\n      value: 0.0550\r\n  consumption_prices:\r\n    - start_date: \"2023-06-01\"\r\n      quantity_value: 0.07790\r\n      vat_id: \"normal\"\r\n  transport_prices:\r\n    - start_date: \"2023-06-01\"\r\n      quantity_value: 0.00194 # €/kWh\r\n      price_unit: \"€\"\r\n      quantity_unit: \"kWh\"\r\n      vat_id: reduced\r\n```\r\n**Formula:**\r\n```math\r\ncost[€] = quantity[kWh] * (cons\\_price[€/kWh] * (1 + vat[normal]) + quantity[kWh] * trans\\_price[€/kWh] * (1 + vat[reduced]))\r\n```\r\n\r\nExample 7: Energy taxes\r\n---\r\n\r\nConsumption may be taxed by additional taxes (known as energy taxes).\r\n\r\n```yaml\r\npricing:\r\n  vat:\r\n    - id: normal\r\n      start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      value: 0.20 # It is the tax rate in [0, 1.0] \u003c==\u003e [0% - 100%].\r\n    - id: reduced\r\n      start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      value: 0.0550\r\n  consumption_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 0.07790 # Default unit is €/kWh.\r\n      vat_id: \"normal\" # Reference to the vat rate that is applied for this period.\r\n  energy_taxes:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 0.00837\r\n      price_unit: \"€\"\r\n      quantity_unit: \"kWh\"\r\n      vat_id: normal\r\n```\r\n**Formula:**\r\n```math\r\ncost[€] = quantity[kWh] * (cons\\_price[€/kWh] + ener\\_taxes[€/kWh])* (1 + vat[normal])\r\n```\r\n\r\nExample 8: All in one\r\n---\r\n\r\nIn the price list, the first item properties are propagated to the next items in the list. If their values does not change, it is not required to repeat them.\r\n\r\n```yaml\r\npricing:\r\n  vat:\r\n    - id: reduced\r\n      start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      value: 0.0550\r\n    - id: normal\r\n      start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      value: 0.20\r\n  consumption_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 0.07790\r\n      price_unit: \"€\"\r\n      quantity_unit: \"kWh\"\r\n      vat_id: normal\r\n    - start_date: \"2023-07-01\"\r\n      quantity_value: 0.05392\r\n    - start_date: \"2023-08-01\"\r\n      quantity_value: 0.05568\r\n    - start_date: \"2023-09-01\"\r\n      quantity_value: 0.05412\r\n    - start_date: \"2023-10-01\"\r\n      quantity_value: 0.06333\r\n    - start_date: \"2023-11-01\"\r\n      quantity_value: 0.06716\r\n    - start_date: \"2023-12-01\"\r\n      quantity_value: 0.07235\r\n    - start_date: \"2024-01-01\"\r\n      quantity_value: 0.06888\r\n    - start_date: \"2024-02-01\"\r\n      quantity_value: 0.05972\r\n    - start_date: \"2024-03-01\"\r\n      quantity_value: 0.05506\r\n    - start_date: \"2024-04-01\"\r\n      quantity_value: 0.04842\r\n    - start_date: \"2025-01-01\"\r\n      quantity_value: 0.07807\r\n  subscription_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      time_value: 19.83\r\n      price_unit: \"€\"\r\n      time_unit: \"month\"\r\n      vat_id: reduced\r\n    - start_date: \"2023-07-01\"\r\n      time_value: 20.36\r\n  transport_prices:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      time_value: 34.38\r\n      price_unit: \"€\"\r\n      time_unit: \"year\"\r\n      vat_id: reduced\r\n  energy_taxes:\r\n    - start_date: \"2023-06-01\" # Date of the price. Format is \"YYYY-MM-DD\".\r\n      quantity_value: 0.00837\r\n      price_unit: \"€\"\r\n      quantity_unit: \"kWh\"\r\n      vat_id: normal\r\n    - start_date: \"2024-01-01\"\r\n      quantity_value: 0.01637\r\n```\r\n\r\n## What's New in v0.4.0\r\n\r\n### Enhanced Cost Breakdown\r\n\r\nStarting from version 0.4.0, Gazpar2HAWS provides detailed cost breakdowns in Home Assistant. In addition to the total cost, separate entities are published for each cost component:\r\n\r\n- `sensor.${name}_consumption_cost`: Cost from gas consumption (quantity × consumption_price)\r\n- `sensor.${name}_subscription_cost`: Cost from fixed subscription fees\r\n- `sensor.${name}_transport_cost`: Cost from transport fees\r\n- `sensor.${name}_energy_taxes_cost`: Cost from energy taxes\r\n- `sensor.${name}_total_cost`: Total cost (sum of all components)\r\n\r\nWhere `${name}` is the device name configured in your `configuration.yaml` file (default: `gazpar2haws`).\r\n\r\nThis breakdown allows you to analyze which components contribute the most to your total gas bill over time.\r\n\r\n### Composite Price Model\r\n\r\nThe new pricing model supports **composite prices** where each price component can have:\r\n\r\n1. **Quantity component**: Variable cost based on consumption (e.g., €/kWh)\r\n2. **Time component**: Fixed cost based on time period (e.g., €/month)\r\n\r\nThis provides more flexibility to accurately model your energy provider's billing structure. For example:\r\n\r\n- **Consumption prices**: Typically have only a quantity component (€/kWh)\r\n- **Subscription prices**: Typically have only a time component (€/month)\r\n- **Transport prices**: Can have either a quantity component (€/kWh) or a time component (€/year)\r\n- **Energy taxes**: Typically have only a quantity component (€/kWh)\r\n\r\n### ⚠️ Migration Required from v0.3.x\r\n\r\n**If you are upgrading from v0.3.x**, the pricing configuration format has changed. You must update your configuration file to the new format.\r\n\r\n**See [docs/MIGRATIONS_GUIDE.md](docs/MIGRATIONS_GUIDE.md) for detailed step-by-step migration instructions** including:\r\n- Complete before/after examples for each price type\r\n- Migration checklist\r\n- Common issues and troubleshooting\r\n\r\nIf you're a new user or already on v0.4.0, you can skip this section.\r\n\r\n### Environment variable for Docker\r\n\r\nIn a Docker environment, the configurations files are instantiated by replacing the environment variables below in the template files:\r\n\r\n| Environment variable | Description                                                                   | Required | Default value  |\r\n| -------------------- | ----------------------------------------------------------------------------- | -------- | -------------- |\r\n| GRDF_USERNAME        | GrDF account user name                                                        | Yes      | -              |\r\n| GRDF_PASSWORD        | GrDF account password (avoid using special characters)                        | Yes      | -              |\r\n| GRDF_PCE_IDENTIFIER  | GrDF meter PCE identifier                                                     | Yes      | -              |\r\n| GRDF_SCAN_INTERVAL   | Period in minutes to refresh meter data (0 means one single refresh and stop) | No       | 480 (8 hours)  |\r\n| GRDF_LAST_DAYS       | Number of days of history data to retrieve                                    | No       | 1095 (3 years) |\r\n| HOMEASSISTANT_HOST   | Home Assistant instance host name                                             | Yes      | -              |\r\n| HOMEASSISTANT_PORT   | Home Assistant instance port number                                           | No       | 8123           |\r\n| HOMEASSISTANT_TOKEN  | Home Assistant access token                                                   | Yes      | -              |\r\n\r\nYou can setup them directly in a docker-compose.yaml file (environment section) or from a Docker command line (-e option).\r\n\r\n## FAQ\r\n\r\nFor a comprehensive list of frequently asked questions, see **[docs/FAQ.md](docs/FAQ.md)** which includes:\r\n\r\n- 📖 **General questions** - What is Gazpar2HAWS, differences from other solutions\r\n- ⚙️ **Configuration issues** - PCE identifier, reset parameter, environment variables\r\n- 📊 **Data \u0026 statistics** - Missing data, date issues, historical retrieval\r\n- 💰 **Cost calculation** - Pricing configuration, v0.4.0 migration, new entities\r\n- 🏠 **Home Assistant integration** - Entity setup, Energy Dashboard, HassIO issues\r\n- 🐳 **Docker \u0026 Add-on** - Installation, logs, version issues\r\n- 🔧 **Troubleshooting** - Common errors, log messages, bug reporting\r\n- 🔄 **Migration \u0026 upgrades** - Version upgrade guides, breaking changes\r\n\r\n### Quick Answers\r\n\r\n**Is it an official GrDF application?**\r\n\r\nNo, absolutely not. It was made by reverse engineering GrDF website without any guarantee of long-term operation. Indeed, any modification made to their website risks breaking it.\r\n\r\n**What are the differences between PyGazpar, home-assistant-gazpar, Gazpar2MQTT, and Gazpar2HAWS?**\r\n\r\n- **[PyGazpar](https://github.com/ssenart/PyGazpar)** - Low-level Python library used to query GrDF data\r\n- **[home-assistant-gazpar](https://github.com/ssenart/home-assistant-gazpar)** - Home Assistant integration providing energy sensor with Recorder/Energy Dashboard support\r\n- **[Gazpar2MQTT](https://github.com/ssenart/gazpar2mqtt)** - Standalone application that publishes data via MQTT (reduces coupling with HA)\r\n- **[Gazpar2HAWS](https://github.com/ssenart/gazpar2haws)** - Uses HA Recorder integration directly, timestamps readings to exact observation dates, reconstructs 3-year history, calculates detailed costs\r\n\r\n**My PCE ID has a leading zero (e.g. \"0123456789\") but it's being truncated. Why?**\r\n\r\nThe PCE identifier must be quoted in your YAML configuration. Without quotes, it's interpreted as a number and loses the leading zero.\r\n\r\n```yaml\r\n# ✓ Correct\r\npce_identifier: \"0123456789\"\r\n\r\n# ✗ Wrong - loses leading zero\r\npce_identifier: 0123456789\r\n```\r\n\r\nSee [docs/FAQ.md](docs/FAQ.md) for more questions and detailed answers.\r\n\r\n## Troubleshooting\r\n\r\nFor comprehensive troubleshooting guidance, see **[docs/FAQ.md](docs/FAQ.md#troubleshooting)** which includes:\r\n\r\n- Common log messages and their meanings\r\n- Step-by-step debugging procedures\r\n- Solutions to known issues from GitHub\r\n- Error handling guides\r\n\r\n### Quick Troubleshooting Steps\r\n\r\nSometimes, for any reason, the application does not work as expected. No entities is created in HA, some error messages are displayed, nothing happens...\r\n\r\n**In this situation:**\r\n\r\n1. **Check the log file** - This is the most valuable troubleshooting tool\r\n2. **Enable debug logging** - Set `logging.level: debug` in your configuration\r\n3. **Verify configuration syntax** - Use a YAML validator\r\n4. **Check [docs/FAQ.md](docs/FAQ.md)** - Many common issues are already documented\r\n\r\nIf your configuration is correct, you may have spotted a bug.\r\n\r\nIn this case, capture a GitHub issue [here](https://github.com/ssenart/gazpar2haws/issues) with the following information:\r\n1. What kind of setup do you use ? Standalone application, Docker container or HA addon.\r\n2. Is this a first installation or a version upgrade ? If upgrading version, what was the previous version and did it work well ?\r\n3. Describe as precisely as possible what is happening.\r\n4. Provide the complete log file (from start to finish) and make sure to erase all your secrets from it.\r\n\r\nThe first log lines should be similar to:\r\n```log\r\n2025-02-17 02:01:17,626 INFO [__main__] Starting Gazpar2HAWS version 0.4.0\r\n2025-02-17 02:01:17,627 INFO [__main__] Running on Python version: 3.12.9 (main, Feb  7 2025, 01:03:02) [GCC 12.2.0]\r\n```\r\n\r\nThe normal last lines of the log should be:\r\n```log\r\n2025-02-17 10:02:42,162 INFO [gazpar2haws.gazpar] No volume data to publish\r\n2025-02-17 10:02:42,162 INFO [gazpar2haws.gazpar] No energy data to publish\r\n2025-02-17 10:02:42,162 INFO [gazpar2haws.gazpar] No cost data to publish\r\n2025-02-17 10:02:42,162 INFO [gazpar2haws.bridge] Device 'gazpar2haws' data published to Home Assistant WS.\r\n2025-02-17 10:02:42,162 INFO [gazpar2haws.bridge] Gazpar data published to Home Assistant WS.\r\n2025-02-17 10:02:42,166 INFO [gazpar2haws.bridge] Waiting 480 minutes before next scan...\r\n```\r\n\r\n## Publish a new image on Docker Hub\r\n\r\n1. List all local images\r\n\r\n```sh\r\n$ docker image ls\r\n```\r\n\r\n2. Build a new local image\r\n\r\n```sh\r\n$ docker compose -f docker/docker-compose.yaml build\r\n```\r\n\r\n3. Tag the new built image with the version number\r\n\r\n```sh\r\n$ docker image tag ssenart/gazpar2haws:latest ssenart/gazpar2haws:0.1.2\r\n```\r\n\r\n4. Login in Docker Hub\r\n\r\n```sh\r\n$ docker login\r\n```\r\n\r\n5. Push all the tagged local images to Docker Hub\r\n\r\n```sh\r\n$ docker push --all-tags ssenart/gazpar2haws\r\n```\r\n\r\nAll the gazpar2haws images are available [here](https://hub.docker.com/repository/docker/ssenart/gazpar2haws/general).\r\n\r\n## Contributing\r\n\r\nPull requests are welcome! For any change proposal, please open an issue first to discuss what you would like to change.\r\n\r\n### Before Contributing\r\n\r\n1. **Read [CLAUDE.md](CLAUDE.md)** - Developer guide with:\r\n   - Architecture overview\r\n   - Development commands (setup, testing, linting)\r\n   - Code structure and patterns\r\n   - Testing guidelines\r\n\r\n2. **Check [docs/TODO.md](docs/TODO.md)** - For planned improvements and test coverage gaps\r\n\r\n3. **Review [CHANGELOG.md](CHANGELOG.md)** - To understand recent changes and version history\r\n\r\n### Contribution Guidelines\r\n\r\n- Write tests for new features (see [docs/TODO.md](docs/TODO.md) for test coverage goals)\r\n- Follow existing code style and patterns\r\n- Update documentation (README.md, docs/FAQ.md) as appropriate\r\n- Add entries to CHANGELOG.md for your changes\r\n- Ensure all tests pass: `poetry run pytest`\r\n- Run linters: `poetry run pylint gazpar2haws`\r\n\r\n## License\r\n\r\n[MIT](https://choosealicense.com/licenses/mit/)\r\n\r\n## Project status\r\n\r\nGazpar2HAWS has been initiated for integration with [Home Assistant](https://www.home-assistant.io/) energy dashboard.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssenart%2Fgazpar2haws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fssenart%2Fgazpar2haws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssenart%2Fgazpar2haws/lists"}