gazpar2haws

Gazpar2HAWS is a gateway that reads data history from the GrDF (French gas provider) meter and send it to Home Assistant using WebSocket interface.

It is compatible with Home Assistant Energy Dashboard and permits to upload the history and keep it updated with the latest readings.

It is a complement to the other available projects:

• home-assistant-gazpar: HA integration that publishes a Gazpar entity with the corresponding meter value.
• gazpar2mqtt: home-assistant-gazpar alternative but using MQTT events (it reduce coupling with HA).
• lovelace-gazpar-card: HA dashboard card compatible with home-assistant-gazpar and gazpar2mqtt.

🎉 What's New in v0.5.0

Flexible Pricing Components

Define unlimited custom pricing component names instead of being limited to 4 hardcoded names!

pricing:
  # Use any names that match your billing structure
  base_energy_cost: [...]
  peak_surcharge: [...]
  carbon_tax: [...]
  distribution_network: [...]
  # Add as many as you need!

Key Features:

• ✅ Unlimited components (not just 4)
• ✅ Custom names (e.g., carbon_tax, peak_rate)
• ✅ Automatic Home Assistant sensors
• ✅ 100% backward compatible

Learn More:

• 📖 Flexible Pricing Guide - Complete documentation
• 📝 Example 9 - See it in action
• 🔄 CHANGELOG - Full release notes

Documentation

User Documentation

• README.md (this file) - Complete installation, configuration, and usage guide
• docs/FAQ.md - Frequently Asked Questions based on GitHub issues and user feedback
  • Common configuration issues
  • Troubleshooting steps
  • Migration guides
  • All known issues and solutions
• CHANGELOG.md - Version history with all changes, fixes, and new features

Developer Documentation

• docs/DEVELOPER_GUIDE.md - Comprehensive developer guide
  • Architecture overview and design patterns
  • Development setup and workflow
  • Testing strategies and code quality
  • Contributing guidelines and release process
• docs/TODO.md - Planned improvements and test coverage tasks
  • Test coverage analysis
  • Missing tests by priority
  • Implementation schedule
  • Known issues requiring tests

Quick Links

• 🐛 Found a bug? → Check docs/FAQ.md first, then open an issue
• 📝 Want to contribute? → Read docs/DEVELOPER_GUIDE.md and docs/TODO.md
• 🔄 Upgrading? → Check CHANGELOG.md for breaking changes
• ❓ Have a question? → See docs/FAQ.md or ask in discussions

Installation

Gazpar2HAWS can be installed in many ways.

1. Home Assistant Add-on

In 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).

For usage and configuration, read the documentation here.

2. Using Docker Hub

The following steps permits to run a container from an existing image available in the Docker Hub repository.

1. Copy and save the following docker-compose.yaml file:

services:
  gazpar2haws:
    image: ssenart/gazpar2haws:latest
    container_name: gazpar2haws
    restart: unless-stopped
    network_mode: bridge
    user: "1000:1000"
    volumes:
      - ./gazpar2haws/config:/app/config
      - ./gazpar2haws/log:/app/log
    environment:
      - GRDF_USERNAME=<GrDF account username>
      - GRDF_PASSWORD=<GrDF account password>
      - GRDF_PCE_IDENTIFIER=<GrDF PCE meter identifier>
      - HOMEASSISTANT_HOST=<Home Assistant instance host name>
      - HOMEASSISTANT_TOKEN=<Home Assistant access token>

Edit the environment variable section according to your setup.

2. Run the container:

$ docker compose up -d

3. Using PIP package

$ cd /path/to/my_install_folder/

$ mkdir gazpar2haws

$ cd gazpar2haws

$ python -m venv .venv

$ source .venv/bin/activate

$ pip install gazpar2haws

4. Using Dockerfile

The following steps permit to build the Docker image based on the local source files.

1. Clone the repo locally:

$ cd /path/to/my_install_folder/

$ git clone https://github.com/ssenart/gazpar2haws.git

2. Edit the docker-compose.yaml file by setting the environment variables corresponding to your GrDF account and Home Assistant setup:

