ha_logger/README.md

Home Assistant Sensor Logger & Reporter

1. Overview

This project consists of a Python script, containerized with Docker, that performs the following actions:

1. Connects to a Home Assistant instance using a URL and a Long-Lived Access Token.
2. Fetches the current state of all temperature (°C) and humidity (%) sensors. It is designed to intelligently exclude battery level sensors that also use the % unit.
3. Stores the readings in a historical data file named sensor_data.json.
4. Generates a static index.html file containing two tables:
   • A table with the most recent sensor readings.
   • A filterable and sortable table with all historical data.
   • The tables are color-coded (temperature in light orange, humidity in light blue) for better readability.

The entire process is designed to be run inside a Docker container, making it portable and easy to schedule.

2. Prerequisites

• Docker installed and running.
• Access to a Home Assistant instance with a Long-Lived Access Token.

3. Configuration

Credentials are not stored in the project or crontab. They are loaded from a secure environment file.

Step 1: Create the Environment File

Create a file at /root/.ha_logger.env.

touch /root/.ha_logger.env

Step 2: Add Credentials

Open the file and add your Home Assistant URL and token.

# /root/.ha_logger.env

HA_URL=http://172.19.0.2:8123
HA_TOKEN=your-long-lived-access-token-goes-here

Step 3: Set Secure Permissions

It is critical to restrict access to this file so only the root user can read and write to it.

chmod 600 /root/.ha_logger.env

4. Building and Pushing the Docker Image

The application is packaged as a Docker image and hosted on a private Gitea registry.

Step 1: Build the Image

From the project's root directory (where the Dockerfile is), run the build command. The image is tagged with the address of the remote registry.

docker build -t git.leszy.net/taciaka/ha_logger .

Step 2: Log in to the Registry

docker login git.leszy.net
# Enter your Gitea username and password/token when prompted

Step 3: Push the Image

Push the newly built image to the remote registry.

docker push git.leszy.net/taciaka/ha_logger

5. Running the Container Manually

To run the container for a one-time execution, use the following command. This is useful for testing.

docker run --rm \
  --env-file /root/.ha_logger.env \
  -v /var/local/docker/dswag/config/www/zdzieci2:/output \
  --network services_vpn \
  git.leszy.net/taciaka/ha_logger

• --env-file: Securely loads the credentials from your configuration file.
• -v ...:/output: Mounts the host directory where SWAG serves files into the container's /output directory. This makes the generated index.html immediately available on your web server.
• --network: Connects the container to the specified Docker network to allow access to the Home Assistant instance.

6. Automating with Cron

To run the script automatically every 10 minutes, add the following entry to your crontab.

Step 1: Open the Crontab Editor

crontab -e

Step 2: Add the Cron Job

Paste the following line into the file, save, and exit.

*/10 * * * * docker pull git.leszy.net/taciaka/ha_logger && docker run --rm --env-file /root/.ha_logger.env -v /var/local/docker/dswag/config/www/zdzieci2:/output --network services_vpn git.leszy.net/taciaka/ha_logger

This command will:

1. Run every 10 minutes (*/10 * * * *).
2. Pull the latest version of the Docker image from the registry.
3. Run the container using the secure environment file and correct volume mount.

7. Output Files

The script generates two files in the host directory you specify (e.g., /var/local/docker/dswag/config/www/zdzieci2):

• index.html: The final HTML report. You can access this file via your web server.
• sensor_data.json: A JSON file containing all historical sensor readings. This file is used by the script to build the historical data table.