Przewodnik dla deweloperów i API

1. Rozpoczęcie użytkowania

1.1 Przygotowanie

Krok 1. Upewnij się, że brama jest włączona i działa prawidłowo.

Krok 2. Upewnij się, że brama i komputer są podłączone do tej samej sieci LAN. Następnie wpisz URL CUBE w swojej przeglądarce.

Uwaga: Jeśli masz kilka bram, możesz uzyskać odpowiadający adres IP, aby uzyskać dostęp do określonej bramy na dwa poniższe sposoby.

1. Zaloguj się do swojego routera bezprzewodowego i sprawdź adres IP bramy w DHCP.

2. CUBE obsługuje lokalne wykrywanie przez mDNS.

1.2 Rozpoczęcie

• Wywołaj interfejs [Access Token], i otrzymasz odpowiedź o błędzie, z komunikatem zachęcającym do kliknięcia <Gotowe>. Zwróć uwagę, że po naciśnięciu dostęp do interfejsu jest ważny nie dłużej niż 5 minut.

// Żądanie
curl --location --request GET 'http://<ip address>/open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json'

// Odpowiedź
{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

• Kliknij <Gotowe> i wywołaj ponownie interfejs [Access Token]. Odpowiedź jest pomyślna i token zostaje uzyskany.

// Żądanie
curl --location --request GET 'http://<ip address>/open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json'

// Odpowiedź
{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

• Zweryfikuj token. Wywołaj interfejs [Get Device List]. Odpowiedź jest pomyślna i lista urządzeń zostaje pobrana.

// Żądanie
curl --location --request GET 'http://<ip address>/open-api/V2/rest/devices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d'

// Odpowiedź
{
  "error": 0,
  "data": {
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "nazwa urządzenia",
        "manufacturer": "nazwa producenta",
        "model": "nazwa modelu",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  }
  "message": "success"
}

• Metoda uzyskania tokenu dostępu do CUBE: Po wywołaniu interfejsu [Access Token], na stronie konsoli WWW CUBE pojawia się globalne wyskakujące okno z prośbą o potwierdzenie uzyskania poświadczeń dostępu do interfejsu.

• Uwaga: Jeśli otworzysz więcej niż jedną stronę konsoli WWW CUBE, okno potwierdzenia pojawi się jednocześnie na wielu stronach konsoli, a wyskakujące okno innych stron zostanie zamknięte po kliknięciu potwierdzenia na jednej ze stron konsoli.

2. Główne pojęcia

2.1 Adres interfejsu deweloperskiego

Interfejs Web API bramy ma dwa sposoby dostępu (na podstawie IP lub nazwy domeny), zwykle ścieżka główna to /open-api/V2/rest/< specific function module >

// Dostęp przez IP http:///open-api/V2/rest/bridge

// Dostęp przez nazwę domeny http:///open-api/V2/rest/bridge

2.2 Kategoria wyświetlania urządzenia i możliwości

• **Kategoria wyświetlania urządzenia (DisplayCategory). **Kategoria wyświetlania urządzenia służy do identyfikacji określonych kategorii (urządzeń), takich jak przełącznik, wtyczka, światło itp. Informacja ta określi efekt wyświetlania UI urządzenia w bramie.

• **Możliwość urządzenia. **Możliwość urządzenia służy do opisu konkretnych podfunkcji urządzenia. Na przykład sterowanie zasilaniem, regulacja jasności, regulacja temperatury barwowej itp. Pojedyncze urządzenie może obsługiwać 1 lub więcej możliwości.

  • capability: Opisuje nazwę możliwości, która musi być globalnie unikalna i typu string. Kilka angielskich słów powinno być oddzielonych myślnikami ("-"). Na przykład: "thermostat-target-setpoint".

  • name: Opisuje kategorię w ramach możliwości, również typu string. Kilka angielskich słów powinno być oddzielonych myślnikami ("-"). Na przykład: "auto-mode", "manual-mode".

  • permission: Opisuje uprawnienia związane z możliwością. Typ to string, sformatowany jako kod binarny 8421. Przykłady obejmują:

    • Urządzenie sterowalne: "1000"

    • Urządzenie konfigurowalne: "0010"

    • Urządzenie sterowalne i konfigurowalne: "1010"

    • Urządzenie sterowalne i raportujące: "1100"

Znaczenie każdego bitu, od prawej do lewej, jest następujące: i. Bit 0: Pozwala na zapytanie urządzenia ii. Bit 1: Pozwala na konfigurację urządzenia iii. Bit 2: Pozwala urządzeniu na raportowanie danych iv. Bit 3: Pozwala na sterowanie urządzeniem

const permission = {
  "update": "1000",
  "updated": "0100",
  "configure": "0010",
  "query": "0001",  
  "update-updated": "1100",
  "update-query": "1001",
  "update-updated-configure": "1110",
  "updated-configure":"0110",
  "update-updated-query":"1101"
}

settings: Opisuje elementy konfiguracji dla możliwości, które są typu obiekt i zawierają opis każdego elementu konfiguracji. i. key: Opisuje nazwę elementu konfiguracji, która jest typu string. Kilka angielskich słów powinno być zapisanych w camelCase. Na przykład: "temperatureUnit". ii. value: Opisuje zawartość elementu konfiguracji. Szczegółowe specyfikacje opisano w poniższej tabeli.

Atrybut	Typ	Opcjonalne	Opis
permission	string	N	Opisuje uprawnienia dla elementu konfiguracji.
Wartości opcjonalne:

• Pozwól na modyfikację tego elementu konfiguracji: "10"

• Pozwól na przeglądanie tego elementu konfiguracji: "01"

• Pozwól zarówno na modyfikację, jak i przeglądanie tego elementu konfiguracji: "11"

Wyjaśnienie bitów:

1. Bit 0: Pozwala na przeglądanie tego elementu konfiguracji

2. Bit 1: Pozwala na modyfikację tego elementu konfiguracji | | typ | string | N | Opisuje typ danych wartości elementu konfiguracji. Wartości opcjonalne:

• "enum"

• "numeric"

• "object"

• "boolean"

• "string"

Wytyczne specyficzne dla typu:

1. Gdy **type = enum**:

   • Pole value (opisujące wartość elementu konfiguracji) jest wymagane jeśli permission pozwala na modyfikację ("10" lub "11").

   • Pole default (opisujące wartość domyślną elementu konfiguracji) oraz values (opisujące możliwe wartości do wyboru dla elementu konfiguracji) pola są opcjonalne.

2. Gdy **type = numeric**:

   • Pole value pole jest wymagane jeśli permission pozwala na modyfikację ("10" lub "11").

   • Poniższe pola są opcjonalne:

     • min (opisujące minimalną wartość elementu konfiguracji)

     • max (opisujące maksymalną wartość elementu konfiguracji)

     • step (opisujące krok wartości dla elementu konfiguracji)

     • precision (opisujące precyzję)

     • unit (opisujące jednostkę elementu konfiguracji)

     • default (opisujące wartość domyślną)

3. Gdy **type = object**:

   • Pole value pole jest wymagane jeśli permission pozwala na modyfikację ("10" lub "11").

   • Pole default pole jest opcjonalne.

4. Gdy **type = boolean**:

   • Pole value pole jest wymagane jeśli permission pozwala na modyfikację ("10" lub "11").

   • Pole default pole jest opcjonalne.

5. Gdy **type = string**:

   • Pole value pole jest wymagane jeśli permission pozwala na modyfikację ("10" lub "11").

   • Pole default pole jest opcjonalne. |

// type = enum
{
  "settings":{
    "temperatureUnit": {
      "type": "enum",
      "permission": "11", 
      "values": ["c", "f"], 
      "default": "c",
      "value": "f"
    }
  }
}
// type = numeric
{
  "settings": {
    "setpointRange": {
      "type": "numeric", 
      "permission": "01", 
      "min": 4, 
      "max": 35,
      "default": 20,
      "step": 0.5,
      "precision": 0.01
      "unit": "c"
    }
  }
}

// type = object
{
  "settings":{
    "weeklySchedule":{
      "type": "object",
      "permission": "11", 
      "value": {
        "maxEntryPerDay": 2, 
        "Monday": [
          {
            "startTimeInMinutes": 440, 
            "upperSetpoint": 36.5 
          },
          {
            "startTimeInMinutes": 900,
            "upperSetpoint": 26.5 
          }
        ]，
        "Tuesday": [...],
        "Wednesday": [...],
        "Thursday": [...],
        "Friday": [...],
        "Saturday": [...],
        "Sunday": [...],
      }
    }
  }
}

3. Web API

Typ danych

Typ	Opis
string	Typ danych string. Kodowanie UTF8.
number	Typ danych liczbowy. podwójna precyzja 64-bitowy format binarny IEEE 754
int	Typ danych całkowity.
object	Typ danych obiekt. Obiekt zgodny z JSON
string[]	Tablica stringów
int[]	Tablica wartości całkowitych
object[]	Tablica obiektów
bool	Boolean
date	Ciąg czasu. Ciąg w formacie ISO (ISO 8601 Extended Format): YYYY-MM-DDTHH:mm:ss.sssZ. Strefa czasowa jest zawsze UTC (Coordinated Universal Time), oznaczona sufiksem "Z".

Ogólne wyniki odpowiedzi

Atrybut	Typ	Opcjonalne	Opis
error	int	N	Kod błędu:
0: Sukces
400: Błąd parametru
401: Uwierzytelnianie nie powiodło się
500: Wyjątek serwera
data	object	N	Treść danych odpowiedzi
message	string	N	Opis odpowiedzi:
Gdy error jest równy 0, treść to success
Gdy error jest różny od 0, jest to niepusty string, a treść to opis błędu.

Przykład odpowiedzi:

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

{
  "error": 400,
  "data": {},
  "message": "invalid parameters"
}

Lista zasobów

Typ	Opis
Obsługiwane dźwięki	- alert1 (Dźwięk alarmu 1)

• alert2 (Dźwięk alarmu 2)

• alert3 (Dźwięk alarmu 3)

• alert4 (Dźwięk alarmu 4)

• alert5 (Dźwięk alarmu 5)

• doorbell1 (Dźwięk dzwonka 1)

• doorbell2 (Dźwięk dzwonka 2)

• doorbell3 (Dźwięk dzwonka 3)

• doorbell4 (Dźwięk dzwonka 4)

• doorbell5 (Dźwięk dzwonka 5)

• alarm1 (Dźwięk alarmu 1)

• alarm2 (Dźwięk alarmu 2)

• alarm3 (Dźwięk alarmu 3)

• alarm4 (Dźwięk alarmu 4)

• alarm5 (Dźwięk alarmu 5) | | Obsługiwane zdarzenia głębokie | - bootComplete (Uruchomienie systemu zakończone)

• networkConnected (Sieć połączona)

• networkDisconnected (Sieć rozłączona)

• systemShutdown (Zamknięcie systemu) -deviceDiscovered (Wykryto urządzenie)

• system Armed (System uzbrojony włączony)

• system Disarmed (System uzbrojony wyłączony)

• factoryReset (Reset urządzenia) |

3.1 Funkcje bramy

a. Token dostępu

Pozwól użytkownikom uzyskać token dostępu.

• Uwaga: Token zostanie wyczyszczony po zresetowaniu urządzenia.

• Uwaga: Po uzyskaniu tokenu trzeba ponownie nacisnąć przycisk, aby pomyślnie uzyskać nowy token.

:::porady

• URL：/open-api/V2/rest/bridge/access_token

• Metoda：GET

• Nagłówek：

  • Content-Type: application/json ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
app_name	string	Y	Opis nazwy aplikacji.

Pomyślna odpowiedź danych:

Atrybut	Typ	Opcjonalne	Opis
token	string	N	Token dostępu do interfejsu. Jest ważny przez długi czas, proszę go zapisać
app_name	string	Y	Opis nazwy aplikacji.

:::porady Warunek: Użytkownik wyzwala < command key > i uzyskuje dostęp do tego interfejsu w czasie ważności. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

Niepowodzenie odpowiedzi danych：pusty Obiekt :::porady Warunki：Użytkownik nie wyzwolił < command key >, lub czas ważności wygasł. **Kod stanu: ** 200 OK ::: Przykład odpowiedzi:

{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

b. Pobierz stan bramy

Pozwól uprawnionym użytkownikom uzyskać status bramy przez ten interfejs :::porady

• URL：/open-api/V2/rest/bridge/runtime

• Metoda：GET

• Nagłówek：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametry żądania: brak Pomyślna odpowiedź danych:

Atrybut	Typ	Opcjonalne	Opis
ram_used	int	N	Procent wykorzystania pamięci RAM.[0-100]
cpu_used	int	N	Procent wykorzystania CPU. [0-100]
power_up_time	date	N	Ostatni czas włączenia zasilania
cpu_temp	int	N	Temperatura CPU:
Jednostka: Celsjusz
cpu_temp_unit	string	N	Jednostka temperatury CPU:
Opcjonalne
values:'c', 'f'
sd_card_used	int	Y	Wykorzystanie karty SD (procent):
Zakres:[0-100] z precyzją do jednego miejsca po przecinku
*Uwaga: Jeśli karta SD nie jest włożona lub nie jest sformatowana, wartość jest pusta.

:::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {
    "ram_used": 40,
    "cpu_used": 30,
    "power_up_time": "2022-10-12T02:58:09.989Z",
    "cpu_temp": 51,
    "cpu_temp_unit": "c",
    "sd_card_used" : "12"
  },
  "message": "success"
}

c. Konfiguracja bramy

Pozwól uprawnionym użytkownikom ustawić bramę przez ten interfejs :::porady

• URL：/open-api/V2/rest/bridge/config

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
volume	int	Y	Głośność systemu. [0-100]

Pomyślna odpowiedź danych: pusty Obiekt {} :::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

d. Pobierz informacje o bramie

Pozwól uprawnionym użytkownikom uzyskać informacje o bramie przez ten interfejs :::porady

• URL：/open-api/V2/rest/bridge

• Metoda：GET

• Nagłówek：

  • Content-Type: application/json ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
ip	string	N	adres IP
mac	string	N	adres MAC
domain	string	Y	Domena usługi bramy
fw_version	string	N	Wersja oprogramowania układowego
name	string	N	Nazwa urządzenia

Pomyślna odpowiedź danych: pusty Obiekt {} :::porady Warunki: Brak **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {
    "ip": "192.168.31.25",
    "mac": "00:0A:02:0B:03:0C",
    "domain": "ihost.local",
    "fw_version": "1.9.0",
    "name": "iHost"
  },
  "message": "success"
}

e. Wyciszenie bramy

Pozwala uprawnionym użytkownikom wyciszyć bramę przez ten interfejs. :::porady

• URL：/open-api/v2/rest/bridge/mute

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania: brak Pomyślna odpowiedź danych: pusty Obiekt {} :::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

f. Wyłączenie wyciszenia bramy

Pozwala uprawnionym użytkownikom wyłączyć wyciszenie bramy przez ten interfejs. :::porady

• URL：/open-api/v2/rest/bridge/unmute

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania: brak Pomyślna odpowiedź danych: pusty Obiekt {} :::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

g. Anulowanie alarmu bramy

Pozwala uprawnionym użytkownikom wyłączyć stan dźwięku alarmu na bramie przez ten interfejs. :::porady

• URL：/open-api/v2/rest/bridge/cancel_alarm

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania: brak Pomyślna odpowiedź danych: pusty Obiekt {} :::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.2 Funkcje sprzętowe

a. Restart bramy

Pozwól uprawnionemu użytkownikowi zrestartować bramę przez ten interfejs :::porady

• URL：/open-api/V2/rest/hardware/reboot

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametry żądania: brak Pomyślna odpowiedź danych: pusty Obiekt {} :::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK :::

{
  "error": 0,
  "data": {},
  "message": "success"
}

b. Sterowanie głośnikiem

Pozwól uprawnionym użytkownikom sterować głośnikiem przez ten interfejs :::porady

• URL：/open-api/V2/rest/hardware/speaker

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
type	string	N	Opcjonalne parametry: 1.play_sound (odtwórz dźwięk) 2.play_beep (odtwórz sygnał dźwiękowy)
sound	SoundObject	Y (N jeśli type to play_sound.)	Dźwięk.
beep	BeepObject	Y (N jeśli type to play_beep.)	Sygnał dźwiękowy

SoundObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa dźwięku. Obsługiwane wartości można sprawdzić w [Resource List - Supported sound]
volume	int	N	Głośność dźwięku. [0-100]
countdown	int	N	Czas trwania odtwarzania dźwięku przez głośnik; odtwarzanie zatrzyma się automatycznie po upływie czasu. Jednostka: sekunda. [0,1799]

BeepObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa zdarzenia głębokiego. Obsługiwane wartości można sprawdzić w [Resource List - Supported deep]
volume	int	N	Głośność zdarzenia głębokiego. [0-100]

Pomyślna odpowiedź danych: pusty Obiekt {} :::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: ** 200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.3 Funkcje zarządzania urządzeniami

a. Obsługiwany typ urządzenia

Typ urządzenia	Wartość	Wersja iHost
Wtyczka	plug	≥ 2.1.0
Przełącznik	switch	≥ 2.1.0
Światło	light	≥ 2.1.0
Zasłona	curtain	≥ 2.1.0
Czujnik drzwi/okna	contactSensor	≥ 2.1.0
Czujnik ruchu	motionSensor	≥ 2.1.0
Czujnik temperatury	temperatureSensor	≥ 2.1.0
Czujnik wilgotności	humiditySensor	≥ 2.1.0
Czujnik temperatury i wilgotności	temperatureAndHumiditySensor	≥ 2.1.0
Czujnik wycieku wody	waterLeakDetector	≥ 2.1.0
Czujnik dymu	smokeDetector	≥ 2.1.0
Przycisk bezprzewodowy	button	≥ 2.1.0
Kamera	camera	≥ 2.1.0
Ogólny czujnik	sensor	≥ 2.1.0
Ogólny czujnik	sensor	≥ 2.1.0
Wentylator z oświetleniem	fanLight	≥ 2.1.0
Klimatyzator	airConditioner	≥ 2.1.0
Wentylator	fan	≥ 2.1.0
Termostat	thermostat	≥ 2.1.0

b. Obsługiwane możliwości urządzenia

Włącznik zasilania (power):

Przykład deklaracji możliwości:

[
  {
    "capability": "power", // Nazwa możliwości
    "permission": "1100",  // ihost nie obsługuje konfigurowania miękkiego startu/stopu, więc brak pola configure
  }
]

Atrybut stanu:

{
  "powerState": "on", // Pole powerState wskazuje stan włącz/wyłącz zasilania. Wymagane. **Typ:** string. "on" oznacza włączone, "off" oznacza wyłączone, "toggle" oznacza przełączenie.
}

Protokół (zapytanie o status i instrukcje sterujące):

Włącz:

{
  "power": {
    "powerState": "on"
  }
}

Wyłącz:

{
  "power": {
    "powerState": "off"
  }
}

Przełącznik kanału (toggle):

Przykład deklaracji możliwości:

Przykład pojedynczego komponentu:

[
  {
    "capability": "toggle", // Nazwa możliwości
    "permission": "1100",  // Uprawnienie
    "name": "1", // Nazwa komponentu, **Typ:** String. Opcjonalne wartości: "1" (Kanał 1), "2" (Kanał 2), "3" (Kanał 3), "4" (Kanał 4) lub inne wartości zawierające wielkie i małe litery oraz cyfry
  }
]

Przykład wielu komponentów:

[
  {
    "capability": "toggle",
    "permission": "1100",
    "name": "1"
  },
  {
    "capability": "toggle",
    "permission": "1100",
    "name": "2"
  }
]

Atrybut stanu:

{
  "toggleState": "on", // Pole toggleState wskazuje stan przełącznika {device_id} o nazwie {name}. Wymagane. **Typ:** String. "on" oznacza włączony, "off" oznacza wyłączony, "toggle" oznacza przełączenie.
}

Protokół (zapytanie o status i instrukcje sterujące):

Format przełączania:

{
  [capability]: {
    [toggle-name]: {
      [toggleState]: [value]
    }
  }
}
Komponent 1 Włączony, Komponent 2 Wyłączony:
{
  "toggle": {
    "1": {
      "toggleState": "on"
    },
    "2": {
      "toggleState": "off"
    }
  }
}

Inching kanału (toggle-inching):

Przykład deklaracji możliwości:

[
  {
    "capability": "toggle-inching", // Nazwa możliwości
    "permission": "0010",  // Uprawnienie
    "settings": {
      "toggleInchingSetting": {
        "permission": "11",
        "type": "object",
        "value": {
          "supported": {
            "1": { // Nazwa komponentu
              "enable": true, // Czy funkcja inching jest włączona. **Typ:** Boolean. Wymagane.
              "inchingSwitch": "off", // Ustawienie przełącznika inching. **Typ:** String. Wymagane. "off" (wyłączone), "on" (włączone)
              "delay": 1000, // Czas opóźnienia inching w milisekundach. **Typ:** Integer. Wymagane.
              "min_delay": 500, // Minimalny czas opóźnienia
              "max_delay": 100000 // Maksymalny czas opóźnienia
            },
            "2": { // Nazwa komponentu
              "enable": true, // Czy funkcja inching jest włączona. **Typ:** Boolean. Wymagane.
              "inchingSwitch": "off", // Ustawienie przełącznika inching. **Typ:** String. Wymagane. "off" (wyłączone), "on" (włączone)
              "delay": 1000, // Czas opóźnienia inching w milisekundach. **Typ:** Integer. Wymagane.
              "min_delay": 500, // Minimalny czas opóźnienia
              "max_delay": 100000 // Maksymalny czas opóźnienia
            },
            "3": { // Nazwa komponentu
              "enable": true, // Czy funkcja inching jest włączona. **Typ:** Boolean. Wymagane.
              "inchingSwitch": "off", // Ustawienie przełącznika inching. **Typ:** String. Wymagane. "off" (wyłączone), "on" (włączone)
              "delay": 1000, // Czas opóźnienia inching w milisekundach. **Typ:** Integer. Wymagane.
              "min_delay": 500, // Minimalny czas opóźnienia
              "max_delay": 100000 // Maksymalny czas opóźnienia
            },
            "4": { // Nazwa komponentu
              "enable": true, // Czy funkcja inching jest włączona. **Typ:** Boolean. Wymagane.
              "inchingSwitch": "off", // Ustawienie przełącznika inching. **Typ:** String. Wymagane. "off" (wyłączone), "on" (włączone)
              "delay": 1000, // Czas opóźnienia inching w milisekundach. **Typ:** Integer. Wymagane.
              "min_delay": 500, // Minimalny czas opóźnienia
              "max_delay": 100000 // Maksymalny czas opóźnienia
            }
          }
        }
      }
    }
  }
]

Atrybut stanu

Brak

Protokół (zapytanie o status i instrukcje sterujące)

Brak

Regulacja jasności (brightness):

Przykład deklaracji możliwości:

{
  "capability": "brightness", // Nazwa możliwości
  "permission": "1100"  // Uprawnienie
}

Atrybut stanu:

{
  "brightness": 100, // Pole brightness wskazuje procent jasności. Wybierz pomiędzy brightness lub brightnessDelta. **Typ:** Number. Zakres: 0-100.
}

Protokół (zapytanie o status i instrukcje sterujące):

Ustaw jasność na 80%. (0 to najciemniej, 100 to najjaśniej.)

json
复制代码
{
  "brightness": {
    "brightness": 80
  }
}

Regulacja temperatury barwowej (color-temperature):

Przykład deklaracji możliwości:

{
  "capability": "color-temperature", // Nazwa możliwości
  "permission": "1100"  // Uprawnienie
}

Atrybut stanu:

{
  "colorTemperature": 100, // Pole colorTemperature wskazuje procent temperatury barwowej. Wybierz pomiędzy colorTemperature lub colorTemperatureDelta. **Typ:** Number. Zakres: 0-100. 0 oznacza ciepłe światło, 50 oznacza światło neutralne, 100 oznacza zimne światło.
}

Protokół (zapytanie o status i instrukcje sterujące):

Dostosuj temperaturę barwową do 50%:

json
 
{
  "color-temperature": {
    "colorTemperature": 50
  }
}

Regulacja koloru (color-rgb):

Przykład deklaracji możliwości:

{
  "capability": "color-rgb", // Nazwa możliwości
  "permission": "1100"  // Uprawnienie
}

Atrybut stanu:

{
  "red": 255, // Pole red reprezentuje kolor czerwony w przestrzeni kolorów RGB. Wymagane. **Typ:** Number. Zakres: 0-255.
  "green": 0, // Pole green reprezentuje kolor zielony w przestrzeni kolorów RGB. Wymagane. **Typ:** Number. Zakres: 0-255.
  "blue": 255 // Pole blue reprezentuje kolor niebieski w przestrzeni kolorów RGB. Wymagane. **Typ:** Number. Zakres: 0-255.
}

Protokół (zapytanie o status i instrukcje sterujące):

Ustaw kolor na fioletowy:

{
  "color-rgb": {
    "red": 255,
    "green": 0,
    "blue": 255
  }
}

Regulacja procentowa (percentage):

Przykład deklaracji możliwości:

{
  "capability": "percentage",
  "permission": "1100",
  "settings": { // Opcjonalne
    "percentageRange": {
      "permission": "01",
      "type": "numeric",
      "min": 0,
      "max": 100,
      "step": 5
    }
  }
}

Atrybut stanu:

{
  "percentage": 100, // Pole percentage wskazuje wartość procentową. Wybierz pomiędzy percentage lub percentageDelta. **Typ:** Number. Zakres: 0-100.
}

Protokół (zapytanie o status i instrukcje sterujące):

Dostosuj do 40%:

{
  "percentage": {
    "percentage": 40
  }
}

Sterowanie silnikiem (motor-control):

Przykład deklaracji możliwości:

{
  "capability": "motor-control",
  "permission": "1100"
}

Atrybut stanu:

json
 
{
  "motorControl": "stop", // Pole motorControl wskazuje stan silnika. Wymagane. **Typ:** String. Możliwe wartości: "open" (otwórz), "close" (zamknij), "stop" (zatrzymaj), "lock" (zablokuj).
}

Protokół (zapytanie o status i instrukcje sterujące):

Otwórz silnik:

{
  "motor-control": {
    "motorControl": "open"
  }
}

Odwrócenie silnika (motor-reverse):

Przykład deklaracji możliwości:

{
  "capability": "motor-reverse",
  "permission": "1100"
}

Atrybut stanu:

{
  "motorReverse": true, // Pole motorReverse wskazuje ustawienie kierunku silnika. Wymagane. **Typ:** Boolean. true oznacza do przodu, false oznacza do tyłu.
}

Protokół (zapytanie o status i instrukcje sterujące):

Ustaw silnik do przodu:

{
  "motor-reverse": {
    "motorReverse": true
  }
}

Kalibracja silnika (motor-clb)

Przykład deklaracji możliwości:

{
  "capability": "motor-clb",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "motorClb": "calibration" // Pole motorClb wskazuje status kalibracji silnika. Wymagane. **Typ:** String. "normal" oznacza tryb normalny (skalibrowany), "calibration" oznacza trwającą kalibrację.
}

Protokół (raportowanie stanu):

Zgłoś, że stan silnika jest w trakcie kalibracji:

{
  "motor-clb": {
    "motorClb": "calibration"
  }
}

Stan włączenia zasilania przy starcie (startup)

Przykład deklaracji możliwości:

{
  "capability": "startup",
  "permission": "1100"
}

Atrybuty (Stan):

{
  "startup": "on" // Stan zasilania przy uruchomieniu. **Typ:** String. Wymagane. Opcjonalne wartości: "on" (włącz przy starcie), "stay" (utrzymaj zasilanie), "off" (wyłącz przy starcie), "toggle" (odwróć stan zasilania).
}

Protokół (zapytanie o status i instrukcje sterujące):

Ustaw stan zasilania na zawsze włączony:

{
  "startup": {
    "startup": "on"
  }
}

---

Aktywacja po przebudzeniu (identify)

Przykład deklaracji możliwości:

{
  "capability": "identify",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "identify": true // Wskazuje, czy urządzenie aktywnie raportuje wyniki rozpoznawania lub jest aktywowane.
}

Protokół (raportowanie stanu i instrukcje sterujące):

Ustaw czas aktywacji po przebudzeniu:

{
  "identify": {
    "countdown": 180 // Pole countdown wskazuje czas odliczania. Wymagane. **Typ:** Number. Jednostka: sekundy.
  }
}

Zgłoś status aktywacji:

{
  "identify": {
    "identify": true // Wskazuje, czy urządzenie aktywnie raportuje wyniki rozpoznawania lub jest aktywowane.
  }
}

Przełącznik statystyk zużycia energii w czasie rzeczywistym (power-consumption)

Przykład deklaracji możliwości:

{
  "capability": "power-consumption",
  "permission": "1101",
  "settings": {
    "resolution": {
      "permission": "01",
      "type": "numeric",
      "value": 3600
    },
    "timeZoneOffset": {
      "permission": "01",
      "type": "numeric",
      "min": -12,
      "max": 14,
      "value": 0
    }
  }
}

Atrybuty (Stan):

Rozpocznij/Zatrzymaj statystyki w czasie rzeczywistym:

{
  "rlSummarize": true, // Rozpocznij/zatrzymaj statystyki czasu rzeczywistego. **Typ:** Boolean. Wymagane.
  "timeRange": { // Zakres czasu do podsumowania. Wymagane.
    "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia statystyk zużycia energii. **Typ:** String. Wymagane.
    "end": "2020-07-05T09:00:00Z" // Czas zakończenia statystyk zużycia energii. **Typ:** String. Wymagane.
  }
}

Zapytaj o zużycie energii według zakresu czasu:

{
  "type": "summarize", // Rodzaj statystyk. **Typ:** String. Wymagane. Opcjonalne wartości: "rlSummarize" (podsumowanie czasu rzeczywistego), "summarize" (podsumowanie bieżące).
  "timeRange": { // Zakres czasu do podsumowania. Wymagane, jeśli type jest "summarize".
    "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia statystyk zużycia energii. **Typ:** String. Wymagane.
    "end": "2020-07-05T09:00:00Z" // Czas zakończenia statystyk zużycia energii. **Typ:** String. Opcjonalne. Jeśli pominięte, oznacza bieżący czas.
  }
}

Odpowiedz wynikiem statystyk w obrębie zakresu czasu:

json
 
{
  "type": "summarize", // Rodzaj statystyk. **Typ:** String. Wymagane. Opcjonalne wartości: "rlSummarize" (podsumowanie czasu rzeczywistego), "summarize" (podsumowanie bieżące).
  "rlSummarize": 50.0, // Całkowite zużycie energii. **Typ:** Number. Jednostka: 0.01 kWh. Opcjonalne.
  "electricityIntervals": [ // Wielokrotne rekordy statystyk podzielone zgodnie z configuration.resolution. Opcjonalne. Nieobecne gdy type jest "rlSummarize".
    {
      "usage": 26.5, // Zużycie energii. **Typ:** Number. Jednostka: 0.01 kWh. Wymagane.
      "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia. **Typ:** Date. Wymagane.
      "end": "2020-07-05T09:00:00Z" // Czas zakończenia. **Typ:** Date. Wymagane. Jeśli odstęp między end i start jest mniejszy niż resolution, wszystkie zgłoszone rekordy są uznawane za nieważne.
    },
    {
      "usage": 26.5, // Zużycie energii. **Typ:** Number. Jednostka: 0.01 kWh. Wymagane.
      "start": "2020-07-05T09:00:00Z", // Czas rozpoczęcia. **Typ:** Date. Wymagane.
      "end": "2020-07-05T10:00:00Z" // Czas zakończenia. **Typ:** Date. Wymagane. Jeśli odstęp między end i start jest mniejszy niż resolution, wszystkie zgłoszone rekordy są uznawane za nieważne.
    }
  ]
}

Protokół (raportowanie stanu i instrukcje sterujące):

Rozpocznij statystyki czasu rzeczywistego:

json
 
{
  "power-consumption": {
    "powerConsumption": {
      "rlSummarize": true,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": ""
      }
    }
  }
}

