homebridge hue
v0.14.7
Copyright © 2016-2024 Erik Baauw. Tous droits réservés.
Ce plugin Homebridge expose les appareils compatibles HomeKit Hue d'Apple (lumières, prises, capteurs, interrupteurs, ...) connectés à un pont Hue par Signify.
Notez que Hue a été initialement développé par Philips, avant de scinder leur division Éclairage en Signify. Signify utilise toujours la marque Philips Hue.
Consultez le wiki pour obtenir une liste des fonctionnalités de Homebridge Hue et des appareils pris en charge, y compris une comparaison des fonctionnalités de :
Homebridge Hue effectue la découverte automatique des ponts de Hue. Il prend en charge plusieurs ponts à partir d'une seule installation. Il prend en charge les ponts Hue v2 (carré) et v1 (rond). Il fonctionne en combinaison avec la fonctionnalité native HomeKit du pont v2 Hue.
Veuillez consulter le Wiki pour une description détaillée de Homebridge Hue.
Vous avez besoin d'un pont Philips Hue pour connecter Homebridge Hue à vos lumières, interrupteurs et capteurs compatibles Hue. Je recommande d'utiliser le dernier firmware du pont Hue, avec l'API v1.61.0 (pont v2) ou v1.16.0 (pont v1) ou supérieur.
Vous avez besoin d'un serveur pour exécuter Homebridge. Il peut s'agir de n'importe quel objet exécutant Node.js : depuis un Raspberry Pi, un système NAS ou un PC toujours allumé exécutant Linux, macOS ou Windows. Consultez le wiki Homebridge pour plus de détails. Je recommande d'utiliser Ethernet filaire pour connecter le serveur exécutant Homebridge, le pont Hue et l'AppleTV faisant office de hub domestique.
Pour interagir avec HomeKit, vous avez besoin de Siri ou d'une application HomeKit sur un iPhone, Apple Watch, iPad, iPod Touch ou Apple TV (4e génération ou version ultérieure). Je recommande d'utiliser les dernières versions d'iOS, watchOS et tvOS.
Veuillez noter que Siri et même l'application Home d'Apple ne fournissent toujours qu'une prise en charge limitée de HomeKit. Pour utiliser toutes les fonctionnalités de Homebridge Hue, vous souhaiterez peut-être consulter d'autres applications HomeKit, comme l'application Eve (gratuite) ou l'application Home+ de Matthias Hochgatterer (payante).
Comme HomeKit utilise le DNS multicast (alias Bonjour) pour découvrir Homebridge, le serveur exécutant Homebridge doit être sur le même sous-réseau que vos iDevices exécutant HomeKit. Pour l'accès à distance et pour les automatisations HomeKit (y compris la prise en charge des commutateurs sans fil), vous devez configurer une Apple TV (4e génération ou ultérieure) ou un HomePod comme hub domestique.
Homebridge Hue inclut l'utilitaire de ligne de commande ph pour interagir avec l'API Hue à partir de la ligne de commande. Consultez le didacticiel sur le Wiki pour une introduction à cet utilitaire.
Émettez ph -h ou ph --help pour fournir un bref aperçu de ses fonctionnalités et de ses arguments de ligne de commande.
Pour installer Homebridge Hue :
Suivez les instructions sur le wiki Homebridge pour installer Node.js et Homebridge ;
Installez le plugin Homebridge Hue via Homebridge Config UI X ou manuellement en :
$ sudo npm -g i homebridge-hue
Modifiez config.json et ajoutez la plateforme Hue fournie par Homebridge Hue, voir Configuration ;
Exécutez Homebridge Hue pour la première fois, appuyez sur le bouton de lien sur (chacun de) vos ponts. Notez la paire de clés ID de pont/API pour chaque pont dans la sortie du journal. Modifiez config.json pour les inclure, voir Configuration .
Notez que vous ne pouvez pas les ajouter via les paramètres Homebridge Hue dans Homebridge Config UI X, mais vous pouvez utiliser l' éditeur de configuration Homebridge .
Pour mettre à jour Homebridge Hue, émettez simplement un autre sudo npm -gi homebridge-hue@latest . Veuillez consulter les notes de version avant de mettre à jour Homebridge Hue. Notez qu'une modification apportée à la version mineure indique généralement que vous devez revoir/refaire votre configuration HomeKit. En raison de changements dans la cartographie de la manière dont les ressources du pont Hue sont exposées, HomeKit peut les traiter comme de nouveaux accessoires, services et/ou caractéristiques, perdant ainsi toute affectation aux pièces, scènes, actions et déclencheurs HomeKit. Pour revenir à une version précédente, spécifiez la version lors de l'installation de Homebridge Hue, comme dans : sudo npm -gi [email protected] .
Dans config.json de Homebridge, vous devez spécifier Homebridge Hue comme plugin de plateforme. De plus, vous devez spécifier ce que vous souhaitez exposer à HomeKit. Consultez le Wiki pour une référence complète des paramètres config.json utilisés par Homebridge Hue et pour quelques exemples.
Pour un contrôle plus précis des ressources que Homebridge Hue expose à HomeKit et comment créer des liens de ressources sur le pont, consultez le Wiki.
Veuillez consulter la FAQ.
Si vous rencontrez des problèmes de démarrage de Homebridge, veuillez vérifier quelles versions de Node.js et de Homebridge ont été installées. Homebridge Hue a été développé et testé à l'aide de la dernière version LTS de Node.js et de la dernière version de Homebridge. D'autres versions peuvent fonctionner ou non - je n'ai tout simplement pas la bande passante pour les tester.
Si vous rencontrez des problèmes de démarrage de Homebridge, veuillez exécuter une instance distincte de Homebridge avec uniquement Homebridge Hue (et Homebridge Config UI X) activé dans config.json . De cette façon, vous pouvez déterminer si le problème est lié à Homebridge Hue lui-même ou à l'interaction de plusieurs plugins Homebridge dans votre configuration. Vous pouvez démarrer cette instance distincte de Homebridge sur un système différent, en tant qu'utilisateur différent ou à partir d'un répertoire utilisateur différent (spécifié par l'indicateur -U ). Assurez-vous d'utiliser un name Homebridge, username et (s'il est exécuté sur le même système) port différent dans le config.json pour chaque instance.
Homebridge Hue génère un message d'information pour chaque valeur de caractéristique HomeKit qu'il définit et pour chaque notification de changement de valeur de caractéristique HomeKit qu'il reçoit. Lorsque Homebridge est démarré avec -D , Homebridge Hue génère un message de débogage pour chaque requête qu'il adresse au pont, pour chaque changement d'état qu'il détecte lors de l'interrogation du pont et pour chaque notification push qu'il reçoit du flux d'événements du pont Gen-2 Hue. De plus, il émet un message de débogage pour chaque ressource de pont détectée.
Pour capturer ces messages dans un fichier journal, procédez comme suit :
$ homebridge -CD 2>&1 | tee homebridge.log
$ gzip homebridge.log
Pour faciliter le dépannage, au démarrage, Homebridge Hue sauvegarde son environnement, y compris ses paramètres config.json et l'état complet de tous les ponts, dans un fichier json compressé, homebridge-hue.json.gz . Les adresses IP et les clés API du pont sont masquées. Ce fichier est créé dans le répertoire utilisateur Homebridge, ~/.homebridge par défaut. Il peut être téléchargé via l'interface utilisateur Homebridge Config UI X, à partir de la fenêtre contextuelle Homebridge Hue SETTINGS , dans l'onglet Plugins .
Si vous avez une question, veuillez poster un message sur la chaîne #hue de la communauté Homebridge sur Discord.
Si vous rencontrez un problème, veuillez ouvrir un ticket sur GitHub. Veuillez joindre une copie de homebridge-hue.json.gz au problème, voir Debug Dump File . Veuillez joindre une copie de homebridge.log.gz au problème, voir Fichier journal de débogage . Veuillez ne pas copier/coller de grandes quantités de résultats de journaux.
Parfois, on me demande comment les gens peuvent soutenir mon travail sur Homebridge Hue. J'ai créé Homebridge Hue comme projet de loisir, pour mon propre usage. Je le partage sur GitHub pour que d'autres puissent en bénéficier et pour redonner à la communauté open source, sans qui Homebridge Hue n'aurait pas été possible.
Cela dit, ajouter la prise en charge de nouveaux appareils, dans Homebridge Hue, est très difficile sans avoir un accès physique à l'appareil. Puisqu'il s'agit d'un projet de loisir, je ne peux pas me permettre de dépenser de l'argent pour des appareils que je n'utiliserai pas moi-même, juste pour les intégrer au bénéfice des autres. Je suis heureux de recevoir de petits dons sous forme de nouveaux appareils à intégrer, ou de l'argent pour acheter moi-même ces appareils. Je me ferai également un plaisir de renvoyer les appareils par la suite, si vous fournissez les frais d'expédition. Veuillez me contacter par email ou sur Discord pour les détails d'expédition.
Homebridge Hue est un de mes projets de loisirs, fourni tel quel, sans aucune garantie. Je l'utilise avec succès chez moi depuis des années, mais votre kilométrage peut varier.
La terminologie HomeKit nécessite une certaine habitude. Un accessoire correspond plus ou moins à un appareil physique, accessible depuis votre appareil iOS en WiFi ou Bluetooth. Un pont (comme Homebridge) est un accessoire qui permet d'accéder à d'autres accessoires pontés. Un accessoire peut fournir plusieurs services . Chaque service correspond à un appareil virtuel (comme une ampoule, un interrupteur, un détecteur de mouvement, ..., mais aussi : un bouton interrupteur programmable, des informations sur les accessoires, l'état de la batterie). Siri interagit avec les services, pas avec les accessoires. Un service contient une ou plusieurs caractéristiques . Une caractéristique est comme un attribut de service, qui peut être lu ou écrit par les applications HomeKit. Vous souhaiterez peut-être consulter le simulateur d'accessoires HomeKit d'Apple, qui est distribué en tant qu'outil supplémentaire pour Xcode .
En interne, HomeKit identifie les accessoires par UUID. Pour les appareils Zigbee (lumières, capteurs, interrupteurs), Homebridge Hue base cet UUID sur l'adresse MAC Zigbee. Pour les ressources non Zigbee (groupes, horaires, capteurs CLIP), l'UUID est basé sur l'ID du pont et le chemin de la ressource (par exemple /sensors/1 ). En n'utilisant pas le nom de la ressource (par exemple Daylight ), Homebridge Hue peut gérer les noms en double. De plus, HomeKit reconnaîtra toujours l'accessoire après le changement du nom de la ressource sur le pont, en se souvenant de la pièce HomeKit, des groupes, des scènes, des actions et des déclencheurs auxquels il appartient. Cependant, lorsqu'une ressource de pont non Zigbee est supprimée puis recréée, ce qui entraîne un chemin de ressource différent, HomeKit la traitera comme un nouvel accessoire et vous devrez reconfigurer HomeKit.
