Home Assistant Data Analysis

Data analysis notebooks for investigating power consumption and other smart home metrics collected by Home Assistant.

Project Structure

.
├── .gitea/
│   └── workflows/
│       └── setup_database.yml    # CI workflow to setup PostgreSQL database
├── notebooks/
│   └── boiler_warning.ipynb      # Power consumption analysis notebook
├── utils/
│   ├── __init__.py
│   └── db_connection.py          # Shared database connection utilities
├── .env.example                   # Example environment variables
├── .gitignore
├── pyproject.toml                # Project dependencies and configuration
└── README.md

Setup

1. Install UV (Python Package Manager)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via Homebrew
brew install uv

2. Create Virtual Environment and Install Dependencies

# Create and activate virtual environment with UV
uv venv
source .venv/bin/activate  # On macOS/Linux

# Install dependencies
uv pip install -e .

3. Configure Database Connection

# Copy example environment file
cp .env.example .env

# Edit .env with your PostgreSQL credentials
nano .env  # or use your preferred editor

4. Run Jupyter Notebooks

# Start Jupyter Lab
jupyter lab

# Or Jupyter Notebook
jupyter notebook

Database Setup

The repository includes a CI workflow (.gitea/workflows/setup_database.yml) that can be manually triggered to initialize the PostgreSQL database. Ensure the following secrets are configured in your Gitea repository:

• POSTGRES_HOST
• POSTGRES_PORT
• POSTGRES_ROOT_PASSWORD
• DB_NAME
• DB_USER
• DB_PASSWORD

Notebooks

Current Notebooks

• boiler_warning.ipynb: Analysis of power consumption data from Home Assistant

Adding New Notebooks

1. Create new notebook in the notebooks/ directory
2. Use descriptive names (e.g., temperature_trends.ipynb, energy_efficiency.ipynb)
3. Import shared utilities: from utils import get_db_connection, get_db_engine

Shared Utilities

The utils/ module provides common functions for database connections:

from utils import get_db_connection, get_db_engine

# Using psycopg2 (for raw SQL)
conn = get_db_connection()
cursor = conn.cursor()
cursor.execute("SELECT * FROM states LIMIT 10")

# Using SQLAlchemy (for pandas integration)
engine = get_db_engine()
import pandas as pd
df = pd.read_sql("SELECT * FROM states LIMIT 10", engine)

Development

Optional Development Tools

Install development dependencies for code formatting and linting:

uv pip install -e ".[dev]"

Format code with Black:

black utils/

Lint code with Ruff:

ruff check utils/

Contributing

When adding new analysis notebooks:

1. Document the purpose and findings in the notebook
2. Add any new dependencies to pyproject.toml
3. Update this README if adding significant new functionality