environment:
  - GRDF_USERNAME=<GrDF account username>
  - GRDF_PASSWORD=<GrDF account password>
  - GRDF_PCE_IDENTIFIER=<GrDF PCE meter identifier>
  - HOMEASSISTANT_HOST=<Home Assistant instance host name>
  - HOMEASSISTANT_PORT=<Home Assistant instance port number>
  - HOMEASSISTANT_TOKEN=<Home Assistant access token>

3. Build the image:

$ docker compose -f docker/docker-compose.yaml build

4. Run the container:

$ docker compose -f docker/docker-compose.yaml up -d

5. Using source files

The project requires Poetry tool for dependency and package management.

$ cd /path/to/my_install_folder/

$ git clone https://github.com/ssenart/gazpar2haws.git

$ cd gazpar2haws

$ poetry install

$ poetry shell

Usage

Command line

$ python -m gazpar2haws --config /path/to/configuration.yaml --secrets /path/to/secrets.yaml

Configuration file

The default configuration file is below.

logging:
  file: log/gazpar2haws.log
  console: true
  level: debug
  format: "%(asctime)s %(levelname)s [%(name)s] %(message)s"

grdf:
  scan_interval: 0 # Number of minutes between each data retrieval (0 means no scan: a single data retrieval at startup, then stops).
  devices:
    - name: gazpar2haws # Name of the device in home assistant. It will be used as the entity_id prefix: sensor.${name}_*.
      username: "!secret grdf.username"
      password: "!secret grdf.password"
      pce_identifier: "!secret grdf.pce_identifier"
      data_source: json # Data source to use: "json" | "excel" | "test" (default: "json")
      consumption_type: informative # GrDF readings to use: "informative" | "published" (default: "informative"). See below.
      timezone: Europe/Paris
      last_days: 365 # Number of days of data to retrieve
      reset: false # If true, the data will be reset before the first data retrieval

homeassistant:
  host: "!secret homeassistant.host"
  port: "!secret homeassistant.port"
  token: "!secret homeassistant.token"
  secure: false # If true, connect using wss:// instead of ws:// (default: false)
  verify_ssl: true # If false, disable TLS certificate verification, e.g. for self-signed certificates (default: true, ignored if secure is false)

Consumption type

For some GrDF accounts, the informative readings endpoint returns no data (an empty {} response) even though a consumption history is visible on the GrDF customer portal. If you see no volume/energy data being published and your logs show Json meter data: {}, set consumption_type: published on the affected device to read from GrDF's published consumption history instead:

grdf:
  devices:
    - name: gazpar2haws
      ...
      consumption_type: published

Note that published readings can cover more than one day; their consumption is attributed to the last day of the covered period rather than split evenly across days.

The default secret file:

grdf.username: ${GRDF_USERNAME}
grdf.password: ${GRDF_PASSWORD}
grdf.pce_identifier: ${GRDF_PCE_IDENTIFIER}

homeassistant.host: ${HA_HOST}
homeassistant.port: ${HA_PORT}
homeassistant.token: ${HA_TOKEN}

The history is uploaded on the entities with names:

• sensor.${name}_volume: Volume history in m³.
• sensor.${name}_energy: Energy history in kWh.
• sensor.${name}_consumption_cost: Cost from consumption (if pricing configured).
• sensor.${name}_subscription_cost: Cost from subscription (if pricing configured).
• sensor.${name}_transport_cost: Cost from transport (if pricing configured).
• sensor.${name}_energy_taxes_cost: Cost from energy taxes (if pricing configured).
• sensor.${name}_total_cost: Total cost (if pricing configured).

${name} is 'gazpar2haws' defined in the above configuration file. It can be replaced by any other name.

Cost configuration

Gazpar2HAWS is able to compute and publish cost history to Home Assistant.

The cost computation is based in gas prices defined in the configuration files.

The section 'Pricing' is broken into 5 sub-sections:

• vat: Value added tax definition.
• consumption_prices: Gas consumption prices, typically in €/kWh (quantity-based).
• subscription_prices: Fixed subscription prices, typically in €/month or €/year (time-based).
• transport_prices: Transport prices, either fixed (€/month or €/year) or based on consumption (€/kWh).
• energy_taxes: Energy taxes, typically in €/kWh (quantity-based).

