Créer un appareil virtuel Matter

1. Introduction

Matter est un protocole de connectivité qui offre de nouvelles opportunités pour le développement d'appareils connectés. Dans cet atelier de programmation, vous allez créer votre premier appareil Matter à l'aide des ressources du SDK Matter.

Pour en savoir plus sur Matter, consultez le Centre pour les développeurs Google Home 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
  • Configurer et contrôler l'appareil Matter virtuel avec Google Home

Prérequis

  • Un hub, c'est-à-dire tout appareil Google Nest compatible avec Matter, comme le Nest Hub (2e génération).
  • Une machine Linux exécutant le système de fenêtrage X11.
  • Docker.
  • Git.
  • Connaissances de base de Linux.
    • Notez que le shell supposé pour toutes les commandes de cet atelier de programmation est BASH.

2. Configurer votre environnement

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 supposent que votre machine Linux exécute le système de fenêtrage X11. Si votre machine Linux exécute Wayland, assurez-vous que X.Org est également installé.

Configurer l'environnement de développement

  1. Installez Docker Engine (n'utilisez pas Docker Desktop).
  2. Clonez le SDK Matter et notez le commit que nous utilisons ci-dessous.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Exécutez un conteneur de compilation à l'aide des images CI publiques du SDK, puis exécutez l'appareil virtuel nouvellement créé à partir de ce conteneur. Recherchez l'image à utiliser correspondant à notre version du SDK, comme suit :
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Si vous utilisez le même commit, vous devriez voir ghcr.io/project-chip/chip-build:66First, forward xhost ports so we can later use UI applications:
    xhost local:1000
    Ensuite, démarrez le conteneur avec les ressources appropriées transférées depuis l'hôte (notre checkout SDK, les ressources réseau et les ressources d'affichage/de communication).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

Examinons 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 l'extrayant du registre Docker si nécessaire.
  • --ipc=host permet à Docker de partager l'espace de noms de communication interprocessus 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 qu'il puisse transmettre le trafic mDNS de l'hôte au conteneur et partager l'affichage X11 de l'hôte.
  • -e DISPLAY exporte $DISPLAY vers l'hôte, ce qui permet d'accéder à l'interface graphique de votre système. Cette étape est nécessaire pour exécuter l'outil ZAP lors de la modification des clusters Matter.
  • -it exécute Docker avec un terminal interactif (tty), au lieu d'un processus en arrière-plan.
  • --mount monte le SDK que nous avons extrait précédemment dans le conteneur.
  • --workdir définit le répertoire de travail au lancement sur notre répertoire SDK monté.

Vous pouvez également 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, vous créez un conteneur avec l'image spécifiée. Dans ce cas, vos anciennes données enregistrées dans une instance de conteneur précédente seront perdues. C'est parfois ce que vous souhaitez, car cela vous permet de commencer par une nouvelle installation. Toutefois, il peut arriver que vous préfériez enregistrer votre travail et la configuration de votre environnement entre les sessions.

Pour cette raison, une fois votre conteneur créé, vous pouvez l'arrêter pour éviter de perdre votre travail.

user@host> docker stop matter-container

Lorsque vous êtes prêt à exécuter à nouveau le conteneur, démarrez-le 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 dans votre conteneur avec :

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

Vous pouvez également démarrer une session root à l'aide de la commande suivante :

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

Configuration initiale de Matter

Initialiser le SDK

Initialisez le SDK Matter. Cette opération prendra plusieurs minutes.

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

Votre SDK Matter est maintenant initialisé. Pour réinitialiser rapidement l'environnement à l'avenir, exécutez la commande suivante :

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

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

Auparavant, nous avons accédé aux fichiers de votre machine hôte depuis le conteneur à l'aide d'un montage de liaison. Vous pouvez également écrire des fichiers dans le répertoire installé depuis le conteneur pour y accéder depuis l'hôte.

En général, utilisez des montages de liaison en exécutant votre conteneur avec l'argument supplémentaire --mount source=$(pwd),target=/workspace,type=bind pour monter votre répertoire de travail actuel dans le conteneur à l'adresse /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 monté doivent être gérées dans l'hôte.

Obtenez l'ID de groupe de l'utilisateur du conteneur depuis le 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 monté par le conteneur.

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

user@host> sudo chgrp -R 1000 .

Accordez au groupe les autorisations souhaitées dans le répertoire. Cet exemple accorde au groupe d'utilisateurs du conteneur les autorisations de lecture, d'écriture et d'exécution sur tous les fichiers du répertoire monté.

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 modifier 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 Google Home pour les développeurs

La console développeur 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 de la 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 sous certaines conditions. Pour en savoir plus, consultez Restrictions d'association.

Créer un projet de développeur

