ZCL Advanced Platform (ZAP)

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

ZAP udostępnia te funkcje w przypadku Matter aplikacji i pakietów SDK:

• Konfigurowanie Matter punktów końcowych, klastrów, atrybutów i innych funkcji urządzenia za pomocą interfejsu GUI.
• Tworzenie szablonów, które automatycznie generują definicje modelu danych, wywołania zwrotne i inny Matter kod źródłowy.
• Tworzenie i używanie wstępnie skonfigurowanych plików ZAP, które można dołączyć do pakietów SDK.

Zainstaluj

1. Otwórz stronę wersji ZAP.

2. Znajdź wersję oznaczoną jako „Najnowsza” (większość będzie oznaczona jako „Wersja wstępna”).

3. W tej wersji 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 to polecenie:

   sudo dpkg -i path/to/zap_installation_package

W systemie Debian lub Ubuntu Linux plik binarny zap jest instalowany w katalogu /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ę rozszerzeniem .zap. Na przykład, lighting-app.zap w connectedhomeip/examples/lighting-app/lighting-common.

Plik all-clusters-app.zap znajdujący 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 Matter Secondary Network Commissioning. To dobry przykład do poznania różnych konfiguracji klastrów.

Uruchom

1. Wybierz plik ZAP z jednego z Matter przykładów.
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 settings Ustawieniach możesz skonfigurować interfejs użytkownika ZAP, w tym wybrać jasny lub ciemny motyw oraz włączyć lub wyłączyć narzędzia dla programistów.

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

Kliknij extension 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 Matter węzłem głównym (Punkt końcowy – 0) i Matter ściemnianym światłem (Punkt końcowy – 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 opisów, klastry poświadczeń operacyjnych i klastry OTA.

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

1. W repozytorium Matter connectedhomeip uruchom ZAP.

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

2. Kliknij Punkt końcowy – 1, a potem edit Edytuj.

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

   

Więcej informacji znajdziesz w artykule Urządzenia i punkty końcowe w Matter 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ć search klastry według nazwy, np. on.

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

Więcej informacji znajdziesz w artykule Klastry w przewodniku Matter.

Atrybuty i polecenia

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

1. Znajdź klaster On/Off.

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

   

W tym miejscu 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 On/off dla światła będzie zawierać polecenia On, Off, i Toggle. Niektóre klastry, np. klaster Temperature Measurement, mogą nie mieć powiązanych poleceń.

Więcej informacji znajdziesz w artykule Atrybuty i polecenia w przewodniku Matter.

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ą specyficzne dla aplikacji, a inne ogólne pliki ZAP są pogrupowane 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, które można zintegrować z 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 w przypadku lighting-app.
3. Opcjonalnie. Otwórz pliki w preferowanym IDE.

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

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

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

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

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 zrozumiesz, jak można używać plików ZAP w Matter kodzie źródłowym, możesz zintegrować ZAP na kilka sposobów:

• Użyj dotychczasowych plików zzz_generated, aby utworzyć nowe przykłady unikalne dla Twoich typów urządzeń.
• Utwó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 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 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 następnych czynności podczas pracy z ZAP:

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

Zasoby

Dodatkowe zasoby ZAP znajdziesz w repozytorium ZAP (zap) w GitHubie.