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 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 virtuel Matter qui s'exécute sur votre ordinateur
  • Mettre en service et contrôler un appareil virtuel Matter avec Google Home

Prérequis

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

2. Configurer votre environnement

Vérifiez 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 dans ce qui suit.
    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. Localisez 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 le message ghcr.io/project-chip/chip-build:66Commencez par transférer les ports xhost afin que nous puissions utiliser ultérieurement des applications d'interface utilisateur:
    xhost local:1000
    Ensuite, démarrez le conteneur avec les ressources appropriées transférées depuis l'hôte (nos ressources SDK de paiement, de mise en réseau et 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

Voyons à présent 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 1 000, 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 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'affichage X11 de l'hôte.
  • -e DISPLAY exporte $DISPLAY vers l'hôte et donne accès à l'interface graphique de votre système. Cela est nécessaire pour exécuter l'outil ZAP lors de la modification de clusters Matter.
  • -it exécute Docker avec un terminal interactif (tty), plutôt qu'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 le répertoire du SDK installé.

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, 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 faire, car cela vous permet de commencer par une nouvelle installation. Mais il peut arriver que vous préfériez conserver votre travail et la configuration 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 à exécuter à nouveau le projet, 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

Vous pouvez aussi démarrer une session racine à 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 prend 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

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

En règle générale, utilisez les montages "Lier" 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'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.

Récupérez l'identifiant du 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 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 au groupe les autorisations souhaitées dans l'annuaire. Cet exemple donne 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 afin d'hériter des autorisations sur les fichiers qu'il a créés.

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

3. Console développeur de 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.

Tous les appareils Matter qui ont obtenu la certification Matter de la Connectivity Standards Alliance (Alliance) fonctionnent 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éveloppement

Commencez par accéder à la console développeur de Google Home:

  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. Vous y trouverez la documentation sur le développement Matter et certains outils.
  4. Lorsque vous êtes prêt à continuer, cliquez sur Suivant: Développer. La page Checklist Matter s'affiche.
  5. Cliquez sur Suivant: Configuration.
  6. Sur la page Configuration, saisissez le nom de votre produit.
  7. Cliquez sur Sélectionner un type d'appareil, puis sélectionnez le type d'appareil dans le menu déroulant (dans ce cas, Light).
  8. Sous "ID fournisseur", sélectionnez Tester le VID, puis "0xFFF1" dans le menu déroulant "Tester le VID". Dans "Identifiant produit", saisissez "0x8000", puis cliquez sur Enregistrer et continuer, puis cliquez sur Enregistrer sur la page suivante. Utilisez ces valeurs VID/PID exactes (les prochaines étapes de l'atelier de programmation en dépendront).
    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 ultérieurement, vous devrez également redémarrer après avoir enregistré le projet pour que la modification soit prise en compte. Pour obtenir des instructions de redémarrage détaillées, consultez l'article 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:

  • Exemple d'application qui fournit une interface de terminal, encapsulant les fonctionnalités également disponibles sur l'application examples/shell.
  • Script qui adopte le principe de la convention sur la configuration pour 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 quelques options qui peuvent être affiché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 créons une application d'éclairage avec des commandes d'activation/de désactivation et de réglage du 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 que vous choisissez, ZAP créera automatiquement du code à intégrer au 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: builds.
  • -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 les 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, arrêtez-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 allumé. Nous allons maintenant nous intéresser à l'application Google Home afin de mettre en service votre appareil.

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 devez supprimer ces fichiers en exécutant la commande suivante:

$ rm /tmp/chip*

5. Mettre l'appareil en service

Remarque: Cette étape ne peut aboutir 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 la structure Matter. Il s'agit d'un appareil Google Nest, tel que Nest Hub (2e génération), compatible avec Matter. Il servira à la fois de routeur de bordure pour les appareils compatibles avec Thread et de chemin de traitement local pour router les intents de la maison connectée.

Consultez cette liste pour voir 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 virtuel Matter.
  • Votre hub présente la même structure que celle de l'application Google Home. (La "maison" dans le graphique Google Home représente votre structure.)

Obtenir un code QR

Pour le processus de mise en service, les informations d'intégration Matter doivent être fournies via un code QR. Examinez la sortie de la console de l'application Matter qui contiendra un lien vers le code QR correspondant à la mise en service.

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 et 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. Poursuivez 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 devrait apparaître sous la forme d'une nouvelle icône dans l'application Google Home.

Ampoule associée dans l'application Google Home

Dépannage

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

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

Échec de la mise en service après "Analyse de votre appareil" pendant une longue période

6. Contrôler l'appareil

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

  • Utilisation de l'Assistant Google.
  • Depuis l'application Google Home

Assistant Google

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

Pour découvrir d'autres exemples de commandes, consultez la section Contrôler vos appareils connectés avec des commandes vocales 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 représentant une ampoule dans l'application Google Home.

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

7. Félicitations !

Vous venez de créer votre premier appareil Matter. Parfait !

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

  • Installer un environnement de développement Matter
  • 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: