แพลตฟอร์มขั้นสูง ZCL (ZAP)

ZCL Advanced Platform (ZAP) เป็นเครื่องมือเทมเพลต Node.js ที่อิงตามMatterคลัสเตอร์

ZAP มีฟีเจอร์ต่อไปนี้สําหรับแอปและ SDK ของ Matter

  • กำหนดค่าMatterอุปกรณ์ปลายทาง คลัสเตอร์ แอตทริบิวต์ และฟีเจอร์อื่นๆ ของอุปกรณ์จากอินเทอร์เฟซ GUI
  • สร้างเทมเพลตที่สร้างคําจํากัดความของโมเดลข้อมูล Callback และซอร์สโค้ด Matter อื่นๆ โดยอัตโนมัติ
  • สร้างและใช้ไฟล์ ZAP ที่กําหนดค่าไว้ล่วงหน้าเพื่อรวมไว้ใน SDK
เครื่องมือ ZAP

ติดตั้ง

  1. ไปที่หน้ารุ่น ZAP

  2. มองหารุ่นที่ติดแท็ก "ล่าสุด" (ส่วนใหญ่จะติดแท็ก "รุ่นทดลองใช้ก่อนเปิดตัว")

  3. ในส่วนชิ้นงานของรุ่นนี้ ให้เลือกแพ็กเกจที่กําหนดไว้สําหรับระบบปฏิบัติการของคุณและดาวน์โหลด

  4. ในเครื่องที่ใช้ Debian หรือ Ubuntu ให้ติดตั้ง ZAP โดยเรียกใช้คำสั่งต่อไปนี้

    sudo dpkg -i path/to/zap_installation_package

ใน Debian หรือ Ubuntu Linux ระบบจะติดตั้งไบนารี zap ใน /usr/bin/ ในระบบปฏิบัติการอื่นๆ ระบบอาจติดตั้งไบนารีไว้ที่อื่น ไม่ว่าในกรณีใด ให้ตรวจสอบว่าตำแหน่งของไฟล์ปฏิบัติการอยู่ในตัวแปรPATHสภาพแวดล้อมของคุณ

ไฟล์ ZAP

ZAP ใช้ไฟล์เทมเพลตที่เรียกว่าไฟล์ ZAP ไฟล์ ZAP คือไฟล์ JSON ที่กําหนดปลายทาง คําสั่ง แอตทริบิวต์ และฟีเจอร์อื่นๆ ของอุปกรณ์ ไฟล์ ZAP มีชื่อที่ลงท้ายด้วย .zap เช่น lighting-app.zap ใน connectedhomeip/examples/lighting-app/lighting-common

ไฟล์ all-clusters-app.zap ที่พบใน connectedhomeip/examples/all-clusters-app/all-clusters-common ได้รับการกําหนดค่าล่วงหน้าด้วยคลัสเตอร์ Matter ทั่วไปและอุปกรณ์ปลายทาง 3 เครื่อง รวมถึงประเภทอุปกรณ์ตรวจสอบเครือข่ายรอง Matter นี่เป็นตัวอย่างที่ดีในการสำรวจการกําหนดค่าคลัสเตอร์ต่างๆ

เรียกใช้

  1. เลือกไฟล์ ZAP จากตัวอย่าง Matter รายการใดรายการหนึ่ง
  2. จากไดเรกทอรีรูทของที่เก็บ Matter (connectedhomeip) ให้เรียกใช้สคริปต์ Wrapper run_zaptool.sh โดยส่งเส้นทางไปยังไฟล์ .zap

เช่น

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

ตั้งค่า

ใน การตั้งค่า คุณสามารถกําหนดค่าอินเทอร์เฟซผู้ใช้ ZAP รวมถึงเลือกธีมสว่างหรือธีมมืด รวมถึงเปิดหรือปิดใช้เครื่องมือสําหรับนักพัฒนาซอฟต์แวร์

การคลิก Options ให้คุณเลือกผู้ผลิตนโยบายการตอบกลับเริ่มต้น และเปิดหรือปิดใช้ Command Discovery

