Metadata-Version: 2.4
Name: gazpar2haws
Version: 0.5.0
Summary: Gazpar2HAWS is a gateway that reads data history from the GrDF (French gas provider) meter and send it to Home Assistant using WebSocket interface
License: MIT License
         
         Copyright (c) 2024 Stéphane Senart
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
License-File: LICENSE
Author: Stéphane Senart
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: pydantic-extra-types (>=2.10.2,<3.0.0)
Requires-Dist: pydantic[email] (>=2.10.6,<3.0.0)
Requires-Dist: pygazpar (>=1.3.1)
Requires-Dist: pyyaml (>=6.0.2)
Requires-Dist: websockets (>=14.1)
Description-Content-Type: text/markdown

# 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](https://github.com/ssenart/home-assistant-gazpar): HA integration that publishes a Gazpar entity with the corresponding meter value.
- [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).
- [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).

---

## 🎉 What's New in v0.5.0

### Flexible Pricing Components

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

```yaml
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](docs/FLEXIBLE_PRICING_GUIDE.md) - Complete documentation
- 📝 [Example 9](#example-9-flexible-pricing-with-custom-component-names-v050) - See it in action
- 🔄 [CHANGELOG](CHANGELOG.md#050---2026-01-30) - Full release notes

---

## Documentation

### User Documentation

- **[README.md](README.md)** (this file) - Complete installation, configuration, and usage guide
- **[docs/FAQ.md](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](CHANGELOG.md)** - Version history with all changes, fixes, and new features

### Developer Documentation

- **[docs/DEVELOPER_GUIDE.md](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](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](docs/FAQ.md) first, then open an [issue](https://github.com/ssenart/gazpar2haws/issues)
- 📝 Want to contribute? → Read [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) and [docs/TODO.md](docs/TODO.md)
- 🔄 Upgrading? → Check [CHANGELOG.md](CHANGELOG.md) for breaking changes
- ❓ Have a question? → See [docs/FAQ.md](docs/FAQ.md) or ask in [discussions](https://github.com/ssenart/gazpar2haws/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).

[![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)

For usage and configuration, read the documentation [here](addons/gazpar2haws/DOCS.md).

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

```yaml
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:

```sh
$ docker compose up -d
```

### 3. Using PIP package

```sh
$ 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:

```sh
$ 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:

```yaml
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:

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

4. Run the container:

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

### 5. Using source files

The project requires [Poetry](https://python-poetry.org/) tool for dependency and package management.

```sh
$ cd /path/to/my_install_folder/

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

$ cd gazpar2haws

$ poetry install

$ poetry shell

```

## Usage

### Command line

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

### Configuration file

The default configuration file is below.

```yaml
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"
      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"
```

The default secret file:

```yaml
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:**
```math
cost[€] = quantity[kWh] * price[€/kWh]
```


```yaml
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:**
```math
cost[€] = \frac{quantity[kWh] * price[¢/MWh] * converter\_factor[¢->€]} {converter\_factor[MWh->kWh]}
```


```yaml
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
---

```yaml
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%.

```yaml
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:**
```math
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.

```yaml
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:**
```math
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.

```yaml
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:**
```math
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.

```yaml
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:**
```math
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).

```yaml
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:**
```math
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.

```yaml
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](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:

| Environment variable | Description                                                                   | Required | Default value  |
| -------------------- | ----------------------------------------------------------------------------- | -------- | -------------- |
| GRDF_USERNAME        | GrDF account user name                                                        | Yes      | -              |
| GRDF_PASSWORD        | GrDF account password (avoid using special characters)                        | Yes      | -              |
| GRDF_PCE_IDENTIFIER  | GrDF meter PCE identifier                                                     | Yes      | -              |
| GRDF_SCAN_INTERVAL   | Period in minutes to refresh meter data (0 means one single refresh and stop) | No       | 480 (8 hours)  |
| GRDF_LAST_DAYS       | Number of days of history data to retrieve                                    | No       | 1095 (3 years) |
| HOMEASSISTANT_HOST   | Home Assistant instance host name                                             | Yes      | -              |
| HOMEASSISTANT_PORT   | Home Assistant instance port number                                           | No       | 8123           |
| HOMEASSISTANT_TOKEN  | Home Assistant access token                                                   | Yes      | -              |

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](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](https://github.com/ssenart/PyGazpar)** - Low-level Python library used to query GrDF data
- **[home-assistant-gazpar](https://github.com/ssenart/home-assistant-gazpar)** - Home Assistant integration providing energy sensor with Recorder/Energy Dashboard support
- **[Gazpar2MQTT](https://github.com/ssenart/gazpar2mqtt)** - Standalone application that publishes data via MQTT (reduces coupling with HA)
- **[Gazpar2HAWS](https://github.com/ssenart/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.

```yaml
# ✓ Correct
pce_identifier: "0123456789"

# ✗ Wrong - loses leading zero
pce_identifier: 0123456789
```

See [docs/FAQ.md](docs/FAQ.md) for more questions and detailed answers.

## Troubleshooting

For comprehensive troubleshooting guidance, see **[docs/FAQ.md](docs/FAQ.md#troubleshooting)** 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](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](https://github.com/ssenart/gazpar2haws/issues) 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:
```log
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:
```log
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

```sh
$ docker image ls
```

2. Build a new local image

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

3. Tag the new built image with the version number

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

4. Login in Docker Hub

```sh
$ docker login
```

5. Push all the tagged local images to Docker Hub

```sh
$ docker push --all-tags ssenart/gazpar2haws
```

All the gazpar2haws images are available [here](https://hub.docker.com/repository/docker/ssenart/gazpar2haws/general).

## 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](CLAUDE.md)** - Developer guide with:
   - Architecture overview
   - Development commands (setup, testing, linting)
   - Code structure and patterns
   - Testing guidelines

2. **Check [docs/TODO.md](docs/TODO.md)** - For planned improvements and test coverage gaps

3. **Review [CHANGELOG.md](CHANGELOG.md)** - To understand recent changes and version history

### Contribution Guidelines

- Write tests for new features (see [docs/TODO.md](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](https://choosealicense.com/licenses/mit/)

## Project status

Gazpar2HAWS has been initiated for integration with [Home Assistant](https://www.home-assistant.io/) energy dashboard.

