Home Assistant (HA) : installation

Introduction

La domotique est un phénomène qui existe depuis très longtemps : on en parlait déjà dans les années 80 avec l’automatisation de l’éclairage, puis avec l’arrivée dans les années 90/2000 d’Internet, il devenait plus facile de piloter sa domotique et ce qui la composait, mais ce n’est que dans les années 2010/2020 qu’un réel essor est apparu avec plusieurs solutions commerciales, mais également OpenSource de qualité. Pour ne citer que quelques produit, on notera DomoticZ, Domogik, Yana, Jeedom… et Home Assistant.

Home Assistant (aka « HA ») est une des meilleurs solution domotique actuelle… j’ai d’ailleurs migré ma solution DomoticZ que j’utilisais depuis plus de 10 ans vers cette solution plus performante et ayant surtout la capacité de pouvoir gérer beaucoup plus de périphérique « simplement » que d’autres via un large système de plugin.

Beaucoup de choses ont déjà été dites sur HA, mais beaucoup de choses, notamment sur l’installation et la configuration de HA ne sont décrites qu’en anglais ou partiellement en français.

Je vous propose donc plusieurs articles qui seront donc en français et détaillés de façon à ce que tout novice en informatique (surtout sous Linux) puissent réussir son installation… La distribution choisie pour réaliser notre installation est une Débian version 12, mais n’importe quelle distribution Linux pourra faire l’affaire : les versions Ubuntu ou Mint font parti de la lignée Debian alors que des Fedora ou CentOS font parti du monde RedHat, il suffira alors de remplacer la commande « apt » par « yum » (ou « dnf ») si vous êtes sur l’une de ces distributions.

Cet article commence par évoquer l’installation de ZigBee2MQTT qui est un élément essentiel pour piloter les nouveaux périphériques/détecteurs, puis l’installation de HA qui abordera alors les sujets suivant :

1. Premier lancement et premières configurations
2. Installer et définir un thème de l’interface
3. Les modules intégrés et les découvertes
4. Installer et paramétrer un module

[tds_warning]ATTENTION

Toutes les commandes système sous Linux seront exécutées en étant root; si vous êtes connecté sur votre serveur avec un USER normal depuis votre terminal, vous devez commencer par exécuter la commande « sudo -i » qui devrait vous passer « root » sur votre machine.

Des commandes « chown » viendront régulariser certains droits sur une partie de la configuration.[/tds_warning]

Installation de ZigBee2mqtt

[tds_council]

ZibBee : kesako ?

Zigbee est un protocole de haut niveau permettant la communication d’équipements personnels ou domestiques équipés de petits émetteurs radios à faible consommation ; il est basé sur la norme IEEE 802.15.4 pour les réseaux à dimension personnelle (Wireless Personal Area Networks : WPAN) (Source: Wikipedia)

Voyez en « Zigbee », le nouveau « wifi » pour les objets connectés, ayant la capacité de pouvoir fonctionner avec une pile pendant plusieurs mois, voir, des années, ce que ne sait pas faire le Wifi (quelque soit sa version).

[/tds_council]

ZigBee2MQTT est un programme OpenSource développé en JavaScript et exécuté sur un moteur NodeJS; ses sources peuvent être trouvées sur https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

[tds_note]Pourquoi utiliser des produits ZigBee ?

ZigBee est une sorte de « wifi » comme vous l’aurez compris… mais l’une de ses grandes forces est de pouvoir proposer une connexion sans fils pendant des mois, voir des années. Imaginez vous installer un détecteur (d’ouverture de porte ou fenêtre, d’inondation sous votre meuble de SdB encastré, etc…) dont la pile n’aurait que 5 jours d’autonomie ? moi pas…[/tds_note]

ZigBe2MQTT est en réalité une passerelle entre les objets/périphériques ZigBee et le reste du monde…

