Integración comunitaria Nuki, gratuita y de código abierto
Nuki Smart Lock, Opener y Smart Door: vía Bridge, MQTT o Nuki Web.
Publicado por gboulvin
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Controle sus dispositivos Nuki desde Gladys: Smart Lock (todas las generaciones, 3.0 Pro, 4.ª generación, Ultra), Smart Door y Opener — bloquear, desbloquear, abrir la puerta, vigilar las baterías, el sensor de puerta y el teclado, y reaccionar a cada operación en sus escenas.
Elegir cómo habla Gladys con sus dispositivos Nuki
La integración ofrece tres canales. Configure al menos uno; puede combinarlos.
| Canal | Tipo | Dispositivos | Qué aporta |
|---|---|---|---|
| Nuki Bridge | Local (HTTP) | Todas las Smart Lock, Smart Door y Opener | Funciona sin internet, detección del timbre del Opener |
| MQTT | Local (tiempo real) | Smart Lock 3.0 Pro, 4.ª generación, Ultra | Actualizaciones instantáneas sin sondeo, quién/cómo (botón, teclado…) |
| Nuki Web | Nube | Todos los dispositivos de su cuenta Nuki Web | Quién accionó la cerradura (nombre, teclado, huella), registro de actividad |
Cuando varios canales llegan a un dispositivo, Gladys usa primero el local (MQTT, luego el Bridge) y recurre al otro si falla. Desactive Preferir la conexión local en la configuración para usar primero Nuki Web. La insignia de cada dispositivo indica el canal en uso: Local, Nube o Inaccesible; un punto naranja indica un modo de respaldo (por ejemplo: Bridge sin conexión, se usa Nuki Web).
Instalación
Nuki Bridge (local)
- En la app Nuki, abra Gestionar Bridge y active la API HTTP.
- En Gladys, abra la configuración de la integración Nuki y haga clic en Buscar mi Bridge: la dirección IP se rellena sola (o introdúzcala, aparece en la app Nuki).
- Haga clic en Emparejar el Bridge y pulse el botón del Bridge en menos de 30 segundos: el token de la API se guarda automáticamente. También puede copiar el token que muestra la app.
- Deje activado Enviar el token con hash (seguro) (firmware del Bridge 1.13 o posterior): el token nunca viaja en claro por su red.
Asigne una IP fija al Bridge en su router: si cambia, vuelva a usar Buscar mi Bridge.
MQTT (local, Smart Lock 3.0 Pro / 4.0 / Ultra)
- Necesita un broker MQTT (Mosquitto…). Sirve el de la integración MQTT de Gladys.
- En la app Nuki, abra los ajustes de la cerradura → Funciones y configuración → MQTT, actívelo e indique la dirección IP del broker, el puerto, el usuario y la contraseña.
- En Gladys, rellene URL del broker MQTT (p. ej.
mqtt://192.168.1.10:1883), el usuario y la contraseña. Las cerraduras aparecen en unos segundos.
Nuki Web (nube)
- Active Nuki Web para sus dispositivos en la app Nuki.
- En web.nuki.io, abra API y genere un token de API con al menos los permisos Smartlock, Smartlock action y Smartlock log.
- Péguelo en Token de la API Nuki Web.
Crear los dispositivos
Abra la pestaña Descubrimiento de la integración y cree los dispositivos que desee. Si más adelante empareja un sensor de puerta o un teclado, la pestaña ofrece actualizar el dispositivo.
Opciones
- Intervalo de actualización: frecuencia de lectura del Bridge (10 s como mínimo, 30 s por defecto). Nuki Web se lee como mucho cada 30 segundos y solo cuando hace falta. MQTT no necesita sondeo.
- Cuando Gladys desbloquea: Solo desbloquear (por defecto) o Desbloquear y abrir la puerta.
- Cuando Gladys bloquea: Bloquear (por defecto) o Bloqueo completo (dos vueltas, Smart Lock 3.0 y posteriores; bloqueo simple en modelos anteriores).
Dispositivos y funciones
Smart Lock / Smart Door
| Función | Descripción |
|---|---|
| Cerradura | Interruptor: 1 = bloqueada, 0 = desbloqueada (controlable) |
| Estado de la cerradura | Bloqueada / desbloqueada / en movimiento / error |
| Batería | Nivel de carga en % |
| Batería baja | Alerta de batería crítica |
| Cargando | Carga del Power Pack (3.0 y posteriores) |
| Puerta | Abierta / cerrada (si hay un sensor de puerta emparejado) |
| Pila del sensor de puerta | (si hay un sensor de puerta emparejado) |
| Pila del teclado | (si hay un teclado emparejado) |
Opener: interruptores Ring to Open y Modo continuo, Batería baja y Timbre (detección de llamada, mediante el Bridge).
Escenas
Disparadores
- Cerradura Nuki accionada — una cerradura se bloqueó, desbloqueó, abrió o usó Lock 'n'
Go. Filtre por cerradura, operación, cómo se accionó (app, a mano, botón, teclado,
huella, bloqueo automático, Nuki Web, HomeKit, MQTT, Gladys…) y por el usuario Nuki
(con Nuki Web). Variables:
action,trigger,user,device_name. Ejemplo: «cuando Alice desbloquea la puerta principal con el teclado, desactivar la alarma». - Nuki Opener: han llamado al timbre — alguien llamó al portero (Opener con Bridge).
- Problema de cerradura Nuki — motor bloqueado, cerradura sin calibrar u orden rechazada.
- Batería Nuki crítica — la batería de una cerradura, un Opener, un teclado o un sensor de puerta está baja.
Las operaciones iniciadas por la propia Gladys se indican con el disparador gladys:
exclúyalo en el filtro para que una escena no reaccione a sus propias acciones.
Acciones
- Accionar una cerradura Nuki — bloquear, desbloquear, abrir la puerta, Lock 'n' Go,
bloqueo completo. Salida:
success. - Accionar un Nuki Opener — abrepuertas, activar/desactivar Ring to Open o el modo
continuo. Salida:
success. - Leer un dispositivo Nuki — salidas
locked,state,door_open,battery,battery_critical,reachable, para las acciones siguientes (p. ej. enviar «la puerta sigue desbloqueada»). - Bloquear todas las cerraduras Nuki — salidas
locked_countyfailed_count.
El disparador estándar «estado de un dispositivo» de Gladys también funciona con cada función (puerta abierta, batería por debajo del 20 %…).
Widgets del panel
- Cerradura Nuki — una cerradura u Opener: estado, batería en directo, puerta, accesorios, canal, última actividad y botones Bloquear / Desbloquear / Abrir la puerta (la apertura pide confirmación). Para un Opener: Abrir y Ring to Open.
- Resumen Nuki — todos los dispositivos Nuki de un vistazo y un botón Bloquear todo.
- Actividad Nuki — las últimas operaciones: quién, cómo y cuándo (desde Nuki Web si está configurado; si no, desde lo que observó la integración).
Solución de problemas
- «The Nuki Bridge refused the API token»: vuelva a emparejar el Bridge o desactive Enviar el token con hash (seguro) si el firmware de su Bridge es anterior a 1.13.
- «Nuki Bridge unreachable»: compruebe la dirección IP y que la API HTTP está activada. El Bridge atiende una petición cada vez: evite que otro programa lo consulte demasiado.
- MQTT: no aparece ninguna cerradura: compruebe en la app Nuki que MQTT está conectado, que la cerradura usa la dirección IP del broker y que Gladys usa el mismo broker.
- Sin nombre de usuario en los disparadores: los nombres vienen de Nuki Web; añada un token de API.
- El botón Probar la conexión comprueba cada canal configurado e indica qué funciona.
Privacidad y seguridad
Los tokens y contraseñas los guarda Gladys como secretos y nunca se escriben en los registros. El token del Bridge se envía con hash por defecto. Solo se contacta con Nuki Web si configura un token de API. El historial de actividad se guarda en el volumen de datos propio de la integración.
Parámetros de configuración
Estos son los parámetros que Nuki te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Conecte sus dispositivos Nuki | section | No | Rellene al menos uno de los tres canales siguientes. El Bridge y MQTT son locales (rápidos, funcionan sin internet); Nuki Web pasa por la nube e indica además quién accionó la cerradura. Puede combinarlos: Gladys usa primero el local y recurre al otro como respaldo (vea «Preferir la conexión local»). |
| Nuki Bridge (local) | section | No | En la app Nuki, abra los ajustes del Bridge y active la API HTTP. Después use «Buscar mi Bridge» y «Emparejar el Bridge» más abajo (pulse el botón del Bridge cuando se le pida), o copie la dirección IP y el token de la API que muestra la app. |
| Dirección IP del Bridge | string | No | |
| Puerto del Bridge | number | No | |
| Token de la API del Bridge | secret | No | Se rellena automáticamente con «Emparejar el Bridge». |
| Enviar el token con hash (seguro) | boolean | No | Recomendado: el token nunca viaja en claro por su red. Desactívelo solo para un firmware del Bridge anterior a 1.13. |
| MQTT (local, tiempo real) | section | No | Para los Smart Lock 3.0 Pro, 4.ª generación y Ultra: en la app Nuki, active MQTT e indique su broker a la cerradura (con su dirección IP). Introduzca aquí el mismo broker. Los cambios llegan al instante, sin sondeo. |
| URL del broker MQTT | string | No | |
| Usuario MQTT | string | No | |
| Contraseña MQTT | secret | No | |
| Nuki Web (nube) | section | No | Active Nuki Web en la app Nuki y, en web.nuki.io, abra «API» y genere un token con los permisos smartlock, smartlock action y log. Nuki Web indica además quién bloqueó o desbloqueó (usuario, teclado, huella...). |
| Token de la API Nuki Web | secret | No | |
| Opciones | section | No | Con qué frecuencia se leen el Bridge y Nuki Web (MQTT no necesita sondeo) y qué hace el interruptor de cerradura de Gladys. |
| Intervalo de actualización (s) | number | No | Segundos entre dos lecturas del Bridge (10 como mínimo). Nuki Web nunca se lee más de una vez cada 30 segundos. |
| Cuando Gladys desbloquea | select | No | |
| Cuando Gladys bloquea | select | No |
Cómo instalar Nuki en Gladys
- En Gladys, abre Integraciones: Nuki aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/gboulvin/gladys-nuki:1.0.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/gboulvin/Gladys-Nuki.
Nuki requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
Nuki es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene gboulvin, no el equipo principal de Gladys.
- Explorar todas las integraciones, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación