122 lines
4.0 KiB
Markdown
122 lines
4.0 KiB
Markdown
# 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`.
|
|
|
|
```bash
|
|
touch /root/.ha_logger.env
|
|
```
|
|
|
|
**Step 2: Add Credentials**
|
|
|
|
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
|
|
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.
|
|
|
|
```bash
|
|
docker build -t git.leszy.net/taciaka/ha_logger .
|
|
```
|
|
|
|
**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. |