Compila un dispositivo virtual de 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 proporcionados en una imagen de Docker preconfigurada.

Para obtener información sobre Matter, visita el Centro de programadores 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 Matter virtual 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 con anterioridad 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 tu hardware

Por el momento, esta instalación de Docker no admite computadoras con Windows ni MacOS. Puedes instalar y compilar Matter manualmente en macOS o Windows.

Además, en estas instrucciones, se supone que tu máquina Linux ejecuta el sistema de ventanas X11. Si tu máquina de 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 lo siguiente:
    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 que se ejecuta:
    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ía ver un resultado del diagnóstico seguido de un mensaje que indica que la configuración del contenedor es correcta y, por último, el símbolo del sistema 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 X Window reciba conexiones del host local en el puerto 1000, lo que permite usar una interfaz gráfica de usuario.
  • 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, que es necesaria para pasar el tráfico mDNS del host al contenedor y compartir la pantalla del host X11.
  • -e DISPLAY exporta $DISPLAY al host y proporciona acceso a la interfaz gráfica del sistema. Esto es necesario para ejecutar la herramienta de ZAP cuando se editan clústeres de Matter.
  • -it ejecuta Docker con una terminal interactiva (tty), en lugar de como un proceso en segundo plano.

De manera opcional, puedes ejecutar una segunda sesión 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. Si lo hace, se perderán sus datos anteriores, que se guardaron en una instancia anterior del contenedor. A veces, esto es lo que quieres que suceda, porque te permite comenzar con una instalación nueva. Sin embargo, hay momentos en los que prefieres guardar la configuración de trabajo y del entorno entre sesiones.

Por esta razón, después de crear su contenedor, puede detenerlo para evitar perder su trabajo.

user@host> docker stop matter-container

Cuando esté listo para volver a ejecutarse, inicie el contenedor y abra 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 las siguientes opciones:

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 de configuración adicionales de Matter.

Comparte archivos entre el host y el contenedor

Para acceder a los archivos de su máquina anfitrión desde el contenedor, puede usar una activación de vinculación. También puede escribir archivos en el directorio activado desde el contenedor para poder acceder al host con facilidad.

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 deben administrarse en el host.

Obtén el ID de grupo del usuario del 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 activado por el contenedor.

Establece de forma recurrente el grupo para los archivos del directorio activado en el grupo del usuario del contenedor.

user@host> sudo chgrp -R 1000 .

Otorga los permisos que desees en el directorio al grupo. En este ejemplo, se le otorga al grupo del usuario del contenedor permisos de lectura, escritura y ejecución para 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 nuevos archivos que crea el usuario del host. Recuerda actualizar los permisos de los archivos nuevos creados en el host según sea necesario.

Puedes agregar tu usuario host al grupo del usuario del contenedor para heredar los permisos de los archivos que creó 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 administras las integraciones de Matter con Google Home.

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

Crea un proyecto de desarrollador

Primero, ve a la consola para desarrolladores de Google Home:

  1. En la página Administrar proyectos, haz clic en Crear un proyecto.
    Centro de desarrolladores de Google Home
  2. En la página Comenzar, haz clic en Crear proyecto.

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

4. Cómo compilar un dispositivo

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

Chef tiene las siguientes características:

  • Una app de ejemplo que proporciona una interfaz de terminal y funciones de unión también se encuentran en la app de examples/shell.
  • Una secuencia de comandos que adopta el principio de configuración sobre convenciones mediante la cual se encapsulan 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, estamos creando una app de iluminación con controles de encendido y apagado y niveles.
  • -z: Invoca la herramienta ZAP para generar los archivos de origen que implementan el tipo de dispositivo. Es decir, según el tipo de iluminación que elijas, el ZAP creará automáticamente un código para incorporarlo en la compilación que defina 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 Matter para que otros componentes (como la GUI) puedan comunicarse con el dispositivo a fin de configurar y recuperar atributos de modelos de datos.
  • -t linux: Es la plataforma de destino. Las plataformas de asistencia 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 virtuales Matter.

Ejecuta el dispositivo

Matter usa el puerto TCP/UDP 5540, por lo que si tienes un firewall ejecutándose en la computadora, puedes apagarlo o permitir las 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, nos enfocaremos en la app de Google Home para que puedas asignar el dispositivo a Google Home.

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 de tu dispositivo virtual se almacenan en el directorio /tmp/, en archivos que comienzan con el prefijo chip.

Si desea repetir todo el proceso de puesta en marcha desde el principio, ejecute el siguiente comando para borrar esos archivos:

$ rm /tmp/chip*

5. El controlador de dispositivo virtual

El controlador de dispositivo virtual es una app independiente que proporciona una interfaz gráfica de usuario para controlar y mostrar los estados de tus dispositivos virtuales Matter. Usa un cliente de RPC para comunicarse con los dispositivos Matter conectados a tu entorno de desarrollo.

El controlador de dispositivo virtual

El controlador de dispositivo virtual proporciona una representación visual del dispositivo virtual.

Puedes interactuar con el dispositivo virtual a través de la interfaz gráfica de usuario (GUI) de Virtual Device Controller. Los cambios en la GUI afectan el modelo de datos subyacente. Actualmente, el controlador de dispositivo virtual admite el tipo de dispositivo de luz regulable.

Instala el controlador de dispositivo virtual

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

Ejecuta el controlador de dispositivo virtual

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

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

Para iniciar el controlador de 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á la opción de socket de red de forma predeterminada con el puerto localhost 33000. Una vez que el control pueda conectarse al dispositivo virtual, mostrará una pantalla en la que se muestra el estado del dispositivo:

Interfaz de usuario gráfica de dispositivo virtual

La aplicación envía solicitudes al servidor de RPC del dispositivo a medida que realizas cambios en la aplicación de Virtual Controller y sondea el servidor de RPC una vez por segundo para recuperar el estado.

La app de controlador de dispositivo virtual también se puede usar para recuperar el código QR como parte del flujo de asignación de dispositivos. Haz clic en el ícono de código QR junto a la imagen del dispositivo para ver su código:

Código QR

Puedes usar este código QR para asignar tu dispositivo.

6. Asignar el dispositivo

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

Nest Hub

Se requiere un concentrador para la asignación del dispositivo en la tela Matter. Este es un dispositivo Google Nest, como Nest Hub (2a gen.), que admite Matter y servirá 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 iniciar el proceso de puesta en marcha, compruebe lo siguiente:

  • El concentrador está vinculado con la misma Cuenta de Google que usaste para acceder en la consola de Google Home.
  • Tu concentrador está en la misma red Wi-Fi que la computadora que estás usando para ejecutar tu dispositivo de Matter.
  • El concentrador se encuentra en la misma estructura que usas en la app de Google Home (la "casa" del gráfico de Google Home representa tu estructura).

Obtener un código QR

El proceso de comisión necesita información de integración de Matter proporcionada a través de un código QR. Puedes obtener el código QR para tu dispositivo virtual en el controlador de dispositivo virtual.

Realiza la operación de comisión

  1. Abre la app de Google Home.
  2. Presiona + 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 dispositivos. Si aparece el mensaje "Se encontró un dispositivo Matter...", presiona "Sí". De lo contrario, presiona Configurar un dispositivo diferente y selecciona Dispositivo Matter de la lista de dispositivos.
  7. Apunta la cámara al código QR del dispositivo o al código 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 Matter se deberá encargar 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 comisión falla con 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 correcta de VID/PID en Google Home Console y de no tener otros proyectos que usen la misma combinación.

La puesta en marcha falla después de buscar el dispositivo por un período prolongado.

7. Controla el dispositivo

Una vez que el dispositivo compatible con Matter se haya encargado correctamente y aparezca en la app de Google Home como bombilla, puedes probar el control del dispositivo de diferentes maneras:

  • Asistente de Google
  • Con la app de Google Home.
  • Usar 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 "Hey Google, enciende las luces".

Para obtener más ejemplos de comandos, consulta la sección Cómo controlar dispositivos de casa inteligentes con comandos por voz de la sección Cómo controlar dispositivos de casa inteligente agregados a la app de Google Home.

App de Google Home

Puedes presionar las etiquetas Activado y Desactivado junto al ícono de 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 de Cómo controlar dispositivos de casa inteligente agregados a la app de Google Home.

GUI de dispositivos virtuales

Puede interactuar con la GUI del dispositivo virtual para cambiar el estado del dispositivo. Independientemente de si controlas el dispositivo virtual con el controlador de dispositivo virtual, la app de Google Home en el teléfono o el 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:

  • Instala un entorno de desarrollo de Matter con una imagen de Docker empaquetada previamente.
  • Compila y ejecuta un dispositivo virtual de Matter.
  • Consigue y controla tu dispositivo virtual desde Google Home.

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