Action requise ! À compter du 21 novembre 2022, Nest Hub a activé le Programme Preview pour intégrer Matter 1.0 en prévision de la disponibilité générale de Google en matière de Matter. Tous les appareils Matter utilisés avec le programme Preview devront être mis à jour. Pour en savoir plus, consultez les notes de version.

Créer un appareil virtuel Matter

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

1. Présentation

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

Prérequis

  • Hub, c'est-à-dire tout appareil Google Nest compatible avec Matter, comme Nest Hub (2e génération). Vous pouvez acheter un hub sur le Google Store ou chez le revendeur de votre choix.
  • Machine Linux exécutant le système de fenêtrage X11
  • Docker
  • Connaissances de base de Linux

2. Configurer votre environnement

Nous allons utiliser 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 actuellement pas compatibles avec cette installation Docker. Vous pouvez installer et créer manuellement Matter sous macOS ou Windows.

En outre, 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 Docker

  1. Installez Docker Engine (n'utilisez pas Docker Desktop).
  2. Extraire 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
    

Après avoir démarré le conteneur, vous devriez voir un résultat de diagnostic suivi d'un message confirmant que la configuration de votre conteneur est correcte, et enfin, l'invite de l'interface système du conteneur:

Environment looks good, you are ready to go!
$

Penchons-nous sur la commande Docker et sur les options que nous lui avons transmises:

  • xhost local:1000 permet au système Windows X de recevoir des connexions provenant 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 et l'extrait 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 transmette 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, ce qui vous donne accès à l'interface graphique de votre système. Cette opération est nécessaire pour exécuter l'outil ZAP lorsque vous modifiez des clusters Matter.
  • -it exécute Docker avec un terminal interactif (tty) au lieu d'un 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, vous créez un conteneur avec l'image spécifiée. Vos anciennes données, qui ont été enregistrées sur une instance de conteneur antérieure, seront perdues. C'est parfois ce que vous souhaitez faire, car cela vous permet de repartir de zéro. Toutefois, il peut arriver que vous préfériez enregistrer la configuration de votre environnement de travail et de votre environnement entre deux sessions.

C'est pourquoi, 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 dans votre conteneur avec:

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

Ou démarrez une session racine en utilisant:

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

Configuration initiale du litige

Lorsque votre terminal s'ouvre, il se trouve déjà dans le dépôt cloné Matter à l'adresse ~/connectedhomeip. Aucune autre étape de configuration du litige 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 un support de liaison. Vous pouvez également écrire des fichiers dans le répertoire installé à partir du conteneur pour y accéder facilement 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'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 du groupe d'utilisateurs 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éfinir de manière récursive le groupe pour les fichiers du répertoire installé sur le groupe de l'utilisateur du conteneur.

user@host> sudo chgrp -R 1000 .

Attribuez au groupe les autorisations souhaitées dans l'annuaire. Cet exemple donne au groupe d'utilisateurs du conteneur l'autorisation de lire, écrire et exécuter tous les fichiers du répertoire installé.

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

Notez que ces commandes n'ont aucune incidence sur l'autorisation d'accès aux 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 d'utilisateurs du conteneur pour qu'il hérite 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.

Tout appareil Matter ayant obtenu la certification CSA Matter fonctionne dans l'écosystème Google Home.

Créer un projet de développeur

Pour commencer, accédez à la console développeur de Google Home :

  1. Sur l'écran "Gérer les projets", cliquez sur Créer un projet.
    Centre des développeurs Google Home
  2. Sur l'écran "Premiers pas", cliquez sur Créer un projet.

  1. Saisissez un nom de projet unique, puis cliquez sur Créer un projet. Boîte de dialogue "Créer un projet"
  2. Cliquez sur + Ajouter une intégration Matter pour accéder à l'écran "Ressources Matter", où vous trouverez la documentation de développement Matter et des outils.
  3. Lorsque vous êtes prêt à continuer, cliquez sur l'écran Next: Develop (Suivant : Développer) qui contient la checklist "Matter".
  4. Cliquez sur Suivant: Configuration du litige.
  5. Sur l'écran "Configuration du domaine", saisissez le nom du produit.
  6. Cliquez sur Sélectionner un type d'appareil, puis choisissez le type d'appareil dans le menu déroulant (ici, "Light'").
  7. Dans "Configuration", saisissez l'ID du fournisseur de test (VID) 0xFFF1 et l'ID de produit (PID) 0x8000, puis cliquez sur Envoyer.
    Configurer un projet
  8. Vous verrez désormais un appareil Matter sous"Intégrations Matter".Intégration de litiges
  9. 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 redémarrer après l'enregistrement du projet pour que la modification soit prise en compte.

4. Créer un appareil

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

Chef:

  • Un exemple d'application qui fournit une interface de terminal et encapsule des fonctionnalités également disponibles dans l'application examples/shell.
  • Un script qui applique le principe de la convention plutôt que 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 plusieurs options que vous pouvez afficher en exécutant chef.py -h. Voici les options que nous utilisons:

  • -d: définit le type d'appareil à utiliser. Dans le cas présent, nous créons une application d'éclairage avec des commandes Marche/Arrêt et de niveau.
  • -z: appelle l'outil ZAP pour générer les fichiers sources qui mettent en œuvre le type d'appareil. En d'autres termes, en fonction de l'éclairage que vous avez choisi, ZAP crée automatiquement du code à incorporer dans le build qui définit l'éclairage (le modèle de données) et la manière dont il interagit avec les 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 du 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

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://dhrishi.github.io/connectedhomeip/qrcode.html?data=MT%3AY3.13Y2N00KA0648G00
[1648562026.946915][433632:433632] CHIP:SVR: Manual pairing code: [34970112332]

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.

Laissez votre appareil allumé. À présent, nous allons nous intéresser à l'application Google Home afin de commander votre appareil dans Google Home.

Arrêter l'appareil

Vous pouvez quitter le programme avec CTRL+C. Si l'application ne se ferme pas, vous devrez peut-être également appuyer sur 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 voulez répéter le 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'appareils virtuels

Le contrôleur d'appareil virtuel est une application autonome qui offre une interface utilisateur graphique permettant de contrôler et d'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'appareils virtuels

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 de l'appareil virtuel. Les modifications apportées à l'interface utilisateur affectent le modèle de données sous-jacent. Actuellement, le contrôleur d'appareil virtuel est compatible avec le type de lumière à intensité variable.

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, l'option de socket réseau sera utilisée par défaut sur le port localhost 33000. Une fois que la manette est en mesure de se connecter à l'appareil virtuel, un écran indiquant l'état de l'appareil s'affiche:

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 de contrôleur virtuel, puis interroge le serveur RPC une fois par seconde pour récupérer l'état.

L'application Virtual Device Controller vous permet également de récupérer le code QR lors du processus de mise en service de votre appareil. Cliquez sur l'icône de code QR à côté de l'image de l'appareil pour afficher le code QR:

Code QR

Vous pouvez utiliser ce code QR pour commander votre appareil.

6. Mettre l'appareil en service

Remarque: Cette étape n'aboutit que si vous avez déjà configuré votre projet dans la Google Play Developer Console.

Nest Hub

Un hub est nécessaire pour commander votre appareil sur le tissu Matter. Il s'agit d'un appareil Google Nest, tel que Nest Hub (2e génération), compatible avec Matter, 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.

Avant de commencer le processus de 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 se trouve dans la structure que vous utilisez dans votre application Google Home. (La &house dans 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 via un code QR. Vous pouvez obtenir le code QR de votre appareil virtuel depuis le 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 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 le flux de l'application Google Home.

Une fois ces étapes terminées, l'appareil virtuel Matter doit être mis en service et apparaîtra 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 un message 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.

Échec de la mise en service après une longue période d'analyse de votre appareil

7. Contrôler l'appareil

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

  • Avec l'Assistant Google.
  • Avec l'application Google Home
  • Utilisation de l'IUG d'appareil virtuel

Assistant Google

Utilisez l'Assistant Google sur votre téléphone ou votre hub pour changer l'état de l'appareil à partir des commandes vocales (par exemple, "Hey Google, allume ou allume mes ampoules").

Pour voir d'autres exemples de commandes, consultez la section Contrôler des appareils connectés via des commandes vocales de l'article Contrôler des 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 affichée dans l'application Google Home.

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

IUG d'appareil virtuel

Vous pouvez interagir avec l'IUG d'un appareil virtuel pour modifier son état. Que vous contrôliez l'appareil virtuel avec le contrôleur d'appareil virtuel, l'application Google Home sur votre téléphone ou votre hub, toutes ces interfaces reflètent 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 à:

  • Installer un environnement de développement Matter à l'aide d'une image Docker pré-empaquetée
  • Créer et exécuter un appareil virtuel Matter
  • Commandez et contrôlez votre appareil virtuel depuis Google Home.

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