ZCL 進階平台 (ZAP)

ZCL Advanced Platform (ZAP) 是以Matter叢集為基礎的 node.js 範本引擎。

ZAP 為 Matter 應用程式和 SDK 提供下列功能：

  • 透過圖形使用者介面設定Matter端點、叢集、屬性和其他裝置功能。
  • 建立範本，自動產生資料模型定義、回呼和其他 Matter 原始碼。
  • 建立及使用預先設定的 ZAP 檔案，並納入 SDK。
ZAP 工具

安裝

  1. 前往「ZAP releases」(ZAP 版本) 頁面。

  2. 找出標示為「最新」的版本 (大部分會標示為「預先發布」)。

  3. 在此版本中，在標題為「Assets」下，選擇適用於您的作業系統的軟體包並下載它。

  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 結尾。例如，lighting-app.zap 中的 connectedhomeip/examples/lighting-app/lighting-common。

all-clusters-app.zap 檔案位於 connectedhomeip/examples/all-clusters-app/all-clusters-common 中，已預先設定常見的 Matter 集群和三個端點，包括 Matter 次要網路委派裝置類型。這是探索各種叢集設定的好例子。

執行

  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 全域選項

點選 擴充 為 Zigbee 叢集配置器新增自訂 ZCL 叢集或命令。

使用

端點

lighting-app.zap 檔案預先配置了 Matter 根節點（端點 - 0）和 Matter 可調光燈（端點 - 1）。

端點 - 0 包含與整個節點相關的一般叢集，例如網路、委派、描述元、作業憑證和 OTA 叢集。

ZAP 端點 0

接下來，您將查看並配置範例 lighting-app 中的 Endpoint - 1 Matter 可調光燈。

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

詳情請參閱 Matter 基礎課程中的「叢集」。

屬性和指令

如要設定屬性和指令，請完成下列步驟：

  1. 找出 On/Off 叢集。

  2. 在同一行中，按一下配置圖示 。

    設定 ZAP

你可以在這裡啟用或停用屬性、設定各種屬性選項，以及依名稱搜尋屬性 。

ZAP 屬性

按一下「指令」，為這個叢集設定動作。舉例來說，燈的「On/off」(開/關) 叢集會包含「On」(開啟)、「Off」(關閉) 和「Toggle」(切換) 指令。部分叢集 (例如 Temperature Measurement 叢集) 可能沒有任何相關聯的指令。

ZAP 指令

詳情請參閱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. 按一下「生成」。
  2. 選取要儲存 ZAP 輸出的資料夾。例如，導覽至 connectedhomeip/zzz_generated/lighting-app/zap-generated 即可找到 lighting-app。
  3. (選用) 在想用的 IDE 中開啟檔案。

ZAP 會產生定義、函式和其他原始碼，這些原始碼會根據裝置類型和 ZAP 設定自訂。

ZAP 產生的檔案

舉例來說，callback-stub.cpp 包含 Cluster 回呼方法，其中只包含您已啟用的 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");
    }
}

一旦你瞭解如何在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 資源，請參閱 GitHub 上的 ZAP 存放區 (zap)。