hue control
1.0.0
El sistema de iluminación Philips Hue le permite controlar la iluminación en su hogar desde una aplicación móvil, o desde cualquier aplicación que escriba que pueda conectarse a Internet. El centro del sistema es el puente Hue, un dispositivo conectado a Ethernet que se comunica con lámparas compatibles a través del protocolo de radio Zigbee HA. Philips hace una gama de lámparas compatibles con el tono, y muchas lámparas de terceros funcionan con el mismo protocolo. IconNectthue mantiene una lista exhaustiva de lámparas compatibles con Hue. Principalmente centrado en el mercado del euro, pero aún muy útil.
Cada puente de tono es su propio servidor web HTTP y se puede controlar utilizando la API REST de HUE. Hay bibliotecas para controlar el tono disponible en muchos lenguajes de programación. Los tutoriales aquí están todos en JavaScript del lado del cliente utilizando P5.JS, JavaScript simple o del lado del servidor usando Node.js o MicrController basado en Arduino.
El Hue API V2 se lanzó recientemente, y eventualmente reemplazará a V1. Estas notas se refieren actualmente a V1 (19 de enero de 2021) y aún funcionan. HUE API V2 presenta HTTPS, así como algunos cambios de ruptura de V1.
Para comenzar a programar aplicaciones de Hue, necesitará acceso a un puente Hue. También querrás una cuenta de tono. Las cuentas de desarrolladores son gratuitas. Mantenga a mano el enlace del sitio de los desarrolladores de Hue.
La aplicación Hue para Android o iOS es útil cuando se desarrolla, porque funciona cuando su proyecto aún no. La aplicación Hue Essentials también es una alternativa bastante útil.
Cada tono tiene una interfaz de depuración, disponible en http://$ADDR/debug/clip.html Reemplace $ADDR con la dirección IP de su puente. Cuando se está desarrollando, puede usar esto para enviar comandos API al puente para probar las cosas.
La biblioteca Node-Hue-API de Peter Murray para Node.js es la mejor de las diversas bibliotecas JavaScript de nodo.js que he probado para controlar el tono.
Para controlar el tono de un cliente de navegador, P5.JS hace un buen trabajo, ya que tiene una API de solicitud HTTP simple. También puede usar JavaScript simple, por supuesto.
La biblioteca ArduinohttpClient y la biblioteca Arduino_Json son útiles si está utilizando cualquiera de las tablas habilitadas para WiFi de Arduino para conectarse a su puente Hue. (Nota: Hay otra biblioteca JSON del mismo nombre sin subrayamiento. Ese no es el que se usa aquí).
La herramienta de línea de comando Curl es útil para probar las solicitudes HTTP en su puente, si está familiarizado con la línea de comando POSIX (Linux/Unix). Curl no está disponible en la interfaz de comando de Windows, pero puede obtenerlo a través del subsistema de Windows para Linux en Windows 10, o a través de Cygwin, una aplicación que proporciona un shell de Linux para Windows. Aquí hay algunos detalles sobre el uso de Curl para acceder a un puente de tono.
Aparte de estos, necesitará conocer algunos HTML y JavaScript, y un editor de texto, una interfaz de línea de comandos y un navegador para probar los ejemplos en este sitio. Los ejemplos de línea de comando que se muestran aquí son todos para Linux o UNIX, pero funcionarán en Windows 10 usando el subsistema de Windows para Linux en Windows 10.
Su aplicación deberá identificarse en su puente utilizando un nombre de usuario único. Esta página de ejemplo simplificará eso, si conoce la dirección IP de su puente. No puede ejecutar esta página desde un servidor remoto; Descárguelo y abra el archivo index.html en un navegador desde su sistema de archivos. Esto se debe a que el HUE API versión 1 usa HTTP, no HTTPS.
También puede seguir las instrucciones de inicio del sitio de Hue Developer.
Cuando lo haces bien, debes obtener una respuesta como esta:
[
{
"success": {
"username": "newusername"
}
}
]
Ahora estás listo para escribir código para tu puente. Independientemente del entorno que esté programando, usará el nombre de usuario que estableció aquí.
La interfaz de clip de depuración es una página que puede usar para probar funciones en su puente. Su dirección es:
http://your.bridge.ip.address/debug/clip.html
Se puede usar para enviar cualquier comando API a su puente. La cadena de consulta general es la siguiente:
/api/$HUE_USER/command
En general, la consulta del estado del dispositivo se realiza utilizando comandos GET, y cambiarlos se realiza usando PUT. Por ejemplo, para consultar el estado de todas sus luces, ingrese lo siguiente en el campo URL:
/api/$HUE_USER/lights
Y haga clic en Get. Para consultar la configuración, ingrese:
/api/$HUE_USER/config
Y haga clic en Get. Para encender la luz 1, ingrese lo siguiente en el campo URL:
/api/$HUE_USER/lights/1/state
E ingrese lo siguiente en el campo del cuerpo del mensaje:
{"on":true}
Y haga clic en Put. La luz debe encenderse y el puente debe responder:
[
{
"success": {
"/lights/1/state/on": true
}
}
]
Para obtener más información sobre la API de Hue, consulte la Guía de Getting Starting, los conceptos centrales de la API de Hue y la documentación completa de la API de Hue. Deberá crear una cuenta gratuita e iniciar sesión para usar el portal de desarrollador.
Cuando haya agregado su puente a su red, debería poder usar la aplicación Hue o la aplicación Hue Essentials para obtener la dirección IP. Pero en una red compleja como una red escolar, eso puede no funcionar. Su dispositivo móvil y su puente de Hue deben estar en la misma red local para que esto funcione. Por ejemplo, si su red WiFi no es la misma red local que su red Ethernet con cable (donde vive el puente), es posible que no pueda obtener la dirección. Pero si puede obtener la dirección MAC del puente, puede buscarla en su red. Aquí está como
Cada puente tiene un único que puede encontrar la dirección MAC en la parte inferior de su puente. Es un número de seis bytes en notación hexadecimal como así:
00:17:88:0B:14:48
Algunos puentes solo mostrarán los últimos tres bytes. Por ejemplo, el puente de arriba podría mostrar solo 0b1448. Con los puentes de tono más antiguos, los primeros tres bytes siempre serán 00:17:88 . Con los más nuevos, también puede ver EC:B5:FA .
Para buscar su puente en su red, asegúrese de tener los primeros tres dígitos de la red local y que pueda acceder a él, luego abrir una interfaz de línea de comando y escribir:
$ ping -c 5 xxx.xxx.xxx.255
Donde xxx.xxx.xxx son los primeros tres números de su red. Por ejemplo, en una red cuyo enrutador es 172.16.130.1, ingresaría 172.16.130.255. A veces, las grandes instituciones utilizarán dos subredes diferentes para redes cableadas versus inalámbricas, pero aún así estarán en la misma red local más grande.
Obtendrá una lista de respuestas, a medida que los dispositivos en la red respondan a sus solicitudes de ping. Cuando esté listo, escriba:
$ arp -a
Obtendrá una lista de todos los dispositivos en la misma red que su computadora puede ver. Busque la que coincida con la dirección MAC de su puente, y la dirección IP al lado será la dirección IP de su puente. Los últimos tres bytes de su dirección MAC de la etiqueta en la parte inferior. Los primeros tres probablemente sean 00:17:88 o EC: B5: FA, como se explicó anteriormente. Aquí hay un ejemplo típico:
$ 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]
En este caso, la dirección IP del tono es 192.168.0.3.
Puede buscar nuevas lámparas en el puente utilizando la aplicación móvil móvil regular. También puede hacerlo desde la interfaz de clip de depuración utilizando una solicitud de publicación en la siguiente URL:
/api/$HUE_USER/lights/
Complete la dirección de su puente para $ AdDR y su nombre de usuario Hue para $ HUE_USER. Deberías obtener una respuesta como esta:
[[ { "success": { "/lights": "Searching for new devices" } }]
Después de 90 segundos, puede escanear nuevas lámparas que se agregaron así:
/api/$HUE_USER/lights/new
En curl:
$ curl -X GET http://$ADDR/api/$HUE_USER/lights/new
Esto enumerará solo las nuevas lámparas agregadas después de un escaneo de nuevas lámparas.
Si está tratando de agregar una lámpara que estaba conectada previamente a un puente diferente, necesitará usar un enfoque diferente. Coloque la lámpara cerca del puente con el que desea controlarla (más cerca que cualquier otra lámpara, idealmente menos de 1 metro). Apague todas las otras lámparas conectadas al puente, o asegúrese de que estén mucho más lejos que las que desee.
Envíe la siguiente interfaz de clip de depuración utilizando una solicitud PUT:
/api/$HUE_USER/config/
En el cuerpo de su solicitud, colocada:
{"touchlink": true}
En curl eso es:
$ curl -X PUT -d '{"touchlink": true}' http://$ADDR/api/$HUE_USER/config
La lámpara debe parpadear varias veces, y el servidor responderá con un mensaje de éxito. Ahora puede agregar la lámpara utilizando la solicitud de búsqueda de lámparas nuevas descrita anteriormente.
Si Touchlink no tiene éxito en restablecer una lámpara, es posible que deba restablecerla manualmente. Es diferente para cada fabricante, pero el patrón general es encender y apagar la lámpara de tres a cinco veces, después de lo cual parpadeará o se atenuará ligeramente para indicar que se ha restablecido. Por ejemplo, con las bombillas de enlace GE, el patrón es:
Para algunas bombillas de terceros, como el Cree Connect o las bombillas INNR, puede hacerlo con intervalos de 2 segundos. Sin embargo, en caso de duda, vaya con tres segundos.
Si tiene uno de los controles remotos de Hue, también puede restablecer una lámpara que la use. Para hacer esto, encienda la lámpara y coloque el control remoto dentro de las seis pulgadas de la lámpara. Presione los botones de encendido y apagado (o encendido y los botones de selección de escena en modelos más recientes) similtáneamente y manténgalos hasta que la bombilla parpadee. Esto pondrá la lámpara en su estado de fábrica predeterminado, lista para emparejar con un nuevo puente.
Puede eliminar una lámpara de un puente de la interfaz de clip de depuración utilizando una solicitud de eliminación en la siguiente URL:
/api/$HUE_USER/lights/1
En curl:
$ curl -X DELETE http://$ADDR/api/$HUE_USER/lights/1
Reemplace 1 con el número de la luz que desea eliminar.
Para obtener el estado de todas las luces conectadas, envíe lo siguiente desde la interfaz de clip de depuración utilizando una solicitud GET:
/api/$HUE_USER/lights/
En curl, eso es:
$ curl http://$ADDR/api/$HUE_USER/lights/
Esto debería devolver la lista de luces disponibles, así:
{"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"}}
Para encender una luz, necesitas saber qué número es. Entonces cambias su estado así:
Envíe lo siguiente desde la interfaz de clip de depuración utilizando una solicitud PUT:
/api/$HUE_USER/lights/4/state
En el cuerpo de su solicitud, colocada:
{"on": true}
En curl, eso es:
$ curl -X PUT -d '{"on":true}' http://$ADDR/api/$HUE_USER/lights/4/state
Para apagarlo, cambie el cuerpo de la solicitud a
{"on": false}
Puede cambiar cualquiera de las propiedades del estado de una luz de esta manera. Eche un vistazo, por ejemplo, a la luz 1 desde la sección de estado de todas las luces anteriores:
{"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},
Mientras la propiedad reachable sea verdadera, lo que significa que el puente intentó alcanzar la lámpara y obtuvo una respuesta, puede cambiar cualquiera de las otras propiedades. Esta es una lámpara de color, y tiene tres modos, HS (para Hue, Saturación), CT (para temperatura del color) y XY (para dimensiones X e Y en el espacio de color CIE1931). Si cambia el tono o la saturación, el colormodo de la lámpara cambia a HS, y si cambia la temperatura de color, el colormodo cambia a CT. Si envía valores XY, el ColorMode cambia al modo XY.
Las diferentes luces tendrán diferentes propiedades en su variable de estado que puede cambiar. El boceto P5.JS escaneará todas las propiedades de cada lámpara en el
Los modelos MKR1000, MKR1010 y Nano 33 IoT Arduino también pueden controlar el puente HUE a través de solicitudes HTTP. Hay algunos ejemplos de Hue Arduino, con notas, en este repositorio también.
