homeassistant-timothy

Home Assistant + écosystème (Zigbee2MQTT, Mosquitto, ha-bridge, Whisper, Piper) pour le ThinkCentre maison A, plus edge Zigbee (Mosquitto + Z2M) à Lescuretie maison C. Archi hub-and-spoke : un seul HA central à A, deux meshes Zigbee séparés (un par site), bridge MQTT bidirectionnel via tailnet pour que le HA voie tous les devices.

Périmètre

Maison A (Argenteuil, ThinkCentre)

Service	Type	Réseau	Notes
Home Assistant	Docker compose	host	mDNS, découverte, websocket. Central pour toute la topologie multi-sites
Mosquitto MQTT	Docker compose	web	broker partagé HA + Z2M local + reçoit le bridge de Lescuretie sur 100.64.0.7:1883
Zigbee2MQTT	Docker compose	web	dépend du coordinateur USB (Sonoff V2 CC2652P), base topic zigbee2mqtt
ha-bridge	Docker compose	web	build local (Dockerfile dans le repo), expose 127.0.0.1:8765 derrière nginx infra
Whisper	Docker compose	host port 127.0.0.1:10300	STT local (faster-whisper, FR, base-int8)
Piper	Docker compose	host port 127.0.0.1:10200	TTS local (voix fr_FR-siwis-medium)

Maison C (Lescuretie, Pi 4B)

Service	Type	Réseau	Notes
Mosquitto MQTT	Docker compose	web	broker local + bridge bidirectionnel vers Argenteuil (100.64.0.7:1883 via tailnet)
Zigbee2MQTT	Docker compose	web	dongle Sonoff CC2674P10 (nouveau chip 2024), base topic zigbee2mqtt_lescuretie, frontend :8080 en LAN/tailnet only

Pas de HA à Lescuretie — l'archi hub-and-spoke exige la connectivité tailnet pour piloter les devices distants depuis HA central (accepté comme tradeoff, cf. project_homeassistant.md en mémoire session Claude).

Hors périmètre (vivent dans le repo Infra) : OS bootstrap, nginx + certbot, WireGuard, ntfy, mariepro, chessia, runner Forgejo.

Le réseau Docker web est créé par le repo infra/, ce repo s'y attache (external: true).

Layout

homeassistant/
├── stacks/
│   ├── homeassistant/
│   │   ├── docker-compose.yml
│   │   └── config/
│   │       ├── configuration.yaml          # importé du RPi au D-day
│   │       ├── packages/
│   │       │   └── voice_assistant.yaml    # intents tempo / PC / Claude remote
│   │       ├── custom_sentences/fr/
│   │       │   └── voice_assistant.yaml    # phrases FR → intents
│   │       ├── prompts/
│   │       │   └── claude_system.md        # template prompt Anthropic Conversation
│   │       └── ...                         # automations.yaml, scripts.yaml, etc.
│   ├── mosquitto/
│   │   ├── docker-compose.yml
│   │   └── config/mosquitto.conf
│   ├── zigbee2mqtt/
│   │   ├── docker-compose.yml
│   │   └── data/                           # importé du RPi au D-day (network_key, coordinator_backup, database, state)
│   ├── ha-bridge/
│   │   ├── docker-compose.yml
│   │   ├── Dockerfile
│   │   └── server.py
│   ├── whisper/
│   │   └── docker-compose.yml
│   └── piper/
│       └── docker-compose.yml
├── .forgejo/workflows/
│   └── deploy.yml
└── docs/
    └── ARCHITECTURE.md

Workflow

Push main → Forgejo Actions (runner unique sur ThinkCentre) déclenche selon les paths :

• deploy.yml (aucun path filter, se lance à chaque push) → converge Argenteuil : docker compose -f stacks/{homeassistant,mosquitto,zigbee2mqtt,ha-bridge,whisper,piper}/docker-compose.yml up -d.
• deploy-lescuretie.yml (path filter stacks/lescuretie/**) → converge Lescuretie via SSH sur tailnet : rsync stacks/lescuretie/ vers le Pi + docker compose up -d distant.

Les repos infra/ et homeassistant/ se déploient indépendamment. Pré-requis : le réseau Docker web doit déjà exister (créé par infra/) sur les deux hosts (Argenteuil ET Lescuretie).

Migration depuis le RPi (D-day)

Voir infra/docs/migration.md — ce repo contribue les data à rsync :

• /opt/stacks/hass/hass-config/ → stacks/homeassistant/config/
• ~/dockercompose/zigbee2mqtt/data/ → stacks/zigbee2mqtt/data/ (⚠️ contient network_key, coordinator_backup.json — sans ça : re-pairing complet des devices Zigbee)
• ~/dockercompose/mosquitto/ → stacks/mosquitto/

Whisper et Piper téléchargent leurs modèles au premier démarrage : rien à rsync.

Pipeline vocale (HA Voice PE → Whisper → Claude → Piper)

Architecture : le HA Voice PE détecte le wake word on-device (XMOS), envoie l'audio à HA, qui :

1. STT via Whisper local (127.0.0.1:10300)
2. Tente le matching local (intents définis dans packages/voice_assistant.yaml, phrases dans custom_sentences/fr/voice_assistant.yaml)
3. Si pas de match : délègue à Claude (intégration Anthropic Conversation, prompt système dans prompts/claude_system.md)
4. TTS via Piper local (127.0.0.1:10200)

Étapes UI à faire après le D-day

Le code du repo couvre les composants déployables. Le câblage final passe par l'UI (config_entries en .storage/, non versionnable).

1. configuration.yaml — ajouter (en haut du fichier) :

   homeassistant:
     packages: !include_dir_named packages
   

   Sans cette ligne, packages/voice_assistant.yaml n'est pas chargé.

2. Ajouter le service Whisper : Paramètres → Appareils & services → Ajouter une intégration → Wyoming Protocol. Hôte 127.0.0.1, port 10300.

3. Ajouter le service Piper : idem, port 10200.

4. Ajouter Anthropic Conversation : Paramètres → Appareils & services → Ajouter → Anthropic. Coller la clé API, choisir le modèle (Claude Sonnet 4.6 par défaut), coller le prompt système depuis config/prompts/claude_system.md.

5. Configurer la pipeline Assist : Paramètres → Voice assistants → créer une pipeline « Maison » avec :

   • Conversation agent : Anthropic Conversation
   • Option « Prefer handling commands locally » : ON (pour que les intents locaux passent en premier)
   • STT : Whisper
   • TTS : Piper (voix fr_FR-siwis-medium)

6. Serveur HTTP / reverse proxy : Paramètres → Système → Réseau → section Serveur HTTP.

   • Trust X-Forwarded-For : ON
   • Trusted proxies : 172.16.0.0/12 (bridges Docker, pour nginx), 127.0.0.1/32, ::1/128

   Sans ça, nginx se présente avec une IP de bridge Docker, HA rejette ses en-têtes X-Forwarded-For et le reverse proxy renvoie 400 Bad Request, sans message explicite. C'était auparavant patché automatiquement par deploy.yml dans le bloc http: de configuration.yaml ; depuis HA 2026.8 cette conf YAML est dépréciée (ignorée en 2027.2.0) et vit dans .storage/, qui n'est pas versionnable — d'où cette étape manuelle. Si les champs n'apparaissent pas dans l'UI, recharger la page en Ctrl+F5.

7. Associer le HA Voice PE à la pipeline : Paramètres → Appareils & services → HA Voice PE → choisir la pipeline « Maison ».

Secrets / Variables

Forgejo Actions, repo-level (cf. .forgejo/workflows/deploy.yml).

Variables (non-secrets, visibles non-redactées dans les logs CI) :

Variable	Usage
MONPC_MAC	ha-bridge — adresse MAC du PC pour le WoL (08:bf:b8:82:e0:dc)
MONPC_HOST	ha-bridge — IP LAN du PC pour net rpc shutdown (192.168.112.41)

Secrets :

Secret	Usage
MONPC_USER	ha-bridge — compte Microsoft du PC pour net rpc shutdown
MONPC_PASS	ha-bridge — mdp du compte Microsoft
HABRIDGE_CLAUDE_CREDENTIALS_JSON	ha-bridge — OAuth Claude Code (abonnement Max)

À ajouter quand on en aura besoin :

• MQTT_PASSWORD — Mosquitto auth (TODO, actuellement anonyme)

La clé API Anthropic n'est pas un secret Forgejo : elle vit dans .storage/core.config_entries côté HA, saisie via l'UI à l'étape 4 ci-dessus.