rolland-labs/haos-project
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit (reset history)

Browse Source
This commit is contained in:
Alexis Rolland
2026-06-20 11:34:50 +02:00
commit da12f0c98f
14 changed files with 1488 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+69
View File
@@ -0,0 +1,69 @@
# Architecture – HAOS Project
## Vue d'ensemble
L'infrastructure repose sur Home Assistant OS installé en natif sur un mini-PC dédié, fonctionnant 24h/24.
## Stack technique
| Couche | Technologie |
| --------------- | ------------------------------------ |
| OS domotique | Home Assistant OS (HAOS) |
| Broker MQTT | Mosquitto (add-on officiel) |
| Réseau Zigbee | Zigbee2MQTT + Sonoff Dongle Plus V2 |
| NVR | Frigate |
| Alarme | Alarmo |
| Tunnel sortant | Cloudflared (add-on officiel) |
| Capteurs custom | ESPHome (add-on officiel) |
| Notifications | Telegram Bot API |
| Énergie | Intégration Enedis officielle |
| Chauffage | Heatzy (intégration HACS) |
> **Le VPN WireGuard ne fait pas partie de la stack HAOS.** Il est hébergé sur un LXC dédié, sur un second mini-PC sous Proxmox VE (cf. `pve-project`). HAOS ne fait tourner aucun serveur VPN : le client WireGuard obtient un accès au LAN, qui inclut HAOS, au même titre que tout autre hôte du réseau local.
## Flux de données
```text
Équipements Zigbee
│
▼ (radio Zigbee 2.4GHz)
Sonoff USB Dongle
│
▼ (USB)
Zigbee2MQTT ──► Mosquitto MQTT ──► Home Assistant
│
├── Alarmo
├── Frigate (RTSP)
├── ESPHome (Wi-Fi)
├── Heatzy (Cloud API)
└── Enedis (Cloud API)
```
## Accès réseau
```text
Internet
│
┌───────────────┴───────────────┐
│ │
▼ HTTPS sortant uniquement ▼ UDP 51820 (seul port WAN ouvert, pas sur HAOS)
Cloudflare WireGuard (LXC sur Proxmox, mini-PC distinct)
│ │
▼ tunnel chiffré ▼ tunnel VPN → accès LAN complet
Cloudflared add-on (HAOS) LAN 192.168.1.0/24 (HAOS, Proxmox, IoT)
│
▼
Home Assistant
```
> L'accès web public à Home Assistant passe uniquement par le tunnel sortant Cloudflared. L'administration (SSH, Samba, UI Zigbee2MQTT/Frigate) passe uniquement par le VPN WireGuard, qui n'est pas un add-on HAOS mais un service distinct hébergé sur le Proxmox.
## Principes de sécurité
- **Zéro port ouvert** sur la box/routeur côté HAOS (le seul port WAN ouvert, UDP 51820, est sur le Proxmox)
- **Tunnel sortant** uniquement (Cloudflared) pour l'accès web à Home Assistant
- **VPN WireGuard** obligatoire pour toute administration (SSH, Samba) — hébergé sur le Proxmox, pas sur HAOS
- **Données locales** : vidéo, Zigbee, capteurs ESPHome restent sur le réseau local
- **Moindre privilège** : chaque service n'accède qu'à ce dont il a besoin
docs/automations-overview.md
+86
View File
@@ -0,0 +1,86 @@
# Automatisations – Vue d'ensemble
## Statistiques
| Domaine | Nombre d'automatisations |
| ------------------- | ------------------------- |
| Alarme & Sécurité | 14 |
| Éclairage | 9 |
| Chauffage | 4 |
| Ventilation & IR | 5 |
| Capteurs | 3 |
| **Total** | **~35 actives** |
> Des scripts et scènes additionnels complètent les automatisations pour atteindre plus de 50 logiques conditionnelles.
---
## Alarme & Sécurité
> Les commandes exactes de pilotage à distance (Telegram) ne sont volontairement pas détaillées ici, pour limiter le risque qu'un tiers les reproduise. Seule la fonction est décrite.
| Fonction | Déclencheur | Action |
| ---------------------------------- | ------------------------------- | -------------------------------------------------- |
| Notification déclenchement | Alarme triggered | Message + bouton désactivation (bot Telegram) |
| Notification absence prolongée | Alarme triggered (vacation) | Notification contacts d'urgence (mobile) |
| Snapshots caméra principale | Alarme triggered | 3 photos + vidéo 10s → Telegram |
| Snapshots caméra secondaire | Alarme triggered | 3 photos + vidéo 10s → Telegram |
| Consultation caméras à distance | Commande Telegram (privée) | Envoi en boucle des caméras → Telegram |
| Notification armement | armed\_away | Confirmation armement → Telegram |
| Notification désarmement | disarmed | Confirmation désarmement → Telegram |
| Désarmement à distance | Commande Telegram (privée) | Désarmement Alarmo |
| Armement à distance | Commande Telegram (privée) | Armement mode vacation |
| Contrôle sirène Zigbee | input\_boolean sirène | MQTT → sirène mode burglar/stop (template) |
| Clavier physique (blueprint) | Clavier Zigbee à code | Arm/Disarm/Night avec code PIN |
| Détection Frigate selon alarme | État alarme (any) | Active/désactive détection caméras |
| Extinction lumières à l'armement | disarmed → arming | Extinction de toutes les lumières |
| Éclairage plantes en absence | armed\_away + 5 min | Lumières plantes à 100% |
---
## Éclairage
| Fonction | Déclencheur | Action |
| --------------------------------- | --------------------------------- | -------------------------------------- |
| Lumière auto sur mouvement | Capteur PIR | Allumage + extinction après délai |
| Toggle lampe via bouton Zigbee | Action bouton Zigbee (single) | Toggle lampe |
| Allumage automatique au retour | Alarme disarmed (retour) | Allumage lampe entrée |
| Toggle lumières via bouton | Action bouton Zigbee (single) | Toggle groupe de lumières |
| Allumage automatique programmé | Heure fixe | Allumage lumière programmée |
| Extinction automatique programmée | Heure fixe | Extinction lumière programmée |
| Éclairage plantes en absence | armed\_away + 5 min | Lumières plantes 100% |
| Scène lumière ambiante | input\_boolean switch | Scène IR on/off |
| Toggle barre LED | input\_boolean switch | Toggle LED via IR |
---
## Chauffage
> Les plages horaires précises ne sont volontairement pas publiées (elles révèlent des habitudes de présence au domicile). Seule la logique est décrite.
| Fonction | Déclencheur | Action |
| -------------------------- | ----------------------- | --------------------- |
| Activation chauffe (x2/jour) | Heure fixe (non publiée) | Radiateurs → heat |
| Fin de chauffe (x2/jour) | Heure fixe (non publiée) | Radiateurs → auto |
---
## Ventilation & IR Blaster
| Fonction | Déclencheur | Action |
| ---------------------- | -------------------------- | -------------------- |
| Toggle ventilateur | input\_boolean switch | Script toggle IR |
| Toggle on/off | Manuel (script) | Code IR on/off |
| Puissance | Manuel (script) | Code IR power |
| Rotation | Manuel (script) | Code IR rotation |
| Mode | Manuel (script) | Code IR mode |
---
## Capteurs & Divers
| Fonction | Déclencheur | Action |
| ---------------------- | --------------------------- | --------------------------------- |
| Alerte fuite d'eau | Capteur humidité (20s) | Notification Telegram |
| Privacy caméra | input\_boolean switch | Toggle mode privacy caméra |
| Diffuseur arômes | input\_boolean switch | Séquence IR on/off diffuseur |
docs/network-diagram.md
+171
View File
@@ -0,0 +1,171 @@
# Diagramme réseau – HAOS Project
## Vue d'ensemble
```text
INTERNET
│
┌──────────────┴──────────────┐
│ │
┌─────────▼─────────┐ ┌───────────▼───────────┐
│ Cloudflare CDN │ │ Admin (mobile / PC) │
│ (DNS + Tunnel) │ │ Client WireGuard │
└─────────┬─────────┘ └───────────┬───────────┘
│ Tunnel chiffré (sortant) │ UDP :51820
┌─────────▼─────────────────────────────▼───────────┐
│ Box / Routeur │
│ 192.168.1.1 │
│ 1 seul port ouvert : UDP 51820 (WireGuard) │
└──────────────────────┬─────────────────────────────┘
│ LAN 192.168.1.0/24
┌─────────────────┼──────────────────┐
│ │ │
┌─────────▼────────┐ ┌─────▼──────────┐ ┌───▼──────────────────┐
│ Mini-PC Proxmox │ │ Mini-PC HAOS │ │ Équipements IoT │
│ 192.168.1.Y │ │ 192.168.1.X │ │ (Wi-Fi / Zigbee) │
│ │ │ │ │ │
│ ┌──────────────┐ │ │ ┌────────────┐ │ │ • Caméras IP (RTSP) │
│ │ WireGuard │ │ │ │Home Asst. │ │ │ • ESP32 ESPHome │
│ │ LXC :51820 │ │ │ │:8123 │ │ │ • Radiateurs Heatzy │
│ └──────┬───────┘ │ │ ├────────────┤ │ └──────────────────────┘
│ │ VPN │ │ │Mosquitto │ │
│ │tunnel │ │ │MQTT :1883 │ │ ┌──────────────────────┐
│ ▼ LAN │ │ ├────────────┤ │ │ Réseau Zigbee │
│ ┌──────────────┐ │ │ │Zigbee2MQTT │◄├──│ Canal 11 / 2.4GHz │
│ │ Apache │ │ │ │UI :8099 │ │ │ │
│ │ Guacamole │ │ │ ├────────────┤ │ │ • Sirène │
│ │ (CF Tunnel) │ │ │ │Frigate NVR │ │ │ • Capteur fuite │
│ └──────────────┘ │ │ │:5000/:1984 │ │ │ • Boutons Zigbee │
│ │ │ ├────────────┤ │ │ • IR Blasters │
│ (cf. pve-project)│ │ │Cloudflared │ │ │ • Clavier à code │
└──────────────────┘ │ │(tunnel out)│ │ │ • Ampoules │
│ └────────────┘ │ └──────────────────────┘
└────────────────┘
```
---
## Rôles des machines
| Machine | IP | Rôle |
| -------------- | ------------- | -------------------------------------------------- |
| Box / Routeur | 192.168.1.1 | Passerelle, NAT, 1 port ouvert (UDP 51820) |
| Mini-PC Proxmox| 192.168.1.Y | WireGuard VPN (LXC), Guacamole, OPNsense, lab |
| Mini-PC HAOS | 192.168.1.X | Home Assistant OS + tous les services domotiques |
> Le serveur WireGuard est hébergé sur le **Proxmox** (LXC dédié), pas sur HAOS.
> L'accès VPN donne un accès au LAN complet, donc aussi à HAOS et ses interfaces d'admin.
---
## Adressage réseau
| Service | Hôte | Port | Protocole | Accessible depuis |
| ------------------- | -------------- | ---------- | ---------- | ----------------------- |
| Home Assistant | 192.168.1.X | 8123 | HTTP/WS | LAN + CF Tunnel |
| Mosquitto MQTT | 192.168.1.X | 1883 | MQTT (TCP) | LAN uniquement |
| Zigbee2MQTT UI | 192.168.1.X | 8099 | HTTP | LAN + VPN |
| Frigate (UI) | 192.168.1.X | 5000 | HTTP | LAN + VPN |
| Frigate (RTSP out) | 192.168.1.X | 1984 | RTSP | LAN uniquement |
| WireGuard VPN | 192.168.1.Y | 51820 | UDP | WAN (port ouvert) |
| Guacamole | 192.168.1.Y | — | HTTPS | CF Tunnel (Proxmox) |
| Caméras IP | 192.168.1.X+n | 554 | RTSP | LAN uniquement |
| ESP32 ESPHome | 192.168.1.X+n | — | mDNS/HTTP | LAN uniquement |
---
## Flux réseau détaillés
### Accès HAOS distant (HTTPS)
```text
Utilisateur
│
▼ HTTPS :443
Cloudflare Edge
│
▼ Tunnel QUIC chiffré (connexion sortante depuis HAOS)
Cloudflared add-on (Mini-PC HAOS)
│
▼ HTTP local
Home Assistant :8123
```
### Administration SSH / Zigbee2MQTT / Frigate
```text
Admin
│
▼ UDP :51820
WireGuard LXC (Proxmox, 192.168.1.Y)
│
▼ Tunnel VPN → LAN 192.168.1.0/24
Mini-PC HAOS :8099 (Z2M) / :5000 (Frigate) / SSH
```
### Flux Zigbee → Home Assistant
```text
Équipement Zigbee
│ Radio 2.4GHz
▼
Sonoff USB Dongle (coordinateur, USB sur HAOS)
│ Série USB
▼
Zigbee2MQTT (add-on HAOS)
│ MQTT publish
▼
Mosquitto :1883 (add-on HAOS)
│ MQTT subscribe
▼
Home Assistant
```
### Flux caméras → Frigate → Home Assistant
```text
Caméra IP
│ RTSP :554 (LAN)
▼
Frigate NVR (add-on HAOS — décodage + détection CPU)
├─▼ Événements MQTT → Mosquitto → Home Assistant
├─▼ Snapshots → /config/www/
└─▼ Enregistrements → /media/frigate/
```
### Flux ESPHome → Home Assistant
```text
ESP32 (capteur sol)
│ Wi-Fi LAN
▼
ESPHome add-on (HAOS)
│ API native chiffrée (mDNS)
▼
Home Assistant
```
---
## WireGuard – Plage VPN (LXC Proxmox)
| Interface | Adresse | Usage |
| ------------ | ------------- | -------------- |
| wg0 (serveur)| 10.0.0.1/24 | LXC Proxmox |
| Client 1 | 10.0.0.2/32 | Mobile admin |
| Client 2 | 10.0.0.3/32 | PC admin |
Les clients VPN ont accès au LAN `192.168.1.0/24` via la route configurée dans WireGuard, ce qui inclut HAOS (`192.168.1.X`) et Proxmox (`192.168.1.Y`).
---
## Segmentation et isolation
L'isolation des équipements IoT repose sur :
- **Aucun accès WAN** configuré pour les caméras, ESP32 et équipements Zigbee
- **Flux RTSP** consommés uniquement par Frigate en local
- **MQTT non exposé** sur le WAN (port 1883 LAN only)
- **ESPHome** sans cloud (API locale uniquement)
> Pour aller plus loin : VLAN IoT dédié sur switch manageable + règles firewall OPNsense (disponible sur le Proxmox — cf. `pve-project`).
docs/security-policy.md
+99
View File
@@ -0,0 +1,99 @@
# Politique de sécurité – HAOS Project
## Principes fondamentaux
### 1. Exposition réseau minimale
Aucun port entrant n'est ouvert sur le routeur/box.
| Service | Exposition | Détail |
| ----------------- | ---------------- | ------------------------------------------ |
| Home Assistant | Tunnel sortant | Cloudflared → Cloudflare → domaine perso |
| SSH | VPN uniquement | Inaccessible hors WireGuard |
| Samba | LAN uniquement | Partage réseau local uniquement |
| MQTT | LAN uniquement | Mosquitto non exposé sur le WAN |
| Zigbee2MQTT | LAN uniquement | Interface web sur port 8099 (LAN) |
### 2. Accès distant via tunnel sortant (Cloudflared)
Le flux réseau est **sortant uniquement** depuis le serveur vers Cloudflare.
```text
Utilisateur distant
│
▼ HTTPS
Cloudflare Edge
│
▼ Tunnel chiffré (WireGuard/QUIC)
Cloudflared add-on (HAOS)
│
▼ HTTP local
Home Assistant
```
Avantages :
- Aucun port ouvert sur la box
- IP publique non exposée
- HTTPS natif via certificat Cloudflare
- Protection DDoS Cloudflare incluse
### 3. Administration via VPN (WireGuard)
Toute administration système (SSH, Samba, Zigbee2MQTT UI) est restreinte au tunnel WireGuard, lui-même hébergé sur un LXC dédié sur le Proxmox (second mini-PC), et non sur HAOS.
### 4. Données locales
Les données sensibles ne transitent pas vers des clouds tiers :
| Donnée | Traitement | Justification |
| ----------------- | ----------------- | -------------------------------------- |
| Flux vidéo | Local | Frigate NVR sur le serveur |
| Réseau Zigbee | Local | Zigbee2MQTT + Mosquitto locaux |
| Capteurs ESP32 | Local | ESPHome sur réseau local |
| Enedis | API officielle | Données de consommation uniquement |
| Heatzy | API officielle | Commandes chauffage uniquement |
### 5. Principe du moindre privilège
- Services limités au strict nécessaire
- Chaque add-on n'a accès qu'à ses ressources propres
- Mot de passe MQTT dédié (non partagé)
- Code PIN alarme non stocké en clair dans les automatisations (secrets.yaml)
### 6. Sauvegardes & Maintenance
- Sauvegardes automatiques régulières de la configuration HAOS
- Mises à jour appliquées régulièrement (HAOS, add-ons, intégrations)
- Surveillance des logs (HAOS, Zigbee2MQTT, Frigate)
## Gestion des secrets
Tous les éléments sensibles sont stockés dans `secrets.yaml` (non commité) :
```yaml
# secrets.yaml – NE PAS COMMITER
telegram_chat_user1: "XXXXXXXXX"
telegram_chat_user2: "XXXXXXXXX"
mqtt_password: "XXXXXXXXX"
alarmo_pin: "XXXX"
wifi_ssid: "XXXXXXXXX"
wifi_password: "XXXXXXXXX"
esphome_api_key: "XXXXXXXXX"
esphome_ota_password: "XXXXXXXXX"
esphome_ap_password: "XXXXXXXXX"
```
## Ce que ce dépôt ne contient pas
- ❌ Clés privées ou tokens
- ❌ Mots de passe (MQTT, Telegram, Wi-Fi)
- ❌ Adresses IP réelles du réseau local
- ❌ Clé réseau Zigbee (network_key)
- ❌ PAN ID / Extended PAN ID Zigbee
- ❌ Adresses MAC des équipements Zigbee
- ❌ Code PIN de l'alarme
- ❌ Chat ID Telegram
- ❌ Prénoms ou noms réels des occupants