feat: Add color-coding, output dir, and detailed README

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.