DocumentationInstaller Home Assistant sur un contrôleur Wiren Board
Description
Home Assistant est une plateforme d’automatisation open source développée et maintenue par la communauté home-assistant.io . Son application mobile permet de commander le système sur le réseau local ou via le service cloud de la plateforme.
Installez-la sur un contrôleur Wiren Board pour commander les appareils connectés à la place de l’ interface web standard.
Compatibilité
Les contrôleurs Wiren Board 8/8M et ultérieurs sont recommandés. La prise en charge de Home Assistant sur Wiren Board 6 et 7 (armhf) a pris fin à la fin de 2025 ; ces modèles ne reçoivent plus de mises à jour. Consultez l’ annonce des développeurs.
Installation
La mémoire flash du contrôleur est partitionnée. Une partition utilisateur distincte est montée dans /mnt/data. Si la partition racine a été agrandie pour occuper presque toute l’eMMC, /mnt/data est un simple répertoire de cette partition. Tenez-en compte lors de l’installation de logiciels ou de la mise à jour du firmware.
Copiez les commandes dans la console du contrôleur avec Shift+Insert et exécutez-les avec Enter. Avant d’exécuter une commande, assurez-vous de comprendre son rôle et les modifications qu’elle apportera. Lisez attentivement les messages d’erreur pour obtenir des indications.
Utilisez nano pour modifier les fichiers de configuration. Si un logiciel tiers manque d’espace, la partition racine peut être agrandie jusqu’à occuper presque toute l’eMMC.
Ce guide utilise la méthode Home Assistant Container recommandée par les développeurs. Elle ne comprend pas Supervisor : les modules complémentaires ne peuvent donc pas être installés depuis l’interface web de Home Assistant. Ces modules intègrent généralement des logiciels tiers tels que zigbee2mqtt, ESPHome ou Node-RED, que vous pouvez installer séparément dans des conteneurs.
- Installez Docker en suivant le guide d’installation de Docker.
- Créez le répertoire d’installation et ouvrez-le :
mkdir -p /mnt/data/.docker-compose/home-assistant cd /mnt/data/.docker-compose/home-assistant
- Créez les répertoires de configuration et de médias :
mkdir -p config/home-assistant mkdir -p store/media
- Ouvrez docker-compose.yaml dans l’éditeur :
nano docker-compose.yaml
- Collez la configuration suivante pour Wiren Board 8 :
services: # HomeAssistant homeassistant: container_name: home-assistant image: homeassistant/home-assistant:latest volumes: # Local path where your home assistant config will be stored - ./config/home-assistant:/config - ./store/media:/media - /etc/localtime:/etc/localtime:ro - /run/dbus:/run/dbus:ro # <-- Bluetooth adapter restart: unless-stopped network_mode: host environment: TZ: "${MYTZ}" privileged: true labels: - "com.centurylinklabs.watchtower.monitor-only=true"Pour Wiren Board 6 et 7, utilisez plutôt cette configuration :
services: # HomeAssistant homeassistant: container_name: home-assistant image: ghcr.io/home-assistant/armhf-homeassistant:latest volumes: # Local path where your home assistant config will be stored - ./config/home-assistant:/config - ./store/media:/media - /etc/localtime:/etc/localtime:ro - /run/dbus:/run/dbus:ro # <-- Bluetooth adapter restart: unless-stopped network_mode: host environment: TZ: "${MYTZ}" privileged: true labels: - "com.centurylinklabs.watchtower.monitor-only=true" - Enregistrez avec Ctrl+S et fermez avec Ctrl+X.
- Définissez votre fuseau horaire dans le fichier .env. Choisissez l’un des exemples ci-dessous ou un autre fuseau horaire Linux valide :
UTC (temps universel coordonné) :
echo "MYTZ=UTC" >> .env
Europe centrale (CEST/CET) :
echo "MYTZ=Europe/Berlin" >> .env
Moscou (MSK) :
echo "MYTZ=Europe/Moscow" >> .env
Affichez tous les fuseaux horaires disponibles sous Linux :
timedatectl list-timezones
- Démarrez le conteneur en arrière-plan :
docker compose up -d
Une fois le conteneur démarré, ouvrez l’adresse IP du contrôleur sur le port 8123 dans un navigateur, par exemple http://192.168.42.1:8123. Vous pouvez alors fermer la console.
Mise à jour
Connectez le contrôleur à Internet, puis téléchargez l’image mise à jour et recréez le conteneur :
cd /mnt/data/.docker-compose/home-assistant docker compose pull homeassistant # Update the image docker compose up -d homeassistant # Recreate the container
Les paramètres sont conservés lors de la recréation du conteneur, car la configuration est stockée dans le répertoire config.
Utiliser les appareils Wiren Board
Installer l’intégration Wiren Board
L’ intégration personnalisée Wiren Board crée automatiquement les entités Home Assistant à partir des topics MQTT des appareils. L’intégration actuelle nécessite Home Assistant 2025.6 ou une version ultérieure.
- Copiez le dossier wirenboard du dépôt dans
/mnt/data/.docker-compose/home-assistant/config/home-assistant/custom_components/. - Ouvrez l’interface web de Home Assistant.
- Redémarrez Home Assistant avec Developer Tools → Restart.
- Ouvrez Settings → Devices & Services → Add Integration et sélectionnez wirenboard.
- Les champs Host et Port contiennent les paramètres de connexion par défaut au contrôleur. Modifiez-les uniquement si nécessaire.
Installer l’intégration MQTT
Home Assistant peut commander des appareils Modbus via MQTT. Installez l’intégration MQTT, puis configurez la réception et l’envoi de données. Les étapes et captures d’écran suivantes utilisent l’ancien menu Configuration ; les versions récentes utilisent Settings.
- Ouvrez l’interface web de Home Assistant.
- Sélectionnez Configuration dans la barre latérale gauche, puis ouvrez Devices & Services.
- Cliquez sur Add Integration en bas de la page, recherchez MQTT et sélectionnez l’intégration.
- Attendez l’ouverture de la boîte de configuration. Saisissez localhost dans Broker et 1883 dans Port. Laissez le nom d’utilisateur et le mot de passe vides pour un contrôleur avec la configuration standard. Cliquez sur Submit.
Configurer les appareils manuellement
Après avoir configuré l’intégration, décrivez chaque appareil dans configuration.yaml. Ouvrez le fichier dans l’éditeur :
nano /mnt/data/.docker-compose/home-assistant/config/home-assistant/configuration.yaml
Le répertoire de configuration est /mnt/data/.docker-compose/home-assistant/config/home-assistant/. Ajoutez des sections contenant les paramètres des appareils ; décrivez par exemple les relais dans la section switch.
Enregistrez le fichier et redémarrez Home Assistant. Dans l’ancienne interface, ouvrez Configuration → Settings et cliquez sur Restart. La configuration est vérifiée avant le redémarrage ; les erreurs sont signalées en détail. Une indentation incorrecte est une cause fréquente, car elle a une signification en YAML.
L’espace de stockage du contrôleur est limité. Ajoutez le paramètre recorder suivant pour conserver 14 jours d’historique. Surveillez l’espace disque disponible ; cette durée de conservation n’impose pas de limite fixe à la taille de la base de données.
recorder: purge_keep_days: 14
- Consultez MQTT Discovery pour la syntaxe complète et les types d’appareils pris en charge.
- Les adresses des topics MQTT se trouvent dans l’interface web standard du contrôleur, sous Settings → MQTT Channels.
- Définissez state_topic avec l’adresse du topic MQTT. Pour command_topic, utilisez la même adresse suivie de /on.
- Définissez les capteurs sous mqtt:, comme dans l’exemple de température ci-dessous. Consultez la documentation des capteurs MQTT de Home Assistant pour le format. Placez switch et light sous la même clé mqtt: ; ne créez pas plusieurs clés mqtt: de premier niveau.
Affichez la valeur du capteur de température du processeur :
mqtt:
sensor:
- unique_id: wb_cpu_temperature
name: "CPU Temperature"
state_topic: "/devices/hwmon/controls/CPU Temperature"
unit_of_measurement: "°C"
Commandez les sorties A1 et A2. Cet exemple peut aussi servir à commander des modules relais :
#mqtt:
switch:
- unique_id: wb_a1_switch
name: "WB A1 Switch"
state_topic: "/devices/wb-gpio/controls/A1_OUT"
command_topic: "/devices/wb-gpio/controls/A1_OUT/on"
payload_on: "1"
payload_off: "0"
retain: true
- unique_id: wb_a2_switch
name: "WB A2 Switch"
state_topic: "/devices/wb-gpio/controls/A2_OUT"
command_topic: "/devices/wb-gpio/controls/A2_OUT/on"
payload_on: "1"
payload_off: "0"
retain: true
Commandez le buzzer du contrôleur. Cet exemple peut être adapté à un variateur de lampes LED :
#mqtt:
light:
- unique_id: wb_buzzer
name: "Buzzer"
state_topic: "/devices/buzzer/controls/enabled"
command_topic: "/devices/buzzer/controls/enabled/on"
brightness_state_topic: '/devices/buzzer/controls/volume'
brightness_command_topic: '/devices/buzzer/controls/volume/on'
brightness_scale: 100
payload_on: "1"
payload_off: "0"
retain: true
Accès via le cloud
Pour accéder à Home Assistant hors du réseau local, ajoutez-le comme service dans Wiren Board Cloud. Sur la page du contrôleur, cliquez sur Services et sélectionnez Home Assistant dans le catalogue. Le port 8123 est renseigné automatiquement.
Au départ, Home Assistant renvoie 400: Bad Request , car il ne fait pas confiance aux requêtes provenant du proxy cloud. Ouvrez Home Assistant sur le réseau local avec l’adresse du contrôleur et le port 8123, puis accédez à Settings → System → Network. La suite dépend de votre version de Home Assistant.
Si la page Network comporte une section HTTP server, vous utilisez Home Assistant 2026.8 ou une version ultérieure. Dans ces versions, configurez les paramètres HTTP dans l’interface web :
- Dans HTTP server, développez Reverse proxy.
- Activez Trust X-Forwarded-For.
- Ajoutez séparément 127.0.0.1, ::1 et 172.16.0.0/12 dans Trusted proxies.
- Cliquez sur Save, puis sur Save and restart.
- Après le redémarrage, cliquez sur Confirm dans la boîte de confirmation de la nouvelle configuration du serveur HTTP. Vous devez confirmer sous 5 minutes ; sinon Home Assistant rétablit les paramètres précédents.
Si la section HTTP server est absente, votre version est antérieure à 2026.8. Cela s’applique aussi aux Wiren Board 6 et 7, qui ne reçoivent plus de nouvelles versions :
- Ajoutez les lignes suivantes dans
/mnt/data/.docker-compose/home-assistant/config/home-assistant/configuration.yaml:http: use_x_forwarded_for: true trusted_proxies: - 127.0.0.1 - ::1 - 172.16.0.0/12 - Redémarrez le conteneur :
docker restart home-assistant
Lors d’une mise à niveau ultérieure vers Home Assistant 2026.8 ou une version plus récente, les paramètres HTTP sont transférés dans la section HTTP server au premier démarrage. Si une confirmation est demandée, cliquez sur Confirm sous 5 minutes ; sinon les paramètres sont rétablis et doivent être saisis à nouveau selon les étapes ci-dessus. Vérifiez les adresses dans Trusted proxies, puis supprimez le bloc http: de configuration.yaml.