24-07-2023

Sommaire

Présentation de Home Assistant et Zigbee2MQTT

Home Assistant est un logiciel open-source, libre et gratuit. Il permet d'agir comme un serveur central de domotique profitant d'énormément d'intégrations (Apple Homekit, Google Assistant ...). Grâce à une interface web et une application mobile il est le parfait remplaçant de nombreuses solutions propriétaires.

Zigbee2MQTT est le compagnon parfait de HomeAssistant, il agit en tant que passerelle pour le protocole Zigbee. Ce logiciel va collecter les données de vos objets connectés (plus de 3000 objets supportés) pour en décoder les trames et renvoyer les différents états et actions à travers des topics MQTT dans Home Assistant. Zigbee2MQTT est directement connecté à votre dongle Zigbee USB.

Pourquoi passer par Docker

Il existe de nombreuses méthodes pour installer Home Assistant (listées ici).

Dans ce tableau comparatif des différentes méthodes d'installation de Home Assistant on remarque qu'installer Home Assistant par le système d'exploitation offre le plus de possibilités. Cependant, nous allons utiliser la méthode Container avec Docker car elle offre d'autres avantages non listés dans ce comparatif :

Utiliser les images docker permet de ne pas consacrer son système hôte à Home Assistant (ou de passer par des machines virtuelles)
L'utilisation de conteneurs est beaucoup plus léger qu'une machine virtuelle
L'impossibilité d'installer des Add-ons (tels que Zigbee2MQTT ou Mosquitto) n'est pas vraiment un sujet car les Add-ons Home Assistant sont des conteneurs. Or, nous pouvons les installer avec Docker.
Plus de flexibilité, vous avez le plein contrôle sur votre installation d'Home Assistant

À noter que la liste de ces avantages peuvent être valables ou non suivant les cas d'usage. Si vous avez une machine plutôt puissante ou dédiée à cela, je vous conseille de partir vers Home Assistant OS.

Pré-requis

Pour installer Home Assistant et Zigbee2MQTT de manière conteneurisée il vous faudra une machine avec un OS compatible avec Docker et une architecture i386, amd64 ou arm. Dans ce billet je vais que couvrir uniquement l'installation avec un OS de type GNU/Linux.

Si vous souhaitez installer Zigbee2MQTT avec un dongle zigbee usb il faudra vous en procurer un. J'utilise personnellement la clé SONOFF CC2652P.

Installation de Docker et Docker-Compose

Installez la version Docker engine (et non Desktop) :

Les instructions très claires sont détaillées sur la documentation de Docker. Exemple : Installation de Docker Engine sur Debian

Une fois Docker installé nous pouvons rentrer dans le vif du sujet et installer nos applicatifs.

Installation

Adresse du dongle Zigbee USB

Pour trouver l'adresse de type /dev/ttyUSBX débranchez votre dongle de votre appareil s'il est déjà branché. Ensuite rebranchez-le puis tapez la commande suivante :

sudo dmesg

Les dernières lignes affichées devraient ressembler à quelque chose de ce type :

[3516855.453770] usb 1-2: new full-speed USB device number 4 using xhci_hcd
[3516855.604520] usb 1-2: New USB device found, idVendor=XXX, idProduct=XXX, bcdDevice= 1.00
[3516855.604541] usb 1-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[3516855.604549] usb 1-2: Product: Sonoff Zigbee 3.0 USB Dongle Plus
[3516855.604556] usb 1-2: Manufacturer: Silicon Labs
[3516855.604561] usb 1-2: SerialNumber: 0001
[3516855.606527] cp210x 1-2:1.0: cp210x converter detected
[3516855.609788] usb 1-2: cp210x converter now attached to ttyUSB0

A la dernière ligne on remarque que notre équipement a été attaché à ttyUSB0, conservez cette information pour la configuration dans l'étape suivante.

Conteneurs

Dans un premier temps créer un dossier qui va contenir nos fichiers de configuration et le fichier docker-compose.yml

mkdir home-assistant

Ensuite, se placer à l'intérieur du dossier et créer le fichier docker-compose.yml suivant :

version: '3.8'
services:
  #Conteneur Home Assistant
  homeassistant:
    image: homeassistant/home-assistant:stable
    container_name: homeassistant
    environment:
      - TZ=Europe/Paris
    ports:
    #Le port sur lequel sera accessible l'interface web PORT_EXPORTE:PORT_CONTENEUR
      - 8123:8123
    #On définit un "bind mount" pour conserver la configuration de Home-Assistant
    volumes:
      - ./home-assistant:/config
    restart: always

  #Conteneur du broker MQTT Mosquitto
  mosquitto:
    image: eclipse-mosquitto
    container_name: mqtt
    #Pas besoin d'exporter de port vers l'extérieur
    #ports:
    #  - 1883:1883
    volumes:
    #Bind mount pour la configuration
      - ./mosquitto/config:/mosquitto/config
    #Volumes pour les logs et les données persistantes
      - mosquitto_data:/mosquitto/data
      - mosquitto_log:/mosquitto/log

  #Conteneur ZigBee2MQTT
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    depends_on:
    #Le conteneur mosquitto doit être démarré pour lancer le conteneur ZigBee2MQTT
      - mosquitto
    volumes:
      - ./zigbee2mqtt:/app/data
      - /run/udev:/run/udev:ro
    ports:
    #Port Zigbee2MQTT
      - 8080:8080
    devices:
    #Adresse de votre dongle usb ZigBee à changer par la votre (uniquement avant les ':')
      - /dev/ttyUSB0:/dev/ttyUSB0
    restart: unless-stopped

volumes:
  mosquitto_config:
  mosquitto_data:
  mosquitto_log:
  zigbee_data:

Ce fichier correspond pour la plupart des cas d'usages et est globalement complet. Cependant avant de lancer vos conteneurs il faut modifier l'adresse de votre dongle usb Zigbee trouvée précédemment.

Configuration des applicatifs

Il faut maintenant créer 2 fichiers de configuration :

ZigBee2MQTT :

Depuis le dossier racine où est notre fichier docker-compose.yml est présent

mkdir zigbee2mqtt; cd zigbee2mqtt; touch configuration.yaml

Ensuite éditer le fichier configuration.yaml pour lui apporter les paramètres suivants : Ne pas éditer /dev/ttyUSB0 et l'adresse MQTT, ce sont celles à l'intérieur du conteneur donc elles sont forcément correctes !

homeassistant: true
permit_join: true
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mosquitto
serial:
  port: /dev/ttyUSB0
frontend:
  port: 8080

Mosquitto :

Depuis le dossier racine où est notre fichier docker-compose.yml est présent

mkdir -p mosquitto/config; cd mosquitto/config; touch mosquitto.conf

Ensuite éditer le fichier mosquitto.conf pour lui apporter la configuration suivante :

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
log_type all
listener 1883
allow_anonymous true

Lancement et tests

On peut désormais lancer les conteneurs avec les commande :

docker compose up -d

Si tout se passe bien il ne devrait pas y avoir d'erreur et il est possible de se connecter aux interfaces web :

Home Assistant : adresse:8123
Zigbee2MQTT : adresse:8080

S'il y a des erreurs ou qu'une des interfaces ne s'affiche pas quand vous essayez d'y accéder essayez de savoir si un conteneur est planté avec docker ps et regardez les logs avec docker logs <nom du service>

Bilan et suite

Nous avons vu comment installer Home Assistant et Zigbee2MQTT avec Docker. La première étape (et la moins amusante) pour entrer dans le monde de la domotique avec Home Assistant est franchie. L'ajout de nouveaux capteurs et la configuration de Home Assistant / Zigbee2MQTT feront l'objet d'autres billets sur ce blog.

Si vous souhaitez récupérer les fichiers de configuration (docker-compose, configuration.yml etc...) ils sont disponibles sur mon git à partir de ce lien