Commencez par accéder à la Google Home Developer Console :

  1. Cliquez sur Create Project (Créer un projet).
  2. Saisissez un nom de projet unique, puis cliquez sur 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, où vous pouvez consulter la documentation sur le développement Matter et en savoir plus sur certains outils.
  4. Lorsque vous êtes prêt à continuer, cliquez sur Suivant : Développer, ce qui affiche la page Check-list Matter.
  5. Cliquez sur Suivant : 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 du fournisseur (VID)", sélectionnez Test VID, puis 0xFFF1 dans le menu déroulant "Test VID". Dans "ID produit (PID)", saisissez 0x8000, puis cliquez sur Enregistrer et continuer, puis sur Enregistrer sur la page suivante. Utilisez ces valeurs exactes de VID/PID, car les étapes ultérieures 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 la plus récente du projet d'intégration Matter. Si vous devez modifier le VID ou le PID ultérieurement, vous devrez également redémarrer l'appareil après avoir enregistré le projet pour que la modification prenne effet. Pour savoir comment redémarrer votre appareil, consultez Redémarrer des appareils Google Nest ou Google Wifi.

4. Créer un appareil

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

Chef est à la fois :

  • Exemple d'application qui fournit une interface de terminal, avec des fonctionnalités également disponibles dans l'application examples/shell.
  • Script qui adopte le principe de convention plutôt que configuration pour encapsuler plusieurs tâches courantes nécessaires au développement d'un appareil compatible avec Matter.

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

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

Chef propose plusieurs options que vous pouvez afficher en exécutant chef.py -h. Les options que nous utilisons ici sont les suivantes :

  • -d : définit le type d'appareil à utiliser. Dans ce cas, nous créons une application d'éclairage avec des commandes d'activation/désactivation et de niveau.
  • -z : appelle l'outil ZAP pour générer les fichiers sources qui implémentent le type d'appareil. En d'autres termes, en fonction de votre choix d'éclairage, ZAP créera automatiquement le code à intégrer dans la compilation qui définit la lumière (le modèle de données) et la façon dont elle interagit avec d'autres appareils (le modèle d'interaction).
  • -b : builds.
  • -r : [facultatif] active le serveur RPC sur l'appareil Matter virtuel afin que d'autres composants (tels que l'interface utilisateur graphique) puissent communiquer avec l'appareil pour définir et récupérer les attributs du modèle de données.
  • -t linux : plate-forme cible. Les plates-formes compatibles 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 Matter virtuels.

Exécuter l'appareil

Matter utilise le port TCP/UDP 5540. Si un pare-feu est en cours d'exécution sur votre ordinateur, désactivez-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 intéresser à l'application Google Home pour pouvoir configurer votre appareil dans Google Home.

Arrêter l'appareil

Si vous devez arrêter l'appareil, vous pouvez quitter le programme avec CTRL+C. Si l'application ne se ferme pas, vous devrez peut-être également utiliser 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 devrez supprimer ces fichiers en exécutant la commande suivante :

$ rm /tmp/chip*

5. Mettre en service l'appareil

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

Nest Hub

Un hub est nécessaire pour mettre en service votre appareil sur le réseau Matter. Il s'agit d'un appareil Google Nest, tel que Nest Hub (2e génération), compatible avec Matter et qui servira à la fois de routeur de bordure pour les appareils compatibles avec Thread et de chemin d'exécution local pour le routage des intentions de maison connectée.

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

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

  • Votre hub est associé au même compte Google que celui que vous avez utilisé pour vous connecter à la Google Home Console.
  • Votre hub est connecté au même réseau Wi-Fi que l'ordinateur que vous utilisez pour exécuter votre appareil Matter virtuel.
  • Votre hub se trouve dans 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

Le processus de mise en service nécessite des informations d'intégration Matter fournies par le biais d'un code QR. Examinez la sortie de la console de l'application Matter, qui contient un lien vers le code QR correspondant à la mise en service.

Effectuer l'opération de mise en service

  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 celui généré par le site Web.
  8. Poursuivez la procédure d'association comme indiqué dans l'application Google Home.

Une fois ces étapes effectuées, l'appareil virtuel Matter devrait être correctement mis en service et s'afficher sous la forme d'une nouvelle icône dans l'application Google Home.

Ampoule associée dans l'application Google Home

Dépannage

L'association échoue et les messages d'erreur "Problème de connectivité" ou "Impossible de contacter Google" s'affichent

  • Assurez-vous d'avoir créé un projet avec la bonne combinaison VID/PID dans la console Google Home et qu'aucun autre projet n'utilise la même combinaison VID/PID.

L'association échoue après l'affichage du message "Recherche de votre appareil" pendant une longue période

6. Contrôler l'appareil

Une fois votre appareil compatible avec Matter mis en service et affiché sous la forme d'une ampoule dans l'application Google Home, vous pouvez tester le contrôle de l'appareil de différentes manières :

  • Utiliser l'Assistant Google
  • Avec l'application Google Home

Assistant Google

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

Pour obtenir d'autres exemples de commandes, consultez la section Contrôler vos appareils connectés par commande vocale de l'article Contrôler les appareils connectés via l'application Google Home.

Application Google Home

Vous pouvez appuyer sur les libellés Activé et Désactivé à côté de l'icône d'ampoule affichée dans l'application Google Home.

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

7. Félicitations !

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

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

  • Installez un environnement de développement Matter.
  • Créez et exécutez un appareil virtuel Matter.
  • Configurez et contrôlez votre appareil virtuel depuis Google Home.

Pour en savoir plus sur Matter, consultez les ressources suivantes :