ZCL Advanced Platform（ZAP）

ZCL Advanced Platform（ZAP）は、Matter クラスタに基づく node.js テンプレート エンジンです。

ZAP は、Matter アプリと SDK に次の機能を提供します。

• GUI インターフェースから Matter エンドポイント、クラスタ、属性、その他のデバイス機能を構成します。
• データモデルの定義、コールバック、その他の Matter ソースコードを自動的に生成するテンプレートを作成します。
• 事前構成された ZAP ファイルを作成して使用し、SDK に含めます。

インストール

1. ZAP リリース ページに移動します。

2. 「最新」のタグが付いたリリースを探します（ほとんどのリリースには「プレリリース」のタグが付いています）。

3. このリリースの [アセット] で、ご使用のオペレーティング システム用に指定されたパッケージを選択してダウンロードします。

4. Debian または Ubuntu を実行しているマシンで、次のコマンドを実行して ZAP をインストールします。

   sudo dpkg -i path/to/zap_installation_package

Debian または Ubuntu Linux では、zap バイナリは /usr/bin/ にインストールされます。他のオペレーティング システムでは、バイナリが別の場所にインストールされている可能性があります。いずれにしても、実行可能ファイルの場所が PATH 環境変数に含まれていることを確認してください。

ZAP ファイル

ZAP は ZAP ファイルと呼ばれるテンプレート ファイルを使用します。ZAP ファイルは、エンドポイント、コマンド、属性、その他のデバイス機能を定義する JSON ファイルです。ZAP ファイルの名前は .zap で終わります。たとえば、connectedhomeip/examples/lighting-app/lighting-common の lighting-app.zap です。

connectedhomeip/examples/all-clusters-app/all-clusters-common にある all-clusters-app.zap ファイルは、一般的な Matter クラスタと、Matter セカンダリ ネットワークのコミッショニング デバイスタイプを含む 3 つのエンドポイントで事前構成されています。これは、さまざまなクラスタ構成を調べるのに適した例です。

実行

1. Matter の例のいずれかから ZAP ファイルを選択します。
2. Matter リポジトリのルート ディレクトリ（connectedhomeip）から、run_zaptool.sh ラッパー スクリプトを実行し、.zap ファイルのパスを渡します。

次に例を示します。

./scripts/tools/zap/run_zaptool.sh ./examples/lighting-app/lighting-common/lighting-app.zap

設定

settings [設定] では、ライトテーマまたはダークテーマの選択、デベロッパー ツールの有効化または無効化など、ZAP ユーザー インターフェースを構成できます。

tune [オプション] をクリックすると、[製品メーカー]、[デフォルトのレスポンス ポリシー] を選択したり、コマンド検出を有効または無効にしたりできます。

extension [Extensions] をクリックして、カスタム ZCL クラスタまたはコマンドを Zigbee Clusters Configurator に追加します。

使用

エンドポイント

lighting-app.zap ファイルには、Matter ルートノード（Endpoint - 0）と Matter 調光可能なライト（Endpoint - 1）が事前に構成されています。

Endpoint - 0 には、ノード全体に関連する一般的なクラスタ（ネットワーキング、コミッショニング、記述子、オペレーション認証情報、OTA クラスタなど）が含まれます。

次のステップでは、例の lighting-app から Endpoint - 1 Matter 調光可能なライトを確認して構成します。

1. Matter リポジトリ connectedhomeip から ZAP を実行します。

   scripts/tools/zap/run_zaptool.sh \
   examples/lighting-app/lighting-common/lighting-app.zap

2. [Endpoint - 1]、[edit 編集] の順にクリックします。

3. 省略可: Matter はさまざまなデバイスタイプをサポートしています。[デバイス] プルダウンで、matter の入力を開始してデバイスを変更し、[保存] をクリックします。

   

詳しくは、Matter の入門ガイドのデバイスとエンドポイントをご覧ください。

クラスタ

事前定義されたクラスタ、属性、レポート オプションは、デフォルトで Endpoint - 1 で有効になっています。

有効なクラスタのみを表示するには、[Endpoint - 1] をクリックし、[表示] メニューから [有効なクラスタ] を選択します。search クラスタを名前（on など）で検索することもできます。

クラスタを [クライアント]、[サーバー]、[クライアントとサーバー] として有効にするには、[有効にする] プルダウンを使用します。また、[Not Enabled] を選択して、デバイスタイプに適用されない事前構成済みのクラスタを無効にすることもできます。

詳細については、Matter Primer のクラスタをご覧ください。

属性とコマンド

属性とコマンドを構成する手順は次のとおりです。

1. On/Off クラスタを見つけます。

2. 同じ行で、構成アイコン settings をクリックします。

   

ここでは、属性を有効または無効にしたり、さまざまな属性オプションを設定したり、名前で属性を検索したりできます。search

[コマンド] をクリックして、このクラスタのアクションを構成します。たとえば、照明の オン/オフ クラスタには、オン、オフ、切り替えのコマンドが含まれます。Temperature Measurement クラスタなど、一部のクラスタには関連付けられたコマンドがない場合があります。

詳細については、Matter 入門の属性とコマンドを参照してください。

ZAP ソースファイルを生成する

Matter の例では、ZAP で生成されたソースコードを使用します。これは connectedhomeip/zzz_generated ディレクトリにあります。一部のファイルはアプリ固有ですが、他の汎用 ZAP ファイルは app-common にグループ化されます。

#include <app-common/zap-generated/ids/Attributes.h>
#include <app-common/zap-generated/ids/Clusters.h>

エンドポイントを構成したら、プロジェクトに統合するソースファイルを生成できます。

1. [video_settings生成] をクリックします。
2. ZAP 出力を保存するフォルダを選択します。たとえば、lighting-app の場合は connectedhomeip/zzz_generated/lighting-app/zap-generated に移動します。
3. （省略可）任意の IDE でファイルを開きます。

ZAP は、デバイスタイプと ZAP 構成に固有の定義、関数、その他のソースコードを生成します。

たとえば、callback-stub.cpp には、有効にしたクラスタのみを含むクラスタ コールバック メソッドが含まれています。

void emberAfClusterInitCallback(EndpointId endpoint, ClusterId clusterId)
{
    switch (clusterId)
    {
     ...
     case ZCL_ON_OFF_CLUSTER_ID :
        emberAfOnOffClusterInitCallback(endpoint);
        break;
     ...
    }
}

ZAP ソースファイルを使用する

zzz_generated/app-common/app-common/zap-generated/ids/ の Attributes.h などの一般的な ZAP ソースファイルを使用して、デバイスタイプの属性を取得および設定できます。

namespace DeviceTemperatureConfiguration {
  namespace Attributes {

  namespace CurrentTemperature {
    static constexpr AttributeId Id = 0x00000000;
    } // namespace CurrentTemperature

  ...

  } // namespace Attributes
} // namespace DeviceTemperatureConfiguration

#include <app-common/zap-generated/att-storage.h>
#include <app-common/zap-generated/attribute-id.h>
#include <app-common/zap-generated/attribute-type.h>
#include <app-common/zap-generated/attributes/Accessors.h>
#include <app-common/zap-generated/callback.h>
#include <app-common/zap-generated/cluster-id.h>
#include <app-common/zap-generated/cluster-objects.h>
#include <app-common/zap-generated/command-id.h>

using namespace ::chip;
using namespace ::chip::app::Clusters;

static void InitServer(intptr_t context)
{
    ...

    // Sets temperature to 20C
    int16_t temperature = 2000;
    auto status         = DeviceTemperatureConfiguration::Attributes::CurrentTemperature::Set(1, temperature);
    if (status != EMBER_ZCL_STATUS_SUCCESS)
    {
        ChipLogError(Shell, "Temp measurement set failed");
    }
}

Matter ソースコードで ZAP ファイルを使用する方法を理解したら、ZAP を統合する方法はいくつかあります。

• 既存の zzz_generated ファイルを使用して、デバイスタイプに固有の新しい例を作成します。
• プロジェクト用のカスタム .zap ファイルを作成します。

カスタマイズ

ZAP ファイルは ZAP テンプレートから生成されます。run_zaptool.sh を使用して ZAP を起動すると、このスクリプトは次のテンプレートを渡します。

node src-script/zap-start.js --logToStdout \
    --gen "$CHIP_ROOT/src/app/zap-templates/app-templates.json" \
    --zcl "$CHIP_ROOT/src/app/zap-templates/zcl/zcl.json" \
    "${ZAP_ARGS[@]}"

templates.json は、Matter の例で使用される Matter テンプレート名と対応する出力ファイルを定義します。

{
    "path": "templates/app/callback-stub-src.zapt",
    "name": "ZCL callback-stub source",
    "output": "callback-stub.cpp"
}

Matter ソリューションをカスタマイズするには、ZAP を使用する際に次の手順を行います。

• ZAP テンプレートを作成します。
• ZAP を SDK に統合します。

リソース

その他の ZAP リソースについては、GitHub の ZAP リポジトリ（zap）をご覧ください。