From d258720411088442ffa16919e5928ab5b50f3d90 Mon Sep 17 00:00:00 2001 From: Adam Date: Sun, 25 Jan 2026 10:49:48 +0100 Subject: [PATCH] feat: Add color-coding, output dir, and detailed README --- README.md | 127 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 103 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 8b48449..85d0d8a 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,122 @@ -# Home Assistant Logger +# Home Assistant Sensor Logger & Reporter -This script connects to a Home Assistant instance, fetches temperature and humidity data, stores it, and generates an HTML report. +## 1. Overview -## Prerequisites +This project consists of a Python script, containerized with Docker, that performs the following actions: -- Docker +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. -## How to Use +The entire process is designed to be run inside a Docker container, making it portable and easy to schedule. -### 1. Build the Docker Image +## 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`. ```bash -docker build -t ha-logger . +touch /root/.ha_logger.env ``` -### 2. Run the Docker Container +**Step 2: Add Credentials** -You need to provide your Home Assistant URL and a Long-Lived Access Token as environment variables. +Open the file and add your Home Assistant URL and token. + +```ini +# /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. ```bash -docker run --rm -v $(pwd):/app - -e HA_URL="http://your-home-assistant-ip:8123" - -e HA_TOKEN="your-long-lived-access-token" - ha-logger +chmod 600 /root/.ha_logger.env ``` -- Replace `"http://your-home-assistant-ip:8123"` with the URL of your Home Assistant instance. -- Replace `"your-long-lived-access-token"` with your token. +## 4. Building and Pushing the Docker Image -The `-v $(pwd):/app` command mounts the current directory into the container, so the output files (`index.html` and `sensor_data.json`) are created and updated in your project folder. +The application is packaged as a Docker image and hosted on a private Gitea registry. -### How it Works +**Step 1: Build the Image** -- The script connects to your Home Assistant instance using the provided URL and token. -- It fetches all devices and filters for sensors that have a unit of `°C` (Celsius) or `%` (for humidity). -- The new readings are appended to the `sensor_data.json` file. -- An `index.html` file is generated, displaying the latest readings and a searchable, sortable history of all readings. +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. -### Generated Files +```bash +docker build -t git.leszy.net/taciaka/ha_logger . +``` -- **`sensor_data.json`**: Stores the historical data for all sensor readings. -- **`index.html`**: The generated HTML report. Open this file in your browser to see the sensor data. +**Step 2: Log in to the Registry** + +```bash +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. + +```bash +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. + +```bash +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** + +```bash +crontab -e +``` + +**Step 2: Add the Cron Job** + +Paste the following line into the file, save, and exit. + +```crontab +*/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. \ No newline at end of file