ZCL Advanced Platform（ZAP）

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

ZAP には、Matter アプリと SDK 向けの次の機能があります。

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

インストール

  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

設定

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

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

ZAP のグローバル オプション

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

使用

エンドポイント

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

エンドポイント - 0 には、Networking、Commissioning、Descriptor、Operational Credentials、OTA Cluster など、ノード全体に関連する一般的なクラスタが含まれます。

ZAP エンドポイント 0

次のステップでは、サンプル lighting-app の エンドポイント - 1 Matter Dimmable Light を確認して構成します。

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

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

  2. [エンドポイント - 1]、[ 編集] の順にクリックします。

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

    ZAP デバイスの選択

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

クラスタ

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

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

ZAP 対応クラスタ

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

ZAP クラスタの無効化

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

属性とコマンド

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

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

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

    ZAP の設定

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

ZAP 属性

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

ZAP コマンド

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

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

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

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

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

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

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

ZAP 生成ファイル

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

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

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

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

Attributes.h

namespace DeviceTemperatureConfiguration {
  namespace Attributes {

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

  ...

  } // namespace Attributes
} // namespace DeviceTemperatureConfiguration

main.cpp

#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");
    }
}

ZAP ファイルを Matter ソースコードで使用する方法を理解したら、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 リソースについては、GitHub の ZAP リポジトリ（zap）をご覧ください。