ZCL Advanced Platform (ZAP)

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

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

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

Zainstaluj

  1. Otwórz stronę Wersje ZAP.

  2. Znajdź wersję oznaczoną jako „Najnowsza” (większość będzie oznaczona jako „Wersja 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 polecenie:

    sudo dpkg -i path/to/zap_installation_package

W systemach Linux Debian i Ubuntu plik binarny zap jest instalowany w folderze /usr/bin/. W przypadku innych systemów 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 zwanych plikami ZAP. Plik ZAP to plik JSON, który definiuje punkty końcowe, polecenia, atrybuty i inne funkcje urządzenia. Pliki ZAP mają nazwy kończące się na .zap. Na przykład:lighting-app.zapconnectedhomeip/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 typami Matter klastrów i 3 punktami końcowymi, w tym z typem urządzenia Matter Secondary Network Commissioning Device Type. To dobry przykład do poznawania różnych konfiguracji klastra.

Uruchom

  1. Wybierz plik ZAP z jednego z Matter przykładów.
  2. W katalogu głównym repozytorium Matter (connectedhomeip) uruchom skrypt opakowujący 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 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 Opcje umożliwia wybranie producenta, domyślnych zasad odpowiedzi oraz włączenie lub wyłączenie wykrywania poleceń.

Opcje globalne ZAP

Kliknij 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 Matterwęzłem głównym (Endpoint – 0) i Matterściemnianym światłem (Endpoint – 1).

Punkt końcowy – 0 obejmuje ogólne klastry, które są istotne dla całego węzła, np. klastry sieciowe, klastry uruchamiania, klastry deskryptorów, klastry poświadczeń operacyjnych i klastry OTA.

Punkt końcowy ZAP 0

W kolejnych krokach sprawdzisz i skonfigurujesz punkt końcowy 1 Matter ściemnialnego oświetlenia z przykładowego 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 EDYTUJ.

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

    ZAP Select Device

Więcej informacji znajdziesz w sekcji Urządzenia i punkty końcoweMatter przewodniku.

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 według nazwy, na przykład on.

Klastry z włączonym ZAP

Aby włączyć dowolny klaster jako klient, serwer lub klient i serwer, użyj menu Włącz. Możesz też wybrać Not Enabled (Wyłączone), aby wyłączyć wstępnie skonfigurowany klaster, który nie ma zastosowania do Twojego typu urządzenia.

ZAP Disable Cluster

Więcej informacji znajdziesz w sekcji KlastryMatter przewodniku.

Atrybuty i polecenia

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

  1. Znajdź On/Off Klaster.
  2. W tym samym wierszu kliknij ikonę Skonfiguruj .

    Konfiguracja ZAP

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

Atrybuty ZAP

Aby skonfigurować działania dla tego klastra, kliknij Polecenia. Na przykład klaster Włączanie/wyłączanie dla światła będzie zawierać polecenia Włącz, WyłączPrzełącz. Niektóre klastry, np. klaster Temperature Measurement, mogą nie mieć powiązanych poleceń.

Polecenia ZAP

Więcej informacji znajdziesz w sekcji Atrybuty i poleceniaMatter przewodniku.

Generowanie plików źródłowych ZAP

Przykłady Matter korzystają z kodu źródłowego wygenerowanego przez ZAP, który jest dostępny w katalogu connectedhomeip/zzz_generated. Niektóre pliki są specyficzne dla aplikacji, a inne ogólne pliki ZAP są zgrupowane w 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 do zintegrowania z projektem.

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

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

Pliki wygenerowane przez ZAP

Na przykład callback-stub.cpp zawiera metodę wywołania zwrotnego Cluster, która obejmuje tylko włączone przez Ciebie klastry:

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

Korzystanie z plików źródłowych ZAP

Typowe źródłowe pliki ZAP, np. Attributes.h in zzz_generated/app-common/app-common/zap-generated/ids/, można wykorzystać do pobierania i ustawiania atrybutów typu urządzenia:

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

Gdy zrozumiesz, jak można używać plików ZAP w Matterkodzie źródłowym, 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 .zap do projektów.

Dostosuj

Pliki ZAP są generowane na podstawie szablonów ZAP. Gdy używasz run_zaptool.sh do uruchamiania 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 określa Matter nazwę szablonu i odpowiedni plik wyjściowy użyty w Matter przykładach.

{
    "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 czynności podczas pracy z ZAP:

Zasoby

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