ตัวเลือก ZAP ทั่วโลก

คลิก ส่วนขยายเพื่อเพิ่มคลัสเตอร์หรือคําสั่ง ZCL ที่กําหนดเองลงในเครื่องมือกําหนดค่าคลัสเตอร์ Zigbee

ใช้

ปลายทาง

ไฟล์ lighting-app.zap ได้รับการกําหนดค่าล่วงหน้าด้วยMatter โหนดรูท (อุปกรณ์ปลายทาง - 0) และMatter หลอดไฟหรี่แสงได้ (อุปกรณ์ปลายทาง - 1)

Endpoint - 0 รวมคลัสเตอร์ทั่วไปที่เกี่ยวข้องกับโหนดทั้งหมด เช่น เครือข่าย การจัดเตรียม รายละเอียด ข้อมูลเข้าสู่ระบบสำหรับการดำเนินการ และคลัสเตอร์ OTA

ปลายทาง ZAP 0

ในขั้นตอนถัดไป คุณจะตรวจสอบและกำหนดค่า Endpoint - 1 Matter หลอดไฟหรี่แสงได้จากตัวอย่าง lighting-app

  1. เรียกใช้ ZAP จาก Matter repo connectedhomeip

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

  2. คลิก Endpoint - 1 แล้วคลิก แก้ไข

  3. ไม่บังคับ: Matter รองรับอุปกรณ์ประเภทต่างๆ ในเมนูแบบเลื่อนลงอุปกรณ์ ให้เริ่มพิมพ์ matter เพื่อเปลี่ยนอุปกรณ์ แล้วคลิกบันทึก

    ZAP เลือกอุปกรณ์

ดูข้อมูลเพิ่มเติมได้ที่หัวข้ออุปกรณ์และปลายทางในMatter Primer

คลัสเตอร์

ระบบจะเปิดใช้ตัวเลือกคลัสเตอร์ แอตทริบิวต์ และการรายงานที่กําหนดไว้ล่วงหน้าในปลายทาง - 1 โดยค่าเริ่มต้น

หากต้องการแสดงเฉพาะคลัสเตอร์ที่เปิดใช้ ให้คลิก Endpoint - 1 แล้วเลือกคลัสเตอร์ที่เปิดใช้จากเมนูแสดง นอกจากนี้ คุณยังค้นหาคลัสเตอร์ ตามชื่อได้ด้วย เช่น on

คลัสเตอร์ที่เปิดใช้ ZAP

หากต้องการเปิดใช้คลัสเตอร์เป็นไคลเอ็นต์ เซิร์ฟเวอร์ หรือไคลเอ็นต์และเซิร์ฟเวอร์ ให้ใช้เมนูแบบเลื่อนลงเปิดใช้ นอกจากนี้ คุณยังเลือกไม่ได้เปิดใช้เพื่อปิดใช้คลัสเตอร์ที่กำหนดค่าไว้ล่วงหน้าซึ่งใช้ไม่ได้กับประเภทอุปกรณ์ของคุณได้ด้วย

ปิดใช้คลัสเตอร์ ZAP

ดูข้อมูลเพิ่มเติมได้ที่คลัสเตอร์ในMatter Primer

แอตทริบิวต์และคำสั่ง

หากต้องการกําหนดค่าแอตทริบิวต์และคําสั่ง ให้ทําตามขั้นตอนต่อไปนี้

  1. ค้นหาคลัสเตอร์ On/Off

  2. ในแถวเดียวกัน ให้คลิกไอคอนกําหนดค่า

    กำหนดค่า ZAP

ในส่วนนี้ คุณสามารถเปิดหรือปิดใช้แอตทริบิวต์ ตั้งค่าตัวเลือกแอตทริบิวต์ต่างๆ และค้นหาแอตทริบิวต์ ตามชื่อ

แอตทริบิวต์ ZAP

คลิกคําสั่งเพื่อกําหนดค่าการดําเนินการสําหรับคลัสเตอร์นี้ ตัวอย่างเช่น กลุ่มเปิด/ปิดสำหรับหลอดไฟจะมีคำสั่งเปิด ปิด และสลับ คลัสเตอร์บางรายการ เช่น Temperature Measurement Cluster อาจไม่มีคําสั่งที่เชื่อมโยง

