Platform Lanjutan ZCL (ZAP)

ZCL Advanced Platform (ZAP) adalah mesin template node.js yang didasarkan pada Matter Cluster.

ZAP menyediakan fitur berikut untuk Matter aplikasi dan SDK:

• Mengonfigurasi Matter Endpoint, Cluster, Atribut, dan fitur perangkat lainnya dari antarmuka GUI.
• Membuat template yang otomatis menghasilkan definisi Model Data, callback, dan kode sumber Matter lainnya.
• Membuat dan menggunakan file ZAP yang telah dikonfigurasi sebelumnya untuk disertakan dengan SDK Anda.

Instal

1. Buka halaman rilis ZAP.

2. Cari rilis yang diberi tag "Terbaru" (sebagian besar akan diberi tag "Pra-rilis").

3. Di bagian rilis ini, di bagian Aset, pilih paket yang ditetapkan untuk sistem operasi Anda, lalu download.

4. Di mesin yang menjalankan Debian atau Ubuntu, instal ZAP dengan menjalankan:

   sudo dpkg -i path/to/zap_installation_package

Di Debian atau Ubuntu Linux, biner zap diinstal di /usr/bin/. Di sistem operasi lain, biner dapat diinstal di tempat lain. Bagaimanapun, pastikan lokasi file yang dapat dieksekusi berada di variabel lingkungan PATH Anda.

File ZAP

ZAP menggunakan file template yang disebut file ZAP. File ZAP adalah file JSON yang menentukan Endpoint, Perintah, Atribut, dan fitur perangkat lainnya. File ZAP memiliki nama yang diakhiri dengan .zap. Misalnya, lighting-app.zap di connectedhomeip/examples/lighting-app/lighting-common.

File all-clusters-app.zap, yang ditemukan di connectedhomeip/examples/all-clusters-app/all-clusters-common, telah dikonfigurasi sebelumnya dengan Cluster Matter umum dan tiga Endpoint, termasuk Jenis Perangkat Komisioning Jaringan Sekunder Matter. Ini adalah contoh yang baik untuk menjelajahi berbagai konfigurasi Cluster.

Jalankan

1. Pilih file ZAP dari salah satu contoh Matter.
2. Dari direktori root repositori Matter (connectedhomeip), jalankan skrip wrapper run_zaptool.sh, dengan meneruskan jalur ke file .zap.

Contoh:

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

Siapkan

Di settings Setelan Anda dapat mengonfigurasi antarmuka pengguna ZAP, termasuk pilihan tema terang atau gelap, dan mengaktifkan atau menonaktifkan alat developer.

Dengan mengklik tune Opsi , Anda dapat memilih Produsen Produk , Kebijakan Respons Default , serta mengaktifkan atau menonaktifkan Penemuan Perintah.

Klik extension Ekstensi untuk menambahkan cluster atau perintah ZCL kustom ke Konfigurator Cluster Zigbee.

Gunakan

Endpoint

File lighting-app.zap telah dikonfigurasi sebelumnya dengan Matter Node Root (Endpoint - 0) dan Matter Lampu yang Dapat Diredupkan (Endpoint - 1).

Endpoint - 0 mencakup Cluster umum yang relevan dengan seluruh node, misalnya Cluster Jaringan, Komisioning, Deskriptor, Kredensial Operasional, dan OTA.

Pada langkah berikutnya, Anda akan meninjau dan mengonfigurasi Endpoint - 1 Matter Lampu yang Dapat Diredupkan dari contoh lighting-app.

1. Dari Matter repo connectedhomeip, jalankan ZAP.

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

2. Klik Endpoint - 1, lalu edit EDIT.

3. Opsional: Matter mendukung berbagai jenis perangkat. Di dropdown Perangkat, mulai ketik matter untuk mengubah perangkat, lalu klik SIMPAN.

   

Untuk mempelajari lebih lanjut, lihat Perangkat dan Endpoint di Matter Primer.

Cluster

Opsi Cluster, Atribut, dan Pelaporan yang telah ditentukan sebelumnya diaktifkan di Endpoint - 1 secara default.

