Compila un dispositivo virtual Matter

1. Introducción

Matter es un protocolo de conectividad que ofrece oportunidades interesantes para el desarrollo de dispositivos inteligentes. En este codelab, compilarás tu primer dispositivo Matter con recursos del SDK de Matter.

Para obtener más información sobre Matter, visita el Centro para desarrolladores 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 ejecuta en tu computadora
  • Cómo habilitar y controlar el dispositivo Matter virtual con Google Home

Requisitos

  • Un concentrador, que es cualquier dispositivo Google Nest compatible con Matter, como el Nest Hub (2ª gen.).
  • Una máquina Linux que ejecuta el sistema de ventanas X11
  • Docker.
  • Git
  • Conocimientos básicos de Linux
    • Ten en cuenta que la shell que se supone para todos los comandos de este codelab es BASH.

2. Configura tu entorno

Revisa tu hardware

Esta instalación de Docker no es compatible con computadoras con Windows ni macOS. Puedes instalar y compilar Matter de forma manual 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 también esté instalado X.Org.

Cómo configurar el entorno de desarrollo

  1. Instala Docker Engine (no uses Docker Desktop).
  2. Clona el SDK de Matter y toma nota de la confirmación que usaremos a continuación.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Ejecuta un contenedor de compilación con las imágenes públicas de CI del SDK y ejecuta el dispositivo virtual recién compilado desde este contenedor. Ubica la imagen para que coincida con nuestra versión del SDK de la siguiente manera:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Si usas la misma confirmación, deberías ver ghcr.io/project-chip/chip-build:66First, forward xhost ports so we can later use UI applications:
    xhost local:1000
    A continuación, inicia el contenedor con los recursos adecuados reenviados desde el host (nuestros recursos de confirmación del SDK, redes y pantalla/comunicaciones).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

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

  • xhost local:1000 permite que X Window System 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 proporcionada 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 host.
  • --net=host permite que Docker use la pila de red del host dentro del contenedor, lo que se requiere para que pase el tráfico de mDNS del host al contenedor y para compartir la pantalla X11 del host.
  • -e DISPLAY exporta $DISPLAY al host, lo que proporciona 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 como un proceso en segundo plano.
  • --mount instala el SDK que extrajimos anteriormente en el contenedor.
  • --workdir establece el directorio de trabajo en el inicio en nuestro directorio del SDK montado.

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

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

Detén e inicia 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 antiguos, que se guardaron en una instancia de contenedor anterior. A veces, esto es lo que quieres que suceda, ya que te permite comenzar con una instalación nueva. Sin embargo, hay ocasiones en las que preferirías guardar tu trabajo y la configuración del entorno entre sesiones.

Por este motivo, después de crear el contenedor, puedes detenerlo para no perder tu trabajo.

user@host> docker stop matter-container

Cuando esté todo listo para volver a ejecutar el contenedor, ábrelo 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 el siguiente comando:

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

O bien, inicia 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

Inicializa el SDK

Inicializa el SDK de Matter. Esta operación tardará varios minutos en completarse.

source scripts/bootstrap.sh
python3 scripts/checkout_submodules.py --shallow --platform linux

Ahora, tu SDK de Matter está inicializado. Para volver a inicializar el entorno rápidamente en el futuro, ejecuta el siguiente comando:

sudo docker exec -it  matter-container /bin/bash
source ./scripts/activate.sh

Comparte archivos entre el host y el contenedor

Anteriormente, accedimos a los archivos de tu máquina host desde el contenedor con una vinculación de montaje. También puedes escribir archivos en el directorio activado desde el contenedor para acceder a ellos desde el host.

En general, usa activaciones de vinculación ejecutando 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 del grupo del usuario del contenedor desde el interior del contenedor.

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

Abre otra sesión de terminal en el host del contenedor y configura el directorio de trabajo en el directorio que montó el contenedor.

Establece de forma recursiva el grupo de 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 otorgan permisos de lectura, escritura y ejecución al grupo del usuario del contenedor en todos los archivos del directorio montado.

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

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

Puedes agregar tu usuario 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 administras tus integraciones de Matter con Google Home.

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

Crea un proyecto de desarrollador

Para comenzar, ve a Google Home Developer Console:

  1. Haz clic en Crear proyecto.
  2. Ingresa un nombre único para el proyecto y, luego, haz clic en Crear proyecto. Diálogo de creación de proyecto nuevo
  3. Haz clic en + Agregar integración, que te llevará a la pantalla Recursos de Matter, donde podrás ver la documentación de desarrollo de Matter y leer sobre algunas herramientas.
  4. Cuando esté todo listo para continuar, haz clic en Siguiente: Desarrollo, que muestra la página 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 Seleccionar el tipo de dispositivo y elige el tipo de dispositivo en el menú desplegable (en este caso, Light).
  8. En ID de proveedor (VID), selecciona VID de prueba y, luego, 0xFFF1 en el menú desplegable VID de prueba. En ID del producto (PID), ingresa 0x8000 y haz clic en Guardar y continuar y, luego, en Guardar en la página siguiente. Usa estos valores exactos de VID/PID, ya que los pasos posteriores del codelab dependen de ellos.
    Configura un proyecto
  9. Ahora verás tu integración en Integraciones de Matter.
  10. Reinicia la unidad central para asegurarte de que reciba la configuración del proyecto de integración de Matter más reciente. Si debes cambiar el VID o el PID más adelante, también deberás reiniciar el dispositivo después de guardar el proyecto para que el cambio se aplique. Consulta Cómo reiniciar los dispositivos Google Nest o Google Wifi para obtener instrucciones paso a paso sobre el reinicio.

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 en este codelab nos centraremos en Chef.