คำสั่ง ZAP

ดูข้อมูลเพิ่มเติมได้ที่หัวข้อแอตทริบิวต์และคําสั่งในMatter Primer

สร้างไฟล์ต้นทาง ZAP

ตัวอย่าง Matter ใช้ซอร์สโค้ดที่ ZAP สร้างขึ้น ซึ่งมีอยู่ในไดเรกทอรี connectedhomeip/zzz_generated ไฟล์บางไฟล์มีไว้สำหรับแอปโดยเฉพาะ ส่วนไฟล์ ZAP ทั่วไปอื่นๆ จะจัดกลุ่มไว้ใน app-common

#include <app-common/zap-generated/ids/Attributes.h>
#include <app-common/zap-generated/ids/Clusters.h>

เมื่อกําหนดค่าปลายทางแล้ว คุณสามารถสร้างไฟล์ต้นฉบับเพื่อผสานรวมเข้ากับโปรเจ็กต์ได้

  1. คลิก สร้าง
  2. เลือกโฟลเดอร์เพื่อบันทึกเอาต์พุต ZAP เช่น ไปที่ connectedhomeip/zzz_generated/lighting-app/zap-generated สำหรับ lighting-app
  3. ไม่บังคับ เปิดไฟล์ใน IDE ที่ต้องการ

ZAP จะสร้างการกําหนด ฟังก์ชัน และซอร์สโค้ดอื่นๆ ที่ปรับแต่งตามประเภทอุปกรณ์และการกําหนดค่า ZAP

ไฟล์ที่ ZAP สร้างขึ้น

ตัวอย่างเช่น callback-stub.cpp มีเมธอดการเรียกกลับคลัสเตอร์ที่รวมเฉพาะคลัสเตอร์ที่คุณเปิดใช้ไว้เท่านั้น

void emberAfClusterInitCallback(EndpointId endpoint, ClusterId clusterId)
{
    switch (clusterId)
    {
     ...
     case ZCL_ON_OFF_CLUSTER_ID :
        emberAfOnOffClusterInitCallback(endpoint);
        break;
     ...
    }
}

ใช้ไฟล์ต้นทาง ZAP

ไฟล์ซอร์ส ZAP ทั่วไป เช่น Attributes.h ใน zzz_generated/app-common/app-common/zap-generated/ids/ สามารถใช้เพื่อรับและตั้งค่าแอตทริบิวต์ประเภทอุปกรณ์ได้ ดังนี้

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");
    }
}

เมื่อเข้าใจวิธีใช้ไฟล์ ZAP ในMatter ซอร์สโค้ดแล้ว คุณผสานรวม ZAP ได้หลายวิธี ดังนี้

  • ใช้ไฟล์ zzz_generated ที่มีอยู่เพื่อสร้างตัวอย่างใหม่ที่ไม่ซ้ำกันสำหรับประเภทอุปกรณ์ของคุณ
  • สร้างไฟล์ .zap ที่กําหนดเองสําหรับโปรเจ็กต์

ปรับแต่ง

ไฟล์ ZAP สร้างขึ้นจากเทมเพลต ZAP เมื่อคุณใช้ run_zaptool.sh เพื่อเปิด ZAP สคริปต์นี้จะส่งเทมเพลตต่อไปนี้

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 กำหนดชื่อเทมเพลต Matter และไฟล์เอาต์พุตที่เกี่ยวข้องซึ่งใช้ในตัวอย่าง Matter

{
    "path": "templates/app/callback-stub-src.zapt",
    "name": "ZCL callback-stub source",
    "output": "callback-stub.cpp"
}

หากต้องการปรับแต่งโซลูชัน Matter คุณสามารถทำตามขั้นตอนต่อไปนี้เมื่อใช้ ZAP

แหล่งข้อมูล

ดูแหล่งข้อมูลเพิ่มเติมของ ZAP ได้ที่ที่เก็บ ZAP (zap) ใน GitHub