Zatrzymaj statystyki czasu rzeczywistego:

json
 
{
  "power-consumption": {
    "powerConsumption": {
      "rlSummarize": false,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}

Pobierz historyczne zużycie energii:

json
 
{
  "power-consumption": {
    "type": "summarize",
    "timeRange": {
      "start": "2020-07-05T08:00:00Z",
      "end": "2020-07-05T09:00:00Z"
    }
  }
}

Pobierz zużycie energii w czasie rzeczywistym:

json
 
{
  "power-consumption": {
    "powerConsumption": {
      "type": "rlSummarize"
    }
  }
}

Wykrywanie trybu temperatury i wilgotności (thermostat-mode-detect)

Przykład deklaracji możliwości:

{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "temperature", // Typ wykrywania kontroli temperatury. **Typ:** String. Wymagane. Opcjonalne wartości: "humidity" (wykrywanie wilgotności), "temperature" (wykrywanie temperatury).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Obsługiwane ustawienia wykrywania. Wymagane.
          {
            "name": "lowerSetpoint", // Wartość wykrywania powinna być powyżej tej nastawy. Wymagane co najmniej jedno z lowerSetpoint lub upperSetpoint.
            "value": { // Zakres wykrywania. Opcjonalne. Określ, jeśli istnieją warunki wstępne.
              "value": 68.0, // Wartość temperatury. **Typ:** Number. Wymagane.
              "scale": "f" // Jednostka temperatury. Wymagane gdy name=temperature. Opcjonalne wartości: "c" (Celsjusz), "f" (Fahrenheit).
            }
          },
          {
            "name": "upperSetpoint", // Wartość wykrywania powinna być poniżej tej nastawy. Wymagane co najmniej jedno z lowerSetpoint lub upperSetpoint.
            "value": { // Zakres wykrywania. Opcjonalne. Określ, jeśli istnieją warunki wstępne.
              "value": 68.0, // Wartość temperatury. **Typ:** Number. Wymagane.
              "scale": "f" // Jednostka temperatury. Wymagane gdy name=temperature. Opcjonalne wartości: "c" (Celsjusz), "f" (Fahrenheit).
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "humidity", // Typ wykrywania kontroli temperatury. **Typ:** String. Wymagane. Opcjonalne wartości: "humidity" (wykrywanie wilgotności), "temperature" (wykrywanie temperatury).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Obsługiwane ustawienia wykrywania. Wymagane.
          {
            "name": "lowerSetpoint", // Wartość wykrywania powinna być powyżej tej nastawy. Wymagane co najmniej jedno z lowerSetpoint lub upperSetpoint.
            "value": { // Zakres wykrywania. Opcjonalne. Określ, jeśli istnieją warunki wstępne.
              "value": 68.0, // Wartość wilgotności. **Typ:** Number. Wymagane
            }
          },
          {
            "name": "upperSetpoint", // Wartość wykrywania powinna być poniżej tej nastawy. Wymagane co najmniej jedno z lowerSetpoint lub upperSetpoint.
            "value": { // Zakres wykrywania. Opcjonalne. Określ, jeśli istnieją warunki wstępne.
              "value": 68.0, // Wartość wilgotności. **Typ:** Number. Wymagane
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

Atrybuty (Stan):

{
  "mode": "COMFORT" // Identyfikator trybu. Opcjonalne. Obsługiwane wartości: "COMFORT" (Tryb komfortu), "COLD" (Tryb zimny), "HOT" (Tryb gorący), "DRY" (Tryb suszenia), "WET" (Tryb wilgotny).
}

Protokół (zapytanie o status i instrukcje sterujące):

Format:

{
    [capability] :{
        [mode name] :{
            "mode": [value]
        }
    }
}

Przykład:

{
  "thermostat-mode-detect": {
    "humidity": {
      "mode": "COMFORT"
    }
  }
}

Tryb termostatu (thermostat-mode)

Przykład deklaracji możliwości:

{
  "capability": "thermostat",
  "permission": "1100",
  "name": "thermostat-mode",
  "settings": {
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "MANUAL",
        "AUTO",
        "ECO"
      ]
    }
  }
}

Atrybuty (Stan):

{
  "thermostatMode": "MANUAL" // Tryb pracy termostatu. **Typ:** String. Opcjonalne wartości: "MANUAL", "AUTO", "ECO".
}

Protokół (zapytanie o status i instrukcje sterujące):

{
   "thermostat": {
    "thermostat-mode": {
      "thermostatMode": "MANUAL"
    }
  }
}

Status adaptacyjnego odzysku termostatu (thermostat/adaptive-recovery-status)

Przykład deklaracji możliwości:

{
  "capability": "thermostat",
  "permission": "0100",
  "name": "adaptive-recovery-status" // Status adaptacyjnego odzysku termostatu
}

Atrybuty (Stan):

{
  "adaptiveRecoveryStatus": "HEATING" // Status adaptacyjnego odzysku termostatu. **Typ:** String. Opcjonalne wartości: "HEATING", "INACTIVE".
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "thermostat": {
    "adaptive-recovery-status": {
      "adaptiveRecoveryStatus": "HEATING"
    }
  }
}

Ustawienie docelowej temperatury trybu termostatu (thermostat-target-setpoint)

Przykład deklaracji możliwości:

[[
  {
    "capability": "thermostat-target-setpoint",
    "name": "manual-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "eco-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "auto-mode",
    "permission": "0110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      },
      "weeklySchedule":{
        "type": "object",
        "permission": "11",
        "value": {
          "maxEntryPerDay": 2,
          "Monday": [
          {
            "startTimeInMinutes": 440, // Czas rozpoczęcia w minutach. **Typ:** int. Np. 7:20 = 440 minut.
            "upperSetpoint": 36.5, // Maksymalna docelowa temperatura. **Typ:** number.
            "lowerSetpoint": 20 // Minimalna docelowa temperatura. **Typ:** number.
          },
          {
            "startTimeInMinutes": 900, // Czas rozpoczęcia w minutach. Np. 15:00 = 900 minut.
            "upperSetpoint": 26.5, // Maksymalna docelowa temperatura. **Typ:** number.
            "lowerSetpoint": 21 // Minimalna docelowa temperatura. **Typ:** number.
          }
        ],
          "Tuesday": [...
          ],
          "Wednesday": [...
          ],
          "Thursday": [...
          ],
          "Friday": [...
          ],
          "Saturday": [...
          ],
          "Sunday": [...
          ],
        }
      }
    }
  }
]

Atrybuty (Stan):

{
  "targetSetpoint": 30 // Docelowa temperatura dla określonego trybu. **Typ:** number, w jednostce określonej przez temperatureUnit.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "thermostat-target-setpoint": {
    "manual-mode": {
        "targetSetpoint": 30 
    },
    "auto-mode": {
        "targetSetpoint": 30 
    }
  }
}

Wykrywanie czujnika (detect)

Przykład deklaracji możliwości:

{
  "capability": "detect",
  "permission": "0110",
  "settings": { // Opcjonalne
    "detectInterval": {
      "permission": "11",
      "type": "numeric",
      "value": 300
    },
    "detectSensitivity": {
      "permission": "11",
      "type": "numeric",
      "value": 1000
    }
  }
}

Atrybuty (Stan):

{
  "detected": true // Wynik wykrywania. **Typ:** Boolean. `true` oznacza wykryte, `false` oznacza brak wykrycia.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
    "detect": {
        "detected": true
    }
}

Wykrywanie temperatury (temperature)

Przykład deklaracji możliwości:

{
  "capability": "temperature",
  "permission": "0110",
  "settings": { // Opcjonalne
    "temperatureCalibration": { // Opcjonalna kalibracja temperatury
      "type": "numeric",
      "permission": "11",
      "min": -7, // Wartość minimalna
      "max": 7, // Wartość maksymalna
      "step": 0.2, // Krok regulacji temperatury, jednostka taka jak temperatureUnit
      "value": 5.2 // Bieżąca wartość kalibracji temperatury. **Typ:** number.
    },
    "temperatureUnit": { // Opcjonalna jednostka temperatury
      "type": "enum",
      "permission": "11",
      "value": "c",
      "values": [
        "c",
        "f"
      ]
    },
    "temperatureRange": { // Opcjonalny zakres wykrywania temperatury
      "type": "numeric",
      "permission": "01",
      "min": -40,
      "max": 80
    }
  }
}

Atrybuty (Stan):

json
复制代码
{
  "temperature": 26.5 // Bieżąca temperatura. **Typ:** Number, w stopniach Celsjusza.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "temperature": {
    "temperature": 20
  }
}

Wykrywanie wilgotności (humidity)

Przykład deklaracji możliwości:

{
  "capability": "humidity",
  "permission": "0100",
  "settings": { // Opcjonalny zakres wykrywania wilgotności.
    "humidityRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 100
    }
  }
}

Atrybuty (Stan):

{
  "humidity": 50 // Bieżąca wilgotność względna (procent). **Typ:** Number, zakres 0-100.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
    "humidity": {
        "humidity": 20
    }
}

Wykrywanie stanu baterii (battery)

Przykład deklaracji możliwości:

{
  "capability": "battery",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "battery": 95 // Pozostały procent baterii. **Typ:** Number, zakres -1 do 100. Uwaga: -1 oznacza nieznany poziom baterii.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "battery": {
    "battery": 40
  }
}

Wykrywanie pojedynczego przycisku (press)

Przykład deklaracji możliwości:

{
  "capability": "press",
  "permission": "1100",
  "settings": { // Opcjonalne
    "actions": { // Akcje przycisku, opcjonalne.
      "type": "enum",
      "permission": "01",
      "values": [ // Opcjonalne akcje przycisku. Domyślne wartości to "singlePress", "doublePress", "longPress". Skonfigurowane akcje zastępują domyślne.
      ]
    }
  }
}

Atrybuty (Stan):

{
  "press": "singlePress" // Typ naciśnięcia przycisku. **Typ:** String. Standardowe wartości: "singlePress" (pojedyncze lub krótkie naciśnięcie), "doublePress" (podwójne naciśnięcie), "longPress" (długie naciśnięcie).
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "press": {
    "press": "singlePress"
  }
}

Wykrywanie wielokrotnego przycisku (multi-press)

Przykład deklaracji możliwości:

{
  "capability": "multi-press",
  "permission": "0100",
  "name": "1", // Nazwa atrybutu multi-press. **Typ:** String. Dozwolone tylko znaki alfanumeryczne.
  "settings": { // Opcjonalne
    "actions": { // Akcje przycisku, opcjonalne.
      "type": "enum",
      "permission": "01",
      "values": [ // Opcjonalne akcje przycisku. Domyślne wartości to "singlePress", "doublePress", "longPress". Skonfigurowane akcje zastępują domyślne.
      ]
    }
  }
}

Atrybuty (Stan):

{
  "press": "singlePress" // Typ naciśnięcia przycisku. **Typ:** String. Standardowe wartości: "singlePress" (pojedyncze lub krótkie naciśnięcie), "doublePress" (podwójne naciśnięcie), "longPress" (długie naciśnięcie).
}

Protokół (zapytanie o status i instrukcje sterujące):

{
    [capability] :{
        [multi-press-name]：{
            press:[value]
        }
    }
}

przykład:
{
  "multi-press": {
    "1": {
      "press": "singlePress"
    },
    "2": {
      "press": "doublePress"
    }
  }
}

Wykrywanie siły sygnału (rssi)

Przykład deklaracji możliwości:

{
  "capability": "rssi",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "rssi": -65 // Siła sygnału bezprzewodowego (Received Signal Strength Indicator). **Typ:** Number, jednostka dBm, wartości ujemne.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "rssi": {
    "rssi": -65
  }
}

