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

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

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

  • Định cấu hình điểm cuối, cụm, thuộc tính và Matter các tính năng khác của thiết bị từ giao diện GUI.
  • 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ủa bạn.
Công cụ ZAP

Cài đặt

  1. Truy cập trang bản phát hành của 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ẻ "Trước khi phát hành").

  3. Trong bản phát hành này, trong phần tiêu đề Assets (Tài sản), hãy chọn gói được thiết kế cho hệ điều hành của bạn và tải xuống ứng dụ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/. Bật 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, kiểm tra để đảm bảo vị trí của tệp thực thi nằm trong môi trường PATH của bạn biến.

Tệp ZAP

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

Chạy

  1. Chọn tệp ZAP ở một trong các ví dụ Matter.
  2. Trong 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 vào đó đườ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 của , 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ủa bạn và bật hoặc tắt công cụ cho nhà phát triển.

Nhấp vào Tùy chọn cho phép bạn chọn Sản phẩm Manufacturer, Chính sách phản hồi mặc định và bật hoặc tắt Command Khám phá.

Tuỳ chọn ZAP Global

Nhấp vào Tiện ích để thêm tùy chỉnh Các cụm ZCL hoặc lệnh được gửi đến 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 Matter Nút gốc (Điểm cuối – 0) và Ánh sáng 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 là liên quan đến toàn bộ nút, ví dụ: Nối mạng, uỷ quyền, Mô tả, Thông tin xác thực hoạt động và cụm OTA.

Điểm cuối ZAP 0

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

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

  2. Nhấp vào Điểm cuối – 1, sau đó 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ị của bạn, sau đó nhấp vào LƯU.

    Thiết bị ZAP chọn lọc

Để tìm hiểu thêm, hãy tham khảo Thiết bị và Điểm cuối trong mồi nhử Matter.

Cụm

Tùy chọn Cụm, Thuộc tính và Báo cáo xác định trước đượ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 Enabled Clusters (Các cụm đã bật) trong ngăn Show (Chương trình) . Bạn cũng có thể tìm kiếm cụm theo tên, ví dụ: on.

Cụm hỗ trợ ZAP

Để bật bất kỳ Cụm nào làm Ứng dụng, Máy chủ hoặc Ứng dụng và Máy chủ, 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 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.

Cụm vô hiệu hoá ZAP

Để tìm hiểu thêm, hãy tham khảo Cụm trong Matter Mẹo.

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 cụ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 các tùy chọn Thuộc tính khác nhau và Tìm kiếm thuộc tính theo tên.

Thuộc tính ZAP

Nhấp vào Commands (Lệnh) để định cấu hình các thao tác cho Cluster này. Cho ví dụ: Cụm Bật/tắt của đèn sẽ bao gồm các trạng thái Bật, Tắt, và Toggle (Bật/tắt). Một số Cụm, như Cụm Temperature Measurement có thể không có lệnh nào được liên kết.

Các lệnh ZAP

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

Tạo tệp nguồn ZAP

Các ví dụ về Matter sử dụng mã nguồn do ZAP tạo, có sẵn 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 vào 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 bạn.

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

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

Tệp do ZAP tạo

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, ví dụ: Attributes.h trong zzz_generated/app-common/app-common/zap-generated/ids/, có thể dùng để tải 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 nắm được cách sử dụng tệp ZAP trong Matter mã nguồn, có một số cách để bạn có thể tích hợp ZAP:

  • Sử dụng các tệp zzz_generated hiện có để tạo các ví dụ mới, chỉ dành cho loại thiết bị của bạn.
  • Tạo tệp .zap tuỳ chỉnh cho các dự án của bạn.

Tuỳ chỉnh

Các tệp ZAP được tạo bằng ZAP mẫu. Khi bạn sử dụng run_zaptool.sh để chạy ZAP, tập lệnh này sẽ truyền như sau mẫu:

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 giải pháp Matter của bạn, có một số bước tiếp theo các bước mà bạn có thể thực hiện khi làm việc với ZAP:

Tài nguyên

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