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.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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 Matter Clusters.

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 người dùng đồ hoạ (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ài đặt

Chuyển đến trang Bản 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 đề 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 của bạ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à 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 (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à ba Điểm cuối, bao gồm cả Loại thiết bị uỷ quyền mạng phụ 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ụ về Matter.
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 đườ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ả việc chọn giao diện sáng hoặc Giao diện tối, cũng như bật hoặc tắt các công cụ cho nhà phát triển.

Khi nhấp vào 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 Command Discovery (Khám phá lệnh).

Nhấp vào Extensions (Tiện ích) để thêm các cụm hoặc lệnh ZCL tuỳ chỉnh vào Zigbee Clusters Configurator (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 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).

Đ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 kết nối mạng, Cụm uỷ nhiệm, 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 Dimmable Light (Đèn có thể điều chỉnh độ sáng) trong ví dụ lighting-app.

Trong Matter kho lưu trữ connectedhomeip, hãy chạy ZAP.

scripts/tools/zap/run_zaptool.sh \
examples/lighting-app/lighting-common/lighting-app.zap

Nhấp vào Thiết bị đầu cuối – 1, sau đó 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ị, 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 Matter Primer.

Cụm

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 Đ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 thị. Bạn cũng có thể tìm kiếm các cụm theo tên, ví dụ: 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 (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 phần Cụm trong tài liệu Sơ lược 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 tất các bước sau:

Tìm cụm On/Off.
Trên cùng 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 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à Chuyển đổi. Một số Cụm, chẳng hạn như Cụm Temperature Measurement, có thể không có bất kỳ Lệnh nào 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 Tài liệu cơ bản về Matter.

Tạo tệp nguồn ZAP

Các ví dụ về 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.

Nhấp vào biểu tượng Tạo.
Chọn một thư mục để lưu kết quả của ZAP. Ví dụ: chuyển đến connectedhomeip/zzz_generated/lighting-app/zap-generated cho lighting-app.
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 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 một phương thức gọi lại Cụm chỉ bao gồm những 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, chẳng hạn như 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 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 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ừ mẫu ZAP. Khi bạn sử dụng run_zaptool.sh để chạy ZAP, tập lệnh này sẽ truyền vào 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ụ 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ạo mẫu ZAP.
Tích hợp ZAP vào SDK của bạn.

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.