Wykrywanie sabotażu (tamper-alert)

Przykład deklaracji możliwości:

{
  "capability": "tamper-alert",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "tamper": "clear" // Status sabotażu. **Typ:** String. Możliwe wartości: "clear" (brak sabotażu), "detected" (sabotaż wykryty).
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "tamper-alert": {
    "tamper": "clear" // Status sabotażu. **Typ:** String. Możliwe wartości: "clear" (brak sabotażu), "detected" (sabotaż wykryty).
  }
}

Wykrywanie natężenia oświetlenia (illumination-level)

Przykład deklaracji możliwości:

{
  "capability": "illumination-level",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "level": "brighter" // Poziom jasności. **Typ:** String. Możliwe wartości: "brighter" (jaśniejszy), "darker" (ciemniejszy).
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "illumination-level": {
    "level": "brighter"
  }
}

Wykrywanie napięcia (voltage)

Przykład deklaracji możliwości:

{
  "capability": "voltage",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "voltage": 50 // Bieżąca wartość napięcia, w jednostkach 0.01V. **Typ:** Number, wartości nieujemne.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "voltage": {
    "voltage": 50
  }
}

Wykrywanie natężenia prądu (electric-current)

Przykład deklaracji możliwości:

{
  "capability": "electric-current",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "electric-current": 50 // Bieżąca wartość prądu, w jednostkach 0.01A. **Typ:** Number, wartości całkowite nieujemne.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "electric-current": {
    "electric-current": 50
  }
}

Wykrywanie mocy elektrycznej (electric-power)

Przykład deklaracji możliwości:

{
  "capability": "electric-power",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "electric-power": 50 // Bieżąca wartość mocy, w jednostkach 0.01W. **Typ:** Number, wartości całkowite nieujemne.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "electric-power": {
    "electric-power": 50
  }
}

Wykrywanie usterek (fault)

Przykład deklaracji możliwości:

{
  "capability": "fault",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "fault": "none" // Status usterki. **Typ:** String. Możliwe wartości: "none" (brak usterki), "detected" (usterka wykryta).
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "fault": {
    "fault": "none"
  }
}

Wyłącznik progu (threshold-breaker)

Przykład deklaracji możliwości:

{
  "capability": "threshold-breaker",
  "permission": "0010",
  "settings": {
    "supportedSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "supported": [
          {
            "name": "lowerPower", // Wyłącznik progu niskiej mocy
            "value": {
              "value": 50, // Wartość wykrywanej mocy, w jednostkach 0.01W. **Typ:** Integer. Zakres: >=0.
              "min_range": 10, // Minimalna wykrywana wartość mocy, w jednostkach 0.01W. **Typ:** Integer. Zakres: >=0.
              "max_range": 3500 // Maksymalna wykrywana wartość mocy, w jednostkach 0.01W. **Typ:** Integer. Zakres: >=0.
            }
          },
          {
            "name": "upperPower", // Wyłącznik progu wysokiej mocy
            "value": {
              "value": 50, // Wartość wykrywanej mocy, w jednostkach 0.01W. **Typ:** Integer. Zakres: >=0.
              "min_range": 10, // Minimalna wykrywana wartość mocy, w jednostkach 0.01W. **Typ:** Integer. Zakres: >=0.
              "max_range": 3500 // Maksymalna wykrywana wartość mocy, w jednostkach 0.01W. **Typ:** Integer. Zakres: >=0.
            }
          },
          {
            "name": "lowerElectricCurrent", // Wyłącznik progu niskiego prądu
            "value": {
              "value": 50, // Wartość wykrywanego prądu, w jednostkach 0.01A. **Typ:** Integer. Zakres: >=0.
              "min_range": 10, // Minimalna wykrywana wartość prądu, w jednostkach 0.01A. **Typ:** Integer. Zakres: >=0.
              "max_range": 1500 // Maksymalna wykrywana wartość prądu, w jednostkach 0.01A. **Typ:** Integer. Zakres: >=0.
            }
          },
          {
            "name": "upperElectricCurrent", // Wyłącznik progu wysokiego prądu
            "value": {
              "value": 50, // Wartość wykrywanego prądu, w jednostkach 0.01A. **Typ:** Integer. Zakres: >=0.
              "min_range": 10, // Minimalna wykrywana wartość prądu, w jednostkach 0.01A. **Typ:** Integer. Zakres: >=0.
              "max_range": 1500 // Maksymalna wykrywana wartość prądu, w jednostkach 0.01A. **Typ:** Integer. Zakres: >=0.
            }
          },
          {
            "name": "lowerVoltage", // Wyłącznik progu niskiego napięcia
            "value": {
              "value": 50, // Wartość wykrywanego napięcia, w jednostkach 0.01V. **Typ:** Integer. Zakres: >=0.
              "min_range": 10, // Minimalna wykrywana wartość napięcia, w jednostkach 0.01V. **Typ:** Integer. Zakres: >=0.
              "max_range": 24000 // Maksymalna wykrywana wartość napięcia, w jednostkach 0.01V. **Typ:** Integer. Zakres: >=0.
            }
          },
          {
            "name": "upperVoltage", // Wyłącznik progu wysokiego napięcia
            "value": {
              "value": 50, // Wartość wykrywanego napięcia, w jednostkach 0.01V. **Typ:** Integer. Zakres: >=0.
              "min_range": 10, // Minimalna wykrywana wartość napięcia, w jednostkach 0.01V. **Typ:** Integer. Zakres: >=0.
              "max_range": 24000 // Maksymalna wykrywana wartość napięcia, w jednostkach 0.01V. **Typ:** Integer. Zakres: >=0.
            }
          }
        ]
      }
    }
  }
}

Atrybuty (Stan)

• Brak

Protokół (zapytanie o status i instrukcje sterujące)

• Brak

Funkcja inch (inching)

Przykład deklaracji możliwości:

{
  "capability": "inching",
  "permission": "0010",
  "settings": {
    "inchingEnable": { // Ustawienie włączenia funkcji inch
      "permission": "11",
      "type": "boolean",
      "value": false
    },
    "inchingSwitch": { // Ustawienie działania inch
      "type": "enum",
      "permission": "11",
      "value": "on",
      "values": ["on", "off"]
    },
    "inchingDelay": { // Ustawienie czasu inch
      "type": "numeric",
      "permission": "11",
      "min": 500,
      "max": 100000,
      "value": 1000,
      "unit": "ms"
    }
  }
}

Atrybuty (Stan):

• Brak

Protokół (zapytanie o status i instrukcje sterujące):

• Brak

Strumień kamery (camera-stream)

Przykład deklaracji możliwości:

{
  "capability": "camera-stream",
  "permission": "0010",
  "settings": {
    "streamSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "username": "String", // Konto dostępu. **Typ:** String. Wymagane.
        "password": "String", // Hasło dostępu. **Typ:** String. Wymagane.
        "streamUrl": "rtsp://<username>:<password>@<hostname>:<port>/streaming/channel01", // URL strumienia. **Typ:** String. Wymagane.
        "videoCodec": "", // Kodek wideo. **Typ:** String. Wymagane. Parametry opcjonalne do zdefiniowania.
        "resolution": { // Rozdzielczość wideo. Wymagane.
          "width": 1080, // Szerokość. **Typ:** Number. Wymagane.
          "height": 720 // Wysokość. **Typ:** Number. Wymagane.
        },
        "keyFrameInterval": 5, // Interwał klatki kluczowej. **Typ:** String. Wymagane.
        "audioCodec": "G711", // Kodek audio. **Typ:** String. Wymagane. Parametry opcjonalne do zdefiniowania.
        "samplingRate": 50, // Częstotliwość próbkowania audio, w Hz. **Typ:** Number. Wymagane. Parametry opcjonalne do zdefiniowania.
        "dataRate": 50 // Przepływność bitów. **Typ:** Number. Wymagane. Jednostka: kb/s.
      }
    }
  }
}

Atrybuty (Stan):

• Brak

Protokół (zapytanie o status i instrukcje sterujące):

• Brak

Sterowanie trybem (mode)

Przykład deklaracji możliwości:

[
  {
    "capability": "mode",
    "name": "fanLevel",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["low", "medium", "high"] // Własne wartości trybu. Skonfigurowane wartości zastępują domyślne.
      }
    }
  },
  {
    "capability": "mode",
    "name": "thermostatMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["auto", "manual"] // Własne wartości trybu. Skonfigurowane wartości zastępują domyślne.
      }
    }
  },
  {
    "capability": "mode",
    "name": "airConditionerMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["cool", "heat", "auto", "fan", "dry"] // Własne wartości trybu. Skonfigurowane wartości zastępują domyślne.
      }
    }
  },
  {
    "capability": "mode",
    "name": "fanMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["normal", "sleep", "child"] // Własne wartości trybu. Skonfigurowane wartości zastępują domyślne.
      }
    }
  },
  {
    "capability": "mode",
    "name": "horizontalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // Własne wartości trybu. Skonfigurowane wartości zastępują domyślne.
      }
    }
  },
  {
    "capability": "mode",
    "name": "verticalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // Własne wartości trybu. Skonfigurowane wartości zastępują domyślne.
      }
    }
  }
]

Atrybuty (Stan):

{
  "modeValue": "low" // Wartość trybu. **Typ:** String. Wymagane. Odnieś się do obsługiwanych trybów preset.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "mode": {
    "fanLevel": {
      "modeValue": "low"
    }
  }
}

Wykrywanie dwutlenku węgla (co2)

Przykład deklaracji możliwości:

{
  "capability": "co2",
  "permission": "0100",
  "settings": {
    "co2Range": {
      "type": "numeric",
      "permission": "01",
      "min": 400,
      "max": 10000
    }
  }
}

Atrybuty (Stan):

{
  "co2": 111 // Stężenie dwutlenku węgla. **Typ:** Integer. Jednostka: ppm.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "co2": {
    "co2": 500
  }
}

Wykrywanie oświetlenia (illumination)

Przykład deklaracji możliwości:

{
  "capability": "illumination",
  "permission": "0100",
  "settings": {
    "illuminationRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 160000
    }
  }
}

Atrybuty (Stan):

{
  "illumination": 11 // Poziom oświetlenia. **Typ:** Integer. Jednostka: luks.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "illumination": {
    "illumination": 50
  }
}

Wykrywanie dymu (smoke)

Przykład deklaracji możliwości:

{
  "capability": "smoke",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "smoke": true // Wynik wykrywania. **Typ:** Boolean. `true` oznacza wykrycie, `false` oznacza brak wykrycia.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "smoke": {
    "smoke": true
  }
}

Wykrywanie otwarcia/zamknięcia drzwi magnetycznych (kontakt)

Przykład deklaracji możliwości:

{
  "capability": "contact",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "contact": true // Wynik wykrywania. **Typ:** Boolean. `true` oznacza wykrycie, `false` oznacza brak wykrycia.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "contact": {
    "contact": true
  }
}

Wykrywanie ruchu (motion)

Przykład deklaracji możliwości:

{
  "capability": "motion",
  "permission": "0110",
  "settings": {
    "motionInterval": {
      "type": "numeric",
      "permission": "11",
      "value": 300
    },
    "motionSensitivity": {
      "type": "numeric",
      "permission": "11",
      "value": 1000
    }
  }
}

Atrybuty (Stan):

{
  "motion": true // Wynik wykrywania. **Typ:** Boolean. `true` oznacza wykrycie, `false` oznacza brak wykrycia.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "motion": {
    "motion": true
  }
}

Wykrywanie wycieku wody (water-leak)

Przykład deklaracji możliwości:

{
  "capability": "water-leak",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "waterLeak": true // Pole `waterLeak` wskazuje aktualny wynik wykrywania. **Typ:** Boolean. `true` oznacza wykrycie, `false` oznacza brak wykrycia.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "water-leak": {
    "waterLeak": true
  }
}

Przełącznik wykrywania okna (window-detection)

Przykład deklaracji możliwości:

{
  "capability": "window-detection",
  "permission": "1100"
}

Atrybuty (Stan):

{
  "powerState": "on" // Pole `powerState` wskazuje stan zasilania. **Typ:** String. `on` oznacza włączone, `off` oznacza wyłączone.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "window-detection": {
    "powerState": "on"
  }
}

Przełącznik blokady rodzicielskiej (child-lock)

Przykład deklaracji możliwości:

{
  "capability": "child-lock",
  "permission": "1100"
}

Atrybuty (Stan):

{
  "powerState": "on" // Pole `powerState` wskazuje stan zasilania. **Typ:** String. `on` oznacza włączone, `off` oznacza wyłączone.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "child-lock": {
    "powerState": "on"
  }
}

Przełącznik przeciwbezpośredniego uderzenia (anti-direct-blow)

Przykład deklaracji możliwości:

{
  "capability": "anti-direct-blow",
  "permission": "1100"
}

Atrybuty (Stan):

{
  "powerState": "on" // Pole `powerState` wskazuje stan zasilania. **Typ:** String. `on` oznacza włączone, `off` oznacza wyłączone.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "anti-direct-blow": {
    "powerState": "on"
  }
}

Przełącznik poziomego wachlowania (horizontal-swing)

Przykład deklaracji możliwości:

{
  "capability": "horizontal-swing",
  "permission": "1100"
}

Atrybuty (Stan):

{
  "powerState": "on" // Pole `powerState` wskazuje stan zasilania. **Typ:** String. `on` oznacza włączone, `off` oznacza wyłączone.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "horizontal-swing": {
    "powerState": "on"
  }
}

