# UpaSmartHome - Complete System Specification & Architecture Reference

> Open, privacy-first, 100% local-capable smart home automation platform built for Raspberry Pi with Zigbee sensors, multi-channel relays, automated per-room heating/boiler controls, and native Matter, Apple HomeKit, Google Home, and Amazon Alexa voice integrations.

## 1. System Architecture Overview

UpaSmartHome is engineered with a strict local-first philosophy:
1. **Controller Node**: A Raspberry Pi (Model 4B, 5, or Zero 2 W) running Debian/Raspberry Pi OS (Bookworm 64-bit), a local Mosquitto MQTT broker, Zigbee2MQTT for wireless Zigbee device management, and the compiled `smarthomeapi` Go daemon.
2. **Local Control & Sub-Millisecond Execution**: All heating control loops (evaluating sensor thresholds every 30 seconds), relay schedules (minute-precision cron intervals), and contact sensor safety triggers evaluate locally inside the Go daemon. Even if WAN internet is disrupted, local automations, LAN web dashboards, and Apple HomeKit controls continue uninterrupted.
3. **Optional Cloud Relay & Push Notifications**: An outbound WebSocket tunnel connects the local controller to the cloud backend (https://upanet.org), providing end-to-end encrypted remote mobile access without port forwarding or dynamic DNS, instant FCM push alerts for alarms and low batteries, and Alexa Smart Home voice integration.
4. **Protocols & Standards**:
   - Zigbee 3.0 via Zigbee2MQTT
   - Matter protocol bridge for local Google Home and Alexa pairing
   - HomeKit Accessory Protocol (HAP) for local Apple HomeKit pairing
   - MQTT for internal sensor and relay pub/sub
   - WebSockets for bi-directional real-time telemetry streaming
   - REST API with OpenAPI 3.0 specification

## 2. Supported Hardware & Accessories

### Single Board Computers (SBC)
- **Raspberry Pi 4 Model B** (Recommended: 2GB/4GB/8GB RAM) - Full hardware bundle.
- **Raspberry Pi 5** (4GB/8GB RAM) - High performance, compatible with GPIO HATs.
- **Raspberry Pi Zero 2 W** - Minimal DIY controller footprint (requires USB OTG adapter for Zigbee stick).
- Any standard Linux ARM64 / x86_64 host running Docker.

### Relay Modules & Actuators
- **Waveshare 8-Channel Industrial Relay HAT**:
  - Direct 40-pin GPIO header connection.
  - Optocoupled isolation (EL817 optocouplers protect the Pi from high-voltage spikes).
  - Relay contact rating: 250V AC / 5A or 30V DC / 5A per channel.
  - Pin mapping:
    - Relay 1: GPIO 5 (Physical Pin 29)
    - Relay 2: GPIO 6 (Physical Pin 31)
    - Relay 3: GPIO 13 (Physical Pin 33)
    - Relay 4: GPIO 16 (Physical Pin 36)
    - Relay 5: GPIO 19 (Physical Pin 35)
    - Relay 6: GPIO 20 (Physical Pin 38)
    - Relay 7: GPIO 21 (Physical Pin 40)
    - Relay 8: GPIO 26 (Physical Pin 37)
  - Isolated Power (JD-VCC): To isolate high-current inductive loads (pumps, solenoid valves), remove the JD-VCC to VCC jumper and supply 5V DC to JD-VCC from an independent power supply while maintaining shared GND.
- **Dry Contact Low-Voltage Relays**: Ideal for garage door openers, automated gates, boiler enable loops, and motorized valves.
- **Tasmota Wi-Fi Relays**: Sonoff 4CH, Shelly 1/2.5/Pro, ESP8266/ESP32 relay modules integrated via MQTT or HTTP.

### Zigbee Sensors (Zigbee2MQTT Compatible)
- **Temperature & Humidity**: SONOFF SNZB-02D (LCD screen, CR2450 battery), SNZB-02, Aqara WSDCGQ11LM, Tuya TS0201.
- **Door & Window Contacts**: SONOFF SNZB-04, Aqara MCCGQ11LM, Tuya TS0203.
- **Motion & Occupancy (PIR)**: SONOFF SNZB-03, Aqara RTCGQ11LM, Tuya PIR.
- **Water Leak Detectors**: SONOFF SNZB-05, Aqara SJCGQ11LM.
- **Vibration & Tamper Sensors**: Aqara DJT11LM.

## 3. Products & Pricing

### Complete Hardware Starter Kit (399 EUR)
- 1x Raspberry Pi 4 Model B (Gigabit Ethernet)
- 1x Waveshare 8-Channel Industrial Relay HAT
- 5x SONOFF SNZB-02D Zigbee LCD Temperature & Humidity Sensors
- 1x Pre-configured Zigbee USB coordinator gateway
- 1 Year Free Cloud Subscription (remote access + push notifications; renewal 60 EUR/year)
- Product URL: https://upanet.org/products#starter-kit

### DIY Hub Pro Cloud License (50 EUR 1st year, then 60 EUR/year)
- 1 Year Cloud Pro license (remote mobile app access from outside LAN + instant FCM notifications)
- Pre-configured Docker Compose stack with smarthomeapi, Zigbee2MQTT, and Mosquitto
- Minimum hardware: Raspberry Pi Zero 2 W or better + Zigbee USB stick (e.g. Sonoff CC2652P, ConBee II)
- Backer recognition on the community backer wall
- Product URL: https://upanet.org/products#digital-pro

## 4. Voice Assistant & Smart Home Integrations

- **Apple HomeKit**:
  - Native pairing via HomeKit Accessory Protocol (HAP).
  - Discovered automatically by iPhone, iPad, Apple Watch, and Apple TV on the local LAN.
  - Relays appear as switches or lights; temperature and humidity sensors display live in the Apple Home app; thermostats allow setpoint adjustments via Siri.
  - Zero cloud accounts or Apple developer accounts required.
- **Google Home & Google Assistant**:
  - Connects locally using the Matter protocol.
  - The UpaSmartHome Matter bridge publishes on/off relay devices and thermostat entities to Google Home.
  - Commands ("Hey Google, set Living Room temperature to 21 degrees") execute locally without third-party cloud linking when an on-network Google Nest Hub or Chromecast Matter controller is present.
- **Amazon Alexa**:
  - Dual options:
    1. Local Matter pairing: Add the Matter bridge in the Alexa app (requires Matter-capable Echo device).
    2. Alexa Smart Home Skill: Cloud-based account linking via `/alexa/directives` supporting voice control and status queries from anywhere in the world using the Alexa smartphone app without extra hardware.

## 5. Technical Documentation & Guides Summary

1. **Raspberry Pi 8-Channel Relay Board Complete Wiring & GPIO Pinout Guide**
   - URL: https://upanet.org/guides/raspberry-pi-8-channel-relay-wiring
   - Teaches safe wiring of 230V mains vs low-voltage dry contacts, optocoupler isolation using EL817 chips, removing the JD-VCC jumper for inductive loads (pumps, compressors), flyback diode protection, and GPIO pin mapping.
2. **How to Build a 100% Local Smart Home with Zero Cloud Dependency**
   - URL: https://upanet.org/guides/local-smart-home-no-cloud
   - Focuses on the four pillars of local-first IoT: offline execution loops, open wireless protocols (Zigbee/Matter), local data persistence (JSON/SQLite), and direct LAN access.
3. **Zigbee Thermostat & Heating Automation**
   - URL: https://upanet.org/guides/zigbee-thermostat-heating-automation
   - Explains how multi-zone heating works with Sonoff SNZB-02D sensors in each room controlling individual relay channels connected to manifold actuators or central boiler pumps.
4. **Raspberry Pi Bluetooth Wi-Fi Setup**
   - URL: https://upanet.org/guides/raspberry-pi-bluetooth-wifi-setup
   - How UpaSmartHome implements BLE headless provisioning via Linux NetworkManager D-Bus API, allowing users to configure Wi-Fi credentials from the mobile app without keyboards or monitors.
5. **Garage Door Control with Zigbee Dry Contact Relay**
   - URL: https://upanet.org/guides/garage-door-zigbee-relay
   - How to wire a low-voltage relay channel across garage door wall-button terminals, pairing with a door contact sensor for open/close state verification and push alerts.
6. **Smart Home Security & Alarm Sensors**
   - URL: https://upanet.org/guides/smart-home-security-sensors
   - Comprehensive guide on door/window contacts, PIR motion detectors, water leak sensors, and vibration sensors for instant emergency push alerts.
7. **SONOFF SNZB-02D Setup Guide**
   - URL: https://upanet.org/guides/sonoff-snzb-02d-setup-guide
   - Pairing procedure, LCD display interpretation, offset calibration, mounting tips for accurate readings, and CR2450 battery optimization.
8. **Zigbee vs Wi-Fi Smart Home Devices**
   - URL: https://upanet.org/guides/zigbee-vs-wifi-smart-home
   - Deep dive comparing 2.4 GHz Wi-Fi congestion, power consumption (CR2032 lasting 2 years on Zigbee vs weeks on Wi-Fi), self-healing mesh topology, and zero-cloud reliability.
9. **Self-Hosted Smart Home Setup**
   - URL: https://upanet.org/guides/upahome-self-hosted-setup
   - Complete guide to compiling and deploying `smarthomeapi` on Linux, configuring MariaDB, provisioning tokens, and running standalone.
10. **What's New in UpaSmartHome**
    - URL: https://upanet.org/guides/upahome-whats-new
    - Changelog and new release highlights covering Matter bridge support, iOS app release, security sensor additions, and multi-language support.

## 6. Developer APIs & Protocols

### Quickstart Installation Command
```bash
curl -sSL https://upanet.org/install.sh | bash
```

### REST API Endpoints Overview
- Base URL: `https://upanet.org/api` (or local `http://<pi-ip>:8080/api`)
- Authentication: HTTP Basic Auth using Agent Serial and One-Time Password (OTP) or Session Bearer Token.
- Key Endpoints:
  - `GET /api/sensors`: List all telemetry sensors (temperature, humidity, battery, contact, motion, water leak, vibration).
  - `POST /api/sensors/{id}/target`: Set target thermostat temperature.
  - `GET /api/relays`: List relay channels and states (on/off, label, mode).
  - `POST /api/relays/{id}/toggle`: Toggle relay channel state.
  - `GET /api/schedules`: List configured automated schedules.
  - `POST /api/schedules`: Create or update heating/relay timer schedules.
  - `POST /api/pairing/permit-join`: Open Zigbee coordinator for device discovery (60s window).
  - `GET /api/notifications`: Retrieve event history and alarm triggers.
  - `GET /ws`: WebSocket stream for live real-time state synchronization (`refresh_sensors`, `refresh_relays`, `refresh_schedules`, `refresh_notifications`).

### Resources & Specifications
- Interactive Swagger UI: https://upanet.org/docs/
- OpenAPI 3.0 Specification: https://upanet.org/openapi.json
- Open Source Repository: https://github.com/paveurba/appapi