Créer un appareil virtuel Matter

1. Introduction

Matter est un protocole de connectivité qui offre des opportunités intéressantes pour le développement d'appareils connectés. Dans cet atelier de programmation, vous allez créer votre premier appareil Matter à l'aide des SDK et des dépendances qui vous sont fournis dans une image Docker préconfigurée.

Pour en savoir plus sur Matter, consultez le Google Home Developer Center ou le site Web de la Connectivity Standards Alliance.

Points abordés

  • Configurer un environnement de compilation Matter
  • Créer un appareil Matter virtuel qui s'exécute sur votre ordinateur
  • Mettre en service et contrôler l'appareil virtuel Matter avec Google Home

Ce dont vous avez besoin

2. Configurer votre environnement

Nous utiliserons un conteneur Docker précédemment configuré sur une machine hôte Linux. Ce conteneur inclut toutes les dépendances nécessaires à la création et à l'exécution d'un appareil virtuel Matter.

Vérifier votre matériel

Les ordinateurs Windows et macOS ne sont pas compatibles avec cette installation Docker. Vous pouvez installer et compiler manuellement Matter sur macOS.

De plus, ces instructions partent du principe que votre ordinateur Linux exécute le système de fenêtrage X11. Si votre ordinateur Linux exécute Wayland, assurez-vous que X.Org est également installé.

