Smart Home Assistant – Modular IoT Hub (Python/FastAPI)

Overview

This project is a modular smart home automation hub built with Python and FastAPI. It integrates diverse IoT devices (thermostats, lights, cameras, motion sensors), supports automation (triggers → conditions → actions), and provides secure remote access. It includes stubs for MQTT, WebSockets, voice assistants (Alexa/Google), analytics, and a device adapter abstraction layer for easy extension.

Key Features

• Central hub with FastAPI for REST and WebSocket APIs
• Device abstraction layer and sample adapters (thermostat, light, camera, motion sensor)
• Automation engine skeleton with triggers, conditions, and actions
• Security skeleton: JWT auth, API keys, permission hooks
• Realtime messaging via MQTT and WebSockets (stubs)
• Analytics/metrics pipeline skeleton
• Voice assistant integration stubs (Alexa/Google)
• Docker Compose with optional services (MQTT, Postgres, Redis) – included later

Raspberry Pi Support

• Optional GPIO light adapter using gpiozero (auto-registers on Raspberry Pi)
• Works with PWM for smooth brightness when available, falls back to on/off
• Example device id: light.gpio18 (GPIO pin 18 by default)

Monorepo Structure

.
├── app/
│   ├── api/
│   ├── analytics/
│   ├── automation/
│   ├── devices/
│   │   └── adapters/
│   ├── integrations/
│   │   └── voice/
│   ├── security/
│   ├── storage/
│   ├── config.py
│   └── main.py
├── tests/
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

Getting Started

1. Prerequisites

• Python 3.11+
• On Windows PowerShell: py -3.11 -m venv .venv to create venv
• Optional: Docker Desktop for containerized services

2. Setup

python -m venv .venv
. .venv/Scripts/Activate.ps1
pip install -r requirements.txt

3. Run the API

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

4. Quick Check

• Health: GET http://localhost:8000/health → { "status": "ok" }
• Docs: http://localhost:8000/docs

Raspberry Pi Setup

1. Prepare the Pi

• Install Raspberry Pi OS (Lite recommended for headless)
• Enable SSH and set up Wi‑Fi or Ethernet

2. Install system deps

sudo apt update
sudo apt install -y python3-pip python3-venv

3. Install gpiozero (for GPIO adapters)

sudo apt install -y python3-gpiozero

4. Deploy the app

git clone <this-repo-url> smarthome
cd smarthome
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000

5. Wire a light/LED to a GPIO pin

• Default adapter uses GPIO 18 (with resistor and appropriate power)
• Verify device is registered:
  • GET http://<pi-ip>:8000/devices → includes light.gpio18
  • Turn on: POST /devices/light.gpio18/execute with { "command": "turn_on" }
  • Set brightness (PWM pins only): { "command": "set_brightness", "params": { "value": 60 } }

Security & Config

• Copy .env.example to .env and set values
• JWT secret and allowed origins are read from environment via app.config.Settings

Architecture

• API Layer (app.api): REST/WebSocket endpoints
• Devices (app.devices): Device abstraction and adapters per device type
  • Demo light: app/devices/adapters/demo_light.py
  • Raspberry Pi GPIO light: app/devices/adapters/rpi_gpio_light.py
• Automation (app.automation): Routines, triggers, conditions, actions
• Security (app.security): AuthN/Z, JWT issuance/verification, permission hooks
• Integrations (app.integrations): MQTT client, voice assistants, 3rd-party APIs
• Analytics (app.analytics): Metrics capture and reporting
• Storage (app.storage): Database/Redis clients (skeleton)

Device Abstraction

Each device adapter implements a simple interface defined in app.devices.base:

class DeviceAdapter:
    def get_id(self) -> str: ...
    async def get_state(self) -> dict: ...
    async def execute(self, command: str, params: dict | None = None) -> dict: ...

Adapters register themselves with a DeviceRegistry so they can be discovered and controlled uniformly by the API and automation engine.

Automation Model

Trigger -> Condition(s) -> Action(s)

Examples:

• Motion detected after sunset → turn on hallway lights for 10 minutes
• Temperature above 26°C and occupancy true → set thermostat to eco mode

Roadmap

• Implement persistent storage with Postgres + SQLAlchemy + Alembic
• Finish MQTT integration and bi-directional device updates
• Add Redis Pub/Sub for internal event bus
• Build web dashboard and/or mobile app as a separate frontend
• Add comprehensive test suite and CI

Security Notes

• Use HTTPS in production with a reverse proxy (e.g., Traefik or Nginx)
• Rotate JWT secrets and API keys, store secrets in a vault (not in .env)
• Principle of least privilege for device control permissions

Contributing

Issues and PRs are welcome. Please follow Python type hints and the code style outlined in the repo.