¡Atención! Pronto se lanzarán nuevos programas de vista previa para desarrolladores. Postúlate aquí y sé una de las primeras personas en probar herramientas nuevas y enviar comentarios.

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 que se proporcionan en una imagen de Docker preconfigurada.

Para obtener más 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 encargar y controlar el dispositivo virtual Matter con Google Home

Requisitos

  • Un concentrador, que es cualquier dispositivo Google Nest compatible con Matter, como el Nest Hub (2a generación). Puedes comprar un hub en Google Store o en tu tienda preferida.
  • Una máquina Linux que ejecuta el sistema de ventanas X11
  • Docker
  • Conocimientos básicos de Linux

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 Matter.

Revisa tu hardware

Por el momento, las computadoras con Windows y MacOS no son compatibles con la instalación de Docker. Puedes instalar y compilar Matter de forma manual 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 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. Ejecuta el siguiente comando en una ventana de la terminal:
    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ía ver un resultado de diagnóstico seguido de un mensaje que afirme que su configuración del contenedor es correcta y, finalmente, el indicador de shell del contenedor:

Environment looks good, you are ready to go!
$

Veamos el comando 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 que se use 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 mDNS del host al contenedor, y compartir la pantalla X11 del host.
  • -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 editas clústeres de Matter.
  • -it ejecuta Docker con una terminal interactiva (tty), en lugar de como proceso en segundo plano.

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

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

user@host> docker stop matter-container

Cuando esté listo para volver a ejecutarse, inicie el contenedor y abra una ventana de la 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

O inicia una sesión raíz con:

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 (~/connectedhomeip). No se necesitan pasos adicionales de configuración de Matter.

Comparte archivos entre el host y el contenedor

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

Ejecuta el 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 desde el contenedor.

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

Abra otra sesión de la terminal en el host del contenedor y configure el directorio de trabajo en el directorio que activa el contenedor.

De manera recurrente, establece el grupo de archivos en el directorio activado en el grupo del usuario del contenedor.

user@host> sudo chgrp -R 1000 .

Otorga los permisos deseados en el directorio al grupo. En este ejemplo, se otorgan 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 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 del programador de Google Home

La Consola del programador de Google Home es la aplicación web en la que puedes administrar las integraciones de Matter con Google Home.

Cualquier dispositivo Matter que haya aprobado la certificación CSA Matter funciona en el ecosistema de Google Home. Los dispositivos en desarrollo que no están certificados pueden ser asignados en el ecosistema de Google Home en ciertas condiciones. Consulta las restricciones de sincronización para obtener más información.

Crea un proyecto de desarrollador

Primero, ve a la Consola para programadores de Google Home:

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

  1. Ingresa un nombre de proyecto único y, luego, haz clic en Crear proyecto nuevo. Cuadro de diálogo Crear proyecto nuevo
  2. Haz clic en + Agregar integración para ir 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. Haga clic en Siguiente: Configuración.
  5. En la página Configuración, ingresa el Nombre del producto.
  6. Haga clic en Select device type y seleccione el tipo de dispositivo en el menú desplegable (en este caso, Light).
  7. En Vendor ID (VID), selecciona Test VID y selecciona 0xFFF1 en el menú desplegable Test VID. En ID del producto (PID), ingresa 0x8000, haz clic en Guardar y continuar y, luego, haz clic en Guardar en la siguiente página.
    Configura un proyecto
  8. Ahora verás un dispositivo Matter en integraciones de Matter. Integraciones de Matter
  9. Reinicia el 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 el cambio se efectúe.

4. Crea 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 está en Chef.

Chef sirve para lo siguiente:

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

Navega a la carpeta de ejemplo de Chef y haz 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 usamos son las siguientes:

  • -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 nivel.
  • -z: Invoca la herramienta ZAP para generar los archivos de origen que implementan el tipo de dispositivo. Es decir, según la 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 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 Matter virtuales.

Ejecuta el dispositivo

Matter usa el puerto TCP/UDP 5540, por lo que si ejecutas un firewall en tu computadora, ciérralo o permite 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, pasaremos la atención a la app de Google Home para que puedas poner el dispositivo en funcionamiento en la plataforma.

Detener el dispositivo

Puedes salir del programa con las teclas 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, deberá borrar esos archivos mediante la ejecución del siguiente comando:

$ rm /tmp/chip*

5. El controlador de dispositivo virtual

El dispositivo virtual es una aplicación independiente que proporciona una interfaz gráfica de usuario para controlar y mostrar los estados de los dispositivos virtuales Matter. Usa un cliente 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 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. Actualmente, el controlador de dispositivo virtual admite el tipo de dispositivo atenuable.

Instala el controlador de dispositivo virtual

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

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
$

Inicia el controlador del dispositivo virtual proporcionando 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 RPC del dispositivo cuando realizas cambios en la aplicación del controlador virtual y sondea el servidor de RPC una vez por segundo para recuperar el estado.

La app de Virtual Device Controller también se puede usar para recuperar el código QR como parte de tu flujo de puesta en marcha del dispositivo. Haz clic en el ícono del código QR que aparece junto a la imagen del dispositivo para mostrar el código QR.

Código QR

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

6. Asignar el dispositivo

Nota: Este paso será exitoso solo si ya configuraste tu proyecto en Google Home Developer Console.

Nest Hub

Se requiere un concentrador para poner en marcha el dispositivo en la tela Matter. Este es un dispositivo Google Nest, como el Nest Hub (2a generación), que admite Matter y que funcionará 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 asignación, verifica que se cumplan las siguientes condiciones:

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

Obtener un código QR

El proceso de puesta en marcha necesita la 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 desde el controlador de dispositivo virtual.

Realiza la operación de comisión

  1. Abre la app de Google Home.
  2. Presiona el signo + que aparece 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 de 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 del 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 Matter se pondrá en marcha con éxito 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 marcha 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 VID/PID correcta en Google Home Console y de que no tengas otros proyectos que usen la misma combinación VID/PID.

La puesta en marcha falla después de "escanear el dispositivo" durante un período prolongado.

7. Controlar el dispositivo

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

  • Con el 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".

Consulta la sección Cómo controlar dispositivos del hogar inteligente con comandos por voz del artículo Cómo agregar dispositivos del hogar inteligente a la app de Google Home para ver más ejemplos de comandos.

App de Google Home

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

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

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 hub, 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 Matter mediante una imagen de Docker empaquetada previamente
  • Compila y ejecuta un dispositivo virtual Matter.
  • Asigna y controla el dispositivo virtual desde Google Home.

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