Compila un dispositivo virtual Matter

1. Introducción

Matter es un protocolo de conectividad que ofrece oportunidades emocionantes para el desarrollo de dispositivos inteligentes. En este codelab, compilarás tu primer dispositivo Matter con SDK y dependencias que se te proporcionarán en una imagen de Docker preconfigurada.

Para obtener más información sobre Matter, visita el Developer Center de Google Home o el sitio web de Connectivity Standards Alliance.

Qué aprenderás

  • Cómo configurar un entorno de compilación de Matter
  • Cómo compilar un dispositivo virtual Matter que se ejecute en tu computadora
  • Cómo asignar y controlar el dispositivo virtual Matter con Google Home

Qué necesitarás

2. Configure su entorno

Usaremos un contenedor de Docker configurado previamente en una máquina anfitrión de Linux. Este contenedor incluye todas las dependencias necesarias para compilar y ejecutar un dispositivo virtual de Matter.

Verifica el hardware

Las computadoras con Windows y macOS no son compatibles con esta instalación de Docker. Puedes instalar y compilar Matter manualmente en macOS.

Además, en estas instrucciones, se supone que tu máquina Linux ejecuta el sistema de ventanas X11. Si tu máquina Linux ejecuta Wayland, asegúrate de que X.Org también esté instalado.

Configura Docker

  1. Instala Docker Engine (no uses Docker Desktop).
  2. Extrae la imagen de Docker desde Docker Hub. En una ventana de terminal, ejecuta el siguiente comando:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    
    Esta operación puede tardar unos minutos en completarse.
  3. Inicia el contenedor de Docker en ejecución:
    user@host> xhost local:1000
    user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    

Después de iniciar el contenedor, deberías ver un resultado de diagnóstico seguido de un mensaje que indica que la configuración de tu contenedor es correcta y, por último, el símbolo del sistema de shell del contenedor:

Environment looks good, you are ready to go!
$

Veamos el comando de Docker y las opciones que le pasamos:

  • xhost local:1000 permite que el sistema de ventanas X reciba conexiones del host local en el puerto 1000, lo que permite usar una interfaz de usuario gráfica.
  • docker run … image ejecuta la imagen determinada y la extrae del registro de Docker si es necesario.
  • --ipc=host permite que Docker comparta el espacio de nombres de comunicación entre procesos con tu máquina anfitrión.
  • --net=host permite que Docker use la pila de red del host dentro del contenedor, lo cual es necesario para pasar el tráfico de mDNS del host al contenedor y compartir la pantalla del host X11.
  • -e DISPLAY exporta $DISPLAY al host, lo que brinda acceso a la interfaz gráfica del sistema. Esto es necesario para ejecutar la herramienta ZAP cuando se editan clústeres de Matter.
  • -it ejecuta Docker con una terminal interactiva (tty), en lugar de hacerlo como un proceso en segundo plano.

De manera opcional, puedes ejecutar una segunda instancia de sesión de terminal:

user@host> docker exec -it matter-container /bin/bash
$

Inicia y detén el contenedor de Docker de Matter

Cada vez que ejecutes un comando docker run, crearás un contenedor nuevo con la imagen especificada. Cuando lo hagas, se perderán tus datos anteriores, que se guardaron en una instancia de contenedor anterior. A veces, esto es lo que quieres que suceda, porque te permite comenzar con una instalación nueva. Sin embargo, a veces preferirías guardar tu configuración de trabajo y entorno entre sesiones.

Por este motivo, después de crear su contenedor, puede detenerlo para evitar perder su trabajo.

user@host> docker stop matter-container

Cuando esté todo listo para volver a ejecutarlo, inicia el contenedor y abre una ventana de terminal:

user@host> docker start matter-container
user@host> docker exec -it matter-container /bin/bash

Puedes abrir sesiones de terminal adicionales en tu contenedor con lo siguiente:

user@host> docker exec -it matter-container /bin/bash

También puedes iniciar una sesión raíz con el siguiente comando:

user@host> docker exec -u 0 -it matter-container /bin/bash

Configuración inicial de Matter

Cuando se abra la terminal, ya estará en el repositorio clonado de Matter en ~/connectedhomeip. No se necesitan pasos adicionales para configurar Matter.

Cómo compartir archivos entre el host y el contenedor

Para acceder a los archivos de tu máquina anfitrión desde el contenedor, puedes usar una activación de vinculación. También puedes escribir archivos en el directorio activado desde el contenedor para facilitar el acceso desde el host.

Ejecuta tu contenedor con el argumento adicional --mount source=$(pwd),target=/workspace,type=bind para activar tu directorio de trabajo actual en el contenedor en /workspace.

user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

Los permisos del usuario del contenedor en el directorio activado se deben administrar en el host.

Obtén el ID de grupo del usuario del contenedor desde el contenedor.

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

Abre otra sesión de la terminal en el host del contenedor y establece el directorio de trabajo en el directorio que activó el contenedor.

Configura de forma recurrente el grupo de archivos del directorio activado para el grupo del usuario del contenedor.

user@host> sudo chgrp -R 1000 .

Otorga al grupo los permisos que desees en el directorio. En este ejemplo, se le otorga al grupo del usuario del contenedor permisos de lectura, escritura y ejecución en todos los archivos del directorio activado.

user@host> sudo chmod -R g+rwx .

Ten en cuenta que estos comandos no afectan el permiso de los archivos nuevos que crea el usuario del host. Recuerda actualizar los permisos de los nuevos archivos creados en el host según sea necesario.

Puedes agregar tu usuario de host al grupo del usuario del contenedor para heredar permisos en los archivos creados por el usuario del contenedor.

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

3. Consola para desarrolladores de Google Home

La consola para desarrolladores de Google Home es la aplicación web en la que puedes administrar tus integraciones de Matter con Google Home.

Cualquier dispositivo Matter que haya aprobado la certificación de Matter de la Connectivity Standards Alliance (Alliance) funciona en el ecosistema de Google Home. Los dispositivos en desarrollo que no están certificados se pueden encarar en el ecosistema de Google Home bajo ciertas condiciones. Consulta Restricciones de vinculación para obtener más información.

Cómo crear un proyecto de desarrollador

En primer lugar, ve a la consola para desarrolladores de Google Home:

  1. Haz clic en Crear proyecto.
  2. Ingresa un nombre de proyecto único y haz clic en Crear proyecto. Diálogo de creación de proyecto nuevo
  3. Haz clic en + Add integration, que te llevará a la pantalla Matter resources, en la que podrás ver la documentación de desarrollo de Matter y leer sobre algunas herramientas.
  4. Cuando estés listo para continuar, haz clic en Next: Develop, que muestra la página de la lista de tareas de Matter.
  5. Haz clic en Siguiente: Configuración.
  6. En la página Configuración, ingresa el Nombre del producto.
  7. Haz clic en Select device type y selecciona el tipo de dispositivo en el menú desplegable (en este caso, Light).
  8. En el ID del proveedor (VID), selecciona Test VID y elige 0xFFF1 en el menú desplegable Test VID. En ID del producto (PID), ingresa 0x8000, haz clic en Guardar y continuar y, luego, en Guardar en la siguiente página. Usa estos valores exactos de VID/PID; los pasos posteriores del codelab dependerán de ellos.
    Configura un proyecto
  9. Ahora verás tu integración en Integraciones de Matter.
  10. Reinicia tu concentrador para asegurarte de que reciba la configuración más reciente del proyecto de integración de Matter. Si tienes que cambiar el VID o PID más adelante, también deberás reiniciar el dispositivo después de guardar el proyecto para que se aplique el cambio. Consulta Cómo reiniciar los dispositivos Google Nest o Google Wifi para obtener instrucciones de reinicio paso a paso.

4. Compila un dispositivo

Todos los ejemplos de Matter se encuentran en la carpeta examples del repositorio de GitHub. Hay varios ejemplos disponibles, pero nuestro enfoque en este codelab es Chef.

Chef es ambas cosas:

  • Una app de ejemplo que proporciona una interfaz de terminal, uniendo funciones que también se encuentran en la app de examples/shell.
  • Una secuencia de comandos que adopta el principio de convención sobre la configuración para encapsular varias de las tareas comunes necesarias para desarrollar un dispositivo compatible con Matter.

Navega a la carpeta de ejemplo de Chef y crea tu primera compilación de Matter:

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

Chef tiene algunas opciones que se pueden ver ejecutando chef.py -h. Estas son las opciones que usamos:

  • -d: Define el tipo de dispositivo que se usará. En este caso, crearemos una app de iluminación con controles de nivel y encendido.
  • -z: Invoca la herramienta ZAP para generar los archivos de origen que implementan el tipo de dispositivo. Es decir, en función de tu selección de iluminación, ZAP creará automáticamente un código para incorporarlo a la compilación que define la luz (el modelo de datos) y cómo interactúa con otros dispositivos (el modelo de interacción).
  • -b: compilaciones.
  • -r: [Opcional] habilita el servidor de RPC en el dispositivo virtual de Matter para que otros componentes (como la GUI) puedan comunicarse con el dispositivo a fin de establecer y recuperar atributos del modelo de datos.
  • -t linux: Es la plataforma de segmentación. Las plataformas de compatibilidad son linux, nrfconnect y esp32. Puedes ejecutar ./chef.py -h para ver todos los comandos disponibles y las plataformas de destino compatibles. linux se usa para dispositivos Matter virtuales.

Cómo ejecutar el dispositivo

Matter usa el puerto TCP/UDP 5540. Por lo tanto, si tienes un firewall en ejecución en la computadora, apágalo o permite conexiones TCP/UDP entrantes en el puerto 5540.

Ejecuta el dispositivo virtual en el contenedor con lo siguiente:

$ ./linux/out/rootnode_dimmablelight_bCwGYSDpoe
   [1648589956496] [14264:16538181] CHIP: [DL] _Init]
...
[1648562026.946882][433632:433632] CHIP:SVR: SetupQRCode: [MT:Y3.13Y2N00KA0648G00]
[1648562026.946893][433632:433632] CHIP:SVR: Copy/paste the below URL in a browser to see the QR Code:
[1648562026.946901][433632:433632] CHIP:SVR: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY3.13Y2N00KA0648G00
[1648562026.946915][433632:433632] CHIP:SVR: Manual pairing code: [34970112332]

Deja el dispositivo en funcionamiento. Ahora, centraremos nuestra atención en la app de Google Home para que podamos poner tu dispositivo en el Google Home.

Detén el dispositivo

Si necesitas detener el dispositivo, puedes salir del programa con CTRL+C. Si la app no se cierra, es posible que también debas usar Ctrl + \.

Las credenciales para tu dispositivo virtual se almacenan en el directorio /tmp/, en archivos que comienzan con el prefijo chip.

Si quieres repetir todo el proceso de asignación desde el principio, deberás borrar esos archivos mediante la ejecución del siguiente comando:

$ rm /tmp/chip*

5. El controlador de dispositivo virtual

Virtual Device Controller es una app independiente que proporciona una interfaz gráfica de usuario para controlar y mostrar los estados de tus dispositivos virtuales Matter. Utiliza un cliente de RPC para comunicarse con los dispositivos Matter conectados a su entorno de desarrollo.

El controlador de dispositivo virtual

Virtual Device Controller proporciona una representación visual de tu dispositivo virtual.

Puedes interactuar con el dispositivo virtual a través de la interfaz gráfica de usuario (GUI) del controlador de dispositivo virtual. Los cambios en la GUI afectan el modelo de datos subyacente. Consulta Dispositivos compatibles para ver la lista completa de tipos de dispositivos virtuales de Matter compatibles.

Instala el controlador de dispositivo virtual

El controlador de dispositivo virtual viene preinstalado en el contenedor de Docker de Ubuntu LTS 20.04.

Cómo ejecutar el controlador de dispositivo virtual

Crea la segunda instancia de sesión de la terminal:

user@host> docker exec -it matter-container /bin/bash
$

A fin de iniciar el controlador del dispositivo virtual, proporciona el socket de red que se usará para comunicarse con el dispositivo virtual:

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

Si inicias el controlador sin proporcionar ningún argumento, se usará de forma predeterminada la opción del socket de red utilizando el puerto localhost 33000. Una vez que el control pueda conectarse al dispositivo virtual, aparecerá una pantalla en la que se mostrará el estado del dispositivo:

Interfaz gráfica de usuario del dispositivo virtual

La app envía solicitudes al servidor de RPC del dispositivo a medida que realizas cambios en la app de controlador virtual y sondea el servidor de RPC una vez por segundo para recuperar el estado.

La aplicación Virtual Device Controller también se puede usar para recuperar el código QR como parte del flujo de comisión del dispositivo. Haz clic en el ícono de código QR junto a la imagen del dispositivo para mostrar el código QR de este dispositivo. Usa este código QR para solicitar el dispositivo.

6. Solicita el dispositivo

Nota: Este paso solo se realizará correctamente si ya configuraste tu proyecto en la consola para desarrolladores de Google Home.

Nest Hub

Se requiere un concentrador para poner tu dispositivo en la estructura Matter. Este es un dispositivo Google Nest, como el Nest Hub (2a generación), que es compatible con Matter y que funciona como router de borde para dispositivos compatibles con Thread y como ruta de entrega local para enrutar intents de casa inteligente.

Consulta esta lista para ver qué concentradores son compatibles con Matter.

Antes de comenzar el proceso de comisión, asegúrate de que se cumpla lo siguiente:

  • Tu concentrador está vinculado con la misma Cuenta de Google que usaste para acceder a la consola de Google Home.
  • El concentrador está conectado a la misma red Wi-Fi que la computadora que usas para ejecutar tu dispositivo virtual de Matter.
  • La unidad central está en la misma estructura que usas en la app de Google Home (la "casa" en Google Home Graph representa la estructura).

Obtener un código QR

El proceso de comisión necesita que la información de integración de Matter se proporcione a través de un código QR. Puedes obtener el código QR de tu dispositivo virtual desde Virtual Device Controller.

Realiza la operación de comisión

  1. Abre la app de Google Home.
  2. Presiona el signo + en la esquina superior izquierda.
  3. Presiona Configurar dispositivo.
  4. Presiona Dispositivo nuevo.
  5. Selecciona tu casa y presiona Siguiente.
  6. La app de Google Home busca tu dispositivo. Si aparece el mensaje "Se encontró un dispositivo Matter...", presiona "Sí". De lo contrario, presiona Configurar un dispositivo diferente y selecciona Dispositivo Matter en la lista de dispositivos.
  7. Apunta la cámara al código QR de tu dispositivo o al código QR generado por el sitio web.
  8. Continúa el proceso de vinculación como se indica en el flujo de la app de Google Home.

Una vez que completes estos pasos, el dispositivo virtual de Matter se debería poner en marcha correctamente y debería aparecer como un ícono nuevo en la app de Google Home.

Bombilla sincronizada en la app de Google Home

Solución de problemas

La puesta en servicio falla y se muestran los mensajes de error "Problema de conectividad" o "No se pudo establecer contacto con Google"

  • Asegúrate de haber creado un proyecto con la combinación de VID/PID en la consola de Google Home y de no tener otros proyectos que usen la misma combinación de VID/PID.

La puesta en servicio falla después de "Buscando tu dispositivo" durante un largo período

7. Cómo controlar el dispositivo

Una vez que tu dispositivo compatible con Matter se ponga en marcha correctamente y aparezca en la app de Google Home como una bombilla, podrás probar el control del dispositivo de diferentes métodos:

  • Con Asistente de Google
  • Con la app de Google Home
  • Uso de la GUI del dispositivo virtual.

Asistente de Google

Usa Asistente de Google en tu teléfono o concentrador para activar o desactivar el estado del dispositivo a partir de comandos por voz, como decir "Hey Google, enciende las luces".

Para ver más ejemplos de comandos, consulta la sección Cómo controlar los dispositivos de casa inteligente con comandos por voz de Cómo controlar los dispositivos de casa inteligente que se agregaron a la app de Google Home.

App de Google Home

Puedes presionar las etiquetas Activar y Desactivar junto al ícono de la bombilla que se muestra en la app de Google Home.

Para obtener más información, consulta la sección Cómo controlar dispositivos con la app de Google Home del artículo Cómo controlar los dispositivos de casa inteligente que se agregaron a la app de Google Home.

GUI del dispositivo virtual

Puedes interactuar con la GUI del dispositivo virtual para cambiar el estado del dispositivo. Ya sea que controles el dispositivo virtual con el controlador de dispositivo virtual, la app de Google Home en tu teléfono o con tu concentrador, todas estas interfaces reflejarán el estado actual del dispositivo virtual.

8. Felicitaciones.

Creaste correctamente tu primer dispositivo Matter. ¡Genial!

En este codelab aprendiste a hacer lo siguiente:

  • Instalar un entorno de desarrollo de Matter con una imagen de Docker empaquetada previamente
  • Compila y ejecuta un dispositivo virtual de Matter.
  • Comisión y controla tu dispositivo virtual desde Google Home.

Para obtener más información sobre Matter, explora estas referencias: