ZCL 進階平台 (ZAP) 是以 Matter 叢集為基礎的 node.js 範本引擎。
ZAP 為 Matter 應用程式和 SDK 提供下列功能:
- 透過 GUI 介面設定 Matter 端點、叢集、屬性和其他裝置功能。
- 建立可自動產生資料模型定義、回呼和其他 Matter 原始碼的範本。
- 建立及使用預先設定的 ZAP 檔案,並納入您的 SDK。
安裝
前往 ZAP 版本頁面。
找出標記為「最新」的發布版本 (多數內容會標記為「預先發布版」)。
在這個版本的「Assets」下方,選取您為作業系統指定的套件,並下載。
在執行 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 次要網路組合裝置類型。這個例子很適合探索各種叢集設定。
執行
- 請從其中一個 Matter 範例選擇 ZAP 檔案。
- 從 Matter 存放區 (
connectedhomeip
) 的根目錄執行run_zaptool.sh
包裝函式指令碼,並將路徑傳遞至.zap
檔案。
例如:
./scripts/tools/zap/run_zaptool.sh ./examples/lighting-app/lighting-common/lighting-app.zap
設定
在
「Settings」(設定) 中,您可以設定 ZAP 使用者介面,包括選擇淺色或深色主題,以及啟用或停用開發人員工具。按一下
「選項」,您可以選取「產品製造商」、「預設回應政策」,並啟用或停用指令探索功能。按一下
「Extensions」(擴充功能),將自訂 ZCL 叢集或指令新增至 Zigbee Clusters Configurator。使用
端點
lighting-app.zap
檔案已預先設定 Matter 根節點 (Endpoint - 0) 和 Matter 可調光燈 (Endpoint - 1),
端點 - 0 包含與整個節點相關的一般叢集,例如網路、佣金、描述元、作業憑證和 OTA 叢集。
在後續步驟中,您將透過 lighting-app
範例查看及設定「Endpoint - 1」Matter 的調光燈。
從 Matter 存放區
connectedhomeip
執行 ZAP。scripts/tools/zap/run_zaptool.sh \ examples/lighting-app/lighting-common/lighting-app.zap
依序按一下「Endpoint - 1」和「
EDIT」。選用: Matter 支援多種裝置類型。在「Device」(裝置) 下拉式選單中,開始輸入
matter
以變更裝置,然後按一下「SAVE」(儲存)。
詳情請參閱 Matter Primer 中的裝置和端點。
叢集
根據預設,「Endpoint - 1」(端點 - 1) 會啟用預先定義的叢集、屬性和報告選項。
如果只想顯示已啟用的叢集,請按一下「Endpoint - 1」,然後在「Show」(顯示) 選單中選取「Enabled Clusters」(已啟用的叢集)。您也可以按名稱搜尋 on
。
如要啟用任何叢集做為「Client」(用戶端)、「Server」(伺服器) 或「Client & Server」(用戶端與伺服器),請使用「Enable」(啟用) 下拉式選單。您也可以選取「Not Enabled」,停用不適用於您裝置類型的預先設定叢集。
詳情請參閱 Matter Primer 中的叢集。
屬性和指令
如要設定屬性和指令,請完成下列步驟:
- 找出
On/Off
叢集。 在同一列中按一下「設定」圖示
。
您可以在這裡啟用或停用屬性、設定各種屬性選項,以及依名稱設定「搜尋屬性」
。點選「指令」即可設定這個叢集的動作。例如,燈具的「On/off」叢集會包含 On、Off 和 Toggle 指令。某些叢集 (例如 Temperature Measurement
叢集) 可能沒有任何相關聯的指令。
詳情請參閱 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>
設定端點後,您可以產生要整合至專案中的來源檔案。
- 按一下「產生」圖示 。
- 選取要儲存 ZAP 輸出內容的資料夾。例如,前往
lighting-app
的connectedhomeip/zzz_generated/lighting-app/zap-generated
。 - (選用) 在想用的 IDE 中開啟檔案。
ZAP 會產生針對裝置類型和 ZAP 設定的自訂定義、函式和其他原始碼。
舉例來說,callback-stub.cpp
包含一個叢集回呼方法,其中只包含已啟用的叢集:
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 範本。
- 將 ZAP 整合至 SDK。
資源
如需其他 ZAP 資源,請參閱 GitHub 上的 ZAP 存放區 (zap
)。