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 de ressources du SDK Matter.

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 Matter virtuel avec Google Home

Ce dont vous avez besoin

  • Un hub, qui est un 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 l'interface système supposée 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 Matter manuellement 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 dans la suite.
    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:66Tout d'abord, transférez les ports xhost afin de pouvoir utiliser ultérieurement les applications d'interface utilisateur :
    xhost local:1000
    Ensuite, démarrez le conteneur avec les ressources appropriées transférées depuis l'hôte (notre extraction du SDK, la mise en 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 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 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. Cela 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 installe le SDK que nous avons précédemment extrait dans le conteneur.
  • --workdir définit le répertoire de travail au lancement sur notre répertoire SDK installé.

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, qui ont été enregistrées sur une instance de conteneur précédente, seront perdues. C'est parfois ce que vous voulez, car cela vous permet de commencer par une nouvelle installation. Mais il arrive que vous préfériez enregistrer votre travail et la configuration de l'environnement entre les sessions.

Pour cette raison, 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 à exécuter à nouveau, 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 dans votre conteneur avec :

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

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

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 :

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'une installation 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 installations de liaison en exécutant 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'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 installé 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 installé par le conteneur.

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

user@host> sudo chgrp -R 1000 .

Accordez les autorisations souhaitées dans le répertoire au groupe. 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 pas d'incidence sur l'autorisation 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. Google Home Developer Console

La Google Home Developer Console est l'application Web dans laquelle vous gérez 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 Create project (Créer un projet). Boîte de dialogue "Créer un projet"
  3. Cliquez sur + Add integration (+ Ajouter une intégration), ce qui vous redirige vers l'écran Matter resources (Ressources Matter), où vous pouvez consulter la documentation de développement Matter et en savoir plus sur certains outils.
  4. Lorsque vous êtes prêt à continuer, cliquez sur Next: Develop (Suivant : développer), ce qui affiche la page Matter checklist (Liste de contrôle Matter).
  5. Cliquez sur Next: Setup (Suivant : configuration).
  6. Sur la page Setup (Configuration), saisissez le Product name (Nom du produit).
  7. Cliquez sur Select device type (Sélectionner le type d'appareil), puis sélectionnez le type d'appareil dans le menu déroulant (dans ce cas, Light).
  8. Dans Vendor ID (VID) (ID de fournisseur), sélectionnez Test VID (ID de test), puis sélectionnez 0xFFF1 dans le menu déroulant Test VID. Dans Product ID (PID) (ID de produit), saisissez 0x8000, puis cliquez sur Save &continue (Enregistrer et continuer), puis sur Save (Enregistrer) sur la page suivante. Utilisez ces valeurs VID/PID exactes, 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 Matter integrations (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 après avoir enregistré le projet pour que la modification prenne effet. 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 de Matter se trouvent dans le dossier examples du dépôt GitHub. Plusieurs exemples sont disponibles, mais cet atelier de programmation se concentre sur Chef.

Chef est à la fois :

  • Une application exemple qui fournit une interface de terminal, en encapsulant des fonctionnalités également disponibles dans l'application examples/shell.
  • Un script qui adopte le principe de convention plutôt que de 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 première compilation Matter :

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

Chef propose quelques options qui peuvent être affichées en exécutant chef.py -h. Voici les options que nous utilisons ici :

  • -d : définit le type d'appareil à utiliser. Dans ce cas, nous créons une application d'éclairage avec des commandes d'activation/de désactivation et 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 votre choix d'éclairage, ZAP crée automatiquement du code à intégrer dans la compilation qui définit la lumière (le modèle de données) et son interaction avec d'autres appareils (le modèle d'interaction).
  • -b : compile.
  • -r : [facultatif] active le serveur RPC sur l'appareil Matter virtuel afin que d'autres composants (tels que l'interface 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. Par conséquent, 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 :

$ ./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 cours d'exécution. Nous allons maintenant nous concentrer sur l'application Google Home afin de pouvoir mettre en service votre appareil dans Google Home.

Arrêter l'appareil

Si vous devez arrêter l'appareil, vous pouvez quitter le programme en appuyant sur 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 devez supprimer ces fichiers en exécutant la commande suivante :

$ rm /tmp/chip*

5. Mettre en service l'appareil

Remarque : Cette étape ne réussira 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 le 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 intents Smart Home.

Consultez cette liste pour voir 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 se trouve sur le 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 votre application Google Home. (La "maison" du graphique Google Home représente votre structure.)

Obtenir un QR code

Le processus de mise en service nécessite des informations d'intégration Matter fournies via un QR code. Examinez la sortie de la console de l'application Matter, qui contient un lien vers le QR code pertinent pour 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 Set up device (Configurer un appareil).
  4. Appuyez sur New device (Nouvel appareil).
  5. Sélectionnez votre maison, puis appuyez sur Next (Suivant).
  6. L'application Google Home recherche votre appareil. Si le message "Matter Device found..." (Appareil Matter détecté...) s'affiche, appuyez sur "Yes" (Oui). Sinon, appuyez sur Set up a different device (Configurer un autre appareil), puis sélectionnez Matter device (Appareil Matter) dans la liste des appareils.
  7. Dirigez votre caméra vers le QR code de votre appareil ou le QR code généré par le site Web.
  8. Poursuivez le processus d'association comme indiqué dans le flux de l'application Google Home.

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

Ampoule associée dans l'application Google Home

Dépannage

La mise en service échoue avec les messages d'erreur "Connectivity problem" (Problème de connectivité) ou "Could not contact Google" (Impossible de contacter Google)

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

La mise en service échoue après une longue période de "Scanning your device" (Analyse de votre appareil)

6. Contrôler l'appareil

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

  • Avec 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, allume mes lumières".

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

Application Google Home

Vous pouvez appuyer sur les libellés On (Activé) et Off (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 les appareils avec l'application Google Home de 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 :

  • Installer un environnement de développement Matter.
  • Créer et exécuter un appareil Matter virtuel.
  • Mettre en service et contrôler votre appareil virtuel depuis Google Home.

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