Przełącznik pionowego wachlowania (vertical-swing)

Przykład deklaracji możliwości:

{
  "capability": "vertical-swing",
  "permission": "1100"
}

Atrybuty (Stan):

{
  "powerState": "on" // Pole `powerState` wskazuje stan zasilania. **Typ:** String. `on` oznacza włączone, `off` oznacza wyłączone.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "vertical-swing": {
    "powerState": "on"
  }
}

Przełącznik trybu ECO (eco)

Przykład deklaracji możliwości:

{
  "capability": "eco",
  "permission": "1100"
}

Atrybuty (Stan):

{
  "powerState": "on" // Pole `powerState` wskazuje stan zasilania. **Typ:** String. `on` oznacza włączone, `off` oznacza wyłączone.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "eco": {
    "powerState": "on"
  }
}

Przełącznik uruchamiania (toggle-startup)

Przykład deklaracji możliwości:

{
  "capability": "toggle-startup",
  "permission": "1100",
  "name": "1" // Pole `name` określa nazwę atrybutu dla `toggle-startup`. **Typ:** String. Dozwolone są tylko litery i cyfry.
}

Atrybuty (Stan):

{
  "startup": "on" // **Typ:** String. Opcje: `on` (włączenie zasilania), `stay` (utrzymanie zasilania), `off` (wyłączenie zasilania).
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "toggle-startup": {
    "1": {
      "startup": "on"
    },
    "2": {
      "startup": "off"
    }
  }
}

Wykryj przytrzymanie (detect-hold)

Przykład deklaracji możliwości:

{
  "capability": "detect-hold",
  "permission": "0100",
  "settings": {
    "detectHoldEnable": { // Ustawienie włączenia wykrywania przytrzymania
      "permission": "01",
      "type": "boolean",
      "value": false
    },
    "detectHoldSwitch": { // Ustawienie akcji wykrywania przytrzymania
      "type": "enum",
      "permission": "01",
      "value": "on",
      "values": ["on", "off"]
    },
    "detectHoldTime": { // Ustawienie czasu wykrywania przytrzymania
      "type": "numeric",
      "permission": "01",
      "min": 1,
      "max": 359,
      "value": 5,
      "unit": "minute"
    }
  }
}

Atrybuty (Stan):

{
  "detectHold": "on" // Pole `detectHold` wskazuje stan trybu wykrywania przytrzymania. **Typ:** String. `on` oznacza, że wykrywanie przytrzymania jest aktywne, `off` oznacza, że nie jest aktywne.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "detect-hold": {
    "detectHold": "on"
  }
}

Przełącznik identyfikacji/aktywacji (toggle-identify)

Przykład deklaracji możliwości:

{
  "capability": "toggle-identify",
  "permission": "1100", // Uwaga: Ta zdolność nie jest używana do raportowania w bieżącej wersji (V1.13.7) na ihost.
  "name": "1" // Nazwa komponentu. **Typ:** String. Wartości opcjonalne: "1" (Kanał 1), "2" (Kanał 2), "3" (Kanał 3), "4" (Kanał 4).
}

Atrybuty (Stan):

{
  "identify": true, // Wskazuje, że urządzenie aktywnie zgłosiło identyfikację lub aktywację.
  "countdown": 180 // Pole `countdown` wskazuje czas trwania aktywacji. **Typ:** Number. Jednostka: sekundy.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "toggle-identify": {
    "1": {
      "countdown": 180 // Aktywuj urządzenie na 180 sekund.
    }
  }
}

// Urządzenie zgłasza samoaktywację
{
  "toggle-identify": {
    "1": {
      "identify": true
    }
  }
}

Przełącznik wykrywania napięcia (toggle-voltage)

Przykład deklaracji możliwości:

{
  "capability": "toggle-voltage",
  "permission": "1100"
}

Atrybuty (Stan):

{
  "voltage": 230 // Pole `voltage` wskazuje wykryte napięcie. **Typ:** Number. Jednostka: Wolty.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "toggle-voltage": {
    "voltage": 230
  }
}

Wykrywanie prądu elektrycznego podkomponentu (toggle-electric-current)

Przykład deklaracji możliwości:

[
  {
    "capability": "toggle-electric-current",
    "permission": "0100",
    "name": "1" // Nazwa komponentu. **Typ:** String. Wartości opcjonalne: "1" (Kanał 1), "2" (Kanał 2), "3" (Kanał 3), "4" (Kanał 4).
  }
]

Atrybuty (Stan):

{
  "electricCurrent": 50 // Pole `electricCurrent` reprezentuje wartość prądu. **Jednostka:** 0.01 A. **Typ:** Integer. Wartość musi być większa lub równa 0.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "toggle-electric-current": {
    "1": {
      "electricCurrent": 50
    }
  }
}

Wykrywanie mocy podkomponentu (toggle-electric-power)

Przykład deklaracji możliwości:

[
  {
    "capability": "toggle-electric-power",
    "permission": "0100",
    "name": "1" // Nazwa komponentu. **Typ:** String. Wartości opcjonalne: "1" (Kanał 1), "2" (Kanał 2), "3" (Kanał 3), "4" (Kanał 4).
  }
]

Atrybuty (Stan):

{
  "electricPower": 50, // Pole `electricPower` reprezentuje bieżącą wartość mocy. **Jednostka:** 0.01 W. **Typ:** Integer. Wartość musi być większa lub równa 0.
  "reactivePower": 50, // Pole `reactivePower` reprezentuje bieżącą wartość mocy biernej. **Jednostka:** 0.01 W. **Typ:** Integer. Opcjonalne.
  "activePower": 50, // Pole `activePower` reprezentuje bieżącą wartość mocy czynnej. **Jednostka:** 0.01 W. **Typ:** Integer. Opcjonalne.
  "apparentPower": 50 // Pole `apparentPower` reprezentuje bieżącą wartość mocy pozornej. **Jednostka:** 0.01 W. **Typ:** Integer. Opcjonalne.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "toggle-electric-power": {
    "1": {
      "electricPower": 50,
      "reactivePower": 50,
      "activePower": 50,
      "apparentPower": 50
    }
  }
}

Statystyka zużycia energii podkomponentu (toggle-power-consumption)

Przykład deklaracji możliwości:

[
  {
    "capability": "toggle-power-consumption",
    "permission": "1101",
    "name": "1", // Nazwa komponentu. **Typ:** String. Wartości opcjonalne: "1" (Kanał 1), "2" (Kanał 2), "3" (Kanał 3), "4" (Kanał 4).
    "settings": {
      "resolution": {
        "permission": "01",
        "type": "numeric",
        "value": 3600
      },
      "timeZoneOffset": {
        "permission": "01",
        "type": "numeric",
        "min": -12,
        "max": 14,
        "value": 0
      }
    }
  }
]

Atrybuty (Stan):

Rozpocznij/Zatrzymaj statystyki w czasie rzeczywistym:

{
  "rlSummarize": true, // Rozpocznij lub zatrzymaj statystyki w czasie rzeczywistym. **Typ:** Boolean. Wymagane.
  "timeRange": { // Zakres czasowy podsumowania. Wymagane.
    "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia zużycia energii. **Typ:** String. Wymagane.
    "end": "2020-07-05T09:00:00Z" // Czas zakończenia zużycia energii. **Typ:** String. Wymagane.
  }
}

Zapytaj o zużycie energii według zakresu czasu:

{
  "type": "summarize", // Typ podsumowania. **Typ:** String. Wymagane. Opcje: "rlSummarize" (Podsumowanie w czasie rzeczywistym), "summarize" (Podsumowanie okresowe).
  "timeRange": { // Zakres czasowy podsumowania, wymagany gdy type jest "summarize".
    "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia zużycia energii. **Typ:** String. Wymagane.
    "end": "2020-07-05T09:00:00Z" // Czas zakończenia zużycia energii. **Typ:** String. Opcjonalne. Jeśli nie podano, domyślnie używany jest bieżący czas.
  }
}

Odpowiedź dla zużycia energii w ramach zakresu czasowego:

{
  "type": "summarize", // Typ podsumowania. **Typ:** String. Wymagane.
  "rlSummarize": 50.0, // Całkowite zużycie energii. **Jednostka:** 0.01 kWh. **Typ:** Number. Opcjonalne.
  "electricityIntervals": [ // Podzielone według `configuration.resolution` na wiele rekordów. Opcjonalne. Nieobecne gdy type jest "rlSummarize".
    {
      "usage": 26.5, // Zużycie energii. **Jednostka:** 0.01 kWh. **Typ:** Number. Wymagane.
      "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia. **Typ:** String. Wymagane.
      "end": "2020-07-05T09:00:00Z" // Czas zakończenia. **Typ:** String. Wymagane. Rekordy z interwałami krótszymi niż rozdzielczość są uznawane za nieprawidłowe.
    },
    {
      "usage": 26.5, // Zużycie energii. **Jednostka:** 0.01 kWh. **Typ:** Number. Wymagane.
      "start": "2020-07-05T09:00:00Z", // Czas rozpoczęcia. **Typ:** String. Wymagane.
      "end": "2020-07-05T10:00:00Z" // Czas zakończenia. **Typ:** String. Wymagane. Rekordy z interwałami krótszymi niż rozdzielczość są uznawane za nieprawidłowe.
    }
  ]
}

Protokół (zapytanie o status i instrukcje sterujące):

Rozpocznij statystyki czasu rzeczywistego:

{
  "toggle-power-consumption": {
    "1": {
      "rlSummarize": true,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": ""
      }
    }
  }
}

Zatrzymaj statystyki czasu rzeczywistego:

{
  "toggle-power-consumption": {
    "1": {
      "rlSummarize": false,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}

Pobierz historyczne zużycie energii:

{
  "toggle-power-consumption": {
    "1": {
      "type": "summarize",
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}

Pobierz zużycie energii w czasie rzeczywistym:

{
  "toggle-power-consumption": {
    "1": {
      "type": "rlSummarize"
    }
  }
}

Wskaźnik jakości łącza (lqi)

Przykład deklaracji możliwości:

{
  "capability": "lqi",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "lqi": 60 // Pole `lqi` reprezentuje wskaźnik jakości łącza. **Typ:** Number. Zakres wartości: 0 do 255.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "lqi": {
    "lqi": 60
  }
}

Konfiguracja funkcjonalna (configuration)

Przykład deklaracji możliwości:

[
  {
    "capability": "configuration",
    "permission": "1100"
  }
]

Atrybuty (Stan):

{
  "deviceConfiguration": { // Konfiguracja funkcji związanych z urządzeniem
    "defaultResolution": 300, // Domyślna rozdzielczość do odczytu danych nasycenia wilgoci. **Typ:** Integer. **Jednostka:** Sekundy. Wymagane.
    "maxResolution": 86400, // Maksymalna rozdzielczość do odczytu danych nasycenia wilgoci. **Typ:** Integer. **Jednostka:** Sekundy. Wymagane.
    "minResolution": 60 // Minimalna rozdzielczość do odczytu danych nasycenia wilgoci. **Typ:** Integer. **Jednostka:** Sekundy. Wymagane.
  }
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "configuration": {
    "deviceConfiguration": { // Konfiguracja funkcji związanych z urządzeniem
      "defaultResolution": 300, // Domyślna rozdzielczość do odczytu danych nasycenia wilgoci. **Typ:** Integer. **Jednostka:** Sekundy. Wymagane.
      "maxResolution": 86400, // Maksymalna rozdzielczość do odczytu danych nasycenia wilgoci. **Typ:** Integer. **Jednostka:** Sekundy. Wymagane.
      "minResolution": 60 // Minimalna rozdzielczość do odczytu danych nasycenia wilgoci. **Typ:** Integer. **Jednostka:** Sekundy. Wymagane.
    }
  }
}

System (system)

Przykład deklaracji możliwości:

[
  {
    "capability": "system",
    "permission": "1000"
  }
]

Atrybuty (Stan):

{
  "restart": true // Polecenie restartu urządzenia. **Typ:** Boolean. Wymagane. Wartość musi być `true`.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "system": { // Konfiguracja związana z tą zdolnością. Opcjonalne.
    "restart": true
  }
}

Wilgotność (moisture)

Przykład deklaracji możliwości:

[
  {
    "capability": "moisture",
    "permission": "0100"
  }
]

Atrybuty (Stan):

{
  "moisture": 55.5 // Pole `moisture` reprezentuje procent nasycenia wilgocią. **Typ:** Number. Wymagane. Zakres: 0 do 100.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "moisture": {
    "moisture": 55.5
  }
}

Ciśnienie atmosferyczne (barometric-pressure)

Przykład deklaracji możliwości:

[
  {
    "capability": "barometric-pressure",
    "permission": "0100",
    "settings": {
      "barometricPressureRange": {
        "type": "numeric",
        "permission": "01",
        "min": 540, // Wartość minimalna. **Typ:** Integer. Wymagane. Musi być mniejsze niż `max`.
        "max": 1100 // Wartość maksymalna. **Typ:** Integer. Wymagane. Musi być większa niż `min`.
      }
    }
  }
]

Atrybuty (Stan):

{
  "barometricPressure": 50 // Wartość ciśnienia atmosferycznego. **Typ:** Integer. Wymagane. **Jednostka:** hPa.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "barometric-pressure": {
    "barometricPressure": 50
  }
}

Prędkość wiatru (wind-speed)

Przykład deklaracji możliwości:

[
  {
    "capability": "wind-speed",
    "permission": "0100",
    "settings": {
      "windSpeedRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Wartość minimalna. **Typ:** Number. Wymagane. Musi być mniejsza niż `max`.
        "max": 50 // Wartość maksymalna. **Typ:** Number. Wymagane. Musi być większa niż `min`.
      }
    }
  }
]

Atrybuty (Stan):

{
  "windSpeed": 50 // Wartość prędkości wiatru. **Typ:** Number. Wymagane. **Jednostka:** m/s (metry na sekundę).
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "wind-speed": {
    "windSpeed": 50
  }
}

Kierunek wiatru (wind-direction)

Przykład deklaracji możliwości:

[
  {
    "capability": "wind-direction",
    "permission": "0100"
  }
]

Atrybuty (Stan):

{
  "windDirection": 10 // Kierunek wiatru. **Typ:** Integer. Wymagane. **Jednostka:** Stopnie. Zakres: 0 do 360 stopni (kierunek zgodny z ruchem wskazówek zegara).
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "wind-direction": {
    "windDirection": 10
  }
}

Opady (rainfall)

Przykład deklaracji możliwości:

[
  {
    "capability": "rainfall",
    "permission": "0100",
    "settings": {
      "rainfallRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Wartość minimalna. **Typ:** Number. Wymagane. Musi być mniejsza niż `max`.
        "max": 450 // Wartość maksymalna. **Typ:** Number. Wymagane. Musi być większa niż `min`.
      }
    }
  }
]

Atrybuty (Stan):

{
  "rainfall": 11.11 // Wartość opadów. **Typ:** Number. Wymagane. **Jednostka:** mm/h (milimetry na godzinę).
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "rainfall": {
    "rainfall": 11.11
  }
}

Indeks ultrafioletowy (ultraviolet-index)

Przykład deklaracji możliwości:

[
  {
    "capability": "ultraviolet-index",
    "permission": "0100",
    "settings": {
      "ultravioletIndexRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Wartość minimalna. **Typ:** Number. Wymagane. Musi być mniejsza niż `max`.
        "max": 16 // Wartość maksymalna. **Typ:** Number. Wymagane. Musi być większa niż `min`.
      }
    }
  }
]

Atrybuty (Stan):

{
  "ultravioletIndex": 11.1 // Indeks ultrafioletowy. **Typ:** Number. Wymagane.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "ultraviolet-index": {
    "ultravioletIndex": 11.1
  }
}

Przewodność elektryczna (electrical-conductivity)

Przykład deklaracji możliwości:

[
  {
    "capability": "electrical-conductivity",
    "permission": "0100",
    "settings": {
      "electricalConductivityRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Wartość minimalna. **Typ:** Number. Wymagane. Musi być mniejsza niż `max`.
        "max": 23 // Wartość maksymalna. **Typ:** Number. Wymagane. Musi być większa niż `min`.
      }
    }
  }
]

Atrybuty (Stan):

{
  "electricalConductivity": 11.11 // Wartość przewodności elektrycznej. **Typ:** Number. Wymagane. **Jednostka:** dS/m.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "electrical-conductivity": {
    "electricalConductivity": 11.11
  }
}

Moc nadawcza (transmit-power)

Przykład deklaracji możliwości:

[
  {
    "capability": "transmit-power",
    "permission": "1100"
  }
]

Atrybuty (Stan):

{
  "transmitPower": 9 // Wartość mocy nadawczej urządzenia. **Typ:** Integer. Wymagane. **Jednostka:** dBm.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "transmit-power": {
    "transmitPower": 9
  }
}

Wykrywanie PM2.5 (pm25)

Przykład deklaracji możliwości:

[
  {
    "capability": "pm25",
    "permission": "0100"
  }
]

Atrybuty (Stan):

{
  "pm25": 10 // Stężenie PM2.5 w powietrzu. **Typ:** Number. Wymagane. **Jednostka:** µg/m³.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "pm25": {
    "pm25": 10
  }
}

Indeks VOC (voc-index)

Przykład deklaracji możliwości:

{
  "capability": "voc-index",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "vocIndex": 10 // Indeks VOC odzwierciedlający poziom zanieczyszczenia gazami szkodliwymi. **Typ:** Number. Wymagane. **Jednostka:** µg/m³.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "voc-index": {
    "vocIndex": 10
  }
}

Wykrywanie gazu ziemnego (gas)

Przykład deklaracji możliwości:

{
  "capability": "gas",
  "permission": "0100"
}

Atrybuty (Stan):

{
  "gas": true // Wskazuje, czy wykryto wyciek gazu ziemnego. **Typ:** Boolean. Wymagane.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "gas": {
    "gas": true
  }
}

Status pracy nawadniania (irrigation/work-status)

Przykład deklaracji możliwości:

[
  {
    "capability": "irrigation",
    "permission": "0101",
    "name": "work-status",
    "settings": {
      "volumeUnit": {
        "type": "enum",
        "permission": "01",
        "values": ["L"],
        "value": "L"
      }
    }
  }
]

Atrybuty (Stan):

{
  "realTimeVolume": 20, // Rzeczywista objętość nawadniania w czasie rzeczywistym. **Typ:** Number. Opcjonalne. **Jednostka:** L.
  "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia nawadniania. **Typ:** Date. Opcjonalne.
  "end": "2020-07-05T09:00:00Z", // Czas zakończenia nawadniania. **Typ:** Date. Opcjonalne.
  "dailyVolume": 20 // Dzienne zużycie wody do nawadniania. **Typ:** Number. Opcjonalne. **Jednostka:** L.
}

Protokół (zapytanie o status i instrukcje sterujące):

Raportowanie statusu pracy:

{
  "irrigation": {
    "work-status": {
      "realTimeVolume": 20,
      "start": "2020-07-05T08:00:00Z",
      "end": "2020-07-05T09:00:00Z",
      "dailyVolume": 20
    }  
  }
}

Zapytanie o status pracy:

{
  "irrigation": {
    "type": "oneDay", // Typ agregacji. **Typ:** String. Wymagane. Opcje: "oneDay", "30Days", "180Days".
    "timeRange": { // Zakres czasowy dla agregacji. **Typ:** Object. Wymagane.
      "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia agregacji danych nawadniania. **Typ:** String. Wymagane.
      "end": "2020-07-05T09:00:00Z" // Czas zakończenia agregacji danych nawadniania. **Typ:** String. Opcjonalne. Jeśli pominięte, używany jest czas bieżący.
    }
  }
}

Wynik zapytania o status pracy:

{
  "irrigation": {
    "type": "oneDay", // Typ agregacji. **Typ:** String. Wymagane.
    "irrigationIntervals": [
      {
        "volume": 6500, // Objȩtość nawadniania. **Typ:** Number. Wymagane. **Jednostka:** L.
        "duration": 30, // Czas trwania nawadniania. **Typ:** Number. Wymagane. **Jednostka:** minuty.
        "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia. **Typ:** String. Wymagane.
        "end": "2020-07-05T09:00:00Z" // Czas zakończenia. **Typ:** String. Wymagane.
      },
      {
        "volume": 6500, // Objȩtość nawadniania. **Typ:** Number. Wymagane. **Jednostka:** L.
        "duration": 30, // Czas trwania nawadniania. **Typ:** Number. Wymagane. **Jednostka:** minuty.
        "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia. **Typ:** String. Wymagane.
        "end": "2020-07-05T09:00:00Z" // Czas zakończenia. **Typ:** String. Wymagane.
      }
    ]
  }
}

Tryb pracy nawadniania (irrigation/work-mode)

Przykład deklaracji możliwości:

[
  {
    "capability": "irrigation",
    "permission": "0100",
    "name": "work-mode",
    "settings": {
      "supportedModes": {
        "type": "enum",
        "permission": "01",
        "values": [
          "MANUAL", // Tryb ręczny
          "TIMER", // Jednorazowe harmonogramowanie
          "CYCLE-TIMER", // Powtarzane harmonogramowanie
          "VOLUME", // Jednorazowa objętość
          "CYCLE-VOLUME" // Powtarzana objętość
        ]
      }
    }
  }
]

Atrybuty (Stan):

{
  "workMode": "MANUAL" // Tryb pracy nawadniania. **Typ:** String. Opcjonalne. Wartości powinny pochodzić z `settings.supportedModes`.
}

Protokół (zapytanie o status i instrukcje sterujące):

{
  "irrigation": {
    "work-mode": "MANUAL"
  }
}

Automatyczny sterownik nawadniania (irrigation/auto-controller)

Przykład deklaracji możliwości:

[
  {
    "capability": "irrigation",
    "permission": "1100",
    "name": "auto-controller",
    "settings": {
      "volumeRange": { // Zakres objętości
        "type": "enum",
        "permission": "01",
        "min": 0,
        "max": 6500,
        "unit": "L"
      },
      "timeRange": { // Zakres czasu
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 86400,
        "unit": "second"
      },
      "cycleCountRange": { // Zakres liczby cykli
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 100,
        "step": 1
      }
    }
  }
]

Atrybuty (Stan):

Harmonogram jednorazowy lub powtarzany:

{
  "type": "time", // Tryb nawadniania. **Typ:** String. Wymagane. Opcje: "volume", "time".
  "action": {
    "perDuration": 60, // Czas trwania pojedynczego cyklu nawadniania. **Typ:** Number. Wymagane.
    "intervalDuration": 20, // Przerwa między cyklami nawadniania. **Typ:** Number. Wymagane.
    "count": 3 // Liczba cykli nawadniania. **Typ:** Number. Wymagane.
  }
}

Jednorazowa lub powtarzana objętość:

{
  "type": "volume", // Tryb nawadniania. **Typ:** String. Wymagane. Opcje: "volume", "time".
  "action": {
    "perConsumedVolume": 60, // Objętość zużywana w jednym cyklu nawadniania. **Typ:** Number. Wymagane.
    "intervalDuration": 20, // Przerwa między cyklami nawadniania. **Typ:** Number. Wymagane.
    "count": 3 // Liczba cykli nawadniania. **Typ:** Number. Wymagane.
  }
}

Protokół (zapytanie o status i instrukcje sterujące):

Harmonogram jednorazowy lub powtarzany:

{
  "irrigation": {
    "auto-controller": {
      "type": "time", // Tryb nawadniania. **Typ:** String. Wymagane.
      "action": {
        "perDuration": 60, // Czas trwania pojedynczego cyklu nawadniania. **Typ:** Number. Wymagane.
        "intervalDuration": 20, // Przerwa między cyklami. **Typ:** Number. Wymagane.
        "count": 3 // Liczba cykli. **Typ:** Number. Wymagane.
      }
    }
  }
}

Jednorazowa lub powtarzana objętość:

{
  "irrigation": {
    "auto-controller": {
      "type": "volume", // Tryb nawadniania. **Typ:** String. Wymagane.
      "action": {
        "perConsumedVolume": 60, // Objętość zużywana w jednym cyklu. **Typ:** Number. Wymagane.
        "intervalDuration": 20, // Przerwa między cyklami. **Typ:** Number. Wymagane.
        "count": 3 // Liczba cykli. **Typ:** Number. Wymagane.
      }
    }
  }
}

Obsługiwane tryby presetów

**Nazwy trybów **	**Wartości opcjonalne **
fanLevel (poziom wentylatora)	"low"
"medium"
"high"
thermostatMode (tryb termostatu)	"auto"
"manual"
airConditionerMode >= 1.11.0 (Tryb klimatyzatora)	"cool"
"heat"
"auto"
"fan"
"dry"
fanMode >= 1.11.0 (Tryb wentylatora)	"normal"
"sleep"
"child"
horizontalAngle >= 1.11.0 (Kąt poziomy)	"30"
"60"
"90"
"120"
"180"
"360"
verticalAngle >= 1.11.0 (Kąt pionowy)	"30"
"60"
"90"
"120"
"180"
"360"

c. Opis tagów

• Specjalny klucz toggle służy do ustawienia nazwy podkomponentu toggle.

{
    "toggle": {
        '1': 'Kanał1',
        '2': 'Kanał2',
        '3': 'Kanał3',
        '4': 'Kanał4',
    },
}

• Specjalny klucz temperature_unit służy do ustawienia jednostki temperatury.

{
    "temperature_unit":'c' // c-Celsjusz; f-Fahrenheit
}

d. Specjalny kod błędu i opis

Kod błędu	Opis	Wersja iHost
110000	Podurządzenie/grupa odpowiadająca id nie istnieje	≥2.1.0
110001	Brama jest w stanie wykrywania urządzeń zigbee	≥2.1.0
110002	Urządzenia w grupie nie mają wspólnej zdolności	≥2.1.0
110003	Niepoprawna liczba urządzeń	≥2.1.0
110004	Niepoprawna liczba grup	≥2.1.0
110005	Urządzenie offline	≥2.1.0
110006	Nie udało się zaktualizować stanu urządzenia	≥2.1.0
110007	Nie udało się zaktualizować stanu grupy	≥2.1.0
110008	Osiągnięto maksymalną liczbę grup. Utwórz do 50 grup	≥2.1.0
110009	Adres IP urządzenia kamery jest nieprawidłowy	≥2.1.0
110010	Błąd autoryzacji dostępu do urządzenia kamery	≥2.1.0
110011	Błąd adresu strumienia urządzenia kamery	≥2.1.0
110012	Kodowanie wideo urządzenia kamery nie jest obsługiwane	≥2.1.0
110013	Urządzenie już istnieje	≥2.1.0
110014	Kamera nie obsługuje działania offline	≥2.1.0
110015	Hasło konta nie jest zgodne z hasłem konta w adresie strumienia RTSP	≥2.1.0
110016	Brama jest w stanie wykrywania kamer onvif	≥2.1.0
110017	Przekroczono maksymalną liczbę dodanych kamer	≥2.1.0
110018	Ścieżka kamery ESP jest nieprawidłowa	≥2.1.0
110019	Nie udało się uzyskać dostępu do adresu usługi urządzenia zewnętrznego	≥2.1.0

e. Wyszukiwanie podurządzeń

Pozwól autoryzowanym użytkownikom włączyć lub wyłączyć wyszukiwanie podurządzeń przez bramę za pomocą tego interfejsu

• 💡Uwaga: Obecnie obsługiwane jest tylko wyszukiwanie podurządzeń Zigbee.

• 💡Uwaga: Podurządzenia Zigbee zostaną automatycznie dodane po wyszukaniu. Nie ma potrzeby używania interfejsu "Ręcznie dodaj podurządzenia" :::tips

• URL：/open-api/V2/rest/devices/discovery

• Metoda: PUT

• Nagłówek：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
enable	boolean	N	true (Rozpocznij parowanie); false (Wstrzymaj parowanie)
type	string	N	Typ wyszukiwania: Zigbee

Pomyślna odpowiedź danych: pusty Obiekt {} :::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: ** 200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

f. Ręczne dodawanie podurządzenia

Pozwól autoryzowanym użytkownikom dodać pojedyncze podurządzenie za pomocą tego interfejsu.

• Uwaga: Obecnie obsługiwane są tylko kamery RTSP i ESP32 Camera :::tips

• URL：/open-api/V2/rest/devices

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa podurządzenia
display_category	string	N	Typ urządzenia. Obsługiwane tylko kamery.
capabilities	CapabilityObject[]	N	Lista możliwości. Gdy display_category = camera, capabilities zawiera tylko możliwości camera-stream.
protocal	string	N	Protokół urządzenia. RTSP; ESP32-CAM
manufacturer	string	N	Producent.
model	string	N	Model urządzenia
firmware_version	string	N	Wersja oprogramowania urządzenia

CapabilityObject

Atrybut	Typ	Opcjonalne	Opis
capability	string	N	Nazwa możliwości. Obsługiwane tylko "camera-stream"
permission	string	N	Uprawnienia urządzenia. Obsługiwane tylko odczytywanie.
configuration	CameraStreamConfigurationObject	Y	Konfiguracja strumienia kamery.

SettingsObject

Atrybut	Typ	Opcjonalne	Opis
streamSetting	StreamSettingObject	N	Konfiguracja usługi strumieniowej

StreamSettingObject

Atrybut	Typ	Opcjonalne	Opis
type	string	N	Konfiguracja usługi strumieniowej
permission	string	N	Uprawnienia możliwości. Obsługuje tylko "11" (możliwe do modyfikacji).
value	StreamSettingValueObject	N	Konkretne wartości konfiguracji

StreamSettingValueObject

Atrybut	Typ	Opcjonalne	Opis
stream_url	string	N	Format URL strumienia
Format:<schema>://<hostname>:<port>/<username>:<password>@<service_path>
Przykład:rtsp://admin:[email protected]:554/streaming/channel01
Opcje schematu:
rtsp (Protokół przesyłania strumieni czasu rzeczywistego)
http (Protokół transferu hipertekstu) — Dla urządzeń ESP32-CAM
*Uwaga: Niektóre kamery mogą nie wymagać nazwy użytkownika ani hasła. W takich przypadkach można pominąć <username> oraz <password> pola w URL.

Pomyślna odpowiedź danych:

Atrybut	Typ	Opcjonalne	Opis
serial_number	string	N	Unikalny numer seryjny urządzenia

:::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {
    "serial_number": "serial_number"
  },
  "message": "success"
}

Odpowiedź z danymi niepowodzenia: pusty obiekt :::tips Warunek：

1. Błąd dostępu do adresu strumienia kamery (błąd formatu, błąd autoryzacji, wyjątek sieciowy itp.)

2. Urządzenie już istnieje

3. Jeśli dodanie pojedynczego urządzenia nie powiedzie się, zwracane są wszystkie urządzenia jako nieudane do dodania.

Kod statusu: 200 OK Kod błędu： ● 110009 Błąd adresu IP kamery ● 110010 Błąd autoryzacji dostępu do kamery ● 110011 Błąd adresu strumienia kamery ● 110012 Kodowanie wideo kamery nie jest obsługiwane ● 110013 Urządzenie już istnieje ::: Przykład odpowiedzi:

{
  "error": 110009,
  "data": {},
  "message": "camera ip access failed" 
}

g. Pobierz listę podurządzeń

Pozwól autoryzowanym użytkownikom uzyskać listę podurządzeń bramy za pomocą tego interfejsu. :::tips

• URL：/open-api/V2/rest/devices

• Metoda: GET

• Nagłówek：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametry żądania: brak Pomyślna odpowiedź danych:

Atrybut	Typ	Opcjonalne	Opis
device_list	ResponseDeviceObject[]	N	Lista urządzeń

ResponseDeviceObject

Atrybut	Typ	Opcjonalne	Opis
serial_number	string	N	Unikalny numer seryjny urządzenia
third_serial_number	string	"N" gdy podłączone jest urządzenie zewnętrzne, w przeciwnym razie "Y"	Unikalny numer seryjny urządzenia zewnętrznego
service_address	string	"N" gdy podłączone jest urządzenie zewnętrzne, w przeciwnym razie "Y"	Adres usługi urządzenia zewnętrznego
name	string	N	Nazwa urządzenia; jeśli nie została zmieniona, front-end wyświetli ją zgodnie z domyślnymi zasadami wyświetlania.
manufacturer	string	N	Producent
model	string	N	Model urządzenia
firmware_version	string	N	Wersja oprogramowania. Może być pustym ciągiem.
hostname	string	Y	Nazwa hosta urządzenia
mac_address	string	Y	Adres MAC urządzenia
app_name	string	Y	Nazwa aplikacji, do której należy. Jeśli app_name został wypełniony przy uzyskiwaniu certyfikatu interfejsu otwartego, wszystkie późniejsze urządzenia podłączone przez ten certyfikat będą zapisywane w tym polu.
display_category	string	N	Kategoria urządzenia
capabilities	CapabilityObject[]	N	Możliwości urządzenia
protocol	string	"N" gdy podłączone jest urządzenie zewnętrzne, w przeciwnym razie "Y"	Protokół urządzenia: zigbee, onvif, rtsp, esp32-cam
stan	object	Y	Obiekt stanu urządzenia. Przykłady stanów dla różnych możliwości znajdziesz w 【Obsługiwane możliwości urządzeń】
tagi	object	Y	Klucz-wartość w formacie JSON, niestandardowe informacje o urządzeniu. Funkcje są następujące: - Używane do przechowywania kanałów urządzenia - Używane do przechowywania jednostek temperatury - Niestandardowe informacje dla innych urządzeń stron trzecich
online	boolean	N	Stan online: True oznacza onlineFalse oznacza offline
podsiec	boolean	Y	Czy znajduje się w tej samej podsieci co brama

CapabilityObject 💡Uwaga: Sprawdź przykłady obsługiwanych możliwości urządzeń w [Obsługiwane możliwości urządzeń].

Atrybut	Typ	Opcjonalne	Opis
capability	string	N	Nazwa możliwości. Szczegóły sprawdź w [Obsługiwane możliwości urządzeń]
permission	string	N	Uprawnienie możliwości. Możliwe wartości to "read" (do odczytu), "write" (do zapisu), "readWrite" (do odczytu i zapisu).
configuration	object	Y	Informacje konfiguracyjne możliwości. Aktualnie używane camera-stream, sprawdź [Obsługiwane możliwości urządzeń]
name	string	Y	Pole name w toggle. Numer podkanału używany do identyfikacji urządzeń wielokanałowych. Na przykład, jeśli name to 1, oznacza to kanał 1.

:::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data":{
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "Moje Urządzenie",
        "manufacturer": "SONOFF",
        "model": "BASICZBR3",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          },
          {
            "capability": "rssi",
            "permission": "read"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ],
  }
  "message": "success"
}

h. Aktualizuj określone informacje lub stan urządzenia

Pozwól autoryzowanym użytkownikom modyfikować podstawowe informacje o urządzeniu podrzędnym i wydawać polecenia sterujące za pomocą tego interfejsu. :::tips

• URL：/open-api/V2/rest/devices/{serial_number}

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
name	string	Y	Nazwa urządzenia
tagi	object	Y	Klucz-wartość w formacie JSON, niestandardowe informacje o urządzeniu.
stan	object	Y	Obiekt stanu urządzenia. Przykłady stanów dla różnych możliwości znajdziesz w [Obsługiwane możliwości urządzeń]
configuration	object	Y	Informacje konfiguracyjne możliwości, obecnie modyfikacji podlega tylko capability camera_stream.

Pomyślna odpowiedź z danymi: :::tips Warunki: Parametry żądania są poprawne, a weryfikacja tożsamości użytkownika zakończona sukcesem. **Kod stanu: **200 OK Kod błędu:

• 110000 Urządzenie podrzędne/grupa odpowiadająca id nie istnieje ::: Przykład odpowiedzi:

{
  "error": 0,
  "data":{
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "我的设备",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "1100"
      },
      {
        "capability": "rssi",
        "permission": "0100"
      }
    ],
    "protocal": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  },
  "message": "success"
}

i. Usuń urządzenie podrzędne

Pozwól autoryzowanym użytkownikom usuwać urządzenia podrzędne za pomocą tego interfejsu. :::tips

• URL：/open-api/V2/rest/devices/{serial_number}

• Metoda：DELETE

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
name	string	Y	Nazwa urządzenia.
tagi	object	Y	Pary klucz-wartość w formacie JSON używane do przechowywania nazw kanałów urządzeń i innych informacji o urządzeniach podrzędnych.
stan	object	Y	Zmień stan urządzenia; szczegóły protokołu znajdują się w "Obsługiwane możliwości urządzeń."
capabilities	CapabilityObject []	Y	Informacje konfiguracyjne możliwości; wszystkie możliwości, które obsługują ustawienia konfiguracji, mogą być modyfikowane. Uwaga: uprawnień nie można zmieniać.

Pomyślna odpowiedź z danymi: :::tips Warunki: Parametry żądania są poprawne, a weryfikacja tożsamości użytkownika zakończona sukcesem. **Kod stanu: **200 OK Kody błędów:

• 110000: Urządzenie podrzędne/grupa odpowiadająca ID nie istnieje.

• 110006: Nie udało się zaktualizować stanu urządzenia.

• 110019: Nie udało się uzyskać dostępu do adresu usługi urządzenia strony trzeciej.

• 110024: Nie udało się zaktualizować konfiguracji urządzenia. ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

import axios from 'axios';

const serial_number = 'serial_number';
const access_token = 'access_token';

(async function main() {
  // włącz urządzenie
  await axios({
    url: `http://<nazwa domeny lub adres ip>/open-api/v2/rest/devices/${serial_number}`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      state: {
        power: {
          powerState: 'on'
        }
      }
    }
  });
})()

j. Usuń urządzenie podrzędne

Pozwala autoryzowanym użytkownikom usuwać urządzenia podrzędne za pomocą tego interfejsu. :::tips

