Matter 仮想デバイスを作成する

1. はじめに

Matter は、スマート デバイスの開発に画期的な機会をもたらす接続プロトコルです。この Codelab では、事前構成済みの Docker イメージに用意されている SDK と依存関係を使用して、初めての Matter デバイスを構築します。

Matter について詳しくは、Google Home Developer Center または Connectivity Standards Alliance のウェブサイトをご覧ください。

学習内容

  • Matter ビルド環境をセットアップする方法
  • パソコンで動作する仮想 Matter デバイスを作成する方法
  • Google Home で仮想 Matter デバイスをコミッショニングして制御する方法

必要なもの

  • ハブとは、Matter 対応の Google Nest デバイス（Google Nest Hub（第 2 世代）など）のことです。
  • X11 ウィンドウ システムを実行している Linux マシン。
  • Docker。
  • Linux に関する基本的な知識。

2. 環境を設定する

ここでは、Linux ホストマシン上で構成済みの Docker コンテナを使用します。このコンテナには、Matter 仮想デバイスをビルドして実行するために必要な依存関係がすべて含まれています。

ハードウェアを確認する

この Docker のインストールは、Windows と macOS のパソコンではサポートされていません。macOS に Matter を手動でインストールしてビルドすることもできます。

また、以下の手順では、Linux マシンで X11 ウィンドウ システムが実行されていることを前提としています。Linux マシンで Wayland が実行されている場合は、X.Org がインストールされていることを確認します。

Docker を設定する

  1. Docker Engine をインストールします（Docker Desktop は使用しないでください）。
  2. Docker Hub から Docker イメージを pull します。ターミナル ウィンドウで次のコマンドを実行します。
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    このオペレーションには数分かかることがあります。
  3. 次のコマンドを実行して Docker コンテナを起動します。
    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

コンテナを起動すると診断結果が表示され、その後にコンテナの設定が正しいことを確認するメッセージと、コンテナのシェル プロンプトが表示されます。

Environment looks good, you are ready to go!
$

Docker コマンドと、それに渡されたオプションを理解しましょう。

  • xhost local:1000 により、X Window System はポート 1000 でローカルホストからの接続を受信できるため、グラフィック ユーザー インターフェースを使用できます。
  • docker run … image は指定されたイメージを実行し、必要に応じて Docker レジストリから pull します。
  • --ipc=host を使用すると、Docker がホストマシンとプロセス間通信の名前空間を共有できるようになります。
  • --net=host は、Docker がコンテナ内のホストのネットワーク スタックを使用できるようにします。これは、ホストからコンテナに mDNS トラフィックを通過させ、ホスト X11 ディスプレイを共有するために必要です。
  • -e DISPLAY は $DISPLAY をホストにエクスポートし、システム グラフィック インターフェースにアクセスできるようにします。これは、Matter クラスタの編集時に ZAP ツールを実行するために必要です。
  • -it は、バックグラウンド プロセスではなく、インタラクティブ ターミナル（tty）で Docker を実行します。

必要に応じて、2 つ目のターミナル セッション インスタンスを実行できます。

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

Matter Docker コンテナを停止して起動する

docker run コマンドを実行すると、指定したイメージで新しいコンテナが作成されます。この操作を行うと、以前のコンテナ インスタンスに保存されていた古いデータは失われます。そのような場合は、新規インストールで開始できます。ただし、セッション間で作業内容や環境構成を保存したい場合もあります。

そのため、コンテナを作成した後は、作業内容が失われないようにコンテナを停止できます。

user@host> docker stop matter-container

再度実行する準備ができたら、コンテナを起動してターミナル ウィンドウを開きます。

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

次のコマンドで、コンテナに追加のターミナル セッションを開くことができます。

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

または、次のコマンドを使用してルート セッションを開始します。

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

Matter の初期設定

ターミナルを開くと、Matter のクローニングされたリポジトリ（~/connectedhomeip）にすでに表示されています。Matter に関する追加の手順は必要ありません。

ホストとコンテナ間でファイルを共有する

コンテナ内からホストマシン上のファイルにアクセスするには、バインド マウントを使用できます。マウントされたディレクトリにコンテナ内からファイルを書き込んで、ホストから簡単にアクセスすることもできます。

追加の引数 --mount source=$(pwd),target=/workspace,type=bind を指定してコンテナを実行し、現在の作業ディレクトリを /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

マウントされたディレクトリに対するコンテナ ユーザーの権限は、ホストで管理する必要があります。

コンテナ内からコンテナ ユーザーのグループ ID を取得します。

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

コンテナホストで別のターミナル セッションを開き、コンテナによってマウントされたディレクトリに作業ディレクトリを設定します。

マウントされたディレクトリにあるファイルのグループをコンテナ ユーザーのグループに再帰的に設定する。

user@host> sudo chgrp -R 1000 .

ディレクトリで必要な権限をグループに付与します。この例では、コンテナ ユーザーのグループに、マウントされたディレクトリ内のすべてのファイルに対する読み取り、書き込み、実行の権限を付与します。

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

これらのコマンドは、ホストユーザーが作成する新しいファイルの権限には影響しません。必要に応じて、ホストに作成された新しいファイルの権限を必ず更新してください。

ホストユーザーをコンテナ ユーザーのグループに追加すると、コンテナ ユーザーが作成したファイルに対する権限を継承できます。

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

3. Google Home デベロッパー コンソール

Google Home Developer Console は、Matter と Google Home の統合を管理するためのウェブ アプリケーションです。

Connectivity Standards Alliance（Alliance）の Matter 認証に合格した Matter デバイスは、Google Home エコシステムで動作します。特定の条件下で、認定されていない開発中のデバイスを Google Home エコシステムでコミッショニングできます。詳しくは、ペア設定の制限をご覧ください。

デベロッパー プロジェクトを作成する

まず、Google Home デベロッパー コンソールに移動します。

  1. [プロジェクトの作成] をクリックします。
  2. 一意のプロジェクト名を入力し、[プロジェクトを作成] をクリックします。 [新しいプロジェクトを作成] ダイアログ
  3. [+ Add integration] をクリックします。[Matter リソース] 画面が表示されます。この画面で、Matter の開発ドキュメントを確認したり、一部のツールについて確認したりできます。
  4. 続行する準備ができたら、[Next: Develop] をクリックして、[Matter Checklist] ページを開きます。
  5. [次へ: 設定] をクリックします。
  6. [設定] ページで [プロダクト名] を入力します。
  7. [デバイスタイプを選択] をクリックし、プルダウン メニューからデバイスタイプ（この場合は Light）を選択します。
  8. [ベンダー ID（VID）] で [テスト VID] を選択し、[Test VID] プルダウン メニューから 0xFFF1 を選択します。[プロダクト ID（PID）] に「0x8000」と入力して [保存して次へ] をクリックし、次のページで [保存] をクリックします。これらの正確な VID/PID 値を使用します。以降の Codelab の手順ではこれらの値に依存します。
    プロジェクトの設定
  9. [Matter の統合] に統合が表示されます。
  10. ハブを再起動して、最新の Matter 統合プロジェクトの設定を受信していることを確認します。後で VID または PID を変更する必要が生じた場合は、変更を有効にするために、プロジェクトを保存した後に再起動する必要もあります。再起動の手順については、Google Nest デバイスまたは Google Wifi デバイスを再起動するをご覧ください。

4. デバイスを作成する

Matter のすべてのサンプルは、GitHub リポジトリの examples フォルダにあります。いくつかのサンプルが用意されていますが、この Codelab では Chef を中心に説明します。

Chef は以下の両方です。

  • ターミナル インターフェースと、examples/shell アプリにあるラッピング機能を提供するサンプルアプリです。
  • Matter 対応デバイスの開発に必要な一般的なタスクのいくつかをカプセル化するために、コンベンション オーバー構成の原則を取り入れたスクリプトです。

Chef のサンプル フォルダに移動し、最初の Matter ビルドを作成します。

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

Chef には chef.py -h を実行することで表示できるオプションがいくつかあります。ここで使用するオプションは次のとおりです。

  • -d: 使用するデバイスタイプを定義します。ここでは、オン/オフとレベルのコントロールを備えた照明アプリを作成します。
  • -z: ZAP ツールを呼び出して、デバイスタイプを実装するソースファイルを生成します。つまり、ZAP は、選択した照明に基づいて、ビルドに組み込まれるコードを自動的に作成します。このコードにより、ライト（データモデル）と他のデバイスとの連携方法（インタラクション モデル）を定義します。
  • -b: ビルド。
  • -r: （省略可）仮想 Matter デバイス上で RPC サーバーを有効にして、他のコンポーネント（GUI など）がデバイスと通信して、データモデル属性を設定および取得できるようにします。
  • -t linux: ターゲット プラットフォーム。サポート プラットフォームは linux、nrfconnect、esp32 です。./chef.py -h を実行すると、使用可能なすべてのコマンドとサポートされているターゲット プラットフォームを表示できます。linux は、Matter の仮想デバイスに使用されます。

デバイスを実行する

Matter は TCP/UDP ポート 5540 を使用するため、パソコンでファイアウォールを実行している場合は、ファイアウォールをシャットダウンするか、ポート 5540 での受信 TCP/UDP 接続を許可します。

次のコマンドを使用して、コンテナ内で仮想デバイスを実行します。

$ ./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]

デバイスを実行したままにしておきます。お客様のデバイスを Google Home にコミッショニングできるように、Google Home アプリについて説明します。

デバイスを停止する

デバイスを停止する必要がある場合は、Ctrl+C キーを押してプログラムを終了できます。アプリが終了しない場合は、Ctrl+\ も使用する必要があります。

仮想デバイスの認証情報は、/tmp/ ディレクトリの chip 接頭辞で始まるファイルに保存されます。

コミッショニング プロセスを最初からやり直す場合は、次のコマンドを実行してそれらのファイルを削除する必要があります。

$ rm /tmp/chip*

5. 仮想デバイス コントローラ

仮想デバイス コントローラは、仮想 Matter デバイスの状態を制御、表示するためのグラフィカル ユーザー インターフェースを備えたスタンドアロン アプリです。RPC クライアントを使用して、開発環境に接続されている Matter デバイスと通信します。

仮想デバイス コントローラ

仮想デバイス コントローラは、仮想デバイスを視覚的に表します。

仮想デバイス コントローラのグラフィック ユーザー インターフェース（GUI）から仮想デバイスを操作できます。GUI の変更は、基になるデータモデルに影響します。サポートされている Matter 仮想デバイスタイプの一覧については、サポートされているデバイスをご覧ください。

仮想デバイス コントローラをインストールする

仮想デバイス コントローラは、Ubuntu LTS 20.04 Docker コンテナにプリインストールされています。

仮想デバイス コントローラを実行する

2 番目のターミナル セッション インスタンスを作成します。

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

仮想デバイスとの通信に使用するネットワーク ソケットを指定して、仮想デバイス コントローラを起動します。

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

引数を指定せずにコントローラを起動すると、デフォルトは localhost ポート 33000 を使用するネットワーク ソケット オプションになります。コントローラが仮想デバイスに接続できるようになると、デバイスの状態を示す画面が表示されます。

仮想デバイスのグラフィック ユーザー インターフェース

仮想コントローラ アプリに変更を加えると、アプリはデバイスの RPC サーバーにリクエストを送信し、1 秒に 1 回 RPC サーバーをポーリングして状態を取得します。

デバイスのコミッショニング フローの一環として、仮想デバイス コントローラ アプリを使用して QR コードを取得することもできます。デバイス画像の横にある QR コードのアイコンをクリックすると、このデバイスの QR コードが表示されます。この QR コードを使用してデバイスをコミッショニングしてください。

6. デバイスをコミッショニングします。

注: このステップが成功するのは、Google Home デベロッパー コンソールでプロジェクトがすでにセットアップされている場合のみです。

Google Nest Hub

デバイスを Matter ファブリックでコミッショニングするには、ハブが必要です。Google Nest Hub（第 2 世代）などの Google Nest デバイスであり、Matter をサポートし、Thread 対応デバイスのボーダー ルーターとしても、スマートホーム インテントをルーティングするためのローカル フルフィルメント パスとしても機能します。

Matter に対応しているハブについては、こちらのリストをご覧ください。

コミッショニング プロセスを開始する前に、次の点を確認してください。

  • ハブは、Google Home Console へのログインに使用した Google アカウントとペア設定されます。
  • ハブは、仮想 Matter デバイスの運用に使用しているパソコンと同じ Wi-Fi ネットワーク上にある。
  • ハブは、Google Home アプリで使用しているのと同じ構造になっています（Google Home グラフの「家」は構造を表します）。

QR コードを取得

コミッショニング プロセスでは、QR コードを通じて提供される Matter のオンボーディング情報が必要です。仮想デバイスの QR コードは、仮想デバイス コントローラから取得できます。

コミッション オペレーションを実行する

  1. Google Home アプリを開きます。
  2. 左上の [+] をタップします。
  3. [デバイスのセットアップ] をタップします。
  4. [新しいデバイス] をタップします。
  5. 家を選択して [次へ] をタップします。
  6. Google Home アプリがデバイスをスキャンします。「Matter デバイスが見つかりました...」というメッセージが表示されたら、[はい] をタップします。それ以外の場合は、[別のデバイスをセットアップ] をタップし、デバイスのリストから [Matter デバイス] を選択します。
  7. デバイスの QR コードまたはウェブサイトで生成された QR コードにカメラを向けます。
  8. Google Home アプリのフローに表示される手順に沿ってペア設定プロセスを進めます。

これらの手順を完了すると、Matter 仮想デバイスが正常にコミッショニングされ、Google Home アプリに新しいアイコンとして表示されます。

Google Home アプリでのペア設定済みの電球

トラブルシューティング

「接続の問題」または「Google に接続できませんでした」というエラー メッセージが表示されてコミッショニングが失敗する

  • Google Home コンソールで正しい VID と PID の組み合わせ でプロジェクトを作成していることと、同じ VID と PID の組み合わせを使用している他のプロジェクトがないことを確認します。

「デバイスのスキャン」が長時間続くとコミッショニングが失敗する

7. デバイスを操作する

Matter 対応デバイスが正常にコミッショニングされ、Google Home アプリに電球として表示されたら、さまざまな方法でデバイスの操作をテストできます。

  • Google アシスタントを使用する。
  • Google Home アプリを使用する場合。
  • 仮想デバイスの GUI の使用

Google アシスタント

スマートフォンやハブの Google アシスタントを使用して、「OK Google, ライトを切り替えて」などの音声コマンドでデバイスの状態を切り替えることができます。

コマンドのその他の例については、Google Home アプリに追加したスマートホーム デバイスを操作するの音声コマンドでスマートホーム デバイスを操作するを参照してください。

Google Home アプリ

Google Home アプリに表示された電球アイコンの横にある [ON] ラベルと [OFF] ラベルをタップします。

詳しくは、Google Home アプリに追加したスマートホーム デバイスを操作するの Google Home アプリでデバイスを操作するを参照してください。

仮想デバイスの GUI

仮想デバイスの GUI を操作して、デバイスの状態を変更できます。仮想デバイス コントローラ、スマートフォンの Google Home アプリ、ハブのいずれを使って仮想デバイスを操作するかにかかわらず、これらのインターフェースすべてに仮想デバイスの現在の状態が反映されます。

8. 完了

最初の Matter デバイスが正常に作成されました。でも使用できます。

この Codelab では、以下について学びました。

  • 事前にパッケージ化された Docker イメージを使用して、Matter 開発環境をインストールします。
  • Matter 仮想デバイスをビルドして実行します。
  • Google Home から仮想デバイスをコミッショニングして操作できます。

Matter について詳しくは、以下の参考資料をご覧ください。