Nền tảng nâng cao ZCL (ZAP)

ZCL Advanced Platform (ZAP) là một công cụ mẫu node.js dựa trên MatterCụm.

ZAP cung cấp các tính năng sau cho ứng dụng và SDK Matter:

  • Định cấu hình Matter Điểm cuối, Cụm, Thuộc tính và các tính năng khác của thiết bị thông qua giao diện người dùng đồ hoạ.
  • Tạo các mẫu tự động tạo định nghĩa Mô hình dữ liệu, lệnh gọi lại và mã nguồn Matter khác.
  • Tạo và sử dụng các tệp ZAP được định cấu hình sẵn để đưa vào SDK.
Công cụ ZAP

Cài đặt

  1. Chuyển đến trang Bản phát hành ZAP.

  2. Tìm bản phát hành được gắn thẻ "Mới nhất" (hầu hết sẽ được gắn thẻ "Phát hành trước").

  3. Trong bản phát hành này, trong phần 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.

  4. 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 của bạn.

Tệp ZAP

ZAP sử dụng các tệp mẫu có tên là tệp ZAP. Tệp ZAP là một tệp JSON xác định các Đ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, có trong connectedhomeip/examples/all-clusters-app/all-clusters-common, được định cấu hình sẵn với các Cụm Matter phổ biến và 3 Điểm cuối, bao gồm cả Loại thiết bị phụ trách mạng phụ Matter. Đây là một ví dụ hay để khám phá nhiều cấu hình Cụm.

Chạy

  1. Chọn một tệp ZAP trong một trong các ví dụ Matter.
  2. 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ọc run_zaptool.sh, truyền cho tập lệnh này đườ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 Settings (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ác công cụ dành 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.

Tuỳ chọn chung của ZAP

Nhấp vào Tiện ích để thêm các lệnh hoặc cụm 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 một Nút gốc Matter (Điểm cuối – 0) và một Đè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 có liên quan đến toàn bộ nút, ví dụ: Cụm Mạng, Cụm Cài đặt, Cụm Mô tả, Cụm Thông tin đăng nhập hoạt động và Cụm OTA.

ZAP Endpoint 0

Trong các bước tiếp theo, bạn sẽ xem xét và định cấu hình Endpoint - 1 Matter Dimmable Light (Đèn có thể điều chỉnh độ sáng) trong ví dụ lighting-app.

  1. Từ 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

  2. Nhấp vào Thiết bị đầu cuối – 1, sau đó nhấp vào CHỈNH SỬA.

  3. 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ị, sau đó nhấp vào LƯU.

    ZAP Select Device

Để tìm hiểu thêm, hãy tham khảo phần Thiết bị và điểm cuối trong phần Matter Primer.

Cụm

Các lựa chọn Cụm, Thuộc tính và Báo cáo được xác định trước sẽ được bật trong Điểm cuối – 1 theo mặc định.

Để chỉ hiển thị các Cụm đã bật, hãy nhấp vào Điểm cuối – 1 rồi chọn Cụm đã bật trong trình đơn Hiện. Bạn cũng có thể tìm kiếm các cụm theo tên, ví dụ: on.

Cụm đã bật ZAP

Để bật bất kỳ Cụm nào dưới dạng Máy khách, Máy chủ hoặc Máy khách 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 Chưa 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ị của bạn.

ZAP Disable Cluster

Để tìm hiểu thêm, hãy tham khảo phần 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:

  1. Tìm Nhóm On/Off.

  2. Trên cùng một hàng, hãy nhấp vào biểu tượng Định cấu hình .

    Định cấu hình ZAP

Tại đây, bạn có thể bật hoặc tắt Thuộc tính, đặt nhiều lựa chọn Thuộc tính và Tìm kiếm thuộc tính theo tên.

Thuộc tính ZAP

Nhấp vào Lệnh để định cấu hình các thao tác cho Cụm này. Ví dụ: Cụm Bật/tắt cho đè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.

Lệnh ZAP

Để tìm hiểu thêm, hãy tham khảo Thuộc tính và lệnh trong Matter Primer.

Tạo tệp nguồn ZAP

Các ví dụ Matter sử dụng mã nguồn do ZAP tạo, có trong thư mục connectedhomeip/zzz_generated. Một số tệp 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 tệp nguồn để tích hợp vào dự án của mình.

  1. Nhấp vào biểu tượng Tạo.
  2. Chọn một thư mục để lưu đầu ra ZAP. Ví dụ: chuyển đến connectedhomeip/zzz_generated/lighting-app/zap-generated để xem lighting-app.
  3. Không bắt buộc. Mở các tệp trong IDE mà bạn muốn.

ZAP tạo ra các định nghĩa, hàm và mã nguồn khác được tuỳ chỉnh theo loại thiết bị và cấu hình ZAP của bạn.

Tệp do ZAP tạo

Ví dụ: callback-stub.cpp bao gồm một 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

Bạn có thể dùng các tệp nguồn ZAP phổ biến (ví dụ: Attributes.h trong zzz_generated/app-common/app-common/zap-generated/ids/) để nhận và đặt 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:

  • Sử dụng các tệp zzz_generated hiện có để tạo các ví dụ mới, dành riêng cho các loại thiết bị của bạn.
  • Tạo 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 dùng run_zaptool.sh để chạy ZAP, tập lệnh này sẽ truyề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 được dùng trong các ví dụ 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

Để biết thêm tài nguyên về ZAP, hãy tham khảo kho lưu trữ ZAP (zap) trên GitHub.