Configurer Docker

  1. Installez Docker Engine (n'utilisez pas Docker Desktop).
  2. Extrayez l'image Docker de Docker Hub. Dans une fenêtre de terminal, exécutez:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    Cette opération peut prendre quelques minutes.
  3. Démarrez le conteneur Docker en cours d'exécution:
    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

Une fois le conteneur démarré, une sortie de diagnostic doit s'afficher, suivie d'un message confirmant que la configuration de votre conteneur est correcte, et enfin de l'invite de l'interface système du conteneur:

Environment looks good, you are ready to go!
$

Découvrons la commande Docker et les options que nous lui avons transmises:

  • xhost local:1000 permet au système X Window de recevoir des connexions de l'hôte local sur le port 1000, ce qui permet d'utiliser une interface utilisateur graphique.
  • docker run … image exécute l'image donnée en la extrayant du registre Docker si nécessaire.
  • --ipc=host permet à Docker de partager l'espace de noms de la communication inter-processus avec votre machine hôte.
  • --net=host permet à Docker d'utiliser la pile réseau de l'hôte dans le conteneur, ce qui est nécessaire pour transmettre le trafic mDNS de l'hôte au conteneur, et pour partager l'écran X11 de l'hôte.
  • -e DISPLAY exporte $DISPLAY vers l'hôte, ce qui vous permet d'accéder à l'interface graphique de votre système. Cette étape est nécessaire pour exécuter l'outil ZAP lorsque vous modifiez des clusters Matter.
  • -it exécute Docker avec un terminal interactif (tty) plutôt qu'en tant que processus en arrière-plan.

Vous pouvez éventuellement exécuter une deuxième instance de session de terminal:

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

Arrêter et démarrer le conteneur Docker Matter

Chaque fois que vous exécutez une commande docker run, un conteneur avec l'image spécifiée est créé. En procédant ainsi, vous perdrez vos anciennes données, qui ont été enregistrées sur une instance de conteneur précédente. C'est parfois ce que vous souhaitez, car cela vous permet de recommencer avec une nouvelle installation. Toutefois, vous pouvez parfois préférer enregistrer la configuration de votre travail et de votre environnement entre les sessions.

Par conséquent, après avoir créé votre conteneur, vous pouvez l'arrêter pour éviter de perdre votre travail.

user@host> docker stop matter-container

Lorsque vous êtes prêt à relancer l'exécution, démarrez le conteneur et ouvrez une fenêtre de terminal:

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

Vous pouvez ouvrir des sessions de terminal supplémentaires sur votre conteneur à l'aide de la commande suivante:

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

Ou démarrez une session racine à l'aide de la commande suivante:

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

Configuration initiale de Matter

Lorsque votre terminal s'ouvre, il se trouve déjà dans le dépôt cloné Matter à ~/connectedhomeip. Aucune étape de configuration supplémentaire de Matter n'est nécessaire.

Partager des fichiers entre l'hôte et le conteneur

Pour accéder aux fichiers de votre machine hôte à partir du conteneur, vous pouvez utiliser une installation liée. Vous pouvez également écrire des fichiers dans le répertoire installé à partir du conteneur pour un accès facile depuis l'hôte.

Exécutez votre conteneur avec l'argument supplémentaire --mount source=$(pwd),target=/workspace,type=bind pour installer votre répertoire de travail actuel dans le conteneur à l'emplacement /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

Les autorisations de l'utilisateur du conteneur sur le répertoire installé doivent être gérées sur l'hôte.

Obtenez l'ID de groupe de l'utilisateur du conteneur à partir du conteneur.

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

Ouvrez une autre session de terminal sur l'hôte du conteneur et définissez le répertoire de travail sur le répertoire installé par le conteneur.

Définissez le groupe des fichiers du répertoire installé de manière récursive sur le groupe de l'utilisateur du conteneur.

user@host> sudo chgrp -R 1000 .

Accordez au groupe les autorisations souhaitées dans l'annuaire. Cet exemple accorde au groupe de l'utilisateur du conteneur des autorisations de lecture, d'écriture et d'exécution sur tous les fichiers du répertoire installé.

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

Notez que ces commandes n'ont aucune incidence sur les autorisations des nouveaux fichiers créés par l'utilisateur hôte. N'oubliez pas de mettre à jour les autorisations des nouveaux fichiers créés dans l'hôte si nécessaire.

Vous pouvez ajouter votre utilisateur hôte au groupe de l'utilisateur du conteneur pour hériter des autorisations sur les fichiers créés par l'utilisateur du conteneur.

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

3. Console pour les développeurs Google Home

La console développeur de Google Home est l'application Web qui vous permet de gérer vos intégrations Matter avec Google Home.

Tout appareil Matter ayant obtenu la certification Matter Connectivity Standards Alliance (Alliance) fonctionne dans l'écosystème Google Home. Les appareils en cours de développement qui n'ont pas été certifiés peuvent être mis en service dans l'écosystème Google Home dans certaines conditions. Pour en savoir plus, consultez la section Restrictions liées à l'association.

Créer un projet de développement

Commencez par accéder à la console Google Home pour les développeurs:

  1. Cliquez sur Créer un projet.
  2. Saisissez un nom de projet unique, puis cliquez sur Create project (Créer un projet). Boîte de dialogue "Créer un projet"
  3. Cliquez sur + Ajouter une intégration pour accéder à l'écran Ressources Matter. Vous y trouverez la documentation sur le développement de Matter et des informations sur certains outils.
  4. Lorsque vous êtes prêt à continuer, cliquez sur Next: Develop (Suivant : Développer). La page Matter checklist s'affiche.
  5. Cliquez sur Étape suivante: Configuration.
  6. Sur la page Configuration, saisissez le nom de votre produit.
  7. Cliquez sur Sélectionner le type d'appareil, puis sélectionnez le type d'appareil dans le menu déroulant (dans ce cas, Light).
  8. Dans "ID fournisseur" (VID), sélectionnez VID test, puis "0xFFF1" dans le menu déroulant VID test. Dans le champ "ID produit (PID), saisissez 0x8000, cliquez sur Enregistrer et continuer, puis sur Enregistrer sur la page suivante. Utilisez ces valeurs VID/PID exactes (les prochaines étapes de l'atelier de programmation en dépendent).
    Configurer un projet
  9. Votre intégration s'affiche désormais sous Intégrations Matter.
  10. Redémarrez votre hub pour vous assurer qu'il reçoit la configuration de projet d'intégration Matter la plus récente. Si vous devez modifier le VID ou le PID par la suite, vous devrez également redémarrer après avoir enregistré le projet pour que la modification soit prise en compte. Pour obtenir des instructions détaillées sur le redémarrage, consultez Redémarrer des appareils Google Nest ou Google Wifi.

4. Créer un appareil

Tous les exemples dans Matter se trouvent dans le dossier examples du dépôt GitHub. Plusieurs exemples sont disponibles, mais cet atelier de programmation porte sur Chef.

Chef est à la fois:

  • Une application exemple qui fournit une interface de terminal et encapsule des fonctionnalités également disponibles dans l'application examples/shell.
  • Script qui adopte le principe de privilégier les conventions afin d'encapsuler plusieurs des tâches courantes nécessaires au développement d'un appareil compatible avec Matter.

Accédez au dossier d'exemple Chef et créez votre premier build Matter:

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

Chef propose plusieurs options qui peuvent être consultées en exécutant chef.py -h. Les options que nous utilisons ici sont les suivantes:

  • -d: définit le type d'appareil à utiliser. Dans le cas présent, nous allons créer une application d'éclairage avec des commandes Marche/Arrêt et des commandes de niveau.
  • -z: appelle l'outil ZAP pour générer les fichiers sources qui implémentent le type d'appareil. Autrement dit, en fonction de l'éclairage choisi, l'équipe ZAP crée automatiquement du code à intégrer dans le build qui définit la lumière (le modèle de données) et la manière dont elle interagit avec d'autres appareils (le modèle d'interaction).
  • -b: compilations.
  • -r: [facultatif] active le serveur RPC sur l'appareil virtuel Matter afin que d'autres composants (tels que l'IUG) puissent communiquer avec l'appareil pour définir et récupérer des attributs de modèle de données.
  • -t linux: plate-forme cible Les plates-formes d'assistance sont linux, nrfconnect et esp32. Vous pouvez exécuter ./chef.py -h pour afficher toutes les commandes disponibles et les plates-formes cibles compatibles. linux est utilisé pour les appareils virtuels Matter.

Exécuter l'appareil

Matter utilise le port TCP/UDP 5540. Par conséquent, si un pare-feu est en cours d'exécution sur votre ordinateur, éteignez-le ou autorisez les connexions TCP/UDP entrantes sur le port 5540.

Exécutez l'appareil virtuel dans le conteneur avec la commande suivante:

$ ./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]