Pour dialoguer facilement avec le reste du monde, il existe en domotique un protocole qui s’appelle « MQTT » développé par un employé d’IBM il y a plus de 20 ans (en 1999) pour lui permettre de récupérer facilement des données… d’un oléoduc  !!!

Il est en général associé à un serveur MQTT (Ex: mosquitto) qui centralisera les informations envoyées par les clients MQTT et pour les mettre à disposition des autres clients qui souhaitent traiter ces informations (Ex: Home Assistant, DomoticZ, OpenHAB, etc…).

Nous allons donc réaliser 2 étapes :

1. Installer Mosquitto sur notre machine fonctionnant sous Linux
2. Installer ZigBee2MQTT toujours sur la même machine Linux

Installation de Mosquitto

L’installation du serveur MQTT « Mosquitto » est ce qu’il y a de plus facile : en étant connecté « root » avec un terminal sur votre machine Linux, exécutez la commande suivante :

[crayon-6766a7ad5cf3a362279678/]

Voilà !!!

Votre premier serveur est installé et fonctionnel… Facile 😜

Bien sur on aurait pu compliquer les choses, notamment en rajoutant dans le fichier de configuration un USER et son mot de passe, un certificat, etc… mais nous sommes dans notre réseau local et il y a peu de chance que quelqu’un vienne « à l’intérieur », pirater votre installation. De plus cet article est là pour vous mettre rapidement en selle sur une solution que vous perfectionnerez par la suite…

Installation de ZigBee2MQTT

Sous Unix, l’un des principe est que tout binaire doit être exécuté avec un USER autre que root; dans le cas de ZigBee2MQTT on va créer un USER spécifique pour cela et qui s’appellera « zigbee » :

[crayon-6766a7ad5cf4e388936148/]

La commande va demander plusieurs choses, je vous propose de passer ces éléments en tapant plusieurs fois que la touche « Enter » de votre clavier – compris pour la définition du mot de passe :

[crayon-6766a7ad5cf51852613911/]

L’installation de ZigBee2MQTT va se faire ensuite dans le dossier /opt de votre serveur : il convient donc de posséder ce type de répertoire… Dans le cas contraire, ajustez les FileSystem de votre Linux pour qu’il présente un répertoire à la racine du serveur.

[tds_note]En cas d’absence de /opt, plusieurs options s’offrent à vous :

• créer un dossier /opt à la racine de votre machine si cette racine possède un grand espace de stockage (mini 5 Go – solution que j’ai adopté sur ma machine embarquée)
• Créer un vrai FileSystem qui, si il sature, ne viendra pas saturer votre machine. Pour cela, il faut se référer à la solution proposée dans cet article.

Vous pouvez facilement voir si /opt est un FileSystem à part en tapant simplement la commande « df -h » dans votre terminal; si une ligne apparaît avec « /opt », c’est que votre système possède bien un FileSystem à part… Dans le cas contraire, vous n’êtes pas à l’abri d’un problème de saturation si la rotation de LOG venait à faillir par exemple et pourrait empêcher l’accès à votre serveur.

[/tds_note]

Commencez par vous rendre dans /opt :

[crayon-6766a7ad5cf54452790248/]

Pour pouvoir installer les sources de ZigBee2MQTT depuis GitHub, il faut que votre serveur possède la commande « git » : pour l’installer, rien de plus facile :

[crayon-6766a7ad5cf57778949449/]

Une fois arrivé dans /opt et installé la commande « git », nous allons télécharger les fichiers d’installation de ZigBee2MQTT depuis GitHub :

[crayon-6766a7ad5cf58082699413/]

Les sources sont maintenant installées… mais pas avec les bon droits sur les fichiers : on verra plus bas pour leur mettre les bons droits, une fois tout installé et compilé.

Mais pour l’instant, le logiciel n’est pas encore fonctionnel : pour cela il faut encore 3 choses :

1. Installer le moteur d’exécution « NodeJS »
2. Lancer la compilation & configuration du code
3. Installer le service de démarrage automatique de ZigBee2MQTT

Installation de NodeJS

Debian 12 intègre nativement dans son REPO une version de « NodeJS » : à cette date, 2 versions 18.x « mineur » sont disponible (à voir via la commande « apt info nodejs -a« ) et si on lance l’installation sans indiquer la version sélectionnée, ce sera la version la plus à jour qui sera installée.

[su_highlight background= »#DDFF99″ color= »#000000″]Actuellement ZigBee2MQTT demande une version 18 minimum de NodeJS : si vous voulez être absolument sur la version la plus à jour sur ce moteur d’exécution, vous pouvez vous inspirer de ce qui est indiqué sur cette page : https://github.com/nodesource/distributions#deb-supported-versions[/su_highlight]

L’installation de NodeJS va donc se faire en lançant la commande « curl -fsSL https://deb.nodesource.com/setup_20.x | bash -« ; la commande « curl » n’étant pas installée par défaut tout comme « sudo », vous devez lancer la commande « apt install curl sudo -y » avant de lancer la commande précédente dont le résultat devrait ressembler à cela :

[crayon-6766a7ad5cf5b863458929/]

A la fin, on nous indique de lancer la commande « apt-get install nodejs -y« , mais nous allons la compléter en installant également GCC et Make :

[crayon-6766a7ad5cf5e428095180/]

On peut vérifier que NodeJS est correctement installé en lançant les commandes suivantes :

[crayon-6766a7ad5cf62579855300/]

Pour plus d’informations, vous pouvez lire la page du projet à ce sujet : https://www.zigbee2mqtt.io/guide/installation/01_linux.html

On peut maintenant compiler le code précédemment téléchargé de GitHub :

[crayon-6766a7ad5cf66355728584/]

Configuration ZigBee2MQTT

Pour configurer ZigBee2MQTT, vous devez déjà avoir branché votre dongle zigbee sur l’un de vos ports USB de la machine (NB: dans le cas d’une machine virtuelle, vous allez devoir associer le port USB de la machine hôte à un port de la machine virtuelle). Une fois fait, vous allez devoir repérer le port logique que Linux a donné à votre dongle. Pour cela, il faut se rendre dans le dossier « /dev/serial/by-id » et lister les périphériques connectés et découvert par Linux :

[crayon-6766a7ad5cf68970479297/]

On trouve ici deux périphériques connecté : celui qui va nous intéresser est celui dont le nom contient « Silicon_Labs » et qui est mappé vers « ttyUSB0 » (disponible dans /dev).
Ici l’emplacement de notre dongle sera donc :
/dev/serial/by-id/usb-Silicon_Labs_CP2102N_USB_to_UART_Bridge_Controller_1809f672e1c3ec118cdf7e480af30733-if00-port0

On garde le chemin de ce fichier (qui représente notre dongle ZigBee) et on va le mettre dans le fichier de configuration un peu plus bas. On commence avant tout par installer un fichier de configuration par défaut :

[crayon-6766a7ad5cf6a495823402/]

Installation de HA

Pour installer un serveur HA il vous faut bien sur serveur Linux : celui-ci peut physique ou virtuel… Mais HA est également disponible via une image Docker pratique à installer sur certains NAS (Ex: Synology DS42x ou 92x) : une explication est disponible ici ou là.

Si l’installation de HA peut être réalisé de différente manière, chaque méthode ne permet pas l’accès ) toutes les options dont on peut vous parler dans les articles que l’on trouve sur Internet. Le schéma suivant permet d’y voir plus clair :

La version « HA OS » est initialement prévu pour les carte ARM (Raspbery PI, Orange PI, etc…) : c’est un OS Linux que l’on installe sur une carte SD et cet OS contient une installation de HA.

La version « Container » est une version stockée dans un environnement Docker : c’est ce type d’installation que l’on réalise en général sur un NAS.

LA version « Core » est… ????

La version « Supervised » est une version que l’on installe de A à Z mais qui a pour avantage comme pour la version « HA OS », de proposer tout un tas d’Add-ons qui vous permettrons de réaliser plein de chose supplémentaire et accessible directement depuis HA. C’est en général ces composants (Addon-ons) dont on parle partout mais qui ne pourra pas être disponible dans uns installation Docker par exemple (c’était mon cas… avant !).

Je vais donc décrire une installation de type « Supervised » qui intègre les Add-ons (NB : autre que les Add-ons « HAC » que l’on verra plus bas).

Votre pré-requis est d’avoir une machine fonctionnant sous Linux DEBIAN : vous trouverez dans cet article, comment faire cela. La version DEBIAN que je vais utiliser ici est la version 12 qui est la dernière à la date ou j’écris cet article.

Première chose : connectez vous sur votre machine LINUX depuis PuTTY ou une fenêtre DOS / PowerShell si vous êtes sous Windows, un terminal si vous êtes sous MacOS ou Linux.
Si vous connaissez l’adresse IP de votre machine (sinon, voir cet article), il vous suffira de taper la commande « ssh <USER>@<Adresse IP> » dans votre terminal ou simplement l’IP sur PuTTY.

Une fois connecté sur le SHELL de votre ordinateur sous Linux DEBIAN, il vous suffira de taper les commandes suivantes :

[crayon-6766a7ad5cf6d190757560/]

ATTENTION: il est possible que le système réponde qu’il n’arrive pas à accéder à « get.docker.com » : bizarrement, la résolution DNS peut ne pas fonctionner… et il faut alors la forcer en réalisant les opérations suivantes :

[crayon-6766a7ad5cf70539514138/]

« nano » est l’éditeur de texte que je préfère car flexible et surtout facilement accessible à ceux qui ont du mal avec la ligne de commande 😄 : si vous préférez utiliser l’éditeur standard dans le monde UNIX, vous pouvez alors remplacer « nano » par « vi » ou « vim »…
Bref… Dans l’édition du fichier, ajoutez les 2 lignes suivantes :

[crayon-6766a7ad5cf72369524314/]

Une fois le fichier édité, relancez le service « systemd-resolved » avec la commande suivante :

[crayon-6766a7ad5cf74401351551/]

Si la commande « curl » ne faisait pas apparaître de problème pour accéder au serveur « get.docker.com » (ou si vous avez corrigé le problème avec les explications ci-dessus), on voit apparaitre que Docker demande l’exécution de la commande « dockerd-rootless-setuptool.sh install » : sauf que pour l’exécuter sans problème, il manque un paquet Linux que l’on installe de suite :

[crayon-6766a7ad5cf76317287620/]

On continu donc avec le lancement de la commande pour initialiser Docker… sauf que cela doit se faire avec un USER sans privilège; on va donc créer un USER « assistant » :

[crayon-6766a7ad5cf78774173547/]

Une fois le nouveau USER « assistant » créé, on passe dessus et on exécute le script que Docker demande de lancer :

[crayon-6766a7ad5cf7b354564318/]

Parfois, le script ne voit pas que SystemD est installé sur votre machine (si ! si ! il est bien installé…😉) et demande alors que l’on rajoute dans le fichier /home/assistant/.profile les lignes qu’il indique; on édite alors le fichier .profile et on ajoute les lignes suivantes dans ce fichier :

[crayon-6766a7ad5cf7d896583536/]

On peut maintenant se déconnecter (« exit » ou touche Control + D) et débuter l’installation de Home Assistant. On télécharge et installons deux fichiers :

[crayon-6766a7ad5cf7f621008765/]

…puis on redémarre l’ordinateur :

[crayon-6766a7ad5cf80708340647/]

Une fois le reboot de la machine effectué, on se rend à l’adresse qui avait été indiqué à la fin de l’installation du paquet « homeassistant-supervised.deb » : http://<votre @IP>:8123

[crayon-6766a7ad5cf82702435600/]

La suite se passe maintenant dans un autre article : initialisation de Home Assistant