Metadata-Version: 2.1
Name: gazpar2haws
Version: 0.1.2
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
Author: Stéphane Senart
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: pygazpar (==1.2.5)
Requires-Dist: pytest-asyncio (>=0.25.0,<0.26.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: websockets (>=14.1,<15.0)
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.

## Installation

Gazpar2HAWS can be installed on any host as a standalone program.

### 1. 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

```

### 2. 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

```

### 3. 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
```

### 4. 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
```

## 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_ids: sensor.${name}_volume and sensor.${name}_energy.
    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.

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

Those two entities have to already exist in Home Assistant.

They may be created using the following templates:

```yaml

  - name: gazpar2haws_volume
    unit_of_measurement: 'm³'
    availability: true
    state: 0
    icon: mdi:fire    
    device_class: gas
    state_class: total_increasing    

  - name: gazpar2haws_energy
    unit_of_measurement: 'kWh'
    availability: true
    state: 0     
    icon: mdi:fire
    device_class: energy
    state_class: total_increasing 

```

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

## 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 major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

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




