ZCL 進階平台 (ZAP)

ZCL 進階平台 (ZAP) 是 node.js 範本引擎 Matter 叢集

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

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

安裝

  1. 前往 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。例如: connectedhomeip/examples/lighting-app/lighting-common 中的 lighting-app.zap

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 通用選項

按一下「擴充功能」圖示 來新增自訂欄位 ZCL 叢集或指令傳送至 Zigbee 叢集設定器。

使用

端點

lighting-app.zap 檔案已預先設定 Matter 根節點 (端點 - 0) 和 Matter 調光燈 (端點 1)。

端點 - 0 包含 與整個節點有關,例如網路、調試、描述元 作業憑證和 OTA 叢集。

ZAP 端點 0

在後續步驟中,您會檢查並設定 Endpoint - 1 Matter 範例 lighting-app 中的可調光燈。

  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

如果只想查看已啟用的叢集,請點選「Endpoint - 1」,然後選取 取自顯示已啟用叢集 或前往 Google 試算表選單也可以搜尋 個叢集 依據名稱,例如 on

已啟用 ZAP 的叢集

啟用用戶端伺服器用戶端伺服器,請使用 「啟用」下拉式選單。您也可以選取「未啟用」, 不適用預先設定的叢集,並不適用於裝置類型。

ZAP 停用叢集

詳情請參閱 叢集 Matter Primer 中。

屬性和指令

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

  1. 找出 On/Off 叢集。
  2. 在同一列按一下「設定」圖示

    設定 ZAP

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

ZAP 屬性

點選「指令」即可設定這個叢集的動作。適用對象 例如燈具的「開啟/關閉」叢集會顯示「開啟」、「關閉」。 和 Toggle 指令有一些叢集 Temperature Measurement 叢集,可能沒有任何相關聯的指令。

ZAP 指令

詳情請參閱 屬性和指令 Matter Primer 中。

產生 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-generatedlighting-app
  3. (選用) 在想用的 IDE 中開啟檔案。

ZAP 會產生定義、函式,以及其他符合您的 裝置類型和 ZAP 設定

ZAP 產生的檔案

舉例來說,callback-stub.cpp 包含叢集回呼方法 僅包含您先前啟用的叢集:

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

使用 ZAP 來源檔案

常見的 ZAP 來源檔案,例如Attributes.h zzz_generated/app-common/app-common/zap-generated/ids/,可用於 get 和 set device type Attributes:

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 資源,請參閱 ZAP 存放區 (zap)