hue control
1.0.0
Le système d'éclairage Hue Philips vous permet de contrôler l'éclairage dans votre maison à partir d'une application mobile ou à partir de toute application que vous vous écrivez qui peut vous connecter à Internet. Le centre du système est le pont Hue, un appareil connecté à Ethernet qui communique avec des lampes compatibles à travers le protocole radio Zigbee HA. Philips fabrique une gamme de lampes compatibles sur les teintes et de nombreuses lampes tierces fonctionnent avec le même protocole. Iconnecthue maintient une liste approfondie de lampes compatibles sur les teintes. Surtout centré sur le marché de l'euro, mais toujours très utile.
Chaque pont Hue est son propre serveur Web HTTP et peut être contrôlé à l'aide de l'API Hue REST. Il existe des bibliothèques pour contrôler la teinte disponible dans de nombreux langages de programmation. Les tutoriels ici sont tous en JavaScript côté client à l'aide de P5.js, JavaScript simple ou côté serveur à l'aide de Node.js ou basés sur des micro-verseurs pour Arduino.
L'API V2 Hue a été récemment publiée et finira par remplacer V1. Ces notes se réfèrent actuellement à la V1 (19 janvier 2021) et fonctionnent toujours. Hue API V2 dispose de HTTPS, ainsi que des changements de rupture de V1.
Pour commencer la programmation des applications Hue, vous aurez besoin d'accéder à un pont de teinte. Vous aurez aussi un compte Hue. Les comptes des développeurs sont gratuits. Gardez la liaison du site Hue Developers Handy.
L'application Hue pour Android ou iOS est utile lors du développement, car elle fonctionne lorsque votre projet ne le fait pas. L'application Hue Essentials est également une alternative assez utile.
Chaque Hue a une interface de débogage, disponible sur http://$ADDR/debug/clip.html Remplacez $ADDR par l'adresse IP de votre pont. Lorsque vous développez, vous pouvez l'utiliser pour envoyer des commandes API au pont pour tester les choses.
La bibliothèque Node-Hue-API de Peter Murray pour Node.js est la meilleure des différentes bibliothèques JavaScript Node.js que j'ai testées pour contrôler la teinte.
Pour contrôler la teinte d'un client de navigateur, P5.js fait du bon travail, car il a une simple API de demande HTTP. Vous pouvez également utiliser JavaScript simple, bien sûr.
La bibliothèque ArduinoHttpClient et la bibliothèque Arduino_Json sont utiles si vous utilisez l'une des cartes compatibles avec Arduino pour vous connecter à votre pont de teinte. (Remarque: il y a une autre bibliothèque JSON par le même nom sans soulignement. Celui n'est pas celui utilisé ici).
La ligne de la ligne de commande Curl est utile pour tester les demandes HTTP à votre pont, si vous connaissez la ligne de commande POSIX (Linux / Unix). Curl n'est pas disponible dans l'interface de commande Windows, mais vous pouvez l'obtenir via le sous-système Windows pour Linux dans Windows 10, ou via Cygwin, une application qui fournit un shell Linux pour Windows. Voici quelques détails sur l'utilisation de Curl pour accéder à un pont Hue.
En dehors de ceux-ci, vous devrez connaître des HTML et JavaScript, et un éditeur de texte, une interface de ligne de commande et un navigateur pour essayer les exemples sur ce site. Les exemples de ligne de commande illustrés ici sont tous pour Linux ou Unix, mais fonctionneront sur Windows 10 à l'aide du sous-système Windows pour Linux dans Windows 10.
Votre application devra être identifiée à votre pont à l'aide d'un nom d'utilisateur unique. Cet exemple de page simplifiera cela, si vous connaissez l'adresse IP de votre pont. Vous ne pouvez pas exécuter cette page à partir d'un serveur distant; Téléchargez-le et ouvrez le fichier index.html dans un navigateur à partir de votre système de fichiers. En effet, la version 1 de l'API Hue utilise HTTP, pas HTTPS.
Vous pouvez également suivre les instructions de démarrage du site de développeur Hue.
Lorsque vous le faites correctement, vous devriez obtenir une réponse comme ceci:
[
{
"success": {
"username": "newusername"
}
}
]
Vous êtes maintenant prêt à écrire du code pour votre pont. Quel que soit l'environnement dans lequel vous programmer, vous utiliserez le nom d'utilisateur que vous avez établi ici.
L'interface Clip Debug est une page que vous pouvez utiliser pour tester les fonctions sur votre pont. Son adresse est:
http://your.bridge.ip.address/debug/clip.html
Il peut être utilisé pour envoyer n'importe quelle commande API à votre pont. La chaîne de requête générale est la suivante:
/api/$HUE_USER/command
Généralement, l'interrogation de l'état de l'appareil se fait à l'aide de commandes GET, et les modifier se fait à l'aide de put. Par exemple, pour interroger l'état de toutes vos lumières, entrez ce qui suit dans le champ URL:
/api/$HUE_USER/lights
Et cliquez sur obtenir. Pour interroger la configuration, entrez:
/api/$HUE_USER/config
Et cliquez sur obtenir. Pour allumer la lumière 1, entrez ce qui suit dans le champ URL:
/api/$HUE_USER/lights/1/state
Et entrez ce qui suit dans le champ Body Message:
{"on":true}
Et cliquez sur Put. La lumière doit s'allumer et le pont doit répondre:
[
{
"success": {
"/lights/1/state/on": true
}
}
]
Pour en savoir plus sur l'API Hue, consultez le Guide de démarrage de Hue, les concepts de base de l'API Hue et la documentation complète de l'API Hue. Vous devrez créer un compte gratuit et vous connecter pour utiliser le portail du développeur.
Lorsque vous avez ajouté votre pont à votre réseau, vous devriez pouvoir utiliser l'application Hue ou l'application Hue Essentials pour obtenir l'adresse IP. Mais sur un réseau complexe comme un réseau scolaire, cela peut ne pas fonctionner. Votre appareil mobile et votre pont Hue doivent être sur le même réseau local pour que cela fonctionne. Par exemple, si votre réseau WiFi n'est pas le même filet local que votre réseau Ethernet filaire (où vit le pont), vous ne pourrez peut-être pas obtenir l'adresse. Mais si vous pouvez obtenir l'adresse MAC du pont, vous pouvez la rechercher sur votre réseau. Voici comment
Chaque pont a un unique, vous pouvez trouver l'adresse MAC au bas de votre pont. C'est un numéro de six octets en notation hexadécimale comme ça:
00:17:88:0B:14:48
Certains ponts ne montreront que les trois derniers octets. Par exemple, le pont ci-dessus peut afficher seulement 0B1448. Avec des ponts de teinte plus anciens, les trois premiers octets seront toujours 00:17:88 . Avec les plus récents, vous pouvez également voir EC:B5:FA à la place.
Pour rechercher votre pont sur votre réseau, assurez-vous d'avoir les trois premiers chiffres du réseau local et que vous pouvez y accéder, puis ouvrez une interface de ligne de commande et tapez:
$ ping -c 5 xxx.xxx.xxx.255
Où xxx.xxx.xxx sont les trois premiers nombres de votre réseau. Par exemple, sur un réseau dont le routeur est 172.16.130.1, vous entreriez 172.16.130.255. Parfois, les grandes institutions utiliseront deux sous-réseaux différents pour les réseaux câblés vs sans fil, mais ils seront toujours sur le même réseau local plus grand.
Vous obtiendrez une liste de réponses, car les appareils du réseau répondent à vos demandes de ping. Quand c'est fait, tapez:
$ arp -a
Vous obtiendrez une liste de tous les appareils du même réseau que votre ordinateur peut voir. Recherchez celui qui correspond à l'adresse MAC de votre pont, et l'adresse IP à côté sera l'adresse IP de votre pont. Les trois derniers octets de votre adresse MAC à partir de l'étiquette en bas. Les trois premiers seront probablement soit 00:17:88 ou EC: B5: FA, comme expliqué ci-dessus. Voici un exemple typique:
$ arp -a
? (192.168.0.1) at ac:b7:16:61:e3:77 on en0 ifscope [ethernet]
? (192.168.0.3) at 00:17:88:0B:14:48 on en0 ifscope [ethernet]
? (192.168.0.255) at ff:ff:ff:ff:ff:ff on en0 ifscope [ethernet]
Dans ce cas, l'adresse IP de Hue est 192.168.0.3.
Vous pouvez rechercher de nouvelles lampes sur le pont à l'aide de l'application Hue mobile ordinaire. Vous pouvez également le faire à partir de l'interface Clip Debug à l'aide d'une demande de publication sur l'URL suivante:
/api/$HUE_USER/lights/
Remplissez l'adresse de votre pont pour $ addr et votre nom d'utilisateur Hue pour $ hue_user. Vous devriez obtenir une réponse comme ceci:
[[ { "success": { "/lights": "Searching for new devices" } }]
Après 90 secondes, vous pouvez rechercher de nouvelles lampes qui ont été ajoutées comme tel:
/api/$HUE_USER/lights/new
Dans Curl:
$ curl -X GET http://$ADDR/api/$HUE_USER/lights/new
Cela ne répertoriera que les nouvelles lampes ajoutées après une analyse pour les nouvelles lampes.
Si vous essayez d'ajouter une lampe qui était auparavant connectée à un autre pont, vous devrez utiliser une approche différente. Placez la lampe près du pont avec lequel vous souhaitez le contrôler (plus proche que toute autre lampe, idéalement moins de 1 mètre). Éteignez toutes les autres lampes connectées au pont ou assurez-vous qu'elles sont beaucoup plus éloignées que celles que vous voulez.
Envoyez l'interface de Clip de débogage suivant à l'aide d'une demande de put:
/api/$HUE_USER/config/
Dans le corps de votre demande, pose:
{"touchlink": true}
Dans Curl, c'est:
$ curl -X PUT -d '{"touchlink": true}' http://$ADDR/api/$HUE_USER/config
La lampe doit cligner des yeux plusieurs fois et le serveur répondra avec un message de réussite. Vous pouvez désormais ajouter la lampe à l'aide de la demande de retrait de retrait décrit ci-dessus.
Si TouchLink ne réussit pas à réinitialiser une lampe, vous devrez peut-être le réinitialiser manuellement. C'est différent pour chaque fabricant, mais le motif général est d'allumer et de désactiver la lampe trois à cinq fois, après quoi il clignote ou diminuera légèrement pour indiquer qu'il a été réinitialisé. Par exemple, avec les ampoules GE Link, le motif est:
Pour certaines ampoules tierces, comme le Cree Connect ou les bulbes InNR, vous pouvez le faire avec 2 secondes intervalles. En cas de doute, allez avec trois secondes, cependant.
Si vous avez l'une des télécommandes Hue, vous pouvez également réinitialiser une lampe en l'utilisant. Pour ce faire, allumez la lampe et placez la télécommande à moins de six pouces de la lampe. Appuyez sur les boutons de mise sous tension et d'élevage (ou de puissance sur les boutons de sélection sur les modèles plus récents) et maintenez-les jusqu'à ce que l'ampoule clignote. Cela mettra la lampe dans son état d'usine par défaut, prêt à s'associer à un nouveau pont.
Vous pouvez supprimer une lampe à partir d'un pont de l'interface Clip de débogage à l'aide d'une demande de suppression sur l'URL suivante:
/api/$HUE_USER/lights/1
Dans Curl:
$ curl -X DELETE http://$ADDR/api/$HUE_USER/lights/1
Remplacez 1 par le numéro de la lumière que vous souhaitez supprimer.
Pour obtenir l'état de toutes les lumières connectées, envoyez les éléments suivants à partir de l'interface Clip de débogage à l'aide d'une demande GET:
/api/$HUE_USER/lights/
Dans Curl, c'est:
$ curl http://$ADDR/api/$HUE_USER/lights/
Cela devrait renvoyer la liste des lumières disponibles, comme ainsi:
{"1":{"state":{"on":true,"bri":254,"hue":14314,"sat":172,"effect":"none","xy":[0.4791,0.4139],"ct":405,"alert":"none","colormode":"ct","reachable":true},"type":"Extended color light","name":"Hue color light 1","modelid":"LCT001","manufacturername":"Philips","uniqueid":"00:17:88:01:00:ff:9a:28-0b","swversion":"5.127.1.26581"}}
Pour allumer une lumière, vous devez savoir de quel numéro il s'agit. Ensuite, vous changez son état comme ça:
Envoyez ce qui suit à partir de l'interface Clip de débogage à l'aide d'une demande de put:
/api/$HUE_USER/lights/4/state
Dans le corps de votre demande, pose:
{"on": true}
Dans Curl, c'est:
$ curl -X PUT -d '{"on":true}' http://$ADDR/api/$HUE_USER/lights/4/state
Pour l'éteindre, modifiez le corps de la demande de
{"on": false}
Vous pouvez modifier l'une des propriétés de l'état d'une lumière de cette façon. Jetez un œil, par exemple, à la lumière 1 de la section d'obtention de l'état de toutes les lumières ci-dessus:
{"1":{"state":{"on":true,"bri":254,"hue":14314,"sat":172,"effect":"none","xy":[0.4791,0.4139],"ct":405,"alert":"none","colormode":"ct","reachable":true},
Tant que la propriété reachable est vraie, ce qui signifie que le pont a essayé d'atteindre la lampe et d'obtenir une réponse, vous pouvez modifier les autres propriétés. Il s'agit d'une lampe couleur et a trois modes, HS (pour la teinte, la saturation), CT (pour la température de couleur) et XY (pour les dimensions X et Y dans l'espace colorimétrique CIE1931). Si vous modifiez la teinte ou la saturation, le ColorMode de la lampe se transforme en HS, et si vous modifiez la température de la couleur, le Colormode se transforme en CT. Si vous envoyez des valeurs XY, le ColorMode passe en mode XY.
Différentes lumières auront différentes propriétés dans leur variable d'état que vous pouvez modifier. Le croquis P5.JS scannera toutes les propriétés de chaque lampe sur le
Les modèles MKR1000, MKR1010 et Nano 33 IoT Arduino peuvent également contrôler le pont Hue via les demandes HTTP. Il existe des exemples de teintes Arduino, avec des notes, dans ce référentiel également.