Below, many examples illustrates how to use pricing configuration for use cases from the simplest to the most complex.

Example 1: A fixed consumption price

The given price applies at the given date, after and before.

The default unit is € per kWh.

Formula:

cost[€] = quantity[kWh] * price[€/kWh]

pricing:
  consumption_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 0.07790 # Default unit is €/kWh.

Example 2: A fixed consumption price in another unit

price_unit is the monetary unit (default: €). quantity_unit is the energy unit (default: kWh).

Formula:

cost[€] = \frac{quantity[kWh] * price[¢/MWh] * converter\_factor[¢->€]} {converter\_factor[MWh->kWh]}

pricing:
  consumption_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 7790.0 # Unit is now ¢/MWh.
      price_unit: "¢"
      quantity_unit: "MWh"

Example 3: Multiple prices over time

pricing:
  consumption_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 0.07790 # Default unit is €/kWh.
    - start_date: "2024-01-01"
      quantity_value: 0.06888 # Default unit is €/kWh.

Price is 0.07790 before 2024-01-01.

Price is 0.06888 on 2024-01-01 and after.

Example 4: Price is given excluding tax

The normal value added tax (vat) rate is 20%.

pricing:
  vat:
    - id: normal
      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
  consumption_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 0.07790 # Default unit is €/kWh.
      vat_id: "normal" # Reference to the vat rate that is applied for this period.

Formula:

cost[€] = quantity[kWh] * price[€/kWh] * (1 + vat[normal])

Example 5: Subscription price

A fixed montly subscription is due over consumption.

Subscription vat tax may be different than the consumption vat tax.

pricing:
  vat:
    - id: normal
      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
    - id: reduced
      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      value: 0.0550
  consumption_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 0.07790 # Default unit is €/kWh.
      vat_id: "normal" # Reference to the vat rate that is applied for this period.
  subscription_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      time_value: 19.83
      price_unit: "€"
      time_unit: "month"
      vat_id: "reduced"

Formula:

cost[€] = quantity[kWh] * cons\_price[€/kWh] * (1 + vat[normal]) + sub\_price * (1 + vat[reduced])

Example 6: Transport price (fixed fee)

A fixed yearly transport may be charged as well.

pricing:
  vat:
    - id: normal
      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
    - id: reduced
      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      value: 0.0550
  consumption_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 0.07790 # Default unit is €/kWh.
      vat_id: "normal" # Reference to the vat rate that is applied for this period.
  transport_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      time_value: 34.38
      price_unit: "€"
      time_unit: "year"
      vat_id: reduced

Formula:

cost[€] = quantity[kWh] * cons\_price[€/kWh] * (1 + vat[normal]) + trans\_price[€/year] * (1 + vat[reduced])

Example 6bis: Transport price (based on consumption)

Transport can also be charged per kWh consumed.

pricing:
  vat:
    - id: normal
      start_date: "2023-06-01"
      value: 0.20
    - id: reduced
      start_date: "2023-06-01"
      value: 0.0550
  consumption_prices:
    - start_date: "2023-06-01"
      quantity_value: 0.07790
      vat_id: "normal"
  transport_prices:
    - start_date: "2023-06-01"
      quantity_value: 0.00194 # €/kWh
      price_unit: "€"
      quantity_unit: "kWh"
      vat_id: reduced

Formula:

cost[€] = quantity[kWh] * (cons\_price[€/kWh] * (1 + vat[normal]) + quantity[kWh] * trans\_price[€/kWh] * (1 + vat[reduced]))

Example 7: Energy taxes

Consumption may be taxed by additional taxes (known as energy taxes).

pricing:
  vat:
    - id: normal
      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      value: 0.20 # It is the tax rate in [0, 1.0] <==> [0% - 100%].
    - id: reduced
      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      value: 0.0550
  consumption_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 0.07790 # Default unit is €/kWh.
      vat_id: "normal" # Reference to the vat rate that is applied for this period.
  energy_taxes:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 0.00837
      price_unit: "€"
      quantity_unit: "kWh"
      vat_id: normal

Formula:

cost[€] = quantity[kWh] * (cons\_price[€/kWh] + ener\_taxes[€/kWh])* (1 + vat[normal])

Example 8: All in one

In 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.

pricing:
  vat:
    - id: reduced
      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      value: 0.0550
    - id: normal
      start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      value: 0.20
  consumption_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 0.07790
      price_unit: "€"
      quantity_unit: "kWh"
      vat_id: normal
    - start_date: "2023-07-01"
      quantity_value: 0.05392
    - start_date: "2023-08-01"
      quantity_value: 0.05568
    - start_date: "2023-09-01"
      quantity_value: 0.05412
    - start_date: "2023-10-01"
      quantity_value: 0.06333
    - start_date: "2023-11-01"
      quantity_value: 0.06716
    - start_date: "2023-12-01"
      quantity_value: 0.07235
    - start_date: "2024-01-01"
      quantity_value: 0.06888
    - start_date: "2024-02-01"
      quantity_value: 0.05972
    - start_date: "2024-03-01"
      quantity_value: 0.05506
    - start_date: "2024-04-01"
      quantity_value: 0.04842
    - start_date: "2025-01-01"
      quantity_value: 0.07807
  subscription_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      time_value: 19.83
      price_unit: "€"
      time_unit: "month"
      vat_id: reduced
    - start_date: "2023-07-01"
      time_value: 20.36
  transport_prices:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      time_value: 34.38
      price_unit: "€"
      time_unit: "year"
      vat_id: reduced
  energy_taxes:
    - start_date: "2023-06-01" # Date of the price. Format is "YYYY-MM-DD".
      quantity_value: 0.00837
      price_unit: "€"
      quantity_unit: "kWh"
      vat_id: normal
    - start_date: "2024-01-01"
      quantity_value: 0.01637

What's New in v0.4.0

Enhanced Cost Breakdown

Starting 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:

• sensor.${name}_consumption_cost: Cost from gas consumption (quantity × consumption_price)
• sensor.${name}_subscription_cost: Cost from fixed subscription fees
• sensor.${name}_transport_cost: Cost from transport fees
• sensor.${name}_energy_taxes_cost: Cost from energy taxes
• sensor.${name}_total_cost: Total cost (sum of all components)

Where ${name} is the device name configured in your configuration.yaml file (default: gazpar2haws).

This breakdown allows you to analyze which components contribute the most to your total gas bill over time.

Composite Price Model

The new pricing model supports composite prices where each price component can have:

1. Quantity component: Variable cost based on consumption (e.g., €/kWh)
2. Time component: Fixed cost based on time period (e.g., €/month)

This provides more flexibility to accurately model your energy provider's billing structure. For example:

• Consumption prices: Typically have only a quantity component (€/kWh)
• Subscription prices: Typically have only a time component (€/month)
• Transport prices: Can have either a quantity component (€/kWh) or a time component (€/year)
• Energy taxes: Typically have only a quantity component (€/kWh)

⚠️ Migration Required from v0.3.x

If you are upgrading from v0.3.x, the pricing configuration format has changed. You must update your configuration file to the new format.

See docs/MIGRATIONS_GUIDE.md for detailed step-by-step migration instructions including:

• Complete before/after examples for each price type
• Migration checklist
• Common issues and troubleshooting

If you're a new user or already on v0.4.0, you can skip this section.

Environment variable for Docker

In a Docker environment, the configurations files are instantiated by replacing the environment variables below in the template files:

You can setup them directly in a docker-compose.yaml file (environment section) or from a Docker command line (-e option).

FAQ

For a comprehensive list of frequently asked questions, see docs/FAQ.md which includes:

• 📖 General questions - What is Gazpar2HAWS, differences from other solutions
• ⚙️ Configuration issues - PCE identifier, reset parameter, environment variables
• 📊 Data & statistics - Missing data, date issues, historical retrieval
• 💰 Cost calculation - Pricing configuration, v0.4.0 migration, new entities
• 🏠 Home Assistant integration - Entity setup, Energy Dashboard, HassIO issues
• 🐳 Docker & Add-on - Installation, logs, version issues
• 🔧 Troubleshooting - Common errors, log messages, bug reporting
• 🔄 Migration & upgrades - Version upgrade guides, breaking changes

Quick Answers

Is it an official GrDF application?

No, 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.