Chef es ambas cosas:

  • Una app de ejemplo que proporciona una interfaz de terminal y funciones de ajuste que también se encuentran en la app de examples/shell
  • Es una secuencia de comandos que adopta el principio de convención sobre 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 realiza 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. Las opciones que usaremos aquí son las siguientes:

  • -d: Define el tipo de dispositivo que se usará. En este caso, crearemos una app de iluminación con controles de encendido/apagado y de nivel.
  • -z: Invoca la herramienta de ZAP para generar los archivos fuente que implementan el tipo de dispositivo. Es decir, según la iluminación que elijas, ZAP creará automáticamente el código que se incorporará a la compilación y 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 RPC en el dispositivo Matter virtual para que otros componentes (como la GUI) puedan comunicarse con el dispositivo para establecer y recuperar atributos del modelo de datos.
  • -t linux: Es la plataforma de destino. Las plataformas compatibles 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.

Ejecuta el dispositivo

Matter usa el puerto TCP/UDP 5540, por lo que, si tienes un firewall en ejecución en tu computadora, ciérralo o permite las conexiones TCP/UDP entrantes en el puerto 5540.

Ejecuta el dispositivo virtual en el contenedor con el siguiente comando:

$ ./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 poner en funcionamiento tu dispositivo en Google Home.

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

Si quieres repetir todo el proceso de puesta en marcha desde el principio, tendrás que borrar esos archivos ejecutando el siguiente comando:

$ rm /tmp/chip*

5. Cómo poner en funcionamiento el dispositivo

Nota: Este paso solo se completará correctamente si ya configuraste tu proyecto en Google Home Developer Console.

Nest Hub

Se requiere una unidad central para poner en funcionamiento tu dispositivo en la estructura de Matter. Este es un dispositivo Google Nest, como el Nest Hub (2ª gen.), que admite Matter y que funcionará como router de borde para los dispositivos compatibles con Thread y como ruta de cumplimiento local para enrutar las intenciones de casa inteligente.

Consulta esta lista para ver qué concentradores admiten Matter.

Antes de comenzar el proceso de puesta en marcha, verifica lo siguiente:

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

Cómo obtener un código QR

El proceso de puesta en marcha necesita información de integración de Matter que se proporciona a través de un código QR. Examina el resultado de la consola de la aplicación de Matter, que contendrá un vínculo al código QR pertinente para la puesta en servicio.

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 Nuevo dispositivo.
  5. Selecciona tu casa y presiona Siguiente.
  6. La app de Google Home buscará tu dispositivo. Si aparece el mensaje "Se encontró un dispositivo Matter…", presiona "Sí". De lo contrario, presiona Configurar otro dispositivo y, luego, 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 debería comisionarse correctamente y aparecer como un ícono nuevo en la app de Google Home.

Bombilla vinculada en la app de Google Home

Solución de problemas

La puesta en marcha 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 correcta de VID y PID en la consola de Google Home y de no tener otros proyectos que usen la misma combinación de VID y PID.

La puesta en marcha falla después de que se muestra el mensaje "Analizando tu dispositivo" durante un período prolongado

6. Controlar el dispositivo

Una vez que el dispositivo compatible con Matter se haya puesto en funcionamiento correctamente y aparezca en la app de Google Home como una bombilla, puedes probar el control del dispositivo con diferentes métodos:

  • Usar Asistente de Google
  • Con la app de Google Home

Asistente de Google

Usa Asistente de Google en tu teléfono o dispositivo central para alternar el estado del dispositivo con comandos por voz, como "Hey Google, alterna mis luces".

Consulta la sección Cómo controlar los dispositivos inteligentes para la casa con comandos por voz en Cómo controlar los dispositivos inteligentes para la casa que se hayan agregado a la app de Google Home para obtener más ejemplos de comandos.

App de Google Home

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

Consulta la sección Cómo controlar dispositivos con la app de Google Home en Cómo controlar los dispositivos inteligentes para la casa que se hayan agregado a la app de Google Home para obtener más información.

7. ¡Felicitaciones!

Creaste correctamente tu primer dispositivo Matter. ¡Genial!

En este codelab aprendiste a hacer lo siguiente:

  • Instala un entorno de desarrollo de Matter.
  • Compila y ejecuta un dispositivo virtual de Matter.
  • Puesta en marcha y control de tu dispositivo virtual desde Google Home

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