• URL：/open-api/v2/rest/devices/{serial_number}

• Metoda：DELETE

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania: Brak Pomyślna odpowiedź z danymi: :::tips Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

k. Zapytaj o stan urządzenia

Pozwala autoryzowanym użytkownikom zapytać o stan urządzenia za pomocą tego interfejsu. :::tips

• URL：/open-api/v2/rest/devices/:serial_number/query-state/{capability}

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
query_state	object	N	Zapytaj o stan urządzenia; szczegóły protokołu znajdują się w "Obsługiwane możliwości urządzeń."

import axios from 'axios';

const serial_number = 'serial_number';
const access_token = 'access_token';

(async function main() {
  // włącz urządzenie
  await axios({
    url: `http://<nazwa domeny lub adres ip>/open-api/v2/rest/devices/${serial_number}/query-state/power-consumption`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      "query_state":{
        "power-consumption":{
          "type": "summarize", // Typ statystyki, wymagane
          "timeRange": { // Zakres czasu dla podsumowania, wymagane gdy type="summarize"
            "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia statystyk zużycia energii
            "end": "2020-07-05T09:00:00Z" // Czas zakończenia statystyk zużycia energii; jeśli pominięte, domyślnie bieżący czas
          }
        }
      }
    });
})()

Pomyślna odpowiedź z danymi: :::tips Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.4 Zarządzanie zabezpieczeniami

a. Pobierz listę zabezpieczeń

Pozwala autoryzowanym użytkownikom modyfikować ustawienia bramy za pomocą tego interfejsu. :::tips

• URL：/open-api/v2/rest/security

• Metoda：GET

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania: Brak Pomyślna odpowiedź z danymi:

Atrybut	Typ	Opcjonalne	Opis
security_list	ResponseSecurityObject[]	N	Lista urządzeń w odpowiedzi

ResponseDeviceObject

Atrybut	Typ	Opcjonalne	Opis
sid	int	N	id zabezpieczeń
name	string	N	Nazwa zabezpieczenia
enable	bool	N	Czy włączone

• true Włączone

• false Wyłączone |

:::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {
    "security_list":[
      {
        "sid": 1,
        "name": "Tryb domowy",
        "enable": true
      }
    ]
  },
  "message": "success"
}

b. Włącz określony tryb zabezpieczeń

Pozwala autoryzowanym użytkownikom włączyć określony tryb zabezpieczeń za pomocą tego interfejsu. :::tips

• URL：/open-api/v2/rest/security/{security_id}/enable

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania: Brak Pomyślna odpowiedź z danymi: pusty Obiekt {} :::tips Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

c. Wyłącz określony tryb zabezpieczeń

Pozwala autoryzowanym użytkownikom wyłączyć określony tryb zabezpieczeń za pomocą tego interfejsu. :::tips

• URL：/open-api/v2/rest/security/{security_id}/disable

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania: Brak Pomyślna odpowiedź z danymi: pusty Obiekt {} :::tips Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

d. Jednoprzyciskowe włączenie zabezpieczeń

Pozwala autoryzowanym użytkownikom włączyć tryb jednoprzyciskowego ustawienia zabezpieczeń za pomocą tego interfejsu. :::tips

• URL：/open-api/v2/rest/security/enable

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania: Brak Pomyślna odpowiedź z danymi: pusty Obiekt {} :::tips Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

e. Wyłącz zabezpieczenia

Pozwala autoryzowanym użytkownikom wyłączyć zabezpieczenia za pomocą tego interfejsu. :::tips

• URL：/open-api/v2/rest/security/disable

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametry żądania: Brak Pomyślna odpowiedź z danymi: pusty Obiekt {} :::tips Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: **200 OK ::: Przykład odpowiedzi:

{
  "error": 0,
  "data": {},
  "message": "success"
}

4. Urządzenia stron trzecich — dostęp

4.1 Instrukcja dostępu

Dostęp do urządzenia

Dostęp bramy stron trzecich

Kroki dostępu

1. Określ klasyfikację urządzenia w bramie. Szczegóły sprawdź w [Obsługiwane typy urządzeń].

2. Określ możliwości, które urządzenie może udostępniać. Szczegóły sprawdź w [Obsługiwane możliwości urządzeń].

3. Wywołaj interfejs [Discovery Request], aby dodać urządzenie do bramy.

   1. Uwaga: Musisz podać adres serwisu do odbierania instrukcji wydawanych przez bramę, który służy do odbierania poleceń sterowania urządzeniem wydawanych przez bramę.

4. Jeśli stan urządzenia strony trzeciej się zmieni, musisz wywołać interfejs [Device States Change Report], aby przesłać najnowszy stan z powrotem do bramy.

5. Po dodaniu urządzenie strony trzeciej pojawi się na liście urządzeń i będzie miało większość funkcji bramy (inne urządzenia nie będące stroną trzecią). Typowe otwarte interfejsy związane z urządzeniem będą działać normalnie.

• Wybierz odpowiednią kategorię urządzenia. Klasyfikacja wpłynie na ostateczny wygląd interfejsu użytkownika po połączeniu urządzenia z bramą.

• Wybierz odpowiednią zdolność urządzenia. Lista możliwości określi stan protokołu stanu urządzenia.

Proces programowy

a. Dostęp urządzenia

b. Dostęp bramy stron trzecich

4.2 Przykład dostępu

Włącznik, Wtyczka

Synchronizuj urządzenia stron trzecich

// Żądanie
URL：/open-api/v2/rest/thirdparty/event
Metoda：POST
Nagłówek：
  Content-Type: application/json
  Autoryzacja: Bearer  <token>
Ciało (Body):
{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "2"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "moja wtyczka",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission": "1100"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "nazwa producenta",
          "model": "nazwa modelu",
          "firmware_version": "wersja firmware",
          "service_address": "http://192.168.31.14/webhook"
      	}
      ]
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "third_serial_number": "third_serial_number",
        "serial_number": "numer seryjny"
      }
    ]
  }
}

Zgłoś stan urządzenia

URL：/open-api/V2/rest/thirdparty/event
Metoda：POST
Nagłówek：
  Content-Type: application/json
  Autoryzacja: Bearer  <token>
Ciało (Body):

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {}
}

Zgłoś offline/online

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {}
}

Odbierz instrukcje dotyczące sterowania urządzeniem przez bramę

URL：<adres serwisu>
Metoda：POST
Nagłówek：
  Content-Type: application/json
B

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "endpoint": {
      "third_serial_number": "third_serial_number",
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {}
}

Zapytaj o urządzenie

URL：/open-api/V2/rest/devices
Metoda：GET
Nagłówek：
  Content-Type: application/json
  Autoryzacja: Bearer  <token>
Body: Brak

{
  "error": 0,
  "data": {
    "device_list": [
      {
        "serial_number": "numer seryjny",
        "third_serial_number": "third_serial_number",
        "name": "moja wtyczka",
        "manufacturer": "nazwa producenta",
        "model": "nazwa modelu",
        "firmware_version": "wersja firmware",
        "display_category": "plug",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  },
  "message": "success"
}

4.3 Web API

Interfejs żądań dla stron trzecich do bramy

Format żądania

Pozwala autoryzowanym użytkownikom wysyłać żądania zdarzeń do bramy za pomocą tego interfejsu. :::tips

• URL：/open-api/V2/rest/thirdparty/event

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
event	EventObject	N	Struktura obiektu zdarzenia w żądaniu

EventObject

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka w żądaniu
endpoint	EndpointObject	Y	Struktura endpointu w żądaniuUwaga: To pole jest puste podczas synchronizacji nowej listy urządzeń.
payload	PayloadObject	N	Struktura ładunku (payload) w żądaniu

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa żądania. parametr opcjonalny: DiscoveryRequest: Synchronizuj nowe urządzenia DeviceStatesChangeReport: Raport aktualizacji stanu urządzenia DeviceOnlineChangeReport: Raport stanu online urządzenia
message_id	string	N	ID wiadomości żądania, UUID_V4
version	string	N	Numer wersji protokołu żądania. Obecnie ustalony na 1

EndpointObject

Atrybut	Typ	Opcjonalne	Opis
serial_number	string	N	Unikalny numer seryjny urządzenia
third_serial_number	string	N	Unikalny numer seryjny urządzenia zewnętrznego
tagi	object	Y	Klucz-wartość w formacie JSON, niestandardowe informacje o urządzeniu. [Funkcja zarządzania urządzeniami] - [Opis tagów]

PayloadObject Zależnie od różnych header.name struktura żądania jest różna.

Format odpowiedzi

:::tips **Kod stanu: **200 OK Parametry odpowiedzi: :::

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka odpowiedzi
payload	PayloadObject	N	Struktura payloadu odpowiedzi

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa nagłówka odpowiedzi. parametry opcjonalne: Response: Pomyślna odpowiedź ErrorResponse: Odpowiedź z błędem
message_id	string	N	ID wiadomości nagłówka odpowiedzi, UUID_V4. Przekaż tutaj message_id z nagłówka żądania *Jeśli parametr message_id w żądaniu jest brakujący, pole to będzie pustym ciągiem w odpowiedzi.
version	string	N	- Numer wersji protokołu żądania. Obecnie ustalony na 1.

Pomyślna odpowiedź--PayloadObject ：

W zależności od typu żądania struktura odpowiedzi jest różna. Szczegóły znajdują się w instrukcji konkretnego żądania.

Odpowiedź o błędzie--PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
type	string	N	Typy błędów:

• INVALID_PARAMETERS: Błąd parametru

• AUTH_FAILURE: Błąd autoryzacji

• INTERNAL_ERROR: Błąd wewnętrznej usługi | | description | string | N | Opis błędu |

DiscoveryRequest Synchronizuj nową listę urządzeń

• Uwaga: Po zsynchronizowaniu urządzenia do bramy, domyślnie jest ono online, czyli online=true. Późniejsze zmiany online są całkowicie zależne od synchronizacji ze stroną trzecią poprzez interfejs DeviceOnlineChangeReport.

Parametry żądania: EndpointObject**：**Brak PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
endpoints	EndpointObject[]	N	Lista urządzeń

EndpointObject:

Atrybut	Typ	Opcjonalne	Opis
third_serial_number	string	N	Unikalny numer seryjny urządzenia zewnętrznego
name	string	N	Nazwa urządzenia
display_category	string	N	Kategoria urządzenia. Szczegóły w [Obsługiwane typy urządzeń]. *Urządzenia stron trzecich obecnie nie obsługują dodawania kamer.
capabilities	CapabilityObject[]	N	Lista możliwości
stan	object	N	Początkowe informacje o stanie
manufacturer	string	N	Producent
model	string	N	Model urządzenia
tagi	object	Y	Klucz-wartość w formacie JSON, niestandardowe informacje o urządzeniu: Służy do przechowywania kanałów urządzenia Służy do przechowywania jednostek temperatury Inne niestandardowe dane stron trzecich
firmware_version	string	N	Wersja oprogramowania układowego
service_address	string	N	Adres serwisu. Na przykład http://192.168.31.14/service_address

Przykład żądania :

{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "moja wtyczka",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission" "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "nazwa producenta",
          "model": "nazwa modelu",
          "firmware_version": "wersja firmware",
          "service_address": "http://192.168.31.14/service_address"
        }
      ]
    }
  }
}

Parametry odpowiedzi: PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
endpoints	EndpointObject[]	N	Lista urządzeń

EndpointObject:

Atrybut	Typ	Opcjonalne	Opis
serial_number	string	N	Unikalny numer seryjny urządzenia
third_serial_number	string	N	Unikalny numer seryjny urządzenia zewnętrznego

Przykład poprawnej odpowiedzi:

{
  "header": {
    "name": "Response",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "serial_number": "numer seryjny",
        "third_serial_number": "third_serial_number"
      }
    ]
  }
}

Przykład odpowiedzi z błędem:

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "webhook nie może być pusty" 
  }
}

DeviceStatesChangeReport Raport zmiany stanu urządzenia

• Uwaga: Powtarzające się raporty stanu mogą fałszywie uruchamiać powiązaną scenę.

Parametry żądania: PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
stan	object	N	Stan urządzenia, zobacz [Obsługiwane możliwości urządzeń] dla szczegółów

Przykład żądania :

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Parametry odpowiedzi: PayloadObject: Pusty obiekt Przykład pomyślnej odpowiedzi:

{
  "header": {
    "name": "Response",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {}
}

DeviceOnlineChangeReport Raport stanu online urządzenia

• Uwaga: Powtarzające się raporty stanu mogą fałszywie uruchamiać powiązaną scenę.

Parametry żądania: PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
online	boolean	N	Stan online urządzenia true: Online
false: Offline

Przykład żądania :

{
  "event": {
    "header": {
      "name": "DeviceOnlineChangeReport",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

Parametry odpowiedzi: PayloadObject: Pusty obiekt Przykład pomyślnej odpowiedzi:

{
  "header": {
    "name": "Response",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {}
}

DeviceInformationUpdatedReport Raport aktualizacji informacji o urządzeniu

• Uwaga: Aktualizacja może wpływać na istniejące sceny lub funkcje zabezpieczeń.

Parametry żądania: PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
capabilities

| CapabilityObject[]

| N

| Lista możliwości. Szczegóły znajdują się w sekcji obsługiwanych możliwości urządzeń. **Uwaga:** Ten parametr zaktualizuje tylko value z ustawienia klucza w CapabilityObject, a aktualizacje są dozwolone tylko jeśli permission dla ustawienia klucza jest 11 lub 01. Szczegółową definicję struktury ustawienia w CapabilityObjectodsyłaj do szczegółowego opisu w sekcji 2.3 Kategorie wyświetlania urządzeń i możliwości urządzeń. | | tags

| object

| Y

| Klucz-wartość w formacie JSON, niestandardowe informacje o urządzeniu.

• Może być używane do przechowywania kanałów urządzenia

• Może być używane do przechowywania jednostek temperatury

• Inne niestandardowe dane stron trzecich |

Przykład żądania :

{
  "event": {
    "header": {
      "name": "DeviceInformationUpdatedReport",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "detect",
          "permission": "0110",
          "settings":{
            "detectInterval":{
              "permission": "11",
              "type": "numeric",
              "value": 300,
            },
            "detectSensitivity":{
              "permission": "11",
              "type": "numeric",
              "value": 1000,
            }
          }
        }
      ]
    }
  }
}

Parametry odpowiedzi: PayloadObject: Pusty obiekt Przykład pomyślnej odpowiedzi:

{
  "header": {
    "name": "Response",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "2"
  },
  "payload": {}
}

Brama wysyła interfejs poleceń przez adres usługi urządzenia

• Uwaga:

1. Strony trzecie muszą odpowiedzieć na żądanie bramy w ciągu 3s. W przeciwnym razie brama uzna przetwarzanie polecenia za przekroczone czasowo.

2. Jeśli usługa strony trzeciej jest offline, brama ustawi urządzenie w stan offline, a usługa strony trzeciej musi zgłosić stan urządzenia (DeviceStatesChangeReport) lub stan online (DeviceOnlineChangeReport), zanim wróci do stanu online.

Format żądania

Brama wysyła instrukcje do strony trzeciej przez interfejs adresu usługi urządzenia. :::tips

• URL：

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
directive	DirectiveObject	N	Struktura obiektu dyrektywy

DirectiveObject

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka w żądaniu
endpoint	EndpointObject	N	Struktura endpointu w żądaniu
payload	PayloadObject	N	Struktura ładunku (payload) w żądaniu

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa żądania. Parametry opcjonalne: UpdateDeviceStates: Aktualizuj stany urządzeń
message_id	string	N	ID wiadomości żądania, UUID_V4
version	string	N	Numer wersji protokołu żądania. Obecnie ustalony na 1.

EndpointObject

Atrybut	Typ	Opcjonalne	Opis
serial_number	string	N	Unikalny numer seryjny urządzenia
third_serial_number	string	N	Unikalny numer seryjny urządzenia zewnętrznego
tagi	object	N	Klucz-wartość w formacie JSON, niestandardowe informacje o urządzeniu. [Funkcja zarządzania urządzeniami] - [Opis tagów]

PayloadObject: W zależności od różnych header.name, dla każdego istnieje specyficzna struktura żądania.

Przykład żądania :

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
      "tags": {}
    },
    "payload": {
      "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Format odpowiedzi

:::tips **HTTP Kod stanu: **200 OK Atrybuty odpowiedzi HTTP： :::

Atrybut	Typ	Opcjonalne	Opis
event	EventObject	N	Struktura zdarzenia odpowiedzi

EventObject

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka w żądaniu
payload	PayloadObject	N	Struktura ładunku (payload) w żądaniu

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa nagłówka odpowiedzi. Parametr opcjonalny: UpdateDeviceStatesResponse: Odpowiedź na aktualizację stanów urządzeń ErrorResponse: Odpowiedź z błędem
message_id	string	N	ID wiadomości nagłówka odpowiedzi, UUID_V4. Przekaż tutaj message_id z nagłówka żądania
version	string	N	Numer wersji protokołu żądania. Obecnie ustalony na 1.

Pomyślna odpowiedź--PayloadObject：

W zależności od typu żądania struktura odpowiedzi jest różna. Szczegóły znajdują się w instrukcji konkretnego żądania.

Odpowiedź o błędzie--PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
type	string	N	Typy błędów:

• ENDPOINT_UNREACHABLE: Urządzenie jest nieosiągalne lub offline

• ENDPOINT_LOW_POWER: Urządzenie jest w trybie niskiego poboru mocy i nie może być sterowane

• INVALID_DIRECTIVE: Nieprawidłowa dyrektywa od bramy

• NO_SUCH_ENDPOINT: Urządzenie nie istnieje

• NOT_SUPPORTED_IN_CURRENT_MODE: Bieżący tryb nie obsługuje tej operacji

• INTERNAL_ERROR: Błąd wewnętrznej usługi

• REMOTE_KEY_CODE_NOT_LEARNED: Kod przycisku pilota nie został nauczony |

:::porady Warunki: Parametry żądania są poprawne. **Kod stanu: **200 OK Parametry odpowiedzi: :::

{
  "event": {
    "header": {
      "name": "UpdateDeviceStatesResponse",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "payload": {}
  }
}

{
  "event": {
    "header": {
      "name": "ErrorResponse",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE"
    }
  }
}

UpdateDeviceStates

Parametry żądania: PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
stan	object	N	Stan urządzenia, zobacz [Obsługiwane możliwości urządzeń] dla szczegółów.

Przykład żądania :

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

Parametry odpowiedzi: PayloadObject：pusty Obiekt Przykład pomyślnej odpowiedzi

{
  "header": {
    "name": "Response",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {}
}

QueryDeviceStates

Parametry żądania: PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
stan	object	N	Stan urządzenia, zobacz [Obsługiwane możliwości urządzeń] dla szczegółów.

Przykład żądania :

{
  "directive": {
    "header": {
      "name": "QueryDeviceStates",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "timeRange": {
            "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia statystyk zużycia energii, wymagane.
            "end": "2020-07-05T09:00:00Z"   // Czas zakończenia statystyk zużycia energii, wymagane.
          }
        }
      }
    }
  }
}

Parametry odpowiedzi: PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
stan	object	N	Stan urządzenia, zobacz [Obsługiwane możliwości urządzeń] dla szczegółów.

Przykład odpowiedzi:

{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "2"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "electricityIntervals": [ // Podzielone na wiele rekordów zgodnie z configuration.resolution
            {
              "usage": 26.5, // Wartość zużycia energii, wymagane. Typ: number.
              "start": "2020-07-05T08:00:00Z", // Czas rozpoczęcia, wymagane. Typ: date.
              "end": "2020-07-05T09:00:00Z"    // Czas zakończenia, wymagane. Typ: date. Jeśli odstęp między end a start jest mniejszy niż resolution, wszystkie zgłoszone rekordy uznaje się za nieważne.
            },
            {
              "usage": 26.5, // Wartość zużycia energii, wymagane. Typ: number.
              "start": "2020-07-05T09:00:00Z", // Czas rozpoczęcia, wymagane. Typ: date.
              "end": "2020-07-05T10:00:00Z"    // Czas zakończenia, wymagane. Typ: date. Jeśli odstęp między end a start jest mniejszy niż resolution, wszystkie zgłoszone rekordy uznaje się za nieważne.
            }
          ]
        }
      }
    }
  }
}

ConfigureDeviceCapabilities

Parametry żądania: PayloadObject：

Atrybut	Typ	Opcjonalne	Opis
capabilities	CapabilityObject[]	N	Lista możliwości. Szczegóły można znaleźć w części obsługiwanych możliwości urządzeń. Uwaga, pole permission nie może być zmienione, przekaż tę samą wartość podczas synchronizacji.

Przykład żądania :

{
  "directive": {
    "header": {
      "name": "ConfigureDeviceCapabilities",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "thermostat-mode-detect",
          "permission": "0110",
          "name": "temperature", // Typ wykrywania temperatury, wymagane. Wartości opcjonalne: humidity (wykrywanie wilgotności), temperature (wykrywanie temperatury)
          "settings": {
            "setpointRange": {
              "permission": "11",
              "type": "object",
              "value": {
                "supported": [ // Obsługiwane ustawienia wykrywania, wymagane.
                  {
                    "name": "lowerSetpoint", // Minimalna wartość, którą wykrywanie powinno utrzymywać. Należy podać albo lowerSetpoint albo upperSetpoint.
                    "value": { // Zakres wykrywania, opcjonalne. Wypełnij, jeśli istnieją warunki wstępne.
                      "value": 68.0, // Wartość temperatury lub wilgotności, wymagana.
                      "scale": "f" // Jednostka temperatury, wymagana jeśli name=temperature. Opcje: c (Celsius), f (Fahrenheit)
                    }
                  },
                  {
                    "name": "upperSetpoint", // Maksymalna wartość, którą wykrywanie powinno utrzymywać. Należy podać albo lowerSetpoint albo upperSetpoint.
                    "value": { // Zakres wykrywania, opcjonalne. Wypełnij, jeśli istnieją warunki wstępne.
                      "value": 68.0, // Wartość temperatury lub wilgotności, wymagana.
                      "scale": "f" // Jednostka temperatury, wymagana jeśli name=temperature. Opcje: c (Celsius), f (Fahrenheit)
                    }
                  }
                ]
              }
            },
            "supportedModes": {
              "type": "enum",
              "permission": "01",
              "values": [
                "COMFORT",
                "COLD",
                "HOT"
              ]
            }
          }
        }
      ]
    }
  }
}

Parametry odpowiedzi: PayloadObject：pusty Obiekt Przykład pomyślnej odpowiedzi

{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "2"
    },
    "payload": {}
  }
}

5. Wydarzenia wysyłane przez serwer (Server-sent events)

Opis interfejsu MDN EventSource：https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

5.1 Instrukcja

Bramka wspiera wysyłanie wiadomości do klienta za pomocą SSE (Server-sent events). Klient może monitorować wiadomości SSE po uzyskaniu poświadczeń dostępu i analizować treść wiadomości push zgodnie z protokołem powiadomień zdarzeń interfejsu po otrzymaniu wiadomości wysłanych przez bramę. Należy zauważyć, że brama obecnie używa protokołu HTTP1.1, więc w przeglądarce SSE będzie ograniczenie maksymalnie do nie więcej niż 6 połączeń (Szczegółowe instrukcje znajdują się w opisie interfejsu MDN EventSource.)

5.2 Wspólny format

:::porady

• URL：/open-api/V2/sse/bridge

• Metoda：GET ::: Parametry żądania:

Nazwa	Typ	Opcjonalne	Opis
access_token	string	N	Token dostępu

Uwaga: Przy żądaniu połączenia SSE brama sprawdzi access_token i zwróci błąd uwierzytelnienia, jeśli jest nieprawidłowy. { "error": 401, "data": {}, "message": "invalid access_token"}

## Na przykład: Nazwa modułu: device Wersja: 1,v2,v3 Typ wiadomości: addDevice

Przykład:

const evtSource = new EventSource("http://<nazwa domeny lub adres ip>/open-api/v2/sse/bridge?access_token=xxxxxx");

evtSource.addEventListener('device#v2#addDevice',function (event) {
  try {
    const data = JSON.parse(event.data);
    console.log('data', data);
  } catch (error) {
    console.error(`parse error`,error);
  }
}

5.3 Moduł urządzeń

a. Zdarzenie dodania urządzenia

:::tips Nazwa modułu：device Wersja：v2 Typ wiadomości：addDevice event.data parametry： :::

Nazwa	Typ	Opcjonalne	Opis
payload	ResponseDeviceObjectObject - Interfejs taki sam jak Pobierz listę urządzeń	N	informacje o urządzeniu

Przykład:

// event.data
{
  "payload": {
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "Mydevice",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "1100"
      },
      {
        "capability": "rssi",
        "permission": "0100"
      }
    ],
    "protocal": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  }
}

b. Zdarzenie aktualizacji stanu urządzenia

:::tips Nazwa modułu：device Wersja：v2 Typ wiadomości：updateDeviceState event.data parametry： :::

Nazwa	Typ	Opcjonalne	Opis
endpoint	EndpointObject	N	Informacje o urządzeniu
payload	object。 Struktura taka sama jak stan urządzenia	N	Dane stanu urządzenia

EndpointObject:

Parametr	Typ	Opcjonalne	Opis
serial_number	string	N	Unikalny numer seryjny urządzenia
third_serial_number	string	Y	Unikalny numer seryjny urządzenia strony trzeciej. Dla urządzeń podłączonych przez otwarte interfejsy, pole to jest wymagane.

Przykład:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "power": {
      "powerState": "on"
    },
    "brightness": {
      "brightness": 100
    }
  }
}

c. Zdarzenie aktualizacji informacji o urządzeniu

:::tips Nazwa modułu：device Wersja：v2 Typ wiadomości：updateDeviceInfo event.data parametry： :::

Nazwa	Typ	Opcjonalne	Opis
endpoint	EndpointObject	N	Informacje o urządzeniu
payload	DeviceChangeObject	N	Dane zmiany urządzenia

EndpointObject:

Atrybut	Typ	Opcjonalne	Opis
serial_number	string	N	Unikalny numer seryjny urządzenia
third_serial_number	string	Y	Unikalny numer seryjny urządzenia strony trzeciej. Dla urządzeń podłączonych przez otwarte interfejsy, pole to jest wymagane.

DeviceChangeObject

Nazwa	Typ	Opcjonalne	Opis
name	string	N	Nazwa urządzenia
capabilities	CapabilityObject []	Y	Lista możliwości urządzenia.
tagi	object	Y	tagiobject | Nullable | Pary klucz-wartość w formacie JSON dla niestandardowych informacji o urządzeniu.

• Może być używane do przechowywania kanałów urządzenia.

• Może być używane do przechowywania jednostek temperatury.

• Dla innych niestandardowych danych stron trzecich. |

Przykład:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "name": "nazwa urządzenia",
    "capabilities": [
      {
        "capability": "thermostat-mode-detect",
        "permission": "0110",
        "name": "temperature", // Typ wykrywania temperatury, wymagane. Wartości opcjonalne: humidity (wykrywanie wilgotności), temperature (wykrywanie temperatury)
        "settings": {
          "setpointRange": {
            "permission": "11",
            "type": "object",
            "value": {
              "supported": [ // Obsługiwane ustawienia wykrywania, wymagane.
                {
                  "name": "lowerSetpoint", // Minimalna wartość, którą wykrywanie powinno utrzymywać. Należy podać albo lowerSetpoint albo upperSetpoint.
                  "value": { // Zakres wykrywania, opcjonalne. Wypełnij, jeśli istnieją warunki wstępne.
                    "value": 68.0, // Wartość temperatury lub wilgotności, wymagana.
                    "scale": "f" // Jednostka temperatury, wymagana jeśli name=temperature. Opcje: c (Celsius), f (Fahrenheit)
                  }
                },
                {
                  "name": "upperSetpoint", // Maksymalna wartość, którą wykrywanie powinno utrzymywać. Należy podać albo lowerSetpoint albo upperSetpoint.
                  "value": { // Zakres wykrywania, opcjonalne. Wypełnij, jeśli istnieją warunki wstępne.
                    "value": 68.0, // Wartość temperatury lub wilgotności, wymagana.
                    "scale": "f" // Jednostka temperatury, wymagana jeśli name=temperature. Opcje: c (Celsius), f (Fahrenheit)
                  }
                }
              ]
            }
          },
          "supportedModes": {
            "type": "enum",
            "permission": "01",
            "values": [
              "COMFORT",
              "COLD",
              "HOT"
            ]
          }
        }
      }
    ]
  }
}

d. Zdarzenie usunięcia urządzenia

:::tips Nazwa modułu：device Wersja：v2 Typ wiadomości：deleteDevice event.data parametry： :::

** Nazwa **	** Typ **	** Opcjonalne**	** Opis **
endpoint	EndpointObject	N	Informacje o urządzeniu

EndpointObject:

Atrybut	Typ	Opcjonalne	Opis
serial_number	string	N	Unikalny numer seryjny urządzenia
third_serial_number	string	Y	Unikalny numer seryjny urządzenia strony trzeciej. Dla urządzeń podłączonych przez otwarte interfejsy, pole to jest wymagane.

Przykład:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  }
}

e. Zdarzenie aktualizacji stanu online urządzenia

:::tips Nazwa modułu：device Wersja：v2 Typ wiadomości：updateDeviceOnline event.data parametry： :::

Nazwa	Typ	Opcjonalne	Opis
endpoint	EndpointObject	N	Informacje o urządzeniu
payload	DeviceChangeObject	N	Dane zmiany urządzenia

EndpointObject:

Atrybut	Typ	Opcjonalne	Opis
serial_number	string	N	Unikalny numer seryjny urządzenia
third_serial_number	string	Y	Unikalny numer seryjny urządzenia strony trzeciej. Dla urządzeń podłączonych przez otwarte interfejsy, pole to jest wymagane.

DeviceChangeObject

Nazwa	Typ	Opcjonalne	Opis
online	boolean	N	Stan online urządzenia

Przykład:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "online": false
  }
}

5.4 Moduł bramy

a. Zdarzenie aktualizacji stanu zabezpieczeń

:::tips Nazwa modułu：device Wersja：v2 Typ wiadomości：updateDeviceOnline event.data parametry： :::

Atrybut	Typ	Opcjonalne	Opis
payload	SecurityStateObject	N	Informacje o urządzeniu

SecurityStateObject

Atrybut	Typ	Opcjonalne	Opis
alarm_state	string	N

• arming | Uzbrojony

• disarming | Rozbrojony |

Przykład:

// event.data
{
  "payload": {
    "alarm_state": "alarming"
  }
}

5.5 Moduł zabezpieczeń

a. Zdarzenie aktualizacji stanu uzbrojenia

:::tips Nazwa modułu：device Wersja：v2 Typ wiadomości：updateDeviceOnline event.data parametry： :::

Atrybut	Typ	Opcjonalne	Opis
payload	ArmStateObject	N	informacje o uzbrajaniu i rozbrajaniu

ArmStateObject：

Atrybut	Typ	Opcjonalne	Opis
arm_state	string	N

• arming | Uzbrojony

• disarming | Rozbrojony | | detail | DetailObject | N | Szczegóły uzbrajania/rozbrajania |

DetailObject：

Atrybut	Typ	Opcjonalne	Opis
sid	int	N	id trybu zabezpieczeń
name	string	N	Nazwa zabezpieczenia

Przykład

// event.data
{
  "payload": {
    "arm_state": "arming",
    "detail": {
      "sid": 1,
      "name": "Tryb domowy"
    }
  }
}