Untuk hanya menampilkan Cluster yang diaktifkan, klik Endpoint - 1 , lalu pilih Cluster yang Diaktifkan dari menu Tampilkan. Anda juga dapat menelusuri search cluster berdasarkan nama, misalnya on.

Untuk mengaktifkan Cluster sebagai Klien, Server, atau Klien & Server, gunakan dropdown Aktifkan. Anda juga dapat memilih Tidak Diaktifkan untuk menonaktifkan Cluster yang telah dikonfigurasi sebelumnya yang tidak berlaku untuk jenis perangkat Anda.

Untuk mempelajari lebih lanjut, lihat Cluster di Matter Primer.

Atribut dan Perintah

Untuk mengonfigurasi Atribut dan Perintah, selesaikan langkah-langkah berikut:

1. Temukan Cluster On/Off.

2. Di baris yang sama, klik ikon Konfigurasi settings.

   

Di sini, Anda dapat mengaktifkan atau menonaktifkan Atribut, menetapkan berbagai opsi Atribut, dan Menelusuri atribut search berdasarkan nama.

Klik Perintah untuk mengonfigurasi tindakan untuk Cluster ini. Misalnya, Cluster On/off untuk lampu akan menyertakan perintah On, Off, dan Toggle. Beberapa Cluster, seperti Cluster Temperature Measurement, mungkin tidak memiliki Perintah terkait.

Untuk mempelajari lebih lanjut, lihat Atribut dan Perintah di Matter Primer.

Membuat file sumber ZAP

Contoh Matter menggunakan kode sumber yang dibuat ZAP, yang tersedia di direktori connectedhomeip/zzz_generated. Beberapa file khusus untuk aplikasi, sedangkan file ZAP generik lainnya dikelompokkan dalam app-common.

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

Setelah Endpoint dikonfigurasi, Anda dapat membuat file sumber untuk diintegrasikan ke dalam project.

1. Klik video_settings Buat.
2. Pilih folder untuk menyimpan output ZAP. Misalnya, buka connectedhomeip/zzz_generated/lighting-app/zap-generated untuk lighting-app.
3. Opsional. Buka file di IDE pilihan Anda.

ZAP membuat definisi, fungsi, dan kode sumber lainnya yang khusus untuk jenis perangkat dan konfigurasi ZAP Anda.

Misalnya, callback-stub.cpp menyertakan metode callback Cluster yang hanya menyertakan Cluster yang telah Anda aktifkan:

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

Menggunakan file sumber ZAP

File sumber ZAP umum, misalnya Attributes.h di zzz_generated/app-common/app-common/zap-generated/ids/, dapat digunakan untuk mendapatkan dan menetapkan Atribut jenis perangkat:

namespace DeviceTemperatureConfiguration {
  namespace Attributes {

  namespace CurrentTemperature {
    static constexpr AttributeId Id = 0x00000000;
    } // namespace CurrentTemperature

  ...

  } // namespace Attributes
} // namespace DeviceTemperatureConfiguration

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

Setelah Anda memahami cara file ZAP dapat digunakan dalam Matter kode sumber, ada beberapa cara untuk mengintegrasikan ZAP:

• Gunakan file zzz_generated yang ada untuk membuat contoh baru yang unik untuk jenis perangkat Anda.
• Buat file .zap kustom untuk project Anda.

Sesuaikan

File ZAP dibuat dari template ZAP. Saat Anda menggunakan run_zaptool.sh untuk meluncurkan ZAP, skrip ini akan meneruskan template berikut:

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 menentukan nama template Matter dan file output yang sesuai yang digunakan dalam contoh Matter.

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

Untuk menyesuaikan solusi Matter, ada beberapa langkah berikutnya yang dapat Anda lakukan saat menggunakan ZAP:

• Buat template ZAP.
• Integrasikan ZAP ke dalam SDK Anda.

Resource

Untuk resource ZAP tambahan, lihat repo ZAP (zap) di GitHub.