ZCL Advanced Platform (ZAP)

ZCL Advanced Platform (ZAP) to silnik szablonów node.js oparty na klastrach Matter.

ZAP zapewnia te funkcje w przypadku aplikacji i pakietów SDK Matter:

• Skonfiguruj punkty końcowe, klastry, atrybuty i inne funkcje urządzenia Matter za pomocą interfejsu GUI.
• Twórz szablony, które automatycznie generują definicje modelu danych, wywołania zwrotne i inny kod źródłowy Matter.
• Tworzenie i używanie wstępnie skonfigurowanych plików ZAP do dołączenia do pakietów SDK.

Zainstaluj

1. Otwórz stronę Wersje ZAP.

2. Znajdź wersję oznaczoną tagiem „Latest” (większość będzie oznaczona tagiem „przedpremierowa”).

3. W sekcji Zasoby wybierz pakiet przeznaczony dla Twojego systemu operacyjnego i pobierz go.

4. Na komputerze z systemem Debian lub Ubuntu zainstaluj ZAP, uruchamiając:

   sudo dpkg -i path/to/zap_installation_package

W systemie Debian lub Ubuntu Linux plik binarny zap jest instalowany w /usr/bin/. W innych systemach operacyjnych plik binarny może być zainstalowany w innym miejscu. W każdym przypadku sprawdź, czy lokalizacja pliku wykonywalnego znajduje się w zmiennej środowiskowej PATH.

Pliki ZAP

ZAP używa plików szablonów nazywanych plikami ZAP. Plik ZAP to plik JSON, który definiuje punkty końcowe, polecenia, atrybuty i inne funkcje urządzenia. Nazwy plików ZAP kończą się na .zap. Na przykład: lighting-app.zap w connectedhomeip/examples/lighting-app/lighting-common.

Plik all-clusters-app.zap, który znajduje się w connectedhomeip/examples/all-clusters-app/all-clusters-common, jest wstępnie skonfigurowany z typowymi klastrami Matter i 3 punktami końcowymi, w tym z typem urządzenia do uruchamiania sieci pomocniczej Matter. To dobry przykład do zapoznania się z różnymi konfiguracjami klastrów.

Uruchom

1. thought Wybierz plik ZAP z jednego z przykładów Matter.
2. W katalogu głównym repozytorium Matter (connectedhomeip) uruchom skrypt otoki run_zaptool.sh, przekazując mu ścieżkę do pliku .zap.

Na przykład:

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

Skonfiguruj

W Ustawieniach settings możesz skonfigurować interfejs ZAP, w tym wybrać jasny lub ciemny motyw oraz włączyć lub wyłączyć narzędzia dla programistów.

Kliknięcie tune Opcje umożliwia wybranie producenta produktu, domyślnych zasad odpowiedzi oraz włączenie lub wyłączenie wykrywania poleceń.

Kliknij extension Extensions (Rozszerzenia), aby dodać niestandardowe klastry lub polecenia ZCL do konfiguratora klastrów Zigbee.

Użyj

Punkty końcowe

Plik lighting-app.zap jest wstępnie skonfigurowany z węzłem głównym Matter (Endpoint – 0) i lampą ze ściemniaczem Matter (Endpoint – 1).

Punkt końcowy – 0 obejmuje ogólne klastry, które są istotne dla całego węzła, np. klastry sieci, uruchamiania, deskryptora, danych uwierzytelniających i OTA.

W następnych krokach sprawdzisz i skonfigurujesz Punkt końcowy – 1 Matter Ściemnialne światło z przykładu lighting-app.

1. Uruchom ZAP z repozytorium Matter connectedhomeip.

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

2. Kliknij Endpoint – 1, a następnie edit EDYTUJ.

3. Opcjonalnie: Matter obsługuje różne typy urządzeń. W menu Urządzenie zacznij wpisywać matter, aby zmienić urządzenie, a następnie kliknij ZAPISZ.

   