6. TTS (Silnik syntezy mowy (Text-to-Speech)

6.1 Instrukcja

Kluczowa rola

• Dostawca usługi TTS: Dostawca usługi silnika TTS odpowiada za zarejestrowanie silnika TTS na bramie i świadczenie usług TTS

• Serwer bramy：iHost

• Klient Open API bramy

6.1.1 Rejestrowanie usługi silnika TTS

1. 【Dostawca usługi TTS】Wywołuje interfejs w celu zarejestrowania silnika TTS na bramie.

2. 【Serwer bramy】Po pomyślnej rejestracji brama zapisze podstawowe informacje o silniku TTS (w tym adres usługi server_address, a dalsza komunikacja między bramą a Dostawcą usług TTS będzie odbywać się przez adres server_address) oraz przydzieli wewnętrzne ID usługi silnika TTS w bramie.

6.1.2 Pobierz listę zsyntetyzowanych plików audio

1. 【Klient Open API bramy】Wywołuje interfejs, aby uzyskać listę zarejestrowanych usług silników TTS. Możesz uzyskać aktualną listę zarejestrowanych silników TTS (w tym ID silnika TTS przydzielone przez bramę).

2. 【Klient Open API bramy】Wywołuje interfejs, aby uzyskać listę audio określonego silnika TTS. Brama wyda synchroniczne polecenie listy audio do określonego Dostawcy usługi TTS i zwróci wynik.

6.1.3 Synteza mowy z określeniem silnika mowy

1. 【Klient Open API bramy】Wywołuje interfejs, aby uzyskać listę zarejestrowanych usług silników TTS. Możesz uzyskać aktualną listę zarejestrowanych silników TTS (w tym ID silnika TTS przydzielone przez bramę).

2. 【Klient Open API bramy】Wywołuje interfejs, aby uzyskać listę audio określonego silnika TTS. Brama wyda synchroniczne polecenie listy audio do określonego Dostawcy usługi TTS i zwróci wynik.

6.1.4 Syntetyzuj audio i odtwarzaj mowę TTS.

1. 【Klient Open API bramy】Wywołuje interfejs, aby uzyskać listę zarejestrowanych usług silników TTS. Możesz uzyskać aktualną listę zarejestrowanych silników TTS (w tym ID silnika TTS przydzielone przez bramę).

2. 【Klient Open API bramy】Wywołuje interfejs, aby uzyskać listę audio określonego silnika TTS. Brama wyda synchroniczne polecenie listy audio do określonego Dostawcy usługi TTS i zwróci wynik. (w tym adres pliku audio TTS)

3. 【Klient Open API bramy】Zapisz adres pliku audio TTS z wyniku zwróconego w poprzednim kroku, wywołaj interfejs odtwarzania pliku audio i odtwórz go przez bramę.

6.2 Moduł silnika TTS

6.2.1 Otwarte możliwości bramy

a. Pobierz listę zarejestrowanych usług silnika TTS

:::porady

• URL：/open-api/V2/rest/tts/engines

• Metoda：GET

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania: brak Poprawna odpowiedź z danymi:

Atrybut	Typ	Opcjonalne	Opis
engines	EngineObject []	N	Lista zarejestrowanych silników TTS

Struktura EngineObject

Atrybut	Typ	Opcjonalne	Opis
id	string	N	ID silnika przydzielone przez bramę
name	string	N	Nazwa usługi silnika TS

:::wskazówki Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika została pomyślnie przeprowadzona. **Kod stanu: **200 OK Przykład odpowiedzi:： :::

{
  "error": 0,
  "data": {
    "engines": [
      {
        "id": "engine id",
        "name": "engine name"
      }
    ]
  },
  "message": "success"
}

b. Pobierz listę audio określonego silnika TTS

:::porady

• URL：/open-api/V2/rest/tts/engine/{id}/audio-list

• Metoda：GET

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania: brak Poprawna odpowiedź z danymi:

Atrybut	Typ	Opcjonalne	Opis
audio_list	AudioObject []	N	Lista audio

Struktura AudioObject

Atrybut	Typ	Opcjonalne	Opis
url	string	N	URL pliku audio, na przykład:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Etykieta pliku audio

:::wskazówki Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika została pomyślnie przeprowadzona. **Kod stanu: **200 OK **Kod błędu: **

• 190000 Silnik działa nieprawidłowo

Przykład odpowiedzi:： :::

{
  "error": 0,
  "data": {
    "audio_list": [
      {
        "url": "adres audio tts", // na przykład: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "etykieta audio tts"
      }
    ]
  },
  "message": "success"
}

c. Wykonaj syntezę mowy przy użyciu określonego silnika TTS

:::porady

• URL：/open-api/V2/rest/tts/engine/{id}/synthesize

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
text	string	N	Tekst używany do zsyntetyzowania audio
label	string	Y	Etykieta pliku audio
language	string	Y	Pole przezroczyste. Opcjonalny kod języka dla żądania syntezy mowy. Konkretna lista obsługiwanych kodów językowych jest dostarczana przez dostawcę usługi silnika TTS. Należy pamiętać, że usługa silnika TTS musi obsługiwać domyślny język do syntezy mowy, co oznacza, że jeśli język nie zostanie przekazany, do syntezy zostanie użyty domyślny język silnika.
options	object	Y	Pole przezroczyste. Służy do przekazywania parametrów konfiguracyjnych wymaganych do syntezy do usługi silnika mowy TTS.

Poprawna odpowiedź z danymi:

Atrybut	Typ	Opcjonalne	Opis
audio	AudioObject	N	Lista audio

Struktura AudioObject

Atrybut	Typ	Opcjonalne	Opis
url	string	N	URL pliku audio, na przykład:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Etykieta pliku audio

:::wskazówki Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika została pomyślnie przeprowadzona. **Kod stanu: **200 OK **Kod błędu: **

• 190000 Silnik działa nieprawidłowo

Przykład odpowiedzi:： :::

{
  "error": 0,
  "data": {
    "audio": {
        "url": "adres audio tts" // na przykład, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "etykieta audio tts"
    }
  },
  "message": "success"
}

6.2.2 Komunikacja między bramą a usługą TTS

a. Rejestrowanie usługi silnika TTS

Wysłanie żądania do bramy przez Dostawcę usługi TTS

:::porady

• URL：/open-api/V2/rest/thirdparty/event

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
event	EventObject	N	Struktura obiektu zdarzenia żądania Informacje

EventObject

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka w żądaniu
payload	PayloadObject	N	Struktura ładunku (payload) w żądaniu

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa żądania. Parametr opcjonalny.

• RegisterTTSEngine | | message_id | string | N | ID komunikatu żądania, UUID_V4 | | version | string | N | Wersja protokołu żądania. Obecnie ustalona na 1 |

PayloadObject

Atrybut	Typ	Opcjonalne	Opis
service_address	string	N	Adres usługi. Na przykład, http:///
name	string	N	Nazwa usługi

Przykład żądania:

{
  "event": {
    "header": {
      "name": "RegisterTTSEngine",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "payload": {
        "service_address": "service_address",
        "name": "nazwa usługi tts"
    }
  }
}

**Poprawne parametry odpowiedzi: **

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka w żądaniu
payload	PayloadObject	N	Struktura ładunku (payload) w żądaniu

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa nagłówka odpowiedzi. Parametr opcjonalny:

• Odpowiedź (Odpowiedź pomyślna)

• ErrorResponse (Odpowiedź błędu) | | message_id | string | N | ID komunikatu nagłówka odpowiedzi, UUID_V4. Tutaj wiadomość żądania przychodzącego: header.message_id | | version | string | N | Wersja protokołu żądania. Obecnie ustalona na 1 |

PayloadObject

Atrybut	Typ	Opcjonalne	Opis
engine_id	string	N	ID silnika przydzielone przez bramę

:::wskazówki Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika została pomyślnie przeprowadzona. **Kod stanu: **200 OK Przykład odpowiedzi:： ::: Poprawny przykład odpowiedzi:：

{
    "header": {
      "name": "Response",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "payload": {
      "engine_id": "engine id"
    }
  }

**Parametry odpowiedzi przy nieprawidłowości: **

Atrybut	Typ	Opcjonalne	Opis
type	string	N	Typ błędu

• INVALID_PARAMETERS (Błąd parametrów)

• AUTH_FAILURE (Błąd uwierzytelniania)

• INTERNAL_ERROR (Błąd wewnętrzny usługi) | | description | string | N | Opis błędu |

Przykład odpowiedzi błędu:：

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address nie może być puste" 
  }
}

b. Synchronizuj polecenie listy audio

Wysłanie polecenia do Dostawcy usługi TTS przez bramę.

:::porady

• URL：<adres usługi>

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
directive	DirectiveObject	N	Struktura informacji obiektu polecenia

DirectiveObject

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka w żądaniu
payload	PayloadObject	N	Struktura ładunku (payload) w żądaniu

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa żądania. Parametr opcjonalny:

• SyncTTSAudioList | | message_id | string | N | ID komunikatu żądania, UUID_V4 | | version | string | N | Wersja protokołu żądania. Obecnie ustalona na 1 |

Przykład żądania:

{
  "directive": {
    "header": {
      "name": "SyncTTSAudioList",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "payload": {}
  }
}

**Poprawne parametry odpowiedzi: **

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka w żądaniu
payload	PayloadObject	N	Struktura ładunku (payload) w żądaniu

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa nagłówka odpowiedzi. Parametr opcjonalny:

• Odpowiedź (Odpowiedź pomyślna)

• ErrorResponse (Odpowiedź błędu) | | message_id | string | N | ID komunikatu nagłówka odpowiedzi, UUID_V4. Tutaj wiadomość żądania przychodzącego: header.message_id | | version | string | N | Wersja protokołu żądania. Obecnie ustalona na 1 |

PayloadObject:

Atrybut	Typ	Opcjonalne	Opis
audio_list	AudioObject []	N	Lista audio TTS

Struktura AudioObject

Atrybut	Typ	Opcjonalne	Opis
url	string	N	URL pliku audio, na przykład:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Etykieta pliku audio

:::wskazówki Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika została pomyślnie przeprowadzona. **Kod stanu: **200 OK Przykład odpowiedzi:： ::: Poprawny przykład odpowiedzi:：

{
    "header": {
      "name": "Response",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "payload": {
      "audio_list": [
        {
            "url": "url audio tts",
            "label": "etykieta audio tts"
        }
      ]
    }
}

**Parametry odpowiedzi przy nieprawidłowości: **

Atrybut	Typ	Opcjonalne	Opis
type	string	N	Typ błędu

• INVALID_PARAMETERS (Błąd parametrów)

• AUTH_FAILURE (Błąd uwierzytelniania)

• INTERNAL_ERROR (Błąd wewnętrzny usługi) | | description | string | N | Opis błędu |

Przykład odpowiedzi błędu:：

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address nie może być puste" 
  }
}

c. Polecenie syntezy mowy

Wysłanie polecenia do Dostawcy usługi TTS przez bramę.

:::porady

• URL：<adres usługi>

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
directive	DirectiveObject	N	Struktura informacji obiektu polecenia

DirectiveObject

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka w żądaniu
payload	PayloadObject	N	Struktura ładunku (payload) w żądaniu

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa żądania. Parametr opcjonalny:

• SynthesizeSpeech | | message_id | string | N | ID komunikatu żądania: UUID_V4 | | version | string | N | Wersja protokołu żądania. Obecnie ustalona na 1 |

PayloadObject

Atrybut	Typ	Opcjonalne	Opis
text	string	N	Tekst używany do zsyntetyzowania audio
label	string	Y	Etykieta pliku audio
language	string	Y	Pole przezroczyste. Opcjonalny kod języka dla żądania syntezy mowy. Konkretna lista obsługiwanych kodów językowych jest dostarczana przez dostawcę usługi silnika TTS. Należy pamiętać, że usługa silnika TTS musi obsługiwać domyślny język do syntezy mowy, co oznacza, że jeśli język nie zostanie przekazany, do syntezy zostanie użyty domyślny język silnika.
options	object	Y	Pole przezroczyste. Służy do przekazywania parametrów konfiguracyjnych wymaganych do syntezy do usługi silnika mowy TTS.

Przykład żądania:

{
    "directive": {
        "header": {
            "name": "SynthesizeSpeech",
            "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
            "version": "1"
        },
        "payload": {
            "text": "Tekst wejściowy do syntezy.",
            "label": "etykieta audio tts"
        }
    }
}

**Poprawne parametry odpowiedzi: **

Atrybut	Typ	Opcjonalne	Opis
header	HeaderObject	N	Struktura nagłówka w żądaniu
payload	PayloadObject	N	Struktura ładunku (payload) w żądaniu

HeaderObject

Atrybut	Typ	Opcjonalne	Opis
name	string	N	Nazwa nagłówka odpowiedzi. Parametr opcjonalny:

• Odpowiedź (Odpowiedź pomyślna)

• ErrorResponse (Odpowiedź błędu) | | message_id | string | N | ID komunikatu nagłówka odpowiedzi, UUID_V4. Tutaj wiadomość żądania przychodzącego: header.message_id | | version | string | N | Wersja protokołu żądania. Obecnie ustalona na 1 |

PayloadObject

Atrybut	Typ	Opcjonalne	Opis
audio	AudioObject	N	Audio TTS

Struktura AudioObject

Atrybut	Typ	Opcjonalne	Opis
url	string	N	URL pliku audio, na przykład:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Etykieta pliku audio

:::wskazówki Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika została pomyślnie przeprowadzona. **Kod stanu: **200 OK Przykład odpowiedzi:： ::: Poprawny przykład odpowiedzi:：

{
    "header": {
      "name": "Response",
      "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
      "version": "1"
    },
    "payload": {
      "audio": {
        "url": "url audio tts",
        "label": "etykieta audio tts"
      }
    }
}

**Parametry odpowiedzi przy nieprawidłowości: **

Atrybut	Typ	Opcjonalne	Opis
type	string	N	Typ błędu

• INVALID_PARAMETERS (Błąd parametrów)

• AUTH_FAILURE (Błąd uwierzytelniania)

• INTERNAL_ERROR (Błąd wewnętrzny usługi) | | description | string | N | Opis błędu |

Przykład odpowiedzi błędu:：

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Unikalny identyfikator, najlepiej UUID w wersji 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address nie może być puste" 
  }
}

7. Moduł multimedialny

7.1 Odtwarzanie pliku audio

:::porady

• URL：/open-api/V2/rest/media/audio-player

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
audio_url	string	N	Adres URL audio

Poprawna odpowiedź z danymi: :::wskazówki Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika została pomyślnie przeprowadzona. **Kod stanu: **200 OK Przykład odpowiedzi:： :::

{
  "error": 0,
  "data": {},
  "message": "success"
}

8. Niestandardowa karta UI

Niestandardowe karty UI pozwalają wyświetlać dowolne treści w karcie. Treścią może być strona internetowa, obraz lub dowolna usługa z interfejsem użytkownika. Wystarczy podać URL treści, którą chcesz wyświetlić. Karta UI automatycznie dopasuje swoją szerokość i wysokość, a zawartość zostanie wyrenderowana przy użyciu iFrame.

8.1 Instrukcja

Kluczowa rola

• Dostawca usługi UI: Dostawca odpowiedzialny za tworzenie niestandardowych kart UI na bramie.

• Serwer bramy: Serwer bramy (iHost).

• Klient Open API bramy: Klient Open API dla bramy.

8.1.1 Tworzenie niestandardowej karty UI

• [Dostawca usługi UI]: Wywołuje API w celu utworzenia niestandardowej karty UI na bramie.

• [Serwer bramy]: Po pomyślnej rejestracji brama zapisuje podstawowe informacje o karcie UI (w tym konfigurację rozmiaru i URL zasobu karty) i przypisuje wewnętrzne ID karty UI w bramie.

8.1.2 Pobieranie listy kart UI

• [Dostawca usługi UI]: Wywołuje API w celu pobrania listy kart UI.

• [Serwer bramy]: Zwraca listę kart UI przechowywanych na bramie, w tym niestandardowe karty UI nieutworzone przez wywołującego.

8.1.3 Modyfikacja konfiguracji określonej karty UI

• [Dostawca usługi UI]: Wywołuje API w celu modyfikacji konfiguracji określonej karty UI, takiej jak konfiguracja rozmiaru i URL zasobu.

• [Serwer bramy]: Po pomyślnej modyfikacji brama zapisuje zaktualizowane informacje o karcie UI, w tym nową konfigurację rozmiaru i URL zasobu.

8.1.4 Usuwanie niestandardowej karty UI

1. [Dostawca usługi UI]: Wywołuje API w celu usunięcia określonej niestandardowej karty UI.

2. [Serwer bramy]: Brama usunie wszystkie informacje związane z określoną kartą UI.

8.2 Moduł niestandardowej karty UI

8.2.1 Tworzenie niestandardowej karty UI

Dostawca usługi UI wysyła żądanie do bramy, aby utworzyć niestandardową kartę UI.

:::porady

• URL：/open-api/v2/rest/ui/cards

• Metoda：POST

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
label	string	Y	Etykieta karty: Służy do opisu karty. Jest to alias karty.
cast_settings	CastSettingsObject	Y	Ustawienia karty cast: Ustawienia konfiguracyjne dla kart cast.
web_settings	WebSettingsObject	N	Ustawienia karty web: Ustawienia konfiguracyjne dla kart web.

CastSettingsObject:

Atrybut	Typ	Opcjonalne	Opis
dimensions	DimensionObject []	N	Konfiguracja rozmiaru: Musi zawierać co najmniej jedną konfigurację.
default	string	N	Specyfikacja domyślna: Domyślna specyfikacja rozmiaru jest używana, z opcjonalnymi parametrami: 2x2

WebSettingsObject:

Atrybut	Typ	Opcjonalne	Opis
dimensions	DimensionObject []	N	Konfiguracja rozmiaru: Musi zawierać co najmniej jedną konfigurację.
drawer_component	DrawerObject	Y	Ustawienia wyświetlania komponentu drawer.
default	string	N	Specyfikacja domyślna:

• 1x1

• 2x1 |

DimensionObject:

Atrybut	Typ	Opcjonalne	Opis
src	string	N	URL zasobu: Na przykład: http://example.html
size	string	N	Specyfikacje rozmiaru:
Opcjonalne parametry CastSettingsObject:

• 2×2

Opcjonalne parametry WebSettingsObject:

• 1x1

• 2x1 |

DrawerObject:

Atrybut	Typ	Opcjonalne	Opis
src	string	N	URL zasobu: Na przykład: http://example.html

Pomyślna odpowiedź danych:

Atrybut	Typ	Opcjonalne	Opis
id	string	N	Unikalne ID karty UI

:::porady Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika przeszła. **Kod stanu: ** 200 OK ::: Przykład żądania：

{
  "label": "ewelink cube card",
  "cast_settings": {
    "dimensions": [
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "2×2"
      }
    ],
    "default": "2×2"
  },
  "web_settings": {
    "dimensions": [
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "2×1"
      },
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "1×1"
      }
    ],
    "drawer_component": {
      "src": "https://ewelink.cc/ewelink-cube/"
    },
    "default": "2×1"
  }
}

Przykład odpowiedzi:

{
  "error": 0,
  "data": {
    "id": "72cc5a4a-f486-4287-857f-b482d7818b16"
  },
  "message": "success"
}

8.2.2 Pobierz listę kart UI

:::porady

• URL：/open-api/v2/rest/ui/cards

• Metoda：GET

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania: Brak Parametry odpowiedzi:

Atrybut	Typ	Opcjonalne	Opis
data	CardObject[]	N	Lista kart UI

Obiekt CardObjec:

Atrybut	Typ	Opcjonalne	Opis
id	string	N	ID karty: Unikalny identyfikator karty.
label	string	Y	Etykieta karty: Służy do opisu karty. Pełni rolę aliasu lub nazwy karty.
cast_settings	CastSettingsObject	Y	Etykieta karty: Służy do opisu karty. Jest to alias karty.
web_settings	WebSettingsObject	N	Ustawienia karty cast: Ustawienia konfiguracyjne dla kart cast.
app_name	string	Y	Ustawienia karty web: Ustawienia konfiguracyjne dla kart web.

CastSettingsObject:

Atrybut	Typ	Opcjonalne	Opis
dimensions	DimensionObject []	N	Konfiguracja rozmiaru: Musi zawierać co najmniej jedną konfigurację.
default	string	N	Specyfikacja domyślna:
Parametr opcjonalny: 2x2
używane	string	N	Aktualna specyfikacja:
Parametr opcjonalny: 2x2

WebSettingsObject:

Atrybut	Typ	Opcjonalne	Opis
dimensions	DimensionObject []	N	Konfiguracja rozmiaru: Musi zawierać co najmniej jedną konfigurację.
drawer_component	DrawerObject	Y	Ustawienia wyświetlania komponentu drawer.
default	string	N	Specyfikacja domyślna:
Parametr opcjonalny:

• 1x1

• 2x1 | | used | string | N | Aktualna specyfikacja: Parametr opcjonalny:

• 1x1

• 2x1 |

DimensionObject:

Atrybut	Typ	Opcjonalne	Opis
src	string	N	URL zasobu: Na przykład: http://example.html
size	string	N	Specyfikacje rozmiaru:
Parametr opcjonalny:

• 1x1

• 2x1

Uwaga: Obecnie karty cast obsługują tylko specyfikację 2x2. Specyfikacja 2x2 nie będzie skuteczna. |

DrawerObject:

Atrybut	Typ	Opcjonalne	Opis
src	string	N	URL zasobu: Na przykład: http://example.html

Przykład odpowiedzi:

{
  "error": 0,
  "data": [
    {
      "id": "72cc5a4a-f486-4287-857f-b482d7818b16",
      "label": "ewelink cube card",
      "cast_settings": {
        "dimensions": [
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "2×2"
          }
        ],
        "default": "2×2",
        "used": "2×2"
      },
      "web_settings": {
        "dimensions": [
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "2×1"
          },
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "1×1"
          }
        ],
        "drawer_component": {
          "src": "https://ewelink.cc/ewelink-cube/"
        },
        "default": "2×1",
        "used": "2×1"
      },
      "appName": "ewelink-cube"
    }
  ],
  "message": "success"
}

8.2.3 Modyfikacja konfiguracji określonej karty UI

Użytkownicy z autoryzacją mogą modyfikować konfigurację istniejącej karty UI za pomocą tego interfejsu. Dostawcy usług niestandardowych kart mogą modyfikować tylko te karty UI, które sami utworzyli.

:::porady

• URL：/open-api/v2/rest/ui/cards/{id}

• Metoda：PUT

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania:

Atrybut	Typ	Opcjonalne	Opis
label	string	Y	Służy do opisu karty. Jest to alias karty.
cast_settings	CastSettingsObject	Y	Ustawienia karty cast
web_settings	WebSettingsObject	Y	Ustawienia karty web

CastSettingsObject:

Atrybut	Typ	Opcjonalne	Opis
używane	string	Y, Jeden z nich używane lub src musi być dostarczony, ale wymagany jest co najmniej jeden z tych parametrów.	Aktualna specyfikacja:
Parametr opcjonalny:

• 2x2

| | src | string | Y, Jeden z nich używane lub src musi być dostarczony, ale wymagany jest co najmniej jeden z tych parametrów. | URL zasobu: http://example.html |

WebSettingsObject:

Atrybut	Typ	Opcjonalne	Opis
używane	string	Y, Jeden z nich używane lub src musi być dostarczony, ale wymagany jest co najmniej jeden z tych parametrów.	Aktualna specyfikacja:
Parametr opcjonalny:

• 1x1

• 2x1 | | src | string | Y, Jeden z nich używane lub src musi być dostarczony, ale wymagany jest co najmniej jeden z tych parametrów. | URL zasobu: http://example.html |

Pomyślna odpowiedź z danymi: :::tips Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika została pomyślnie przeprowadzona. Karta UI podlegająca modyfikacji musi być utworzona przez dostawcę niestandardowej karty UI wywołującego interfejs. **Kod stanu: ** 200 OK Kod błędu:

• 406: Brak uprawnień do dostępu do tego zasobu ::: **Przykład odpowiedzi: **

{
  "error": 0,
  "data": {},
  "message": "success"
}

**Przykład żądania: **

{
  "cast_settings": {
    "used": "2×2"
  },
  "web_settings": {
    "used": "1×1"
  }
}

8.2.4 Usuń niestandardową kartę UI

Użytkownicy z autoryzacją mają uprawnienia do usunięcia istniejącej karty UI za pomocą tego interfejsu. Dostawcy niestandardowych kart mogą usuwać tylko te karty UI, które sami utworzyli.

:::porady

• URL：/open-api/v2/rest/ui/cards/{id}

• Metoda：DELETE

• Nagłówek：

  • Content-Type: application/json

  • Autoryzacja: Bearer ::: Parametry żądania: Brak Pomyślna odpowiedź z danymi: :::wskazówki Warunki: Parametry żądania są prawidłowe, a weryfikacja tożsamości użytkownika została pomyślnie przeprowadzona. Karta UI podlegająca modyfikacji musi być utworzona przez dostawcę niestandardowej karty UI wywołującego interfejs. **Kod stanu: ** 200 OK Kod błędu:

• 406: Brak uprawnień do dostępu do tego zasobu. ::: **Przykład odpowiedzi: **

{
  "error": 0,
  "data": {},
  "message": "success"
}