ZCL Advanced Platform (ZAP) là một công cụ mẫu button.js dựa trên Cụm Matter.
ZAP cung cấp các tính năng sau cho ứng dụng và SDK Matter:
- Định cấu hình Điểm cuối, Cụm, Thuộc tính và các tính năng khác của thiết bị Matter từ giao diện GUI.
- Tạo những mẫu tự động tạo định nghĩa, lệnh gọi lại và các mã nguồn Matter khác của Mô hình dữ liệu.
- Tạo và sử dụng các tệp ZAP được định cấu hình sẵn để đưa vào SDK của bạn.
Cài đặt
Truy cập trang Bản phát hành của ZAP.
Tìm bản phát hành được gắn thẻ "Mới nhất" (hầu hết bản phát hành sẽ được gắn thẻ "Bản phát hành trước").
Trong bản phát hành này, bên dưới tiêu đề Assets (Tài sản), hãy chọn gói được chỉ định cho hệ điều hành của bạn rồi tải gói đó xuống.
Trên máy chạy Debian hoặc Ubuntu, hãy cài đặt ZAP bằng cách chạy:
sudo dpkg -i path/to/zap_installation_package
Trên Debian hoặc Ubuntu Linux, tệp nhị phân zap
được cài đặt trong /usr/bin/
. Trên các hệ điều hành khác, tệp nhị phân có thể được cài đặt ở nơi khác. Trong mọi trường hợp, hãy kiểm tra để đảm bảo vị trí của tệp thực thi nằm trong biến môi trường PATH
.
Tệp ZAP
ZAP sử dụng tệp mẫu có tên là tệp ZAP. Tệp ZAP là tệp JSON xác định Điểm cuối, Lệnh, Thuộc tính và các tính năng khác của thiết bị. Tệp ZAP có tên kết thúc bằng .zap
. Ví dụ: lighting-app.zap
trong connectedhomeip/examples/lighting-app/lighting-common
.
Tệp all-clusters-app.zap
, nằm trong connectedhomeip/examples/all-clusters-app/all-clusters-common
, được định cấu hình sẵn với các Cụm Matter và 3 Điểm cuối phổ biến, trong đó có một Loại thiết bị uỷ quyền mạng phụ Matter. Đây là một ví dụ điển hình để khám phá nhiều cấu hình Cụm.
Chạy
- Chọn một tệp ZAP trong một trong các ví dụ về Matter.
- Từ thư mục gốc của kho lưu trữ Matter (
connectedhomeip
), hãy chạy tập lệnh trình bao bọcrun_zaptool.sh
, truyền tập lệnh này theo đường dẫn đến tệp.zap
.
Ví dụ:
./scripts/tools/zap/run_zaptool.sh ./examples/lighting-app/lighting-common/lighting-app.zap
Thiết lập
Trong phần Cài đặt
, bạn có thể định cấu hình giao diện người dùng ZAP, bao gồm cả lựa chọn giao diện sáng hoặc tối cũng như bật hoặc tắt công cụ cho nhà phát triển.Khi nhấp vào
Tuỳ chọn, bạn có thể chọn Nhà sản xuất sản phẩm, Chính sách phản hồi mặc định và bật hoặc tắt tính năng Khám phá lệnh.Nhấp vào
Tiện ích để thêm cụm hoặc lệnh ZCL tuỳ chỉnh vào Trình định cấu hình cụm Zigbee.Sử dụng
Điểm cuối
Tệp lighting-app.zap
được định cấu hình sẵn bằng Nút gốc Matter (Điểm cuối – 0) và Đèn có thể điều chỉnh độ sáng Matter (Điểm cuối – 1).
Điểm cuối – 0 bao gồm các cụm chung liên quan đến toàn bộ nút, chẳng hạn như Nối mạng, Ủy quyền, Mô tả, Thông tin xác thực hoạt động và Cụm OTA.
Trong các bước tiếp theo, bạn sẽ xem xét và định cấu hình Endpoint – 1
Matter Ánh sáng có thể điều chỉnh được độ sáng trong ví dụ lighting-app
.
Trong kho lưu trữ Matter
connectedhomeip
, hãy chạy ZAP.scripts/tools/zap/run_zaptool.sh \ examples/lighting-app/lighting-common/lighting-app.zap
Nhấp vào Endpoint – 1, rồi nhấp vào
CHỈNH SỬA.Không bắt buộc: Matter hỗ trợ nhiều loại thiết bị. Trong trình đơn thả xuống Thiết bị, hãy bắt đầu nhập
matter
để thay đổi thiết bị của bạn, sau đó nhấp vào LƯU.
Để tìm hiểu thêm, hãy tham khảo phần Thiết bị và điểm cuối trong Tài liệu gợi ý Matter.
Nhiều viên quá quý nhỏ hợp lại
Theo mặc định, các cụm, thuộc tính và tuỳ chọn Báo cáo được xác định trước được bật trong Endpoint – 1.
Để chỉ hiển thị các Cụm đã bật, hãy nhấp vào Endpoint – 1 (Điểm cuối – 1) rồi chọn Enabled Clusters (Cụm đã bật) trên trình đơn Show (Hiển thị). Bạn cũng có thể tìm kiếm cụm on
.
Để bật bất kỳ Cụm nào dưới dạng Ứng dụng, Máy chủ hoặc Ứng dụng và Máy chủ, hãy sử dụng trình đơn thả xuống Bật. Bạn cũng có thể chọn Not Enabled (Không bật) để tắt một Cụm được định cấu hình sẵn không áp dụng cho loại thiết bị.
Để tìm hiểu thêm, hãy tham khảo Cụm trong Matter Primer.
Thuộc tính và lệnh
Để định cấu hình Thuộc tính và lệnh, hãy hoàn tất các bước sau:
- Tìm cụm
On/Off
. Trên cùng một hàng, hãy nhấp vào biểu tượng Định cấu hình
.
Tại đây, bạn có thể bật hoặc tắt Thuộc tính, đặt nhiều tuỳ chọn Thuộc tính và Tìm kiếm thuộc tính
theo tên.Nhấp vào Command (Lệnh) để định cấu hình các thao tác cho Cluster này. Ví dụ: Cụm Bật/tắt của đèn sẽ bao gồm các lệnh Bật, Tắt và Bật/tắt. Một số Cụm, chẳng hạn như cụm Temperature Measurement
, có thể không có Lệnh nào được liên kết.
Để tìm hiểu thêm, hãy tham khảo phần Thuộc tính và lệnh trong Matter Primer.
Tạo tệp nguồn ZAP
Các ví dụ về Matter dùng mã nguồn do ZAP tạo, có trong thư mục connectedhomeip/zzz_generated
. Một số tệp là dành riêng cho ứng dụng, trong khi các tệp ZAP chung khác được nhóm trong app-common
.
#include <app-common/zap-generated/ids/Attributes.h>
#include <app-common/zap-generated/ids/Clusters.h>
Sau khi định cấu hình Điểm cuối, bạn có thể tạo các tệp nguồn để tích hợp vào dự án của mình.
- Nhấp vào Tạo.
- Chọn một thư mục để lưu đầu ra ZAP. Ví dụ: chuyển đến
connectedhomeip/zzz_generated/lighting-app/zap-generated
cholighting-app
. - Optional . Mở các tệp trong IDE mà bạn ưu tiên.
ZAP tạo các định nghĩa, hàm và mã nguồn khác tuỳ chỉnh theo loại thiết bị và cấu hình ZAP của bạn.
Ví dụ: callback-stub.cpp
bao gồm phương thức gọi lại Cụm chỉ bao gồm các Cụm mà bạn đã bật:
void emberAfClusterInitCallback(EndpointId endpoint, ClusterId clusterId)
{
switch (clusterId)
{
...
case ZCL_ON_OFF_CLUSTER_ID :
emberAfOnOffClusterInitCallback(endpoint);
break;
...
}
}
Sử dụng tệp nguồn ZAP
Các tệp nguồn ZAP phổ biến, chẳng hạn như Attributes.h
trong
zzz_generated/app-common/app-common/zap-generated/ids/
, có thể được dùng để
nhận và đặt các Thuộc tính loại thiết bị:
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");
}
}
Sau khi hiểu cách sử dụng tệp ZAP trong mã nguồn Matter, bạn có thể tích hợp ZAP theo một số cách sau:
- Sử dụng các tệp
zzz_generated
hiện có để tạo ví dụ mới, dành riêng cho các loại thiết bị của bạn. - Tạo các tệp
.zap
tuỳ chỉnh cho dự án của bạn.
Tuỳ chỉnh
Tệp ZAP được tạo từ các mẫu ZAP.
Khi bạn sử dụng run_zaptool.sh
để chạy ZAP, tập lệnh này sẽ chuyển các mẫu sau:
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
xác định tên mẫu Matter và tệp đầu ra tương ứng dùng trong các ví dụ về Matter.
{
"path": "templates/app/callback-stub-src.zapt",
"name": "ZCL callback-stub source",
"output": "callback-stub.cpp"
}
Để tuỳ chỉnh các giải pháp Matter, bạn có thể thực hiện một số bước tiếp theo khi làm việc với ZAP:
Tài nguyên
Để xem các tài nguyên ZAP khác, hãy tham khảo kho lưu trữ ZAP (zap
) trên GitHub.