Desarrollo de integración Nuki

Desarrollo
1

El proyecto hasta la fecha

Características

El servicio añade la posibilidad de:

  • controlar los cerraduras inteligentes de la marca Nuki: bloquear, desbloquear
  • recuperar cierta información en Gladys (nivel de batería, estado de la cerradura)

Captura de pantalla

nuki_dashboard_boxes
nuki_dashboard_boxes1840×928 73.7 KB

nuki_integration_devices
nuki_integration_devices1795×1209 139 KB

Integración

Hay 2 integraciones posibles (elegir una, ya que hacer las 2 al mismo tiempo no tiene mucho sentido)

Clave API de NukiWeb

Requisito previo: Gladys debe tener acceso a Internet en todo momento

  1. Activar y configurar su cuenta de Nuki Web [Configuración de Nuki Web]
    (https://help.nuki.io/hc/fr/articles/360016485718-Activer-et-désactiver-un-compte-Nuki-Web#:~:text=Activez%20Nuki%20Web%20dans%20l,dans%20l’App%20de%20Nuki.)

nukiweb
nukiweb3556×1438 250 KB

nukiweb_auth
nukiweb_auth1102×1011 40.2 KB

  1. Configurar el servicio Nuki en Gladys añadiendo la clave API y realizando un escaneo HTTP
    nuki_integration_configuration
    nuki_integration_configuration1831×1033 121 KB

nuki_integration_discover_http
nuki_integration_discover_http1822×1231 150 KB

MQTT

Requisito previo: El MQTT de Gladys está configurado y funciona

  1. Configurar el mqtt en la aplicación Nuki (usar la IP local del mqtt, no el nombre de dominio) Configuración de Nuki con MQTT

    nukiapp_mqtt1
    nukiapp_mqtt1337×750 49.2 KB

    nukiapp_mqtt2
    nukiapp_mqtt21080×2400 173 KB

  2. Ir directamente a la detección MQTT del servicio Nuki en Gladys para ver sus dispositivos

nuki_integration_discover_mqtt
nuki_integration_discover_mqtt1780×1252 146 KB

Hoja de ruta

  • Hacer la documentación (aunque esta no está nada mal)
  • Integrar la noción de trigger (quién o qué ha abierto la cerradura, por ejemplo: User1 ha abierto la cerradura, la cerradura ha procedido a un auto-bloqueo…)
  • Adaptar la parte de la escena al botón de la cerradura
  • Adaptar la parte gráfica (mostrar los estados)

Instalación

La imagen nukidev de prueba está aquí.

Para más información

RFTM :wink:

Llamada a los probadores y a la comunidad

Llamo a las personas que tienen este tipo de dispositivo y que están en capacidad de hacer pruebas, para que me den sus comentarios.

Tengo una Nuki v3 (por lo tanto no disponible con Matter)

A su disposición para información adicional.

2

Gracias por este desarrollo @ProtZ, ¡parece genial!

Para la documentación, puedes hacer una PR en este repositorio:

La documentación son archivos markdown en esta carpeta (para el artículo en inglés):

Y aquí para el artículo en francés:

Para escribir la documentación, te recomiendo hacer capturas de pantalla en inglés y luego en francés en Gladys, luego escribir la documentación en francés y pedirle a ChatGPT que te traduzca el artículo.

3

Por cierto, mencioné este tema en el boletín que se enviará mañana por la mañana :slight_smile:

Espero que tengamos probadores. Si no tenemos a nadie para la próxima semana, podremos seguir avanzando, ya que tú lo has probado por tu parte.

4

Genial, acabo de hacer la PR para la documentación, pero no sé cómo probarla :confused:

5

Creo que hay un pequeño problema en tu PR, modifica más de 1300 archivos :smiley:

Intenta volver a partir de master y crear tus archivos de nuevo.

Screenshot 2025-10-04 at 10.10.31
Screenshot 2025-10-04 at 10.10.311496×550 65.4 KB

Para probar luego en local, todas las instrucciones están en el README: GitHub - GladysAssistant/v4-website: Gladys Assistant website · GitHub

6

Lo siento, he sido un desastre.
Lo he rehecho limpiamente ahora mismo. Pero es imposible probarlo localmente sin profundizar un poco más:


Error: Sentencia return ilegal
  
  - dev.html.template.ejs:5 ./node_modules/html-webpack-plugin/lib/loader.js!./node_modules/@docusaurus/core/lib/webpack/templates/dev.html.template.ejs
    [v4-website]/[@docusaurus]/core/lib/webpack/templates/dev.html.template.ejs:5:1
7

¿En qué versión de Node.js estás? Se debe usar Node >= 18. Yo estoy en Node 22

8

Pareil v22.14.0 :frowning:

9

Estoy en v22.18.0, después no sé si eso cambia mucho.

¿Has hecho bien git clone luego yarn y finalmente npm start?

Acabo de volver a probarlo desde un repositorio vacío para asegurarme de que todo estaba bien, y todo funciona :thinking:

10

Respondo un poco tarde, pero tengo una serie Nuki (si aún necesitas probar…)

11

¡Siempre en busca de probadores @StephaneB!

12

Vale. Pero no he entendido bien en el hilo de esta discusión si estaba listo para probar o si había que esperar modificaciones antes de poder probar…

13

@ProtZ ¿puedes compartir la etiqueta de la imagen Docker para que @StephaneB pueda probarla?

El enlace que publicaste en tu mensaje inicial es un enlace privado

14

Lo siento, no me había dado cuenta de que el enlace era privado:

docker pull ngeissel/gladys:nukidev

Gracias @StephaneB, manténme informado :slight_smile:

15

Hola @ProtZ,

¿Te apetecería hacer una nueva revisión en videollamada con pantalla compartida como la última vez?

Estoy disponible esta tarde, o todas las noches de esta semana, o el viernes durante el día.

Me hubiera gustado tener probadores reales, pero bueno, da igual, no vamos a esperar eternamente :slight_smile:

16

Hola @pierre-gilles; sí, podemos organizar eso, pero ahora mismo estoy realmente agobiado con el trabajo y los niños :confused:
¿Podemos sincronizarnos por MP?

17

¡Sí, te envío un mensaje privado!

18

He tomado el tiempo de probar hoy esta nueva integración. Perdón por haber pasado por alto que les había propuesto hacerlo…

Me puse en la siguiente situación para probar: A priori, no leer las explicaciones de este post y limitarme a lo que está escrito en las páginas de la integración. Y solo leer las explicaciones de este post si es necesario :wink:

Hasta ahora he probado la integración Web. Intentaré probar la integración MQTT más tarde en el día…

Mis sugerencias para mejorar la integración Web (pero en general funciona muy bien, ¡enhorabuena!!!):

  • En la página de integraciones>Nuki
    • La página ‹ dispositivos › muestra una explicación interesante cuando aún no tienes una configuración MQTT (de memoria, un texto que explica que hay dos formas de conectarse: ya sea mediante MQTT o a través de NukiWeb). Pero tan pronto como tienes un MQTT configurado, esta explicación ya no aparece y ves los dos botones Descubrimiento MQTT y Descubrimiento Web. Creo que la explicación debería seguir siendo visible hasta que no se haya realizado ningún descubrimiento de dispositivo.
    • La página ‹ Configuración › en realidad es específica de la versión ‹ web ›. Quizás sería mejor renombrarla a ‹ Configuración Web ›
    • En esta página ‹ Configuración ›, añadir una precisión en el paso 1: "Si aún no tienes una cuenta Nuki Web, créala siguiendo las instrucciones de https://help.nuki.io/hc/fr/articles/360016485718-Activer-et-désactiver-un-compte-Nuki-Web
    • En la página NukiWeb, se muestra una clave API en primer lugar, pero entiendo que no es la clave que necesitas, y que debes bajar un poco en la página para generar un token API. Quizás tu página de configuración podría especificar esto en el paso 3: « … (Atención, no se trata de la clave OAuth2, sino de un token que debe crearse específicamente) ». Y en todas las páginas donde uses el término Clave API, quizás sería mejor reemplazarlo por Token de API ?
    • Cuando creas el token API en NukiWeb, puedes marcar/desmarcar los permisos a otorgar. ¿Necesitas todos? Sería bueno indicar los permisos a marcar que realmente necesitas, para no otorgar permisos en realidad innecesarios.
    • Cuando la clave API se guarda en Gladys, se muestra con asteriscos, y el botón « Guardar configuración » está activo. No lo he probado, pero si vuelvo a hacer clic en este botón, ¿va a sobrescribir la clave real ingresada anteriormente (por ejemplo ‹ qslkjhqdgiuyzeart ›) por ‹ qsl**********art › y ya no funcionará? Sugiero desactivar el botón mientras no se ingrese nada nuevo en el campo Clave API…
    • Después de ingresar una clave API válida, podría haber un texto que invite a ir a la página « Descubrimiento Web »
    • en la página Descubrimiento Web, el texto dice « Descubrimiento automático… » pero no entendí de inmediato que aún así tenía que hacer clic en el botón « Buscar »
  • En el panel de control, la adición de la cerradura con el widget Dispositivo es muy clara, genial. Solo un detalle: un clic en bloquear/desbloquear tarda un tiempo variable en realizarse, entre ‹ inmediato › y varios segundos. Podría haber una información que invite a esperar, para evitar clics innecesarios ?
19

Bueno, bueno, en realidad no podré probar el funcionamiento de MQTT, porque tengo una cerradura 3.0 y el MQTT solo está presente en la cerradura 3.0 Pro y a partir de la 4.0 :smiling_face_with_tear:

¿Quizás sería un detalle a añadir en la explicación inicial en la página ‹ Dispositivos › y en la página ‹ Descubrimiento MQTT ›?

20

¡Gracias por tu prueba @StephaneB con comentarios muy pertinentes!

Normalmente, en Gladys, el clic debe ser instantáneo, aunque la acción tarde más en propagarse al dispositivo conectado. ¿Es este el caso en el que ves un bloqueo real de la interfaz?