# 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.

```json
// Żą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.

```json
// Żą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.

```json
// Żą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

```javascript
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. |

```javascript
// 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](https://en.wikipedia.org/wiki/Double-precision_floating-point_format)                           |
| 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**:

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

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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 :::

```json
{
  "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**:

```json
{
  "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:123456@192.168.10.115: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"
}
```

```javascript
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**:

```json
{
  "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ń." |

```javascript
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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

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

## 4. Urządzenia stron trzecich — dostęp

### 4.1 Instrukcja dostępu

#### Dostęp do urządzenia

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2Fg39SAJlx8k3kQ1NVFPVo%2Fimage.png?alt=media&#x26;token=83139d82-f24e-4e7c-9e75-5062e004b050" alt=""><figcaption></figcaption></figure>

#### Dostęp bramy stron trzecich

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FaZyatnl9w26YKRwSW8Xd%2Fimage.png?alt=media&#x26;token=8b595f5e-37a0-42cd-8cd6-35f92fe6a7be" alt=""><figcaption></figcaption></figure>

#### 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**

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FrwPAhV6PWyBrb8NyzcTw%2Fimage.png?alt=media&#x26;token=035de399-91a4-4525-a475-097823197c3b" alt=""><figcaption></figcaption></figure>

**b. Dostęp bramy stron trzecich**

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FwEPrDBpBKGBOAtL7KbI9%2Fimage.png?alt=media&#x26;token=1b170644-f9cc-47b3-91b8-6a3710f6afa1" alt=""><figcaption></figcaption></figure>

### 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 `CapabilityObject`odsył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 :

```json
{
  "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:

```json
{
  "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 :

```json
{
  "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:**

```json
{
  "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 :

```json
{
  "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

```json
{
  "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:

```javascript
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:

```json
// 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:

```json
// 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          | **tagi**`object` \| 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:

```json
// 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:

```json
// 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:

```json
// 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:

```json
// 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

```json
// 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.

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FFbcZQSx9tkiFsPhFd5Bs%2Fimage.png?alt=media&#x26;token=503d3700-3236-4a96-86c4-42f59aa5ebc8" alt=""><figcaption></figcaption></figure>

#### 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.

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2Fdc7XkFrVPJSM4qelABE0%2Fimage.png?alt=media&#x26;token=58f3edf7-29bf-4709-888a-4bd52e908e0f" alt=""><figcaption></figcaption></figure>

#### 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.

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FUj8BveNMWDcBvMj8pcW1%2Fimage.png?alt=media&#x26;token=6ba23a8d-1bc6-4c72-8267-d359fcff6678" alt=""><figcaption></figcaption></figure>

#### 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:**： :::

```json
{
  "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:**： :::

```json
{
  "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:**： :::

```json
{
  "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:

```json
{
  "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:：

```json
{
    "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:：

```json
{
  "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:

```json
{
  "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:：

```json
{
    "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:：

```json
{
  "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:

```json
{
    "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:：

```json
{
    "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:：

```json
{
  "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:**： :::

```json
{
  "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.

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FBt2FrX78UIyKBkwhUqm8%2Fimage.png?alt=media&#x26;token=cc5844e7-662b-45cf-912a-de419ac13efe" alt=""><figcaption></figcaption></figure>

#### 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.

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2F7a1myMdJ8j33N03L4KBi%2Fimage.png?alt=media&#x26;token=9c7c1ba3-8d28-43f3-a145-05eaeb762691" alt=""><figcaption></figcaption></figure>

#### 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.

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FSub47oZd5irq2dDhLhrf%2Fimage.png?alt=media&#x26;token=c9080c5e-1b49-4b00-ab31-bf2337b49d35" alt=""><figcaption></figcaption></figure>

#### 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.

<figure><img src="https://2450271282-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCnF8kmk9yw3yiy2mRerq%2Fuploads%2FNAX4WVWWxGUwzz33BzHq%2Fimage.png?alt=media&#x26;token=05cacc3e-be1b-44c9-a009-ab83d860bcce" alt=""><figcaption></figcaption></figure>

### 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：

```json
{
  "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:

```json
{
  "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:

```json
{
  "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: \*\*

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

\*\*Przykład żądania: \*\*

```json
{
  "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: \*\*

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