What are the differences between PyGazpar, home-assistant-gazpar, Gazpar2MQTT, and Gazpar2HAWS?

• PyGazpar - Low-level Python library used to query GrDF data
• home-assistant-gazpar - Home Assistant integration providing energy sensor with Recorder/Energy Dashboard support
• Gazpar2MQTT - Standalone application that publishes data via MQTT (reduces coupling with HA)
• Gazpar2HAWS - Uses HA Recorder integration directly, timestamps readings to exact observation dates, reconstructs 3-year history, calculates detailed costs

My PCE ID has a leading zero (e.g. "0123456789") but it's being truncated. Why?

The PCE identifier must be quoted in your YAML configuration. Without quotes, it's interpreted as a number and loses the leading zero.

# ✓ Correct
pce_identifier: "0123456789"

# ✗ Wrong - loses leading zero
pce_identifier: 0123456789

See docs/FAQ.md for more questions and detailed answers.

Troubleshooting

For comprehensive troubleshooting guidance, see docs/FAQ.md which includes:

• Common log messages and their meanings
• Step-by-step debugging procedures
• Solutions to known issues from GitHub
• Error handling guides

Quick Troubleshooting Steps

Sometimes, for any reason, the application does not work as expected. No entities is created in HA, some error messages are displayed, nothing happens...

In this situation:

1. Check the log file - This is the most valuable troubleshooting tool
2. Enable debug logging - Set logging.level: debug in your configuration
3. Verify configuration syntax - Use a YAML validator
4. Check docs/FAQ.md - Many common issues are already documented

If your configuration is correct, you may have spotted a bug.

In this case, capture a GitHub issue here with the following information:

1. What kind of setup do you use ? Standalone application, Docker container or HA addon.
2. Is this a first installation or a version upgrade ? If upgrading version, what was the previous version and did it work well ?
3. Describe as precisely as possible what is happening.
4. Provide the complete log file (from start to finish) and make sure to erase all your secrets from it.

The first log lines should be similar to:

2025-02-17 02:01:17,626 INFO [__main__] Starting Gazpar2HAWS version 0.4.0
2025-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]

The normal last lines of the log should be:

2025-02-17 10:02:42,162 INFO [gazpar2haws.gazpar] No volume data to publish
2025-02-17 10:02:42,162 INFO [gazpar2haws.gazpar] No energy data to publish
2025-02-17 10:02:42,162 INFO [gazpar2haws.gazpar] No cost data to publish
2025-02-17 10:02:42,162 INFO [gazpar2haws.bridge] Device 'gazpar2haws' data published to Home Assistant WS.
2025-02-17 10:02:42,162 INFO [gazpar2haws.bridge] Gazpar data published to Home Assistant WS.
2025-02-17 10:02:42,166 INFO [gazpar2haws.bridge] Waiting 480 minutes before next scan...

Publish a new image on Docker Hub

1. List all local images

$ docker image ls

2. Build a new local image

$ docker compose -f docker/docker-compose.yaml build

3. Tag the new built image with the version number

$ docker image tag ssenart/gazpar2haws:latest ssenart/gazpar2haws:0.1.2

4. Login in Docker Hub

$ docker login

5. Push all the tagged local images to Docker Hub

$ docker push --all-tags ssenart/gazpar2haws

All the gazpar2haws images are available here.

Contributing

Pull requests are welcome! For any change proposal, please open an issue first to discuss what you would like to change.

Before Contributing

1. Read CLAUDE.md - Developer guide with:

   • Architecture overview
   • Development commands (setup, testing, linting)
   • Code structure and patterns
   • Testing guidelines

2. Check docs/TODO.md - For planned improvements and test coverage gaps

3. Review CHANGELOG.md - To understand recent changes and version history

Contribution Guidelines

• Write tests for new features (see docs/TODO.md for test coverage goals)
• Follow existing code style and patterns
• Update documentation (README.md, docs/FAQ.md) as appropriate
• Add entries to CHANGELOG.md for your changes
• Ensure all tests pass: poetry run pytest
• Run linters: poetry run pylint gazpar2haws

License

MIT

Project status

Gazpar2HAWS has been initiated for integration with Home Assistant energy dashboard.