Kể từ năm 2026, mọi hoạt động kiểm thử và tích hợp Matter đều sẽ yêu cầu Kiểm thử khả năng tương tác của Liên minh. Để biết thêm thông tin, hãy xem trang chuyển đổi Phòng thử nghiệm khả năng tương tác của Liên minh.

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

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

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

Đị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ị từ giao diện GUI.
Tạo 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ài đặt

Chuyển đến trang phát hành ZAP.
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ẻ "Bản phát hành trước").
Trong bản phát hành này, trong tiêu đề 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ột 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 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 Đ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ị uỷ quyền mạng thứ cấp Matter. Đây là một ví dụ hay để 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ụ 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ọc run_zaptool.sh, truyền đườ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 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 biểu tượng điều chỉnh Options (Tuỳ chọn), bạn có thể chọn Product Manufacturer (Nhà sản xuất sản phẩm), Default Response Policy (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 Extensions để thêm các 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 với một Matter Nút gốc (Điểm cuối - 0) và một Matter Đèn có thể điều chỉnh độ sáng (Điểm cuối - 1).

Endpoint – 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 uỷ quyền, Cụm mô tả, Cụm 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 Đèn có thể điều chỉnh độ sáng từ ví dụ lighting-app.

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

Nhấp vào Endpoint – 1, sau đó 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 Device (Thiết bị), hãy bắt đầu nhập matter để thay đổi thiết bị, sau đó nhấp vào SAVE (LƯU).

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

Cụm

Các Cụm, Thuộc tính và tuỳ chọn Báo cáo được xác định trước sẽ được bật trong Endpoint – 1 theo mặc định.

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

Để bật bất kỳ Cụm nào dưới dạng Client (Máy khách), Server (Máy chủ) hoặc Client & Server (Máy khách và máy chủ), hãy sử dụng trình đơn thả xuống Enable (Bật). Bạn cũng có thể chọn Not Enabled (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.

Để tìm hiểu thêm, hãy tham khảo Cụm trong phần Giới thiệu về Matter.

Thuộc tính và lệnh

Để định cấu hình Thuộc tính và lệnh, hãy hoàn thành 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à Search attributes theo tên.

Nhấp vào Commands (Lệnh) để định cấu hình các hành động cho Cụm này. Ví dụ: Cụm On/off (Bật/tắt) cho đèn sẽ bao gồm các lệnh On (Bật), Off (Tắt) và Toggle (Chuyển đổi). Một số Cụm, chẳng hạn như Cụm Temperature Measurement (Đo nhiệt độ), có thể không có bất kỳ Lệnh nào được liên kết.

Để tìm hiểu thêm, hãy tham khảo Thuộc tính và lệnh trong phần Giới thiệu về Matter.

Tạo tệp nguồn ZAP

Matter ví dụ 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 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.

Nhấp vào Generate (Tạo).
Chọn một thư mục để lưu kết quả ZAP. Ví dụ: chuyển đến connectedhomeip/zzz_generated/lighting-app/zap-generated cho lighting-app.
Không bắt buộc. Mở 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 dành riêng cho loại thiết bị và cấu hình ZAP của bạn.

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ể sử 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/, để lấy 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 bạn hiểu cách sử dụng tệp ZAP trong Matter mã nguồn, có một số cách để 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, 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ỳ chỉnh

Tệp ZAP được tạo từ các mẫu ZAP ZAP. Khi bạn sử 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 sử 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, 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ạo mẫu ZAP.
Tích hợp ZAP vào SDK.

Tài nguyên

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