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
- Installez Docker Engine (n'utilisez pas Docker Desktop).
- 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
- 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:
Si vous utilisez le même commit, vous devriez voir le messagebuildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}') echo $buildimage
ghcr.io/project-chip/chip-build:66
Commencez par transférer les ports xhost afin que nous puissions utiliser ultérieurement des applications d'interface utilisateur: 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).xhost local:1000
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:
- Cliquez sur Create Project (Créer un projet).
- Saisissez un nom de projet unique, puis cliquez sur Créer un projet.
- 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.
- Lorsque vous êtes prêt à continuer, cliquez sur Suivant: Développer. La page Checklist Matter s'affiche.
- Cliquez sur Suivant: Configuration.
- Sur la page Configuration, saisissez le nom de votre produit.
- Cliquez sur Sélectionner un type d'appareil, puis sélectionnez le type d'appareil dans le menu déroulant (dans ce cas,
Light
). - 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).
- Votre intégration s'affiche désormais sous Intégrations Matter.
- 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 sontlinux
,nrfconnect
etesp32
. 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
- Ouvrez l'application Google Home.
- Appuyez sur + en haut à gauche.
- Appuyez sur Configurer un appareil.
- Appuyez sur Nouvel appareil.
- Sélectionnez votre maison et appuyez sur Suivant.
- 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.
- Dirigez l'appareil photo vers le code QR de votre appareil ou le code QR généré par le site Web.
- 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.
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
- Vérifiez que le pare-feu de votre ordinateur est désactivé et que vous exécutez l'appareil virtuel.
- Débranchez toutes les interfaces réseau physiques (Ethernet) pour vous assurer que votre ordinateur utilise exclusivement le Wi-Fi.
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:
- Consultez l'introduction à Matter dans le Google Home Developer Center pour découvrir les principes de base de Matter.
- Spécification Matter, bibliothèque d'appareils Matter et bibliothèque de clusters d'applications Matter, publiées par la Connectivity Standards Alliance.
- Dépôt GitHub Matter