Więcej informacji znajdziesz w sekcji Urządzenia i punkty końcowe w dokumencie Matter Primer.

Klastry

Wstępnie zdefiniowane klastry, atrybuty i opcje raportowania są domyślnie włączone w punkcie końcowym – 1.

Aby wyświetlić tylko włączone klastry, kliknij Punkt końcowy – 1 i w menu Pokaż wybierz Włączone klastry. Możesz też wyszukiwać klastry search według nazwy, na przykład on.

Aby włączyć dowolny klaster jako klienta, serwer lub klienta i serwer, użyj menu Włącz. Możesz też wybrać Nie włączono, aby wyłączyć wstępnie skonfigurowany klaster, który nie dotyczy Twojego typu urządzenia.

Więcej informacji znajdziesz w sekcji Klastry w dokumencie Matter – wprowadzenie.

Atrybuty i polecenia

Aby skonfigurować atrybuty i polecenia, wykonaj te czynności:

1. Znajdź klaster On/Off.

2. W tym samym wierszu kliknij ikonę konfiguracji settings.

   

Tutaj możesz włączać i wyłączać atrybuty, ustawiać różne opcje atrybutów oraz wyszukiwać atrybuty search według nazwy.

Kliknij Polecenia, aby skonfigurować działania dla tego klastra. Na przykład klaster Wł./wył. dla oświetlenia będzie zawierać polecenia Włącz, Wyłącz i Przełącz. Niektóre klastry, np. Temperature Measurement, mogą nie mieć powiązanych poleceń.

Więcej informacji znajdziesz w sekcji Atrybuty i polecenia w dokumencie Matter Primer.

Generowanie plików źródłowych ZAP

Przykłady Matter używają kodu źródłowego wygenerowanego przez ZAP, który jest dostępny w katalogu connectedhomeip/zzz_generated. Niektóre pliki są przeznaczone dla konkretnych aplikacji, a inne ogólne pliki ZAP są pogrupowane w folderze app-common.

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

Po skonfigurowaniu punktów końcowych możesz wygenerować pliki źródłowe, które zostaną zintegrowane z Twoim projektem.

1. Kliknij video_settings Wygeneruj.
2. Wybierz folder, w którym chcesz zapisać dane wyjściowe ZAP. Na przykład przejdź do connectedhomeip/zzz_generated/lighting-app/zap-generated, aby wyświetlić lighting-app.
3. Opcjonalnie. Otwórz pliki w preferowanym środowisku IDE.

ZAP generuje definicje, funkcje i inny kod źródłowy dostosowany do typu urządzenia i konfiguracji ZAP.

Na przykład callback-stub.cpp zawiera metodę wywołania zwrotnego klastra, która obejmuje tylko klastry, które zostały włączone:

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

Używanie plików źródłowych ZAP

Do pobierania i ustawiania atrybutów typu urządzenia można używać typowych plików źródłowych ZAP, np. Attributes.h w zzz_generated/app-common/app-common/zap-generated/ids/:

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

Gdy już zrozumiesz, jak można używać plików ZAP w kodzie źródłowym Matter, możesz zintegrować ZAP na kilka sposobów:

• Użyj istniejących plików zzz_generated, aby utworzyć nowe przykłady, unikalne dla Twoich typów urządzeń.
• Twórz niestandardowe pliki .zap na potrzeby swoich projektów.

Dostosuj

Pliki ZAP są generowane na podstawie szablonów ZAP. Gdy używasz run_zaptool.sh do uruchomienia ZAP, ten skrypt przekazuje te szablony:

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 definiuje nazwę szablonu Matter i odpowiadający mu plik wyjściowy używany w przykładach Matter.

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

Aby dostosować rozwiązania Matter, możesz wykonać kilka kolejnych kroków we współpracy z ZAP:

• Utwórz szablony ZAP.
• Zintegruj ZAP z pakietem SDK.

Zasoby

Dodatkowe materiały dotyczące ZAP znajdziesz w repozytorium ZAP (zap) na GitHubie.