87. Matter - lighting-app を深堀る

前回の記事　　　　　　　　　　　　　　　　　　　　　　　　次回の記事

はじめに

結局、折角動かせた lighting-app との接続を試す CHIP-TOOL がビルドできなかった、というのが前回までの記事でした。
その状態で、Matter のトピックスを終わらせるのは微妙なので、今回、lighting-app の詳細を調べて、Matter の一連の記事は一旦終了とすることにしました。

lighting-app

85回の記事で ESP32 DEVKIT 向けに Build し、実際に実機で動かしてみた Matter の github から公開された example です。

ファイル一式

もともとのソースコード一式は、

から公開されています。中身は、

https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app

こんな構成になっています。lighting-app の直下は、lighting-common を除いて、様々な HW、実行プラットフォーム特化のソースファイルやビルド用ファイルが存在します。esp32 の下に ESP32 DEVKIT や M5Stack 用のファイル一式が用意されています。そして、main の下は、

esp32 の下のファイル群

こんな風になっています。

ビルド関連ファイル

ビルド関連のファイルは、CMakeLists.txt や sdkconfig* 系です。cmake 用の CMakeLists.txt を覗いてみると、

examples/common

examples/common の下のファイル群も使っているようです。試しに QRCode を辿ってみると、

examples/common/QRCode/repo → QRCode 開発リポジトリ

の様に、別の Github リポジトリがリンクされています。リンク先には、Matter デバイスで共通に使えるライブラリが用意されているという仕組みです。へ～、Rust で書かれたライブラリもあるのね。。。

他に、lighting-common には、Build Tool 系の ninja 向けのファイル（BUILD.gn）もあります。

ZAP ファイル

Matter デバイスが装備する機能は、ZAP ファイルで記述されることになっていて、lighting-app の場合は、examples/lighting-app/lighting-common/lighting-app.zap がそれにあたります。このファイルには、JSON 形式で、

• KeyValuePairs

  • 3つの key-value の定義

• package　※ なぜ複数形ではないのか不思議…

  • 2つのパッケージの定義

• endpointTypes

  • 2つの endpoint type の定義

  • MA-rootdevice

    • id = 1

    • 21 個の clusters 

      • Descriptor -server

      • Access Control -server

      • Basic Information -server

      • OTA Software Update Provider -client

      • OTA Software Update Requestor -server

      • Localization Configuration -server

      • Time Format Localization - server

      • General Commissioning -server

      • Network Commissioning -server

      • Diagnostic Logs -server

      • General Diagnostics - server

      • Software Diagnostics - server

      • Thread Network Diagnostics - server

      • WiFi Network Diagnostics - server

      • Ethernet Network Diagnostics - server

      • Switch - server

      • Administrator Commissioning - server

      • Operational Credentials - server

      • Group Key Management - server

      • Fixed Label - server

      • User Label - server

  • MA-dimmablelight

    • id = 2

      • 8 個の clusters

        • Identity -server

        • Groups - server

        • On/Off -server

        • Level Control -server

        • Descriptor - server

        • Scenes Management -server

        • Color Control -server

        • Occupancy Sensing - server

• endpoints

  • MA-rootdevice

  • MA-dimmablelight

要するに、エンドポイントが二つあって、それぞれ、MA-rootdevice と MA-dimmablelight という deviceType で、上に挙げた cluster が装備されるんだよ、ということですね。
ZAP — Matter documentation (project-chip.github.io)
によれば、

https://project-chip.github.io/connectedhomeip-doc/_images/zap_compiler.png

という流れで zap ファイルは使われるということで、lighting-app.zap と同じ場所に、lighting-app.matter ファイルがあることが確認できます。このファイルの冒頭を見ると、

// This IDL was generated automatically by ZAP.
// It is for view/code review purposes only.

/** Attributes and commands for putting a device into Identification mode (e.g. flashing a light). */
cluster Identify = 3 {
  revision 4;

  enum EffectIdentifierEnum : enum8 {
    kBlink = 0;
    kBreathe = 1;
    kOkay = 2;
    kChannelChange = 11;
    kFinishEffect = 254;
    kStopEffect = 255;
  }

...

こんな風に、ZAP から自動生成されたよと書かれています。また、Dimmablelight については、
connectedhomeip/data_model/device_types/DimmableLight.xml at master · project-chip/connectedhomeip · GitHub
に、対応する xml ファイルがあることが確認できます。

ZAP ファイルについて一言言わせてもらえば、確かに、拡張子を ZAP にすると変換ツールやビルド規則記述向けには便利なのですが、Visual Studio Code 等で開くと、JSON だと自動認識してくれない（何かの Extension をインストールすると認識してくれるのかも）ので、可読性がめちゃくちゃ低いのが玉に瑕。まぁ、ファイルをコピーして、拡張子を .json に変えて開けばいいんですけどね。Visual Studio や Visual Studio Code で DTDL ファイル（Digital Twins のデータモデルを記述するファイル、JSONで書かれていて、こちらの拡張子は .json）を作成・編集する際のインテリセンス付きの拡張と同じようなものがあると便利だよね。。。

ハードウェア・Platform ごとの共通コード

connectedhomeip のリポジトリの examples には実にたくさんの Device Type のサンプルが公開されています。ESP32 に限らず、他の Platform もそうですが、Device Type が変わっても、Commsioning やネットワーク接続、ダイアグの表示など、変わらない機能が必要になります。その辺りのコードは、examples/platform の下に用意されています。

https://github.com/project-chip/connectedhomeip/tree/master/examples/platform

ESP32 の場合は図のように、esp32 というフォルダーに用意されています。

ZAP ファイルの記述で使われている文字列の定義

第82回目の記事で書きましたが、Matter の Cluster は全て、Matter の標準として定義されたものが使われています。実際、lighting-app.zap に記載の項目を、”Matter Application Cluster Specification Version 1.2”と突き合わせると対応する項目があって、詳細が定義されています。各自確認してみてください。

概念モデリングの観点からのおまけ

Matter の Specification での deviceType の定義、ZAP ファイルにおける deviceType の定義、そして、各種、Hardware・Platform 向けの実装、なんとなく判った気になっていただけましたか？
ここでは、”Art of Conceptual Modeling”で解説している概念モデリングの観点から、これらの関係を説明することにします。