Laissez votre appareil en marche. Nous allons maintenant nous concentrer sur l'application Google Home pour pouvoir mettre votre appareil en service.

Arrêter l'appareil

Si vous devez arrêter le périphérique, vous pouvez quitter le programme avec CTRL+C. Si l'application ne se ferme pas, vous devrez peut-être également utiliser les touches Ctrl+\.

Les identifiants de votre appareil virtuel sont stockés dans le répertoire /tmp/, dans des fichiers commençant par le préfixe chip.

Si vous souhaitez répéter l'ensemble du processus de mise en service depuis le début, vous devez supprimer ces fichiers en exécutant la commande suivante:

$ rm /tmp/chip*

5. Contrôleur d'appareil virtuel

Cette application autonome fournit une interface utilisateur graphique pour contrôler et afficher les états de vos appareils virtuels Matter. Il utilise un client RPC pour communiquer avec les appareils Matter connectés à votre environnement de développement.

Contrôleur d'appareil virtuel

Le contrôleur d'appareil virtuel offre une représentation visuelle de votre appareil virtuel.

Vous pouvez interagir avec l'appareil virtuel via l'interface utilisateur graphique (IUG) du contrôleur d'appareil virtuel. Les modifications que vous apportez à l'IUG affectent le modèle de données sous-jacent. Consultez la section Appareils compatibles pour obtenir la liste complète des types d'appareils virtuels Matter compatibles.

Installer le contrôleur d'appareil virtuel

Le contrôleur d'appareil virtuel est préinstallé sur le conteneur Docker Ubuntu LTS 20.04.

Exécuter le contrôleur d'appareil virtuel

Créez la deuxième instance de session de terminal:

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

Démarrez le contrôleur d'appareil virtuel en fournissant le socket réseau qui sera utilisé pour communiquer avec l'appareil virtuel:

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

Si vous démarrez le contrôleur sans fournir d'arguments, il utilisera par défaut l'option de socket réseau via le port localhost 33000. Une fois que la manette se connecte à l'appareil virtuel, elle affiche un écran indiquant l'état de votre appareil:

Interface utilisateur graphique de l'appareil virtuel

L'application envoie des requêtes au serveur RPC de l'appareil lorsque vous apportez des modifications à l'application Virtual Controller et interroge le serveur RPC une fois par seconde pour récupérer l'état.

Vous pouvez également utiliser l'application Virtual Device Controller pour récupérer le code QR lors de la mise en service de votre appareil. Cliquez sur l'icône de code QR située à côté de l'image de l'appareil pour afficher le code QR correspondant. Utilisez ce code QR pour mettre votre appareil en service.

6. Mettre l'appareil en service

Remarque: Cette étape ne fonctionne que si vous avez déjà configuré votre projet dans la Google Home Developer Console.

