Appareils

Appareils et intégrations

Zigbee, MQTT, Matter et le catalogue par marque : matériel et mise en service.

Ces technologies sont distinctes :

• Zigbee est un réseau radio maillé propre (2,4 GHz). Il exige un coordinateur branché au serveur. Les appareils Zigbee ne parlent pas IP.
• MQTT est un protocole de messages sur IP. Il exige un broker, installé ici. Zigbee2MQTT l'utilise pour dialoguer avec My Habita, et des appareils Wi-Fi (Tasmota, Shelly, ESPHome) peuvent s'y connecter directement.
• Matter est un standard applicatif sur IPv6. My Habita s'appuie sur un contrôleur Matter (le serveur Matter). Un appareil Matter peut être en Wi-Fi, en Ethernet ou en Thread. Thread est un réseau radio maillé IPv6, distinct de Zigbee même s'il partage la bande 2,4 GHz, et il exige un routeur de bordure Thread.

Zigbee (Zigbee2MQTT)

Matériel nécessaire

Un coordinateur Zigbee, par exemple :

Conseils de placement : branchez la clé sur une rallonge USB de 50 cm à 1 m, loin des ports USB 3, des disques et du point d'accès Wi-Fi (interférences en 2,4 GHz).

Cette machine est une VM KVM (Proxmox probablement : interface ens18). La clé doit être transmise à la VM (USB passthrough, idéalement par identifiant fabricant et produit). Elle apparaîtra alors dans /dev/serial/by-id/.

⚠ Un coordinateur ne sert qu'un seul système

Un coordinateur (USB ou réseau, par exemple SLZB sur tcp://…:6638) ne peut être piloté que par un seul système à la fois. Si Home Assistant (ZHA ou Zigbee2MQTT), un autre Zigbee2MQTT ou deCONZ l'utilise encore, arrêtez-le d'abord. Sinon les deux systèmes se disputent la clé : chacun la réinitialise et y impose son propre réseau.

De plus, Zigbee2MQTT efface le réseau présent sur le coordinateur s'il ne correspond pas à sa configuration et qu'aucune sauvegarde n'y correspond, puis en forme un autre. C'est le cas avec les pilotes ember (il quitte le réseau) et zstack (il remet la radio en service), d'après le code de zigbee-herdsman 10.10. C'est ce qui s'est produit le 18/10/2026 (voir ETAT.md). Depuis, My Habita ne démarre plus Zigbee2MQTT sans un choix explicite :

• Reprendre un réseau existant, sans réappairer les appareils : collez la sauvegarde de ce réseau au format Open Coordinator Backup. Ce peut être le fichier coordinator_backup.json (dossier data/) d'un ancien Zigbee2MQTT, ou la sauvegarde réseau de ZHA (Home Assistant → Paramètres → Appareils et services → Zigbee → Configurer → Télécharger une sauvegarde). Zigbee2MQTT restaure alors ce réseau sur le coordinateur : même clé, même identifiant, même canal.
• Créer un nouveau réseau : uniquement après avoir confirmé que tout réseau présent sur le coordinateur sera effacé, et que ses appareils devront être réappairés.
• Un réseau déjà connu de My Habita n'est jamais remplacé sans une seconde confirmation explicite.

Protections supplémentaires :

• Si le pont tombe moins de 20 s après son démarrage, deux fois en 10 minutes, My Habita arrête Zigbee2MQTT par sécurité, met ses réglages de côté et vous prévient.
• systemd limite les redémarrages automatiques à 3 par quart d'heure, espacés de 30 s.

Mise en service (dans l'interface)

1. Intégrations → Ajouter → Zigbee (Zigbee2MQTT).
2. Configurer le coordinateur : My Habita liste les ports série détectés (/dev/serial/by-id/…, références stables) et propose le type d'adaptateur selon le modèle reconnu. Pour un coordinateur réseau, saisissez tcp://adresse:port (6638 par défaut sur les SLZB ; les modèles à plusieurs radios exposent un port par radio).
3. Réseau Zigbee : reprendre un réseau existant (sauvegarde) ou créer un nouveau réseau (effacement confirmé). Voir ci-dessus.
4. Enregistrer et démarrer : le script privilégié du service valide les choix, écrit la configuration de Zigbee2MQTT (identifiants MQTT, réseau, disponibilité activée, interface web de Zigbee2MQTT limitée à 127.0.0.1:8099) et retire la clé réseau importée des réglages de l'assistant. Le service démarre ensuite.
5. Associer un appareil (bouton en haut de la page) : appairage ouvert pour 254 s au plus, avec suivi en direct (détection, interrogation, ajout). L'appareil reçoit automatiquement le nom « Fabricant Modèle » (ex. « Aqara MCCGQ11LM », numéroté s'il existe déjà) ; renommez-le et choisissez sa pièce.

Reprendre les appareils d'un autre Zigbee2MQTT (Home Assistant…)

Le fichier coordinator_backup.json seul ne contient que le réseau (clé, identifiants, canal) : avec lui, les appareils restent membres du réseau, mais Zigbee2MQTT ignore leurs messages car il ne les connaît pas (il faudrait les réappairer). Pour tout retrouver, importez la sauvegarde complète :

1. Arrêtez l'ancien Zigbee2MQTT (un coordinateur ne sert qu'un seul système).
2. Récupérez sa sauvegarde : dans son interface web, Paramètres → Outils → sauvegarde (fichier .zip) ; ou bien les fichiers database.db, configuration.yaml et coordinator_backup.json de son dossier de données (zigbee2mqtt/ dans la configuration de Home Assistant). Les sauvegardes .tar de Home Assistant ne sont pas lues directement.
3. Page Zigbee → onglet Sauvegardes → déposez le fichier. My Habita l'analyse sans rien appliquer : réseau de la sauvegarde comparé au réseau actuel, liste des appareils (déjà présents ou à ajouter), groupes, avertissements.
4. Importer : Zigbee2MQTT redémarre ; son script de démarrage (privilégié) applique la sauvegarde :
   • même réseau que celui de My Habita → les appareils manquants sont ajoutés avec leurs noms, options et dernier état ; le réseau n'est pas modifié ; un appareil déjà présent garde ses données actuelles ;
   • aucun réseau encore configuré → réseau et appareils repris ensemble ;
   • autre réseau → remplacement seulement après une confirmation explicite (les appareils du réseau actuel devront être réappairés). Sans confirmation, l'import est refusé et Zigbee2MQTT redémarre normalement.
5. Les fichiers actuels sont d'abord copiés dans /var/lib/myhabita-zigbee2mqtt.avant-import-<date>/. La sauvegarde déposée (qui contient la clé réseau) est supprimée après l'import. Le résultat s'affiche dans l'onglet Sauvegardes.

Les noms Zigbee2MQTT de la forme salon/plafonnier donnent l'appareil « plafonnier » dans la pièce « Salon » (si elle existe). Deux noms identiques reçoivent un suffixe « (2) », car Zigbee2MQTT exige des noms uniques.

L'onglet Sauvegardes permet aussi de télécharger la sauvegarde complète de Zigbee2MQTT (.zip, avec la clé réseau ; le mot de passe MQTT interne en est retiré).

Carte du réseau, coordinateur, outils par appareil

• Appareils : tableau avec photo, pièce, rôle (routeur ou terminal), qualité de liaison, batterie, dernier contact ; recherche et filtres (routeurs, sur pile, à surveiller).
• Carte du réseau : analyse à la demande (de quelques secondes à quelques minutes ; elle charge brièvement le réseau). Graphe interactif (zoom, déplacement, sélection d'un appareil et de ses liaisons), couleurs selon la qualité de liaison, et vue en liste triée du plus fragile au plus solide. La dernière analyse est conservée.
• Coordinateur : puce et micrologiciel, adresse IEEE, canal, PAN, versions ; configurer, redémarrer, vérifier le coordinateur (routeurs absents de sa table, pilotes ember et zstack).
• Journal du service, filtrable (erreurs et avertissements).
• Page d'un appareil Zigbee : rôle, adresses, micrologiciel, interrogation ; actions Reconfigurer, Interroger à nouveau, mises à jour OTA (vérifier, mettre à jour, notification à la fin) ; options du modèle (étalonnage, durées…, d'après Zigbee2MQTT). Une commande sans retour d'état (ex. « Identifier ») apparaît comme un simple bouton.

Photos des produits

Les photos viennent du catalogue public de Zigbee2MQTT (www.zigbee2mqtt.io/images/devices/<modèle>.png). Le serveur télécharge chaque photo une seule fois, à la première demande, puis la sert depuis /var/lib/myhabita/media/zigbee/ : le navigateur ne contacte aucun site extérieur, et seul le nom du modèle est transmis. Pour désactiver ces téléchargements : "deviceImages": { "fetch": false } dans /etc/myhabita/myhabita.json (les icônes remplacent alors les photos).

Garanties :

• My Habita ne reflashe jamais le coordinateur, et ne laisse Zigbee2MQTT former un réseau qu'après votre confirmation explicite.
• Un réseau repris (import) reste accepté aux démarrages suivants sans nouvelle confirmation.
• Le canal n'est jamais changé sur un réseau formé.
• Les appareils sont identifiés par leur adresse IEEE : les renommer, dans My Habita ou dans Zigbee2MQTT, ne casse rien.
• Un nom Zigbee2MQTT de la forme salon/plafonnier place l'appareil dans la pièce « Salon » à sa découverte.
• La clé réseau et la base des appareils sont incluses dans les sauvegardes.

Validé sur matériel (18/10/2026)

• Coordinateur réseau EmberZNet 9.0.1 (tcp://192.168.20.10:6638), réseau repris depuis la sauvegarde du Zigbee2MQTT de Home Assistant.
• Appairage, interrogation et remontées en direct d'un capteur d'ouverture Aqara MCCGQ11LM (266 changements d'état et 186 mesures de qualité de liaison enregistrés en 40 minutes), disponibilité.

Ce qui reste à valider avec du matériel

• Import d'une sauvegarde complète sur votre installation (vérifié par des tests logiciels, de bout en bout, mais pas encore avec votre sauvegarde réelle).
• Commandes (lumières, prises, têtes thermostatiques) et confirmations.
• Carte du réseau, mises à jour OTA et options d'appareil sur un réseau réel (testés avec un Zigbee2MQTT simulé).
• Disponibilité des appareils sur pile au-delà de 25 h (délai par défaut de Zigbee2MQTT).

Appareils MQTT

• Broker : <adresse-du-serveur>:1883 sur le réseau local. Authentification obligatoire : aucun accès anonyme.
• Comptes : Intégrations → Appareils MQTT → « Comptes des appareils ». Chaque appareil reçoit un compte (rôle device) qui ne peut pas toucher aux topics zigbee2mqtt/# ni aux topics système. Le mot de passe est affiché une seule fois.
• Description d'un appareil : topic d'état, topic de commande, valeurs « allumé » et « éteint », champ JSON éventuel, topic de disponibilité. L'outil « Écouter les messages » aide à trouver les topics.
• Un appareil qui ne publie pas son état peut être déclaré « supposé » : sa valeur est alors affichée comme supposée, jamais comme confirmée.
• Pas de chiffrement TLS sur 1883 (réseau local uniquement). Ne redirigez jamais ce port depuis votre box.

Exemple Tasmota (prise) : état stat/prise-tv/POWER, commande cmnd/prise-tv/POWER, valeurs ON / OFF, disponibilité tele/prise-tv/LWT (Online / Offline).

Matter

La page de l'intégration Matter suit le modèle de Zigbee. Elle a cinq onglets :

• Appareils : réseau Thread, Wi-Fi ou Ethernet, rôle Thread, signal, version et mises à jour, partage, renommage, retrait ;
• Ajouter : un assistant selon l'état de l'appareil ;
• Réseau Thread : le routeur de bordure de My Habita et la carte du réseau ;
• Diagnostic : le réseau vu par le serveur ;
• Serveur.

Matter sans IPv6 chez votre opérateur

Matter fonctionne en IPv6, mais seulement en IPv6 local (adresses fe80::). Chaque appareil et le serveur le créent seuls, même quand la box et le Wi-Fi « n'ont pas l'IPv6 ». Deux conditions suffisent :

• Appareils Wi-Fi ou Ethernet : ils doivent être sur le même réseau local (même VLAN) que le serveur.
  • Ce n'est pas le cas aujourd'hui : le serveur est en 192.168.10.x, les appareils Wi-Fi de la maison en 192.168.50.x.
  • Solution recommandée : donner au serveur une seconde carte réseau sur le VLAN du Wi-Fi.
    1. Dans Proxmox : VM → Matériel → Ajouter → Périphérique réseau, avec le pont et l'étiquette VLAN du Wi-Fi.
    2. Dans Debian : déclarer l'interface (/etc/network/interfaces, en DHCP).
    3. Dans My Habita : la choisir dans Matter → Serveur → « Interface réseau principale ».
  • Autre solution : placer les appareils Matter sur le réseau du serveur.
  • L'onglet Diagnostic détecte cette situation et l'explique.
• Appareils Thread : ils passent par un routeur de bordure sur le même réseau que le serveur. Le plus simple est celui de My Habita : avec lui, tout reste sur le serveur, et ni la box ni le Wi-Fi n'ont besoin d'IPv6.

Routeur de bordure Thread de My Habita (OpenThread Border Router)

My Habita peut faire tourner son propre OpenThread Border Router (ot-br-posix v2026.10.0, commit cb4bdae). Il est construit sur le serveur, et My Habita le pilote par son API locale (127.0.0.1:8081).

Il faut une radio Thread avec le micrologiciel OpenThread RCP. Par exemple :

• Home Assistant Connect ZBT-1 ou SkyConnect, en mode Thread ;
• Sonoff ZBDongle-E, flashé en RCP ;
• SMLIGHT SLZB-06 ou SLZB-07 avec le micrologiciel Thread ;
• la seconde radio d'un SLZB multi-radio.

Une radio déjà utilisée par Zigbee ne peut pas servir aux deux. Une radio réseau (SLZB) est reliée par un pont TCP → port série local (socat).

Coordinateurs SMLIGHT (SLZB-06, SLZB-MR…) : « Configurer la radio » lit la page d'information du coordinateur et indique, pour chaque radio, sa puce, son mode (Zigbee ou Thread), si son port réseau est ouvert, et quoi régler. Le port de la radio Zigbee n'est jamais sondé, pour ne pas perturber Zigbee2MQTT. « Tester » vérifie qu'une radio répond bien en OpenThread (version du micrologiciel).

À la maison, le SLZB-MR2U a deux radios :

• la radio 1, une EFR32MG21, sert à Zigbee sur le port 6638 ;
• la radio 2, une CC2652P, est en mode « Matter-over-Thread », mais son port réseau 7638 était fermé le 19/10/2026.

Pour l'ouvrir, dans l'interface web du SLZB (http://192.168.20.10) :

1. Z2M and ZHA → réglages de la radio 2 → Socket Port 7638 → Save ;
2. redémarrer le SLZB ;
3. vérifier avec « Tester ».

Si la radio réseau est injoignable, le routeur de bordure ne démarre pas (sans boucle d'échecs) : My Habita vérifie le port chaque minute et le démarre dès que la radio répond.

Installation (une fois ; elle reprend la compilation déjà faite) :

sudo myhabitactl otbr-install

Mise en service, dans Matter → Réseau Thread :

1. Configurer la radio : port USB ou adresse réseau, vitesse, interface du réseau local.
2. Créer un réseau Thread, ou importer celui d'un autre routeur de bordure. Le réseau est transmis automatiquement au serveur Matter.
3. Exporter le réseau le transmet à un autre routeur ou au téléphone. L'export contient la clé du réseau : à garder secret.

My Habita refuse de remplacer un réseau Thread existant sans confirmation explicite, comme pour Zigbee.

Effets sur le système, seulement quand le routeur est activé (fichier /etc/sysctl.d/60-myhabita-otbr.conf, retiré à la désactivation) :

• l'interface réseau accepte les routes annoncées par les routeurs Thread (accept_ra=2, accept_ra_rt_info_max_plen=64) ;
• si l'option « Routes annoncées sur le réseau local » est activée : routage IPv6, et le routeur annonce un préfixe IPv6 privé (ULA) sur le réseau local, pour que d'autres machines joignent les appareils Thread.

Le service myhabita-otbr tourne sous un compte dédié avec le minimum de droits. Commandes : myhabitactl otbr status|logs|ctl ….

Non vérifié : aucune radio Thread n'a encore été branchée. La compilation et l'installation des binaires sont vérifiées ; le fonctionnement réel du routeur ne l'est pas.

Ajouter un appareil

Dans Matter → Ajouter, choisissez la situation de l'appareil :

Un appareil peut ensuite être partagé avec une autre application : fiche de l'appareil → « Partager », qui affiche un code valable 15 minutes.

Robots aspirateurs Matter (dont le Dreame D30 Ultra) :

• état et commandes ;
• modes Aspiration / Lavage / Aspiration puis lavage ;
• pièces, si le robot gère la zone de service Matter 1.4. Le nettoyage par pièce se fait depuis le panneau de l'aspirateur.

Matter ne transporte pas de carte : seule la liste des pièces est disponible.

Vérifié

Avec un appareil logiciel matter.js (type « OnOff Light »), le 18/10/2026 :

• mise en service par code ;
• découverte et correspondance avec le modèle universel (lumière, marche et arrêt) ;
• commandes marche et arrêt confirmées par l'appareil ;
• disponibilité : moins de 4 s après un arrêt propre (annonce ShutDown), environ 5 min après une coupure brutale (fin d'abonnement Matter).

Note : les appareils de développement (certificats de test) sont refusés par le serveur Matter, comme il se doit. L'essai a utilisé une seconde instance temporaire avec l'option --enable-test-net-dcl. L'instance installée n'accepte que les appareils certifiés.

À valider avec du matériel

Restent à essayer avec du matériel :

• appareils physiques Wi-Fi et Thread ;
• thermostats, volets, couleurs, capteurs (correspondances écrites d'après la spécification Matter, non essayées) ;
• mises à jour OTA ;
• routeur de bordure Thread avec une vraie radio ;
• mise en service depuis le téléphone ;
• pièces des robots (zone de service).

Intégrations réseau et cloud (catalogue)

Elles s'ajoutent depuis Intégrations → Ajouter une intégration : le catalogue se parcourt par famille ou par recherche (marque, type d'appareil). Chaque fiche indique :

• Local : tout passe par le réseau de la maison, cela fonctionne même sans Internet ;
• Cloud : les échanges passent par Internet et les serveurs du fabricant ou du service ;
• Bêta : protocole documenté, intégration récente ;
• Non officielle : interface du fabricant obtenue par rétro-ingénierie, qui peut cesser de fonctionner après une mise à jour de son application.

Aucune n'a encore été essayée avec du matériel ou un compte réels sur cette installation (sauf mention contraire). Toutes ont été testées par logiciel contre de faux équipements reproduisant leurs protocoles (tests/unit/integrations/).

Détectés sur votre réseau : My Habita cherche régulièrement (mDNS, et découverte propre à certains protocoles) les équipements qu'il sait intégrer, et propose de les ajouter. Sur ce réseau, les annonces mDNS traversent mal le routeur entre les sous-réseaux (192.168.10.x ↔ 192.168.50.x) : en cas d'absence, saisissez l'adresse à la main.

Secrets : mots de passe et jetons ne sont jamais renvoyés au navigateur ni écrits dans le journal ; les clés obtenues par association (bouton d'un pont, autorisation OAuth) sont conservées par le moteur (base de données, sauvegardée avec le reste).

MQTT Discovery (format Home Assistant)

Beaucoup d'appareils et de passerelles s'annoncent eux-mêmes sur MQTT au format de découverte de Home Assistant : ESPHome (composant MQTT), Tasmota (SetOption19 1), Shelly (MQTT avec découverte), Valetudo, OpenMQTTGateway, Theengs, Z-Wave JS UI, Frigate, rtl_433… Il suffit de les connecter au broker de My Habita avec un compte créé dans Appareils MQTT : ils apparaissent tout seuls, regroupés par appareil, avec leur pièce suggérée.

• Pris en charge : capteurs (avec conversion d'unités), détecteurs, interrupteurs, lumières (schémas « basic », « json » et « template » : luminosité, blanc, couleur), volets (position), thermostats, ventilation, serrures, boutons, scènes, listes, réglages numériques, sirènes, robots aspirateurs, événements et déclencheurs (boutons), disponibilité.
• Les modèles de valeur (Jinja2) sont évalués par un interpréteur limité et sûr qui couvre les formes courantes ; un modèle non pris en charge est signalé (Santé du système) et seule cette valeur est ignorée.
• Les annonces de Zigbee2MQTT (sujet zigbee2mqtt/…) sont ignorées : ces appareils passent déjà par l'intégration Zigbee. Un appareil géré par une intégration dédiée (Valetudo, Shelly…) et annoncé sur MQTT apparaîtrait deux fois : mettez-le dans la liste « À ignorer ».
• Supprimer un appareil : cochez « Effacer aussi ses annonces MQTT », sinon il revient au prochain démarrage.
• Non pris en charge : attributs JSON, effets, inclinaison des volets, consignes haute/basse, caméras, mises à jour, alarmes.

Philips Hue

• Ce qu'il faut : un pont Hue carré (2e génération). Après l'ajout, appuyez sur le bouton rond du pont : My Habita s'associe tout seul (il attend 5 minutes ; « Associer de nouveau » recommence).
• Fonctionnement : API locale officielle CLIP v2 en HTTPS ; état en direct par le flux d'événements du pont, relecture complète toutes les 10 minutes et à chaque reconnexion. Les commandes sont espacées comme le demande Philips (environ 10 par seconde pour les lampes, 1 par seconde pour les groupes).
• Sécurité : le certificat du pont doit porter son identifiant ; son empreinte est épinglée à l'association. Si le pont est remplacé ou réinitialisé, associez de nouveau.
• Appareils : lumières (marche, luminosité, blanc, couleur, transition, effets bougie, feu de cheminée, étincelles… selon la lampe, « Faire clignoter » pour la repérer), prises Hue, détecteurs de mouvement (mouvement, température, luminosité), capteurs d'ouverture, interrupteurs et télécommandes (événements d'appui pour les automatisations), batterie, disponibilité Zigbee. Option : une « Pièce Hue » / « Zone Hue » par pièce ou zone, avec la lumière de groupe (marche, luminosité, et blanc ou couleur pour toutes les lampes à la fois — valeur supposée, le pont ne la renvoie pas pour un groupe) et ses scènes (activables normalement ou en dynamique quand la scène a une palette).
• Adresse : si le pont change d'adresse IP, My Habita le retrouve par son identifiant (mDNS, puis service de découverte de Philips).
• Vérifié sur le pont réel de la maison (192.168.50.204, BSB002, API 1.78) : connexion HTTPS, certificat (« root-bridge », nom = identifiant du pont), épinglage, refus d'une clé invalide. L'association et le pilotage restent à essayer (appui sur le bouton nécessaire).
• Non pris en charge : effets dynamiques, divertissement (Hue Sync), molettes, mises à jour du micrologiciel. Les ampoules Hue peuvent aussi être appairées directement en Zigbee, sans pont.

WLED

Contrôleurs à ESP8266/ESP32 sous WLED (0.13 ou plus récent conseillé). Liste d'adresses, ou ajout automatique des contrôleurs annoncés sur le réseau. État en direct par WebSocket, relecture toutes les 60 s. Entités : lumière (luminosité, couleur, blanc si le ruban en a), effet, préréglage, signal Wi-Fi. Non pris en charge : segments séparés, palettes, vitesse et intensité des effets, synchronisation.

Yeelight

Activez « Contrôle LAN » dans l'application Yeelight pour chaque lampe. Recherche par le protocole de découverte Yeelight (port 1982). Une connexion permanente par lampe (la lampe signale ses changements) ; la lampe limite à environ 60 commandes par minute, My Habita refuse au-delà avec un message clair. Lumière ambiante des plafonniers prise en charge. Non pris en charge : mode musique, flux de couleurs, scènes, veilleuse.

Nanoleaf

Une intégration par contrôleur. Après l'ajout, maintenez le bouton marche 5 à 7 secondes jusqu'au clignotement : My Habita obtient sa clé (pendant 5 minutes). État en direct (flux d'événements), effets. Non pris en charge : couleur par panneau, événements tactiles. Les produits Nanoleaf Essentials passent par Matter.

Shelly

Relais, prises, variateurs, volets roulants, compteurs d'énergie et capteurs Shelly, générations 1 à 4 (Plus, Pro, Gen3, Gen4), par leur API locale officielle. Ajout par adresse ou automatique (annonces mDNS). Les appareils récents sans mot de passe envoient leurs changements en direct (WebSocket) ; les autres sont relevés toutes les 10 s. Mot de passe : saisi une fois pour tous les appareils, transmis seulement sous forme chiffrée (Digest). Entités : sorties, volets (position), lumières (luminosité, couleur, blanc), puissance et énergie, température, humidité, luminosité, batterie, ouverture, mouvement, fuite, fumée, entrées et appuis de boutons, température interne et signal Wi-Fi.

Les capteurs sur pile (H&T, Door/Window…) dorment et ne répondent qu'à leur réveil : ils ne sont signalés indisponibles qu'après 26 h sans contact. Non pris en charge : Shelly BLU, têtes thermostatiques, détecteur de gaz, cloud Shelly. Réservez une adresse IP fixe à chaque appareil.

TP-Link Kasa

Prises (HS100/103/105/110, KP105/115), multiprises (HS300, KP303 : une sortie par prise, mesure par prise sur HS300), interrupteurs et variateurs (HS200, HS220), ampoules KL/LB, par le protocole local historique (port 9999), documenté par la communauté (python-kasa) : non officiel. Les appareils dont le micrologiciel récent utilise le nouveau chiffrement (« KLAP ») et les produits Tapo ne répondent pas à ce protocole : My Habita l'indique clairement. Recherche par diffusion sur le réseau local ; relève toutes les 10 s.

Google Cast (Google Home, Nest, Chromecast)

« Google Home » n'a pas d'API publique pour piloter les appareils qu'il gère. My Habita parle donc directement aux enceintes et écrans Google Home / Nest et aux Chromecast par le protocole Cast, en local : état (lecture, pause…), volume, sourdine, titre, artiste, album, pochette, durée et position, commandes lecture/pause/suivant, avance dans le titre. La page Multimédia y fait lire la bibliothèque, les radios et les podcasts (lecteur « Default Media Receiver » de Google, informations du morceau affichées sur les écrans Nest Hub et les téléviseurs, fin du titre signalée pour enchaîner la file d'attente) ; les Chromecast et téléviseurs lisent aussi les films (MKV et HEVC convertis à la volée). L'action play_url fait lire une adresse (son, flux) par l'enceinte ; l'adresse doit être joignable par l'enceinte. Les appareils annoncés sur le réseau sont ajoutés automatiquement (option). Non pris en charge : Assistant Google, lancement d'applications tierces, réglages des appareils, Spotify sur Cast autrement que par Spotify Connect.

Les autres appareils de Google Home se partagent avec My Habita par Matter (« Partager avec une autre application » dans Google Home), et les thermostats Nest par l'intégration Google Nest.

Sonos

Enceintes, barres de son, Amp et Port Sonos (S1 ou S2) pilotés en local par leurs services UPnP (port 1400), sans compte Sonos. Une seule adresse suffit : la topologie lue sur une enceinte donne toutes les autres (y compris sur un autre VLAN, où la recherche SSDP ne passe pas). Une entité lecteur par enceinte visible : caissons, enceintes arrière et seconde enceinte d'une paire stéréo sont rattachés à l'enceinte principale. Pris en charge : état, titre, artiste, pochette, durée et position du groupe ; volume et sourdine de chaque enceinte ; lecture/pause/suivant/précédent (sur l'enceinte qui pilote le groupe), aléatoire, répétition ; entrées TV (barres de son, Amp) et ligne (Five, Port, Connect, Amp…) ; groupes (aussi créés tout seuls par une zone My Habita) ; favoris et playlists Sonos ; lecture de la musique et des radios de My Habita, avec la fin de lecture signalée ; graves, aigus, loudness et, sur les barres de son, son nocturne et amélioration des dialogues.

Limites : l'état est relevé toutes les 2 à 6 s (pas d'événements UPnP) ; lire sur une enceinte d'un groupe lit sur tout le groupe ; les services de musique (Spotify, Deezer…) se pilotent depuis leur application, seuls leurs favoris Sonos se lancent ; pas de réveils ni de réglages système ; pas de vidéo. Non validée sur du matériel réel (testée contre des enceintes simulées).

DLNA / UPnP (téléviseurs, amplis, Kodi)

Lecteurs « MediaRenderer » du réseau : téléviseurs (option DLNA ou « contrôle par le réseau » à activer), amplis audio-vidéo, Kodi, lecteurs réseau. Ajout par la recherche (adresse de la description) ou par adresse IP ; l'ajout automatique est désactivé par défaut (ordinateurs et téléphones s'annoncent aussi comme lecteurs). Les enceintes Sonos sont laissées à l'intégration Sonos. Pris en charge : état, titre, pochette, durée et position ; volume et sourdine si le lecteur les propose ; lecture/pause/arrêt (suivant et précédent seulement si le lecteur les offre) ; lecture de la musique, des radios et des vidéos de My Habita — le lecteur va chercher le fichier lui-même, et My Habita convertit ce qu'il ne sait pas lire d'après les formats qu'il annonce ; déplacement ; fin de lecture signalée.

Limites : relève toutes les 2 à 6 s ; un téléviseur en veille ne répond pas (il apparaît injoignable et ne peut pas être allumé par DLNA) ; pas de navigation dans les contenus du lecteur, pas de télécommande, pas de lecture enchaînée sans blanc ; chaque fabricant interprète la norme à sa façon. Non validée sur du matériel réel.

Android TV / Google TV

Télécommande des téléviseurs et boîtiers Android TV et Google TV (Chromecast avec Google TV, Google TV Streamer, Sony, Philips, TCL, Hisense, NVIDIA Shield, Freebox Pop/Ultra…), en local, sans compte Google, par le protocole de l'application Google TV (Android TV Remote v2). Maturité bêta, non validée sur un vrai téléviseur.

Prérequis : téléviseur sur le même réseau que le serveur (mDNS non filtré pour la recherche automatique), service « Android TV Remote Service » présent (d'origine), veille réseau active pour pouvoir le rallumer.

Association (une fois par téléviseur) : ajoutez l'intégration (les téléviseurs se trouvent seuls, ou saisissez leur adresse IP) ; allumez le téléviseur, ouvrez Multimédia → Télévision, « Associer » : un code de 6 caractères s'affiche à l'écran ; saisissez-le dans My Habita (un code mal recopié est signalé sans annuler l'association). Après une réinitialisation du téléviseur, My Habita le signale (« Téléviseur à associer ») : recommencez.

Fonctions : toutes les touches de la télécommande, lancement d'applications (Netflix, YouTube, Prime Video…) ou de liens, allumage et mise en veille, volume et sourdine, saisie de texte, application à l'écran.

Limites : pas d'état de lecture, de titre ni de pochette (l'état vaut « Éteint » ou « Inactif ») ; le volume est réglé par appuis successifs sur Volume + / − et reste impossible si le son passe par un amplificateur (HDMI-CEC) ; pas de liste des applications installées (applications courantes et déjà vues) ; un téléviseur complètement éteint ne peut pas être rallumé. En cas d'erreur répétée : Paramètres › Applications › Applications système › Android TV Remote Service › Stockage › Effacer les données, puis réassociez.

Téléviseurs LG webOS — bêta, non validé sur un téléviseur

• Prérequis : téléviseur LG webOS (2014 et suivants) sur le même réseau que le serveur. Pour l'allumage : « Allumer via le Wi-Fi » / « Mobile TV On » activé sur le téléviseur.
• Ajout : « Rechercher sur le réseau » trouve le téléviseur (SSDP), ou saisissez son adresse IP. Les ports 3001 (chiffré) puis 3000 sont essayés.
• Première association : téléviseur allumé, « Associer » (page de l'intégration ou Multimédia → Télévision), puis acceptez la demande « My Habita » sur l'écran avec la télécommande. Aucune demande n'est envoyée sans votre action.
• Fonctions : allumage (Wake-on-LAN) et extinction, volume et sourdine (relus sur le téléviseur), télécommande complète, liste et lancement des applications, application et chaîne en cours, saisie de texte, notification à l'écran (action « toast »).
• Adresse MAC : relevée toute seule à la première connexion. Sinon, saisissez-la dans « Adresses MAC (allumage) » (« 192.168.1.40 A8:23:FE:12:34:56 »).
• Limites : pas de lecture d'une adresse (passez par l'intégration DLNA du même téléviseur). L'état lecture/pause n'est connu que sur les webOS récents ; aucun titre dans Netflix ou YouTube. Le Wake-on-LAN ne traverse pas les VLAN.

Téléviseurs Samsung Tizen — bêta, non validé sur un téléviseur

• Prérequis : téléviseur Samsung Tizen (2016 et suivants) sur le même réseau. Pour l'allumage : « Allumer avec un mobile » / « Réseau en veille » activé.
• Ajout : recherche SSDP et mDNS, ou adresse IP. Le téléviseur est identifié par son API REST (port 8001), sans association.
• Première association : téléviseur allumé, « Associer », puis choisissez « Autoriser » sur l'écran. Aucune demande n'est envoyée sans votre action.
• Fonctions : allumé/éteint (relevé toutes les 10 s), allumage (Wake-on-LAN) et extinction, toutes les touches de la télécommande (volume +/−, sourdine), applications installées et lancement, saisie de texte dans un champ ouvert, application à l'écran (applications connues, approximatif).
• Limites : le volume et la sourdine ne se lisent pas par ce canal ; ajoutez aussi le téléviseur à l'intégration DLNA pour les voir. Pas d'état de lecture ni de titre. Les touches « suivant » et « précédent » n'existent pas. Le Wake-on-LAN se fait sur le même réseau uniquement.

Bluetooth et sortie audio du serveur

Enceintes et casques Bluetooth appairés au serveur, et sortie audio du serveur lui-même (prise jack, HDMI, carte son USB), comme lecteurs de la page Multimédia : musique de la bibliothèque, radios et podcasts, volume, sourdine, pause et reprise à la position, avance dans le titre.

• Prérequis : sudo myhabitactl audio-install sur le serveur (BlueZ, PipeWire, pactl, ffmpeg ; voir exploitation.md), puis redémarrage de My Habita. Pour le Bluetooth, un adaptateur (clé USB ; sur une machine virtuelle, passée à la VM) ; pour la sortie du serveur, une carte son.
• Ajout : Intégrations → Ajouter → « Bluetooth et sortie audio du serveur ». Mettez l'enceinte en mode appairage, « Rechercher des enceintes », puis appairez-la : aucun code à saisir. Elle devient « de confiance » et se reconnecte d'elle-même à l'allumage.
• Chaque appareil audio appairé devient un appareil My Habita, en ligne quand il est connecté, avec sa batterie quand il la donne ; la sortie du serveur s'appelle « Sortie audio du serveur ». Lancer une lecture sur une enceinte appairée mais déconnectée tente d'abord de la connecter. Une enceinte qui se déconnecte pendant la lecture l'arrête aussitôt.
• Sans adaptateur ni carte son (cas du serveur actuel), l'intégration l'explique et devient utilisable dès que l'un des deux apparaît.
• Plus simple sans adaptateur : l'application Android lit la bibliothèque, les radios et les podcasts sur le téléphone, et le téléphone les envoie à son enceinte Bluetooth (sortie « Ce téléphone »).
• Non pris en charge : micro et appels (HFP), boutons de l'enceinte, choix du codec, plusieurs adaptateurs, lecture synchronisée sur plusieurs enceintes. Non validée sur matériel (testée contre de faux programmes).

Google Nest (Device Access)

API officielle Smart Device Management. Étapes (une seule fois) :

1. S'inscrire à la console Device Access (frais uniques de 5 US$).
2. Dans Google Cloud, créer un projet et un ID client OAuth de type « Application Web », avec l'URI de redirection autorisée https://www.google.com. Publier l'écran de consentement « En production » (sinon l'autorisation expire au bout de 7 jours).
3. Dans la console Device Access, créer un projet avec cet ID client : on obtient l'ID du projet.
4. Dans My Habita : saisir ID du projet, ID client et code secret, puis Ouvrir la page d'autorisation, choisir les appareils, et coller l'adresse de la page Google obtenue.

Thermostats : température, humidité, consigne (chauffage, climatisation ou plage), mode, Éco, chauffe en cours, connexion ; relève toutes les 2 minutes (les quotas de Google sont bas : 5 commandes par minute et par thermostat). Caméras, sonnettes et écrans : état de connexion seulement (les événements exigent Google Cloud Pub/Sub, non pris en charge).

Netatmo

API officielle. Créez une application sur dev.netatmo.com (identifiant et secret client), puis générez un jeton avec le « Token generator » de cette page (droits read_station, read_thermostat, write_thermostat) et collez le refresh token. Netatmo renouvelle ce jeton à chaque usage : My Habita conserve toujours le plus récent (un jeton recollé dans le formulaire est détecté et repris).

Station : un appareil par module (température, humidité, CO₂, bruit, pression, vent, pluie, batterie). Énergie : une entité thermostat par pièce (température, consigne, mode Planning / Manuel / Max / Arrêt, fenêtre ouverte, demande de chauffe) et, par maison, le mode général (Planning / Absent / Hors gel). Une consigne manuelle dure 3 heures par défaut (réglable). Limite Netatmo : 500 requêtes par heure ; relève toutes les 5 minutes.

Météo (Open-Meteo)

Service gratuit sans clé, pour un usage non commercial ; données Open-Meteo.com (CC BY 4.0). Position : celle de la maison (Réglages → Maison) ou une autre saisie dans le formulaire. Relève toutes les 15 minutes. Utile pour le chauffage et les automatisations (température extérieure, pluie, vent, UV, jour/nuit).

EDF Tempo

Couleur Tempo du jour et du lendemain (publiée vers 11 h), heures pleines (6 h – 22 h), jours bleus, blancs et rouges restants. La journée Tempo va de 6 h à 6 h : entre minuit et 6 h, « aujourd'hui » reste la couleur de la veille. Source : le service communautaire gratuit api-couleur-tempo.fr (non officiel ; l'API officielle de RTE demande un compte, prévue plus tard).

Dreame (compte Dreamehome)

Dreame ne publie aucune API. Cette intégration reprend le protocole de l'application Dreamehome, tel que l'ont documenté deux projets libres sous licence MIT : l'adaptateur ioBroker.dreame (TA2k) et l'intégration dreame-vacuum pour Home Assistant (Tasshack). Elle est non officielle et peut cesser de fonctionner si Dreame modifie ses serveurs. Il faut Internet.

Compte

• Saisissez l'e-mail et le mot de passe du compte Dreamehome. Pour MOVA, choisissez la marque.
• Un compte créé avec Google ou Apple doit d'abord recevoir un mot de passe dans l'application.
• Le mot de passe est envoyé haché, comme le fait l'application. Les jetons de session sont conservés par le moteur.
• En cas de refus, My Habita ne réessaie qu'au plus toutes les 30 minutes, pour ne pas bloquer le compte. « Relire » force un nouvel essai.

État : en direct par la messagerie du cloud Dreame (MQTT chiffré), avec une relève toutes les 60 s par sécurité.

Mode de nettoyage (sélecteur « Mode ») : Aspiration, Lavage, Aspiration et lavage, Lavage après aspiration.

• Sur les robots récents comme le D30 Ultra, ce réglage est une valeur compactée (propriété 4-23), décodée et réécrite sans toucher aux autres réglages qu'elle contient.
• Sur les robots qui relèvent leurs serpillières, les codes « aspiration » et « aspiration et lavage » sont inversés. C'est déduit du modèle, et réglable dans les réglages avancés en cas d'erreur.
• Choisir un mode désactive CleanGenius et les réglages par pièce de l'application, comme le fait l'application elle-même ; sinon le robot les appliquerait à la place du mode choisi.
• Avant chaque départ, le mode choisi est renvoyé au robot.

Réglages (créés seulement si le robot les rapporte) : CleanGenius, aspiration renforcée sur tapis, évitement d'obstacles, sécurité enfants, sensibilité tapis, lavage minutieux, reconnaissance des tapis, auto-nettoyage, ajout automatique de détergent, durée de séchage, fixation automatique des serpillières, niveau de lavage, remplissage automatique.

Carte

• La carte enregistrée par le robot est téléchargée depuis le cloud, déchiffrée et décodée : pièces et leurs noms, murs, position du robot et de la base, trajet, zones interdites.
• Elle s'affiche dans le panneau de l'aspirateur, sur sa page, dans la carte de tableau de bord « Aspirateur » et, calée, sur les plans de la maison.
• La carte complète est relue après chaque nettoyage, et toutes les 3 minutes pendant un nettoyage.
• Position en direct : pendant un nettoyage, le robot pousse toutes les quelques secondes une image partielle (« P ») par la messagerie du cloud (propriétés 6-1, 6-3 ou 6-13, comme dans l'application Dreamehome). My Habita la décode (téléchargement si besoin, adresse signée réutilisée), en tire la position du robot et les nouveaux points du trajet, et les transmet aussitôt aux interfaces. Sans image depuis une minute pendant un nettoyage, il demande au robot de reprendre l'envoi. Le diagnostic indique la dernière image reçue.
• Chaque carte porte le repère propre au robot (millimètres) : calée une fois sur un plan, elle le reste quand le robot agrandit ou recadre sa carte.
• Non pris en charge : rotation de la carte, tapis et meubles.

Nettoyage par pièce : touchez les pièces sur la carte (l'ordre de passage s'affiche), choisissez 1 à 3 passages, puis « Nettoyer les pièces sélectionnées ». La puissance d'aspiration et le débit d'eau sont ceux en cours.

Autres entités : batterie, durée et surface du dernier nettoyage, code d'erreur, usure des brosses et du filtre, vidage de la station.

Diagnostic du robot (bouton sur la page de l'intégration, de 30 à 90 secondes) : relit toutes les propriétés une à une, explique le décodage du mode et tente de télécharger et décoder la carte. Le compte rendu, sans aucun jeton ni mot de passe, peut être copié pour l'envoyer.

Non vérifié sur le robot réel : décodage du mode compacté et de la carte, position en direct par les images partielles, nettoyage par pièce. Ils ont été testés avec des données de synthèse au format de référence (en-tête, trajet « tr », images chiffrées ou non).

Autres voies : Matter, en local, sans carte mais avec les pièces si le robot les annonce, et le D30 Ultra est compatible Matter ; ou Valetudo, en local avec carte, pour les modèles compatibles.

Valetudo

Valetudo remplace le cloud du fabricant sur de nombreux robots Dreame, Roborock, Viomi… L'utilisateur l'installe lui-même, ce qui demande d'« ouvrir » le robot.

My Habita utilise son API REST locale :

• état en direct (flux d'événements) ;
• commandes Démarrer / Pause / Arrêter / Retour / Localiser ;
• aspiration, débit d'eau, mode ;
• carte (pièces, murs, robot, base, trajet, zones interdites, murs virtuels) et nettoyage des pièces choisies sur la carte, avec l'ordre de passage et le nombre de passages ;
• vidage de la station, état de la base, accessoires présents et consommables.

Ajout par adresse ou recherche sur le réseau. Non pris en charge : zones dessinées, déplacement vers un point, pilotage manuel.

Panneau et carte des aspirateurs

Chaque robot aspirateur dispose d'un panneau de commande, sur sa page, dans sa fenêtre et dans la carte de tableau de bord « Aspirateur ». Il contient :

• l'état détaillé et la batterie ;
• de grands boutons Démarrer (ou Reprendre) / Pause / Arrêter / Retour à la base / Localiser ;
• le mode (aspiration, lavage, les deux), l'aspiration et le débit d'eau ;
• les consommables ;
• la carte, quand l'intégration en fournit une (Dreame, Valetudo). Les pièces se touchent pour être choisies, et la carte se zoome et se déplace. Elle se met à jour toutes les 5 s pendant un nettoyage, toutes les minutes sinon.

Avec Matter, qui ne transmet pas de carte, les pièces s'affichent en liste.

Robots aspirateurs Matter

L'intégration Matter reconnaît désormais les robots aspirateurs (Matter 1.2 et plus) : état (nettoyage, en pause, retour à la base, en charge, à la base, erreur avec sa cause), Démarrer / Pause / Arrêter / Retour à la base / Localiser selon ce que le robot accepte, mode de nettoyage, batterie. Écrit d'après la spécification, sans essai sur un robot réel ; nettoyage par pièce (Service Area) non pris en charge.

Présence sur le réseau

Repère un téléphone, un ordinateur ou tout appareil par son adresse IP (réservez-la dans la box). Sondes : connexions TCP sur quelques ports courants (une connexion refusée prouve aussi la présence), table ARP du serveur, puis ping si le système l'autorise (vérifié : autorisé pour les utilisateurs sur ce serveur). Absent seulement après 3 minutes sans réponse (les téléphones mettent leur Wi-Fi en veille). Sur le téléphone, désactivez l'adresse MAC privée / aléatoire pour le Wi-Fi de la maison. Pour les téléphones Android, l'application My Habita donne une présence plus fiable.

Application mobile

Intégration créée automatiquement à la première connexion d'un téléphone (application Android My Habita). Chaque téléphone est un appareil : ses capteurs deviennent des entités, My Habita calcule sa présence à la maison (Wi-Fi de la maison ou rayon autour de la position de la maison, avec zone tampon) et sa distance, et lui remet les notifications. Réglages de l'intégration : rayon de présence, noms des Wi-Fi de la maison. Voir application-mobile.md.

Validé par logiciel (tests d'intégration, rendus de l'application) ; pas encore essayé sur un vrai téléphone.

Simulateur

Il sert à découvrir My Habita et à tester les automatisations sans matériel. Il fournit 9 appareils (lumières, prise avec mesure, détecteur de mouvement, thermomètre, fenêtre, porte, tête thermostatique, volet), tous signalés « Simulé ».

On peut y injecter des pannes : échecs de transmission, absences de réponse, latence, appareils rendus indisponibles. Supprimez l'intégration (avec ses appareils) quand vous n'en avez plus besoin.

Écrire une nouvelle intégration

Le contrat est défini dans packages/server/src/integrations/types.ts (API d'intégration v1) ; voir hue/ pour un exemple complet d'intégration réseau (association, flux d'événements, certificat épinglé) et simulator.ts pour le plus simple. Une intégration :

• déclare ses appareils (référence externe stable : numéro de série, adresse MAC, identifiant cloud — jamais une adresse IP) et leurs entités avec leurs capacités ;
• rapporte les valeurs reçues ;
• transmet les commandes sans les confirmer elle-même (c'est le rapport de l'équipement qui confirme) ;
• explique son état par setStatus(état, message, piste de résolution).

Pour apparaître dans le catalogue, elle déclare aussi sa famille (category), connection (local ou cloud), sa maturité (stable, beta, unofficial), des mots-clés (brands) et ses champs de formulaire (fields) : l'interface construit le formulaire d'ajout et la carte « Réglages » toute seule. Les champs secret (mots de passe, jetons) ne sont jamais renvoyés au navigateur ; les clés obtenues par association (bouton d'un pont, jetons OAuth) se rangent dans ctx.storage, jamais dans la configuration. discover (avec mdnsTypes) permet la recherche sur le réseau.

Outils communs dans integrations/net/ : http.ts (JSON, délais, Basic et Digest, certificats épinglés, flux SSE), mdns.ts (recherche DNS-SD), poller.ts (relève périodique sans chevauchement, espacement après échec). Banc d'essai : tests/unit/integrations/harness.ts (contexte en mémoire, faux broker MQTT, faux serveur HTTP).

Enregistrez-la ensuite dans packages/server/src/integrations/catalog.ts.