homeassistant-timothy

Home Assistant + écosystème (Zigbee2MQTT, Mosquitto, ha-bridge, Whisper, Piper) pour le ThinkCentre maison A.

Périmètre

Service	Type	Réseau	Notes
Home Assistant	Docker compose	host	mDNS, découverte, websocket
Mosquitto MQTT	Docker compose	web	broker partagé HA + Z2M
Zigbee2MQTT	Docker compose	web	dépend du coordinateur USB
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)

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 sur le runner local → docker compose -f stacks/*/docker-compose.yml up -d.

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

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. 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.