Nest Hub

Un hub est nécessaire pour mettre votre appareil en service sur la technologie Matter. Il s'agit d'un appareil Google Nest, comme Nest Hub (2e génération), qui est compatible avec Matter et qui sert à la fois de routeur de bordure pour les appareils compatibles Thread et de chemin de traitement local pour acheminer les intents de la maison connectée.

Consultez cette liste pour savoir quels hubs sont compatibles avec Matter.

Avant de commencer la mise en service, vérifiez les points suivants:

  • Votre hub est associé au compte Google que vous avez utilisé pour vous connecter à la console Google Home.
  • Votre hub est connecté au même réseau Wi-Fi que l'ordinateur que vous utilisez pour exécuter votre appareil Virtual Matter.
  • Votre hub a la même structure que celle que vous utilisez dans l'application Google Home (la "maison" dans le Google Home Graph représente votre structure).

Obtenir un code QR

Pour la mise en service, les informations d'intégration Matter doivent être fournies via un code QR. Vous pouvez obtenir le code QR de votre appareil virtuel auprès du contrôleur d'appareil virtuel.

Effectuer l'opération de commission

  1. Ouvrez l'application Google Home.
  2. Appuyez sur + en haut à gauche.
  3. Appuyez sur Configurer un appareil.
  4. Appuyez sur Nouvel appareil.
  5. Sélectionnez votre maison, puis appuyez sur Suivant.
  6. L'application Google Home recherche votre appareil. Si le message "Appareil Matter détecté..." s'affiche, appuyez sur "Oui". Sinon, appuyez sur Configurer un autre appareil, puis sélectionnez Appareil Matter dans la liste des appareils.
  7. Dirigez l'appareil photo vers le code QR de votre appareil ou le code QR généré par le site Web.
  8. Continuez le processus d'association comme indiqué dans la procédure de l'application Google Home.

Une fois ces étapes terminées, l'appareil virtuel Matter devrait être mis en service et une nouvelle icône devrait apparaître dans l'application Google Home.

Ampoule associée dans l'application Google Home

Dépannage

Échec de la mise en service : messages d'erreur "Problème de connectivité" ou "Impossible de contacter Google"

  • Assurez-vous d'avoir créé un projet avec la bonne combinaison VID/PID dans la console Google Home et que vous n'avez pas d'autres projets utilisant la même combinaison VID/PID.

La mise en service échoue après un long processus d'analyse de l'appareil

7. Contrôler l'appareil

Une fois que votre appareil compatible avec Matter est mis en service et qu'il apparaît dans l'application Google Home en tant qu'ampoule, vous pouvez tester son contrôle selon différentes méthodes:

  • Avec l'Assistant Google
  • Depuis l'application Google Home
  • Utiliser l'IUG de l'appareil virtuel

Assistant Google

Utilisez l'Assistant Google sur votre téléphone ou votre hub pour modifier l'état de l'appareil à partir de commandes vocales, par exemple en disant "Hey Google, active mes lumières".

Pour obtenir d'autres exemples de commandes, consultez la section Contrôler vos appareils connectés à l'aide de commandes vocales de l'article Contrôler les appareils connectés ajoutés à l'application Google Home.

Application Google Home

Vous pouvez appuyer sur les boutons Activé ou Désactivé à côté de l'icône représentant une ampoule dans l'application Google Home.

Pour en savoir plus, consultez la section Contrôler des appareils avec l'application Google Home dans l'article Contrôler les appareils connectés ajoutés à l'application Google Home.

IUG de l'appareil virtuel

Vous pouvez interagir avec l'IUG de l'appareil virtuel pour modifier l'état de l'appareil. Que vous contrôliez l'appareil virtuel avec la télécommande d'appareil virtuel, l'application Google Home sur votre téléphone ou avec votre hub, toutes ces interfaces reflèteront l'état actuel de l'appareil virtuel.

8. Félicitations !

Vous avez créé votre premier appareil Matter. Parfait !

Dans cet atelier de programmation, vous avez appris ce qui suit :

  • Installez un environnement de développement Matter à l'aide d'une image Docker pré-empaquetée.
  • Créez et exécutez un appareil virtuel Matter.
  • Mettez en service et contrôlez votre appareil virtuel depuis Google Home.

Pour en savoir plus sur Matter, consultez ces références: