# Desarrollador y guía de API

## 1. Comenzar a usar

### 1.1 Preparación

Paso 1. Asegúrese de que la pasarela esté encendida y funcione correctamente.

Paso 2. Asegúrese de que la pasarela y el PC estén conectados a la misma LAN. Luego ingrese la URL de CUBE en su navegador.&#x20;

Aviso: Si tiene varias pasarelas, puede obtener la dirección IP correspondiente para acceder a la pasarela especificada de las dos maneras que se indican a continuación.

1. Inicie sesión en su router inalámbrico y verifique la dirección IP de la pasarela en DHCP.
2. CUBE admite el descubrimiento local a través de mDNS.

### 1.2 Empezar

* Llame a la interfaz \[Access Token], y obtenga una respuesta de error que indique hacer clic en <**Hecho**>. Tenga en cuenta que después de presionar, el acceso a la interfaz es válido por no más de 5 minutos.

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

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

* Haga clic en <**Hecho**> y vuelva a llamar a la interfaz \[Access Token]. La respuesta es exitosa y se obtiene el token.

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

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

* Verifique el token. Llame a la interfaz \[Get Device List]. La respuesta es exitosa y se obtiene la lista de dispositivos.

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

// Respuesta
{
  "error": 0,
  "data": {
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "device name",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "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"
}
```

* Método para obtener el token de acceso de CUBE: después de llamar a la interfaz \[Access Token], el cuadro emergente global de la página de la consola web de CUBE solicita al usuario confirmar la adquisición de las credenciales para llamar a la interfaz.
* Nota: Si abre más de una página de la consola web de CUBE, el cuadro emergente de confirmación aparecerá en varias páginas de la consola web al mismo tiempo, y el cuadro emergente de las otras páginas se cerrará después de hacer clic en la confirmación en una de las páginas.

## 2. Concepto central

### 2.1 Dirección de la interfaz de desarrollo

La interfaz Web API de la pasarela tiene dos métodos de acceso (basado en IP o en nombre de dominio), por lo general la ruta raíz es /open-api/V2/rest/< módulo funcional específico >

// Acceso por IP http\:///open-api/V2/rest/bridge

// Acceso por nombre de dominio http\:///open-api/V2/rest/bridge

### 2.2 Categoría de visualización del dispositivo y capacidades

* \*\*Categoría de visualización del dispositivo (DisplayCategory). \*\*La categoría de visualización del dispositivo se usa para identificar categorías específicas (del dispositivo), como switch, plug, light, etc. **Esta información determinará el efecto de visualización de la interfaz de usuario del dispositivo en la pasarela**.
* \*\*Capacidad del dispositivo. \*\*La capacidad del dispositivo se usa para describir las subfunciones específicas del dispositivo. Por ejemplo, control de alimentación, control de brillo, control de temperatura de color, etc. **Un solo dispositivo puede soportar 1 o más capacidades**.
  * **capability:** Describe el nombre de la capacidad, que debe ser globalmente único y de tipo cadena. Varias palabras en inglés deben separarse por guiones ("-"). Por ejemplo: `"thermostat-target-setpoint"`.
  * **name:** Describe la categoría bajo la capacidad, también de tipo cadena. Varias palabras en inglés deben separarse por guiones ("-"). Por ejemplo: `"auto-mode"`, `"manual-mode"`.
  * **permission:** Describe los permisos asociados con la capacidad. El tipo es cadena, formateado en código binario 8421. Los ejemplos incluyen:
    * Controlable por dispositivo: `"1000"`
    * Configurable por dispositivo: `"0010"`
    * Controlable y configurable por dispositivo: `"1010"`
    * Controlable y que puede informar por dispositivo: `"1100"`

El significado de cada bit, de derecha a izquierda, es el siguiente: ⅰ. Bit 0: Permite consultar el dispositivo ⅱ. Bit 1: Permite configurar el dispositivo ⅲ. Bit 2: Permite que el dispositivo informe datos ⅳ. Bit 3: Permite controlar el dispositivo

```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:** Describe los elementos de configuración para la capacidad, que son de tipo objeto e incluyen una descripción de cada elemento de configuración. ⅰ. **key:** Describe el nombre del elemento de configuración, que es de tipo cadena. Varias palabras en inglés deben expresarse en camelCase. Por ejemplo: `"temperatureUnit"`. ⅱ. **value:** Describe el contenido del elemento de configuración. Las especificaciones concretas se detallan en la tabla a continuación.

| Atributo                | Tipo   | Opcional | Descripción                                              |
| ----------------------- | ------ | -------- | -------------------------------------------------------- |
| permission              | string | N        | Describe los permisos para el elemento de configuración. |
| **Valores opcionales:** |        |          |                                                          |

* Permitir la modificación de este elemento de configuración: `"10"`
* Permitir la visualización de este elemento de configuración: `"01"`
* Permitir tanto la modificación como la visualización de este elemento de configuración: `"11"`

**Explicación de los bits:**

1. **Bit 0:** Permite la visualización de este elemento de configuración
2. **Bit 1:** Permite la modificación de este elemento de configuración | | tipo | string | N | Describe el tipo de datos del valor del elemento de configuración. **Valores opcionales:**

* `"enum"`
* `"numeric"`
* `"object"`
* `"boolean"`
* `"string"`

**Directrices específicas por tipo:**

1. **Cuando `**type = enum**`:**
   * El `campo` value (que describe el valor del elemento de configuración) es obligatorio si `permission` permite la modificación (`"10"` o `"11"`).
   * El `default` (que describe el valor predeterminado del elemento de configuración) y `values` (que describe los valores seleccionables para el elemento de configuración) los campos son opcionales.
2. **Cuando `**type = numeric**`:**
   * El `campo` el campo es obligatorio si `permission` permite la modificación (`"10"` o `"11"`).
   * Los siguientes campos son opcionales:
     * `min` (que describe el valor mínimo del elemento de configuración)
     * `max` (que describe el valor máximo del elemento de configuración)
     * `step` (que describe el valor de paso para el elemento de configuración)
     * `precision` (que describe la precisión)
     * `unit` (que describe la unidad del elemento de configuración)
     * `default` (que describe el valor predeterminado)
3. **Cuando `**type = object**`:**
   * El `campo` el campo es obligatorio si `permission` permite la modificación (`"10"` o `"11"`).
   * El `default` el campo es opcional.
4. **Cuando `**type = boolean**`:**
   * El `campo` el campo es obligatorio si `permission` permite la modificación (`"10"` o `"11"`).
   * El `default` el campo es opcional.
5. **Cuando `**type = string**`:**
   * El `campo` el campo es obligatorio si `permission` permite la modificación (`"10"` o `"11"`).
   * El `default` el campo es opcional. |

```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. API Web

### Tipo de datos

| Tipo      | Descripción                                                                                                                                                                                   |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| string    | Tipo de dato string. Codificado en UTF8.                                                                                                                                                      |
| number    | Tipo de dato numérico. [formato binario de doble precisión de 64 bits IEEE 754](https://en.wikipedia.org/wiki/Double-precision_floating-point_format)                                         |
| int       | Tipo de dato entero.                                                                                                                                                                          |
| object    | Tipo de dato objeto. Objeto compatible con JSON                                                                                                                                               |
| string\[] | Arreglo de strings                                                                                                                                                                            |
| int\[]    | Arreglo de enteros                                                                                                                                                                            |
| object\[] | Arreglo de objetos                                                                                                                                                                            |
| bool      | Booleano                                                                                                                                                                                      |
| date      | Cadena de tiempo. Cadena en formato ISO (Formato extendido ISO 8601): YYYY-MM-DDTHH:mm:ss.sssZ. La zona horaria siempre es UTC (Tiempo Universal Coordinado), identificada por el sufijo "Z". |

### Resultados genéricos de la respuesta

| Atributo                                                                                           | Tipo   | Opcional | Descripción                     |
| -------------------------------------------------------------------------------------------------- | ------ | -------- | ------------------------------- |
| error                                                                                              | int    | N        | Código de error:                |
| 0: Éxito                                                                                           |        |          |                                 |
| 400: Error de parámetro                                                                            |        |          |                                 |
| 401: Autenticación fallida                                                                         |        |          |                                 |
| 500: Excepción del servidor                                                                        |        |          |                                 |
| data                                                                                               | object | N        | Cuerpo de datos de la respuesta |
| message                                                                                            | string | N        | Descripción de la respuesta:    |
| Cuando error es igual a 0, el contenido es success                                                 |        |          |                                 |
| Cuando error no es igual a 0, es una cadena no vacía, y el contenido es una descripción del error. |        |          |                                 |

**Ejemplo de respuesta**:

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

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

### Lista de recursos

| Tipo                | Descripción                   |
| ------------------- | ----------------------------- |
| Sonidos compatibles | - alert1 (Sonido de alarma 1) |

* alert2 (Sonido de alarma 2)
* alert3 (Sonido de alarma 3)
* alert4 (Sonido de alarma 4)
* alert5 (Sonido de alarma 5)
* doorbell1 (Sonido de timbre 1)
* doorbell2 (Sonido de timbre 2)
* doorbell3 (Sonido de timbre 3)
* doorbell4 (Sonido de timbre 4)
* doorbell5 (Sonido de timbre 5)
* alarm1 (Sonido de alarma 1)
* alarm2 (Sonido de alarma 2)
* alarm3 (Sonido de alarma 3)
* alarm4 (Sonido de alarma 4)
* alarm5 (Sonido de alarma 5) | | Deep compatibles | - bootComplete (Inicio del sistema completado)
* networkConnected (Red conectada)
* networkDisconnected (Red desconectada)
* systemShutdown (Apagado del sistema) -deviceDiscovered (Descubrir dispositivo)
* system Armed (Sistema armado habilitado)
* system Disarmed (Sistema armado deshabilitado)
* factoryReset (Restablecer dispositivo) |

### 3.1 Función de la pasarela

#### a. Token de acceso

Permitir a los usuarios obtener el token de acceso.

* Aviso: El token se borrará después del restablecimiento del dispositivo.
* Aviso: Después de obtener el token, debe volver a presionar el botón para obtener con éxito un nuevo token.

:::consejos

* **URL**：`/open-api/V2/rest/bridge/access_token`
* **Método**：`GET`
* **Encabezado**：
  * Content-Type: application/json ::: Parámetros de la solicitud:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                          |
| ------------ | -------- | ------------ | ---------------------------------------- |
| app\_name    | string   | Y            | Descripción del nombre de la aplicación. |

Respuesta de datos exitosa:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                   |
| ------------ | -------- | ------------ | --------------------------------------------------------------------------------- |
| token        | string   | N            | El token de acceso de la interfaz. Es válido por mucho tiempo, por favor guárdelo |
| app\_name    | string   | Y            | Descripción del nombre de la aplicación.                                          |

:::consejos **Condición**: El usuario activa la < tecla de comando > y accede a esta interfaz dentro del tiempo válido. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

Respuesta de datos de falla：Objeto vacío :::consejos **Condiciones**：El usuario no ha activado la < tecla de comando >, o el tiempo válido ha expirado. \*\*Código de estado: \*\* `200 OK` ::: **Ejemplo de respuesta**:

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

#### b. Obtener el estado de la pasarela

Permitir a los usuarios autorizados obtener el estado de la pasarela mediante esta interfaz :::consejos

* **URL**：`/open-api/V2/rest/bridge/runtime`
* **Método**：`GET`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa:

| **Atributo**                                                                          | **Tipo** | **Opcional** | **Descripción**                    |
| ------------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------- |
| ram\_used                                                                             | int      | N            | Porcentaje de uso de RAM. \[0-100] |
| cpu\_used                                                                             | int      | N            | Porcentaje de uso de CPU. \[0-100] |
| power\_up\_time                                                                       | date     | N            | Última hora de encendido           |
| cpu\_temp                                                                             | int      | N            | Temperatura de la CPU:             |
| Unidad: Celsius                                                                       |          |              |                                    |
| cpu\_temp\_unit                                                                       | string   | N            | Unidad de temperatura de la CPU:   |
| Opcional                                                                              |          |              |                                    |
| valores:`'c'`, `'f'`                                                                  |          |              |                                    |
| sd\_card\_used                                                                        | int      | Y            | Uso de la tarjeta SD (porcentaje): |
| Rango:`[0-100]` con una precisión de un decimal                                       |          |              |                                    |
| \*Nota: Si la tarjeta SD no está insertada o no está formateada, el valor está vacío. |          |              |                                    |

:::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

```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. Configurar la pasarela

Permitir a los usuarios autorizados configurar la pasarela mediante esta interfaz :::consejos

* **URL**：`/open-api/V2/rest/bridge/config`
* **Método**：`PUT`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**               |
| ------------ | -------- | ------------ | ----------------------------- |
| volume       | int      | Y            | Volumen del sistema. \[0-100] |

Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

#### d. Obtener la información de la pasarela

Permitir a los usuarios autorizados obtener la información de la pasarela mediante esta interfaz :::consejos

* **URL**：`/open-api/V2/rest/bridge`
* **Método**：`GET`
* **Encabezado**：
  * Content-Type: application/json ::: Parámetros de la solicitud:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                     |
| ------------ | -------- | ------------ | ----------------------------------- |
| ip           | string   | N            | dirección ip                        |
| mac          | string   | N            | dirección mac                       |
| domain       | string   | Y            | Dominio del servicio de la pasarela |
| fw\_version  | string   | N            | Versión del firmware                |
| name         | string   | N            | Nombre del dispositivo              |

Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Ninguno \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

```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. Silenciar la pasarela

Permite a los usuarios autorizados silenciar la pasarela mediante esta interfaz. :::consejos

* **URL**：`/open-api/v2/rest/bridge/mute`
* **Método**：`PUT`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

#### f. Quitar silencio de la pasarela

Permite a los usuarios autorizados quitar el silencio de la pasarela mediante esta interfaz.\
:::consejos

* **URL**：`/open-api/v2/rest/bridge/unmute`
* **Método**：`PUT`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

#### g. Cancelar la alarma de la pasarela

Permite a los usuarios autorizados desactivar el estado de sonido de alarma en la pasarela mediante esta interfaz. :::consejos

* **URL**：`/open-api/v2/rest/bridge/cancel_alarm`
* **Método**：`PUT`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

### 3.2 Función de hardware

#### a. Reiniciar la pasarela

Permitir a un usuario autorizado reiniciar la pasarela mediante esta interfaz :::consejos

* **URL**：`/open-api/V2/rest/hardware/reboot`
* **Método**：`POST`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK :::

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

#### b. Control del altavoz

Permitir a los usuarios autorizados controlar el altavoz mediante esta interfaz :::consejos

* **URL**：`/open-api/V2/rest/hardware/speaker`
* **Método**：`POST`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud:

| **Atributo** | **Tipo**    | **Opcional**                  | **Descripción**                                                                                 |
| ------------ | ----------- | ----------------------------- | ----------------------------------------------------------------------------------------------- |
| type         | string      | N                             | Parámetros opcionales: 1.play\_sound (reproducir el sonido) 2.play\_beep (reproducir el pitido) |
| sound        | SoundObject | Y (N si type es play\_sound.) | El sonido.                                                                                      |
| beep         | BeepObject  | Y (N si type es play\_beep.)  | El pitido                                                                                       |

SoundObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                                                                                           |
| ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name         | string   | N            | El nombre del sonido. Los valores compatibles se pueden consultar en \[Resource List - Supported sound]                                                   |
| volume       | int      | N            | El volumen del sonido. \[0-100]                                                                                                                           |
| countdown    | int      | N            | La duración durante la cual el altavoz reproducirá el sonido, y dejará de reproducir automáticamente cuando termine el tiempo. Unidad: segundo. \[0,1799] |

BeepObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                                     |
| ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------- |
| name         | string   | N            | El nombre de deep. Los valores compatibles se pueden consultar en \[Resource List - Supported deep] |
| volume       | int      | N            | El volumen de deep. \[0-100]                                                                        |

Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\* `200 OK` ::: **Ejemplo de respuesta**:

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

### 3.3 Función de gestión de dispositivos

#### a. Tipo de dispositivo compatible

| **Tipo de dispositivo**         | **Valor**                    | Versión iHost |
| ------------------------------- | ---------------------------- | ------------- |
| Enchufe                         | plug                         | ≥ 2.1.0       |
| Interruptor                     | switch                       | ≥ 2.1.0       |
| Luz                             | light                        | ≥ 2.1.0       |
| Cortina                         | curtain                      | ≥ 2.1.0       |
| Sensor de puerta/ventana        | contactSensor                | ≥ 2.1.0       |
| Sensor de movimiento            | motionSensor                 | ≥ 2.1.0       |
| Sensor de temperatura           | temperatureSensor            | ≥ 2.1.0       |
| Sensor de humedad               | humiditySensor               | ≥ 2.1.0       |
| Sensor de temperatura y humedad | temperatureAndHumiditySensor | ≥ 2.1.0       |
| Detector de fugas de agua       | waterLeakDetector            | ≥ 2.1.0       |
| Detector de humo                | smokeDetector                | ≥ 2.1.0       |
| Botón inalámbrico               | button                       | ≥ 2.1.0       |
| Cámara                          | camera                       | ≥ 2.1.0       |
| Sensor general                  | sensor                       | ≥ 2.1.0       |
| Sensor general                  | sensor                       | ≥ 2.1.0       |
| Luz de ventilador               | fanLight                     | ≥ 2.1.0       |
| Aire acondicionado              | airConditioner               | ≥ 2.1.0       |
| Ventilador                      | fan                          | ≥ 2.1.0       |
| Termostato                      | thermostat                   | ≥ 2.1.0       |

#### b. Capacidades de Dispositivo Soportadas

**Interruptor de alimentación (power):**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "power", // Nombre de la capacidad
    "permission": "1100",  // ihost no admite configurar arranque/parada suaves, por lo tanto no hay campo configure
  }
]
```

**Atributo de Estado:**

```
{
  "powerState": "on", // El campo powerState indica el estado de encendido/apagado. Requerido. **Tipo:** string. "on" indica encendido, "off" indica apagado, "toggle" indica alternar.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

**Encender:**

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

**Apagar:**

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

**Interruptor de Canal (toggle):**

**Ejemplo de Declaración de Capacidad:**

Ejemplo de Componente Único:

```
[
  {
    "capability": "toggle", // Nombre de la capacidad
    "permission": "1100",  // Permiso
    "name": "1", // Nombre del componente, **Tipo:** String. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4), u otros valores que contengan letras mayúsculas y minúsculas y números
  }
]
```

Ejemplo de Componentes Múltiples:

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

**Atributo de Estado:**

```
{
  "toggleState": "on", // El campo toggleState indica el estado de alternancia del atributo {name} del {device_id}. Requerido. **Tipo:** String. "on" indica habilitado, "off" indica deshabilitado, "toggle" indica alternar.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Formato de Alternancia:

```
{
  [capability]: {
    [toggle-name]: {
      [toggleState]: [value]
    }
  }
}
Componente 1 Encendido, Componente 2 Apagado:
{
  "toggle": {
    "1": {
      "toggleState": "on"
    },
    "2": {
      "toggleState": "off"
    }
  }
}
```

**Inchamiento de Canal (toggle-inching):**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "toggle-inching", // Nombre de la capacidad
    "permission": "0010",  // Permiso
    "settings": {
      "toggleInchingSetting": {
        "permission": "11",
        "type": "object",
        "value": {
          "supported": {
            "1": { // Nombre del componente
              "enable": true, // Si la función de inching está habilitada. **Tipo:** Boolean. Requerido.
              "inchingSwitch": "off", // Ajuste del interruptor de inching. **Tipo:** String. Requerido. "off" (apagado), "on" (encendido)
              "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Requerido.
              "min_delay": 500, // Tiempo mínimo de retardo
              "max_delay": 100000 // Tiempo máximo de retardo
            },
            "2": { // Nombre del componente
              "enable": true, // Si la función de inching está habilitada. **Tipo:** Boolean. Requerido.
              "inchingSwitch": "off", // Ajuste del interruptor de inching. **Tipo:** String. Requerido. "off" (apagado), "on" (encendido)
              "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Requerido.
              "min_delay": 500, // Tiempo mínimo de retardo
              "max_delay": 100000 // Tiempo máximo de retardo
            },
            "3": { // Nombre del componente
              "enable": true, // Si la función de inching está habilitada. **Tipo:** Boolean. Requerido.
              "inchingSwitch": "off", // Ajuste del interruptor de inching. **Tipo:** String. Requerido. "off" (apagado), "on" (encendido)
              "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Requerido.
              "min_delay": 500, // Tiempo mínimo de retardo
              "max_delay": 100000 // Tiempo máximo de retardo
            },
            "4": { // Nombre del componente
              "enable": true, // Si la función de inching está habilitada. **Tipo:** Boolean. Requerido.
              "inchingSwitch": "off", // Ajuste del interruptor de inching. **Tipo:** String. Requerido. "off" (apagado), "on" (encendido)
              "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Requerido.
              "min_delay": 500, // Tiempo mínimo de retardo
              "max_delay": 100000 // Tiempo máximo de retardo
            }
          }
        }
      }
    }
  }
]
```

**Atributo de Estado**

Ninguno

**Protocolo (Consulta de Estado e Instrucciones de Control)**

Ninguno

**Ajuste de Brillo (brightness):**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "brightness", // Nombre de la capacidad
  "permission": "1100"  // Permiso
}
```

**Atributo de Estado:**

```
{
  "brightness": 100, // El campo brightness indica el porcentaje de brillo. Elija entre brightness o brightnessDelta. **Tipo:** Number. Rango: 0-100.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Establecer brillo al 80%. (0 es el más oscuro y 100 es el más claro.)

```
json
copiar código
{
  "brightness": {
    "brightness": 80
  }
}
```

**Ajuste de Temperatura de Color (color-temperature):**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "color-temperature", // Nombre de la capacidad
  "permission": "1100"  // Permiso
}
```

**Atributo de Estado:**

```
{
  "colorTemperature": 100, // El campo colorTemperature indica el porcentaje de temperatura de color. Elija entre colorTemperature o colorTemperatureDelta. **Tipo:** Number. Rango: 0-100. 0 indica luz cálida, 50 indica luz neutra, 100 indica luz fría.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Ajustar la temperatura de color al 50%:

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

**Ajuste de Color (color-rgb):**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "color-rgb", // Nombre de la capacidad
  "permission": "1100"  // Permiso
}
```

**Atributo de Estado:**

```
{
  "red": 255, // El campo red representa el rojo en el espacio de color RGB. Requerido. **Tipo:** Number. Rango: 0-255.
  "green": 0, // El campo green representa el verde en el espacio de color RGB. Requerido. **Tipo:** Number. Rango: 0-255.
  "blue": 255 // El campo blue representa el azul en el espacio de color RGB. Requerido. **Tipo:** Number. Rango: 0-255.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Establecer color a púrpura:

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

**Ajuste Porcentual (percentage):**

**Ejemplo de Declaración de Capacidad:**

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

**Atributo de Estado:**

```
{
  "percentage": 100, // El campo percentage indica un valor porcentual. Elija entre percentage o percentageDelta. **Tipo:** Number. Rango: 0-100.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Ajustar al 40%:

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

**Control de Motor (motor-control):**

**Ejemplo de Declaración de Capacidad:**

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

**Atributo de Estado:**

```
json
 
{
  "motorControl": "stop", // El campo motorControl indica el estado del motor. Requerido. **Tipo:** String. Valores posibles: "open" (abrir), "close" (cerrar), "stop" (detener), "lock" (bloquear).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Abrir Motor:

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

**Inversión de Motor (motor-reverse):**

**Ejemplo de Declaración de Capacidad:**

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

**Atributo de Estado:**

```
{
  "motorReverse": true, // El campo motorReverse indica la configuración de dirección del motor. Requerido. **Tipo:** Boolean. true indica avance, false indica reversa.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Configurar Motor a Avance:

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

**Calibración de Motor (motor-clb)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "motorClb": "calibration" // El campo motorClb indica el estado de calibración del motor. Requerido. **Tipo:** String. "normal" indica modo normal (calibrado), "calibration" indica calibración en curso.
}
```

**Protocolo (Reporte de Estado):**

Informar que el Estado del Motor está en Calibración:

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

**Estado al Encender (startup)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "startup": "on" // Estado de energía al iniciar. **Tipo:** String. Requerido. Valores opcionales: "on" (encendido), "stay" (mantener encendido), "off" (apagado), "toggle" (invertir estado de energía).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Establecer Estado de Energía Siempre Encendido:

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

***

**Activación de Despertar (identify)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "identify": true // Indica si el dispositivo informa activamente resultados de reconocimiento o está activado.
}
```

**Protocolo (Reporte de Estado e Instrucciones de Control):**

Establecer Tiempo de Activación de Despertar:

```
{
  "identify": {
    "countdown": 180 // El campo countdown indica el tiempo de cuenta regresiva. Requerido. **Tipo:** Number. Unidad: segundos.
  }
}
```

Informar Estado de Activación:

```
{
  "identify": {
    "identify": true // Indica si el dispositivo informa activamente resultados de reconocimiento o está activado.
  }
}
```

**Interruptor de Estadísticas de Consumo Eléctrico en Tiempo Real (power-consumption)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

Iniciar/Detener Estadísticas en Tiempo Real:

```
{
  "rlSummarize": true, // Iniciar/detener estadísticas en tiempo real. **Tipo:** Boolean. Requerido.
  "timeRange": { // Rango de tiempo resumido. Requerido.
    "start": "2020-07-05T08:00:00Z", // Hora de inicio de las estadísticas de consumo de energía. **Tipo:** String. Requerido.
    "end": "2020-07-05T09:00:00Z" // Hora de fin de las estadísticas de consumo de energía. **Tipo:** String. Requerido.
  }
}
```

Consultar Consumo de Energía por Rango de Tiempo:

```
{
  "type": "summarize", // Tipo de estadísticas. **Tipo:** String. Requerido. Valores opcionales: "rlSummarize" (resumen en tiempo real), "summarize" (resumen actual).
  "timeRange": { // Rango de tiempo resumido. Requerido si type es "summarize".
    "start": "2020-07-05T08:00:00Z", // Hora de inicio de las estadísticas de consumo de energía. **Tipo:** String. Requerido.
    "end": "2020-07-05T09:00:00Z" // Hora de fin de las estadísticas de consumo de energía. **Tipo:** String. Opcional. Si se omite, indica la hora actual.
  }
}
```

Responder con Resultado de Estadísticas dentro del Rango de Tiempo:

```
json
 
{
  "type": "summarize", // Tipo de estadísticas. **Tipo:** String. Requerido. Valores opcionales: "rlSummarize" (resumen en tiempo real), "summarize" (resumen actual).
  "rlSummarize": 50.0, // Consumo total de energía. **Tipo:** Number. Unidad: 0.01 kWh. Opcional.
  "electricityIntervals": [ // Múltiples registros de estadísticas divididos según configuration.resolution. Opcional. No presente cuando type es "rlSummarize".
    {
      "usage": 26.5, // Consumo de energía. **Tipo:** Number. Unidad: 0.01 kWh. Requerido.
      "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Date. Requerido.
      "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Date. Requerido. Si el intervalo entre end y start es menor que resolution, todos los registros informados se consideran inválidos.
    },
    {
      "usage": 26.5, // Consumo de energía. **Tipo:** Number. Unidad: 0.01 kWh. Requerido.
      "start": "2020-07-05T09:00:00Z", // Hora de inicio. **Tipo:** Date. Requerido.
      "end": "2020-07-05T10:00:00Z" // Hora de fin. **Tipo:** Date. Requerido. Si el intervalo entre end y start es menor que resolution, todos los registros informados se consideran inválidos.
    }
  ]
}
```

**Protocolo (Reporte de Estado e Instrucciones de Control):**

Iniciar Estadísticas en Tiempo Real:

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

Detener Estadísticas en Tiempo Real:

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

Obtener Consumo Histórico de Energía:

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

Obtener Consumo de Energía en Tiempo Real:

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

**Detección de Modo de Temperatura y Humedad (thermostat-mode-detect)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "temperature", // Tipo de detección de control de temperatura. **Tipo:** String. Requerido. Valores opcionales: "humidity" (detección de humedad), "temperature" (detección de temperatura).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Configuraciones de detección soportadas. Requerido.
          {
            "name": "lowerSetpoint", // El valor detectado debe estar por encima de este punto de ajuste. Se requiere al menos lowerSetpoint o upperSetpoint.
            "value": { // Rango de detección. Opcional. Especifique si existen condiciones preestablecidas.
              "value": 68.0, // Valor de temperatura. **Tipo:** Number. Requerido.
              "scale": "f" // Unidad de temperatura. Requerido cuando name=temperature. Valores opcionales: "c" (Celsius), "f" (Fahrenheit).
            }
          },
          {
            "name": "upperSetpoint", // El valor detectado debe estar por debajo de este punto de ajuste. Se requiere al menos lowerSetpoint o upperSetpoint.
            "value": { // Rango de detección. Opcional. Especifique si existen condiciones preestablecidas.
              "value": 68.0, // Valor de temperatura. **Tipo:** Number. Requerido.
              "scale": "f" // Unidad de temperatura. Requerido cuando name=temperature. Valores opcionales: "c" (Celsius), "f" (Fahrenheit).
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "humidity", // Tipo de detección de control de temperatura. **Tipo:** String. Requerido. Valores opcionales: "humidity" (detección de humedad), "temperature" (detección de temperatura).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Configuraciones de detección soportadas. Requerido.
          {
            "name": "lowerSetpoint", // El valor detectado debe estar por encima de este punto de ajuste. Se requiere al menos lowerSetpoint o upperSetpoint.
            "value": { // Rango de detección. Opcional. Especifique si existen condiciones preestablecidas.
              "value": 68.0, // Valor de humedad. **Tipo:** Number. Requerido
            }
          },
          {
            "name": "upperSetpoint", // El valor detectado debe estar por debajo de este punto de ajuste. Se requiere al menos lowerSetpoint o upperSetpoint.
            "value": { // Rango de detección. Opcional. Especifique si existen condiciones preestablecidas.
              "value": 68.0, // Valor de humedad. **Tipo:** Number. Requerido
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}
```

**Atributos (Estado):**

```
{
  "mode": "COMFORT" // ID del modo. Opcional. Valores compatibles: "COMFORT" (Modo Confort), "COLD" (Modo Frío), "HOT" (Modo Calor), "DRY" (Modo Seco), "WET" (Modo Húmedo).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Formato:

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

Ejemplo:

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

**Modo del Termostato (thermostat-mode)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "thermostatMode": "MANUAL" // Modo de funcionamiento del termostato. **Tipo:** String. Valores opcionales: "MANUAL", "AUTO", "ECO".
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Estado de Recuperación Adaptativa del Termostato (thermostat/adaptive-recovery-status)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "thermostat",
  "permission": "0100",
  "name": "adaptive-recovery-status" // Estado de recuperación adaptativa del termostato
}
```

**Atributos (Estado):**

```
{
  "adaptiveRecoveryStatus": "HEATING" // Estado de recuperación adaptativa del termostato. **Tipo:** String. Valores opcionales: "HEATING", "INACTIVE".
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Configuración de Temperatura Objetivo del Modo Termostato (thermostat-target-setpoint)**

**Ejemplo de Declaración de Capacidad:**

```
[[
  {
    "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, // Hora de inicio en minutos. **Tipo:** int. Ej.: 7:20 AM = 440 minutos.
            "upperSetpoint": 36.5, // Temperatura máxima objetivo. **Tipo:** number.
            "lowerSetpoint": 20 // Temperatura mínima objetivo. **Tipo:** number.
          },
          {
            "startTimeInMinutes": 900, // Hora de inicio en minutos. Ej.: 3:00 PM = 900 minutos.
            "upperSetpoint": 26.5, // Temperatura máxima objetivo. **Tipo:** number.
            "lowerSetpoint": 21 // Temperatura mínima objetivo. **Tipo:** number.
          }
        ],
          "Tuesday": [...
          ],
          "Wednesday": [...
          ],
          "Thursday": [...
          ],
          "Friday": [...
          ],
          "Saturday": [...
          ],
          "Sunday": [...
          ],
        }
      }
    }
  }
]
```

**Atributos (Estado):**

```
{
  "targetSetpoint": 30 // Temperatura objetivo para el modo especificado. **Tipo:** number, en la unidad especificada por temperatureUnit.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Sensor (detect)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "detected": true // Resultado de detección. **Tipo:** Boolean. `true` indica detección, `false` indica no detección.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Temperatura (temperature)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "temperature",
  "permission": "0110",
  "settings": { // Opcional
    "temperatureCalibration": { // Calibración de temperatura opcional
      "type": "numeric",
      "permission": "11",
      "min": -7, // Valor mínimo
      "max": 7, // Valor máximo
      "step": 0.2, // Paso de ajuste de temperatura, unidad igual a temperatureUnit
      "value": 5.2 // Valor actual de calibración de temperatura. **Tipo:** number.
    },
    "temperatureUnit": { // Unidad de temperatura opcional
      "type": "enum",
      "permission": "11",
      "value": "c",
      "values": [
        "c",
        "f"
      ]
    },
    "temperatureRange": { // Rango de detección de temperatura opcional
      "type": "numeric",
      "permission": "01",
      "min": -40,
      "max": 80
    }
  }
}
```

**Atributos (Estado):**

```
json
copiar código
{
  "temperature": 26.5 // Temperatura actual. **Tipo:** Number, en Celsius.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Humedad (humidity)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "humidity",
  "permission": "0100",
  "settings": { // Rango de detección de humedad opcional.
    "humidityRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 100
    }
  }
}
```

**Atributos (Estado):**

```
{
  "humidity": 50 // Humedad relativa actual (porcentaje). **Tipo:** Number, rango 0-100.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Batería (battery)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "battery": 95 // Porcentaje de batería restante. **Tipo:** Number, rango -1 a 100. Nota: -1 indica nivel de batería desconocido.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Botón Único (press)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "press",
  "permission": "1100",
  "settings": { // Opcional
    "actions": { // Acciones del botón, opcional.
      "type": "enum",
      "permission": "01",
      "values": [ // Acciones de botón opcionales. Los valores predeterminados son "singlePress", "doublePress", "longPress". Las acciones configuradas reemplazan los valores predeterminados.
      ]
    }
  }
}
```

**Atributos (Estado):**

```
{
  "press": "singlePress" // Tipo de pulsación del botón. **Tipo:** String. Valores estándar: "singlePress" (pulsación simple o corta), "doublePress" (pulsación doble), "longPress" (pulsación larga).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Multibotón (multi-press)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "multi-press",
  "permission": "0100",
  "name": "1", // Nombre del atributo multi-press. **Tipo:** String. Solo se permiten caracteres alfanuméricos.
  "settings": { // Opcional
    "actions": { // Acciones del botón, opcional.
      "type": "enum",
      "permission": "01",
      "values": [ // Acciones de botón opcionales. Los valores predeterminados son "singlePress", "doublePress", "longPress". Las acciones configuradas reemplazan los valores predeterminados.
      ]
    }
  }
}
```

**Atributos (Estado):**

```
{
  "press": "singlePress" // Tipo de pulsación del botón. **Tipo:** String. Valores estándar: "singlePress" (pulsación simple o corta), "doublePress" (pulsación doble), "longPress" (pulsación larga).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

ejemplo:
{
  "multi-press": {
    "1": {
      "press": "singlePress"
    },
    "2": {
      "press": "doublePress"
    }
  }
}
```

**Detección de Intensidad de Señal (rssi)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "rssi": -65 // Intensidad de señal inalámbrica (Indicador de Intensidad de Señal Recibida). **Tipo:** Number, unidad dBm, valores enteros negativos.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Manipulación (tamper-alert)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "tamper": "clear" // Estado de manipulación. **Tipo:** String. Valores posibles: "clear" (no manipulado), "detected" (manipulado).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

```
{
  "tamper-alert": {
    "tamper": "clear" // Estado de manipulación. **Tipo:** String. Valores posibles: "clear" (no manipulado), "detected" (manipulado).
  }
}
```

**Detección de Nivel de Iluminación (illumination-level)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "level": "brighter" // Nivel de brillo. **Tipo:** String. Valores posibles: "brighter" (más brillante), "darker" (más oscuro).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Voltaje (voltage)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "voltage": 50 // Valor de voltaje actual, en unidades de 0.01V. **Tipo:** Number, valores no negativos.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Corriente Eléctrica (electric-current)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "electric-current": 50 // Valor de corriente actual, en unidades de 0.01A. **Tipo:** Number, valores enteros no negativos.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Potencia Eléctrica (electric-power)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "electric-power": 50 // Valor de potencia actual, en unidades de 0.01W. **Tipo:** Number, valores enteros no negativos.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Fallas (fault)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "fault": "none" // Estado de falla. **Tipo:** String. Valores posibles: "none" (sin falla), "detected" (falla detectada).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Interruptor de Umbral (threshold-breaker)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "threshold-breaker",
  "permission": "0010",
  "settings": {
    "supportedSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "supported": [
          {
            "name": "lowerPower", // Interruptor de umbral de baja potencia
            "value": {
              "value": 50, // Valor de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0.
              "min_range": 10, // Valor mínimo de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0.
              "max_range": 3500 // Valor máximo de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0.
            }
          },
          {
            "name": "upperPower", // Interruptor de umbral de alta potencia
            "value": {
              "value": 50, // Valor de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0.
              "min_range": 10, // Valor mínimo de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0.
              "max_range": 3500 // Valor máximo de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0.
            }
          },
          {
            "name": "lowerElectricCurrent", // Interruptor de umbral de baja corriente
            "value": {
              "value": 50, // Valor de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0.
              "min_range": 10, // Valor mínimo de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0.
              "max_range": 1500 // Valor máximo de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0.
            }
          },
          {
            "name": "upperElectricCurrent", // Interruptor de umbral de alta corriente
            "value": {
              "value": 50, // Valor de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0.
              "min_range": 10, // Valor mínimo de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0.
              "max_range": 1500 // Valor máximo de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0.
            }
          },
          {
            "name": "lowerVoltage", // Interruptor de umbral de bajo voltaje
            "value": {
              "value": 50, // Valor de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0.
              "min_range": 10, // Valor mínimo de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0.
              "max_range": 24000 // Valor máximo de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0.
            }
          },
          {
            "name": "upperVoltage", // Interruptor de umbral de alto voltaje
            "value": {
              "value": 50, // Valor de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0.
              "min_range": 10, // Valor mínimo de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0.
              "max_range": 24000 // Valor máximo de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0.
            }
          }
        ]
      }
    }
  }
}
```

**Atributos (Estado)**

* Ninguno

**Protocolo (Consulta de Estado e Instrucciones de Control)**

* Ninguno

**Función Inch (inching)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "inching",
  "permission": "0010",
  "settings": {
    "inchingEnable": { // Ajuste de habilitación de la función inch
      "permission": "11",
      "type": "boolean",
      "value": false
    },
    "inchingSwitch": { // Ajuste de acción de inch
      "type": "enum",
      "permission": "11",
      "value": "on",
      "values": ["on", "off"]
    },
    "inchingDelay": { // Ajuste de tiempo de inch
      "type": "numeric",
      "permission": "11",
      "min": 500,
      "max": 100000,
      "value": 1000,
      "unit": "ms"
    }
  }
}
```

**Atributos (Estado):**

* Ninguno

**Protocolo (Consulta de Estado e Instrucciones de Control):**

* Ninguno

**Transmisión de Cámara (camera-stream)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "camera-stream",
  "permission": "0010",
  "settings": {
    "streamSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "username": "String", // Cuenta de acceso. **Tipo:** String. Requerido.
        "password": "String", // Contraseña de acceso. **Tipo:** String. Requerido.
        "streamUrl": "rtsp://<username>:<password>@<hostname>:<port>/streaming/channel01", // URL de transmisión. **Tipo:** String. Requerido.
        "videoCodec": "", // Códec de video. **Tipo:** String. Requerido. Parámetros opcionales por definir.
        "resolution": { // Resolución de video. Requerido.
          "width": 1080, // Ancho. **Tipo:** Number. Requerido.
          "height": 720 // Alto. **Tipo:** Number. Requerido.
        },
        "keyFrameInterval": 5, // Intervalo de fotogramas clave. **Tipo:** String. Requerido.
        "audioCodec": "G711", // Códec de audio. **Tipo:** String. Requerido. Parámetros opcionales por definir.
        "samplingRate": 50, // Frecuencia de muestreo de audio, en Hz. **Tipo:** Number. Requerido. Parámetros opcionales por definir.
        "dataRate": 50 // Tasa de bits. **Tipo:** Number. Requerido. Unidad: kb/s.
      }
    }
  }
}
```

**Atributos (Estado):**

* Ninguno

**Protocolo (Consulta de Estado e Instrucciones de Control):**

* Ninguno

**Control de Modo (mode)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "mode",
    "name": "fanLevel",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["low", "medium", "high"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados.
      }
    }
  },
  {
    "capability": "mode",
    "name": "thermostatMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["auto", "manual"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados.
      }
    }
  },
  {
    "capability": "mode",
    "name": "airConditionerMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["cool", "heat", "auto", "fan", "dry"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados.
      }
    }
  },
  {
    "capability": "mode",
    "name": "fanMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["normal", "sleep", "child"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados.
      }
    }
  },
  {
    "capability": "mode",
    "name": "horizontalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados.
      }
    }
  },
  {
    "capability": "mode",
    "name": "verticalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados.
      }
    }
  }
]
```

**Atributos (Estado):**

```
{
  "modeValue": "low" // Valor del modo. **Tipo:** String. Requerido. Consulte los modos preestablecidos compatibles.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Dióxido de Carbono (co2)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "co2": 111 // Concentración de dióxido de carbono. **Tipo:** Integer. Unidad: ppm.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Iluminación (illumination)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "illumination": 11 // Nivel de iluminación. **Tipo:** Integer. Unidad: lux.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de Humo (smoke)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "smoke": true // Resultado de detección. **Tipo:** Boolean. `true` indica detección, `false` indica no detección.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de apertura/cierre por imán de puerta (contacto)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "contact": true // Resultado de la detección. **Tipo:** Booleano. `true` indica detección, `false` indica sin detección.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de movimiento (motion)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "motion": true // Resultado de la detección. **Tipo:** Booleano. `true` indica detección, `false` indica sin detección.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de fugas de agua (water-leak)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "waterLeak": true // El campo `waterLeak` indica el resultado actual de la detección. **Tipo:** Booleano. `true` indica detección, `false` indica sin detección.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Interruptor de detección de ventana (window-detection)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica encendido, `off` indica apagado.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Bloqueo infantil (child-lock)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica encendido, `off` indica apagado.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Interruptor anti-soplado directo (anti-direct-blow)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica encendido, `off` indica apagado.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Oscilación horizontal (horizontal-swing)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica encendido, `off` indica apagado.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Oscilación vertical (vertical-swing)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica encendido, `off` indica apagado.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Modo ECO (eco)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica encendido, `off` indica apagado.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Alternar inicio (toggle-startup)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "toggle-startup",
  "permission": "1100",
  "name": "1" // El campo `name` especifica el nombre del atributo para `toggle-startup`. **Tipo:** Cadena. Solo se permiten letras y números.
}
```

**Atributos (Estado):**

```
{
  "startup": "on" // **Tipo:** Cadena. Opciones: `on` (encender), `stay` (mantener encendido), `off` (apagar).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de retención (detect-hold)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "detect-hold",
  "permission": "0100",
  "settings": {
    "detectHoldEnable": { // Configuración de habilitación de detección de retención
      "permission": "01",
      "type": "boolean",
      "value": false
    },
    "detectHoldSwitch": { // Configuración de acción de detección de retención
      "type": "enum",
      "permission": "01",
      "value": "on",
      "values": ["on", "off"]
    },
    "detectHoldTime": { // Configuración del tiempo de detección de retención
      "type": "numeric",
      "permission": "01",
      "min": 1,
      "max": 359,
      "value": 5,
      "unit": "minute"
    }
  }
}
```

**Atributos (Estado):**

```
{
  "detectHold": "on" // El campo `detectHold` indica el estado de la retención de detección. **Tipo:** Cadena. `on` significa que la retención de detección está activa, `off` significa que está inactiva.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Alternar Identificar/Activar (toggle-identify)**

**Ejemplo de Declaración de Capacidad:**

```
{
  "capability": "toggle-identify",
  "permission": "1100", // Nota: Esta capacidad no se usa para reportes en la versión actual (V1.13.7) en ihost.
  "name": "1" // Nombre del componente. **Tipo:** Cadena. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4).
}
```

**Atributos (Estado):**

```
{
  "identify": true, // Indica que el dispositivo ha reportado activamente identificación o activación.
  "countdown": 180 // El campo `countdown` indica la duración de la activación. **Tipo:** Número. Unidad: segundos.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

```
{
  "toggle-identify": {
    "1": {
      "countdown": 180 // Activar el dispositivo durante 180 segundos.
    }
  }
}

// El dispositivo informa auto-activación
{
  "toggle-identify": {
    "1": {
      "identify": true
    }
  }
}
```

**Detección de voltaje alternable (toggle-voltage)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "voltage": 230 // El campo `voltage` indica el voltaje detectado. **Tipo:** Número. Unidad: Voltios.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de corriente eléctrica del subcomponente (toggle-electric-current)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "toggle-electric-current",
    "permission": "0100",
    "name": "1" // Nombre del componente. **Tipo:** Cadena. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4).
  }
]
```

**Atributos (Estado):**

```
{
  "electricCurrent": 50 // El campo `electricCurrent` representa el valor de corriente. **Unidad:** 0.01 A. **Tipo:** Entero. El valor debe ser mayor o igual a 0.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de potencia del subcomponente (toggle-electric-power)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "toggle-electric-power",
    "permission": "0100",
    "name": "1" // Nombre del componente. **Tipo:** Cadena. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4).
  }
]
```

**Atributos (Estado):**

```
{
  "electricPower": 50, // El campo `electricPower` representa el valor de potencia actual. **Unidad:** 0.01 W. **Tipo:** Entero. El valor debe ser mayor o igual a 0.
  "reactivePower": 50, // El campo `reactivePower` representa el valor de potencia reactiva actual. **Unidad:** 0.01 W. **Tipo:** Entero. Opcional.
  "activePower": 50, // El campo `activePower` representa el valor de potencia activa actual. **Unidad:** 0.01 W. **Tipo:** Entero. Opcional.
  "apparentPower": 50 // El campo `apparentPower` representa el valor de potencia aparente actual. **Unidad:** 0.01 W. **Tipo:** Entero. Opcional.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Estadísticas de consumo de energía del subcomponente (toggle-power-consumption)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "toggle-power-consumption",
    "permission": "1101",
    "name": "1", // Nombre del componente. **Tipo:** Cadena. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4).
    "settings": {
      "resolution": {
        "permission": "01",
        "type": "numeric",
        "value": 3600
      },
      "timeZoneOffset": {
        "permission": "01",
        "type": "numeric",
        "min": -12,
        "max": 14,
        "value": 0
      }
    }
  }
]
```

**Atributos (Estado):**

Iniciar/Detener Estadísticas en Tiempo Real:

```
{
  "rlSummarize": true, // Iniciar o detener estadísticas en tiempo real. **Tipo:** Booleano. Requerido.
  "timeRange": { // Rango de tiempo del resumen. Requerido.
    "start": "2020-07-05T08:00:00Z", // Hora de inicio del consumo de energía. **Tipo:** Cadena. Requerido.
    "end": "2020-07-05T09:00:00Z" // Hora de fin del consumo de energía. **Tipo:** Cadena. Requerido.
  }
}
```

Consultar Consumo de Energía por Rango de Tiempo:

```
{
  "type": "summarize", // Tipo de resumen. **Tipo:** Cadena. Requerido. Opciones: "rlSummarize" (Resumen en tiempo real), "summarize" (Resumen actual).
  "timeRange": { // Rango de tiempo del resumen, requerido cuando el tipo es "summarize".
    "start": "2020-07-05T08:00:00Z", // Hora de inicio del consumo de energía. **Tipo:** Cadena. Requerido.
    "end": "2020-07-05T09:00:00Z" // Hora de fin del consumo de energía. **Tipo:** Cadena. Opcional. Si no se proporciona, por defecto es la hora actual.
  }
}
```

Respuesta para consumo de energía dentro del rango de tiempo:

```
{
  "type": "summarize", // Tipo de resumen. **Tipo:** Cadena. Requerido.
  "rlSummarize": 50.0, // Consumo total de energía. **Unidad:** 0.01 kWh. **Tipo:** Número. Opcional.
  "electricityIntervals": [ // Dividido por `configuration.resolution` en varios registros. Opcional. No está presente cuando el tipo es "rlSummarize".
    {
      "usage": 26.5, // Consumo de energía. **Unidad:** 0.01 kWh. **Tipo:** Número. Requerido.
      "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Cadena. Requerido.
      "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Cadena. Requerido. Los registros con intervalos más cortos que la resolución se consideran inválidos.
    },
    {
      "usage": 26.5, // Consumo de energía. **Unidad:** 0.01 kWh. **Tipo:** Número. Requerido.
      "start": "2020-07-05T09:00:00Z", // Hora de inicio. **Tipo:** Cadena. Requerido.
      "end": "2020-07-05T10:00:00Z" // Hora de fin. **Tipo:** Cadena. Requerido. Los registros con intervalos más cortos que la resolución se consideran inválidos.
    }
  ]
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Iniciar Estadísticas en Tiempo Real:

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

Detener Estadísticas en Tiempo Real:

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

Obtener Consumo Histórico de Energía:

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

Obtener Consumo de Energía en Tiempo Real:

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

**Indicador de calidad de enlace (lqi)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "lqi": 60 // El campo `lqi` representa el indicador de calidad de enlace. **Tipo:** Número. Rango de valor: 0 a 255.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Configuración funcional (configuration)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "deviceConfiguration": { // Configuración funcional relacionada con el dispositivo
    "defaultResolution": 300, // Resolución predeterminada para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Requerido.
    "maxResolution": 86400, // Resolución máxima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Requerido.
    "minResolution": 60 // Resolución mínima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Requerido.
  }
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

```
{
  "configuration": {
    "deviceConfiguration": { // Configuración funcional relacionada con el dispositivo
      "defaultResolution": 300, // Resolución predeterminada para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Requerido.
      "maxResolution": 86400, // Resolución máxima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Requerido.
      "minResolution": 60 // Resolución mínima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Requerido.
    }
  }
}
```

**Sistema (system)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "restart": true // Comando de reinicio del dispositivo. **Tipo:** Booleano. Requerido. El valor debe ser `true`.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

```
{
  "system": { // Configuración relacionada con la capacidad. Opcional.
    "restart": true
  }
}
```

**Humedad (moisture)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "moisture": 55.5 // El campo `moisture` representa el porcentaje de saturación de humedad. **Tipo:** Número. Requerido. Rango: 0 a 100.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Presión barométrica (barometric-pressure)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "barometric-pressure",
    "permission": "0100",
    "settings": {
      "barometricPressureRange": {
        "type": "numeric",
        "permission": "01",
        "min": 540, // Valor mínimo. **Tipo:** Entero. Requerido. Debe ser menor que `max`.
        "max": 1100 // Valor máximo. **Tipo:** Entero. Requerido. Debe ser mayor que `min`.
      }
    }
  }
]
```

**Atributos (Estado):**

```
{
  "barometricPressure": 50 // Valor de presión barométrica. **Tipo:** Entero. Requerido. **Unidad:** hPa.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Velocidad del viento (wind-speed)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "wind-speed",
    "permission": "0100",
    "settings": {
      "windSpeedRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Valor mínimo. **Tipo:** Número. Requerido. Debe ser menor que `max`.
        "max": 50 // Valor máximo. **Tipo:** Número. Requerido. Debe ser mayor que `min`.
      }
    }
  }
]
```

**Atributos (Estado):**

```
{
  "windSpeed": 50 // Valor de la velocidad del viento. **Tipo:** Número. Requerido. **Unidad:** m/s (metros por segundo).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Dirección del viento (wind-direction)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "windDirection": 10 // Dirección del viento. **Tipo:** Entero. Requerido. **Unidad:** Grados. Rango: 0 a 360 grados (dirección en sentido horario).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Precipitación (rainfall)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "rainfall",
    "permission": "0100",
    "settings": {
      "rainfallRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Valor mínimo. **Tipo:** Número. Requerido. Debe ser menor que `max`.
        "max": 450 // Valor máximo. **Tipo:** Número. Requerido. Debe ser mayor que `min`.
      }
    }
  }
]
```

**Atributos (Estado):**

```
{
  "rainfall": 11.11 // Valor de precipitación. **Tipo:** Número. Requerido. **Unidad:** mm/h (milímetros por hora).
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Índice ultravioleta (ultraviolet-index)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "ultraviolet-index",
    "permission": "0100",
    "settings": {
      "ultravioletIndexRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Valor mínimo. **Tipo:** Número. Requerido. Debe ser menor que `max`.
        "max": 16 // Valor máximo. **Tipo:** Número. Requerido. Debe ser mayor que `min`.
      }
    }
  }
]
```

**Atributos (Estado):**

```
{
  "ultravioletIndex": 11.1 // Índice ultravioleta. **Tipo:** Número. Requerido.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Conductividad eléctrica (electrical-conductivity)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "electrical-conductivity",
    "permission": "0100",
    "settings": {
      "electricalConductivityRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Valor mínimo. **Tipo:** Número. Requerido. Debe ser menor que `max`.
        "max": 23 // Valor máximo. **Tipo:** Número. Requerido. Debe ser mayor que `min`.
      }
    }
  }
]
```

**Atributos (Estado):**

```
{
  "electricalConductivity": 11.11 // Valor de conductividad eléctrica. **Tipo:** Número. Requerido. **Unidad:** dS/m.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Potencia de transmisión (transmit-power)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "transmitPower": 9 // Valor de potencia de transmisión del dispositivo. **Tipo:** Entero. Requerido. **Unidad:** dBm.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección PM2.5 (pm25)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "pm25": 10 // Concentración de PM2.5 en el aire. **Tipo:** Número. Requerido. **Unidad:** µg/m³.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Índice VOC (voc-index)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "vocIndex": 10 // Índice VOC que refleja el nivel de contaminación por gases nocivos. **Tipo:** Número. Requerido. **Unidad:** µg/m³.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Detección de gas natural (gas)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "gas": true // Indica si se detecta fuga de gas natural. **Tipo:** Booleano. Requerido.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Estado de trabajo de riego (irrigation/work-status)**

**Ejemplo de Declaración de Capacidad:**

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

**Atributos (Estado):**

```
{
  "realTimeVolume": 20, // Volumen de riego en tiempo real. **Tipo:** Número. Opcional. **Unidad:** L.
  "start": "2020-07-05T08:00:00Z", // Hora de inicio del riego. **Tipo:** Fecha. Opcional.
  "end": "2020-07-05T09:00:00Z", // Hora de fin del riego. **Tipo:** Fecha. Opcional.
  "dailyVolume": 20 // Volumen de riego diario. **Tipo:** Número. Opcional. **Unidad:** L.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Reporte de estado de trabajo:

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

Consulta de estado de trabajo:

```
{
  "irrigation": {
    "type": "oneDay", // Tipo de agregación. **Tipo:** Cadena. Requerido. Opciones: "oneDay", "30Days", "180Days".
    "timeRange": { // Rango de tiempo para la agregación. **Tipo:** Objeto. Requerido.
      "start": "2020-07-05T08:00:00Z", // Hora de inicio para la agregación de datos de riego. **Tipo:** Cadena. Requerido.
      "end": "2020-07-05T09:00:00Z" // Hora de fin para la agregación de datos de riego. **Tipo:** Cadena. Opcional. Si se omite, se usa la hora actual.
    }
  }
}
```

Resultado de la consulta de estado de trabajo:

```
{
  "irrigation": {
    "type": "oneDay", // Tipo de agregación. **Tipo:** Cadena. Requerido.
    "irrigationIntervals": [
      {
        "volume": 6500, // Volumen de riego. **Tipo:** Número. Requerido. **Unidad:** L.
        "duration": 30, // Duración del riego. **Tipo:** Número. Requerido. **Unidad:** minutos.
        "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Cadena. Requerido.
        "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Cadena. Requerido.
      },
      {
        "volume": 6500, // Volumen de riego. **Tipo:** Número. Requerido. **Unidad:** L.
        "duration": 30, // Duración del riego. **Tipo:** Número. Requerido. **Unidad:** minutos.
        "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Cadena. Requerido.
        "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Cadena. Requerido.
      }
    ]
  }
}
```

**Modo de trabajo de riego (irrigation/work-mode)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "irrigation",
    "permission": "0100",
    "name": "work-mode",
    "settings": {
      "supportedModes": {
        "type": "enum",
        "permission": "01",
        "values": [
          "MANUAL", // Modo manual
          "TIMER", // Programación única por tiempo
          "CYCLE-TIMER", // Programación repetida
          "VOLUME", // Volumen único
          "CYCLE-VOLUME" // Volumen repetido
        ]
      }
    }
  }
]
```

**Atributos (Estado):**

```
{
  "workMode": "MANUAL" // Modo de trabajo de riego. **Tipo:** Cadena. Opcional. Los valores deben provenir de `settings.supportedModes`.
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

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

**Controlador automático de riego (irrigation/auto-controller)**

**Ejemplo de Declaración de Capacidad:**

```
[
  {
    "capability": "irrigation",
    "permission": "1100",
    "name": "auto-controller",
    "settings": {
      "volumeRange": { // Rango de volumen
        "type": "enum",
        "permission": "01",
        "min": 0,
        "max": 6500,
        "unit": "L"
      },
      "timeRange": { // Rango de tiempo
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 86400,
        "unit": "second"
      },
      "cycleCountRange": { // Rango de conteo de ciclos
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 100,
        "step": 1
      }
    }
  }
]
```

**Atributos (Estado):**

Programación única o repetida:

```
{
  "type": "time", // Modo de riego. **Tipo:** Cadena. Requerido. Opciones: "volume", "time".
  "action": {
    "perDuration": 60, // Duración por ciclo de riego. **Tipo:** Número. Requerido.
    "intervalDuration": 20, // Intervalo entre ciclos de riego. **Tipo:** Número. Requerido.
    "count": 3 // Número de ciclos de riego. **Tipo:** Número. Requerido.
  }
}
```

Volumen único o repetido:

```
{
  "type": "volume", // Modo de riego. **Tipo:** Cadena. Requerido. Opciones: "volume", "time".
  "action": {
    "perConsumedVolume": 60, // Volumen consumido por ciclo de riego. **Tipo:** Número. Requerido.
    "intervalDuration": 20, // Intervalo entre ciclos de riego. **Tipo:** Número. Requerido.
    "count": 3 // Número de ciclos de riego. **Tipo:** Número. Requerido.
  }
}
```

**Protocolo (Consulta de Estado e Instrucciones de Control):**

Programación única o repetida:

```
{
  "irrigation": {
    "auto-controller": {
      "type": "time", // Modo de riego. **Tipo:** Cadena. Requerido.
      "action": {
        "perDuration": 60, // Duración por ciclo de riego. **Tipo:** Número. Requerido.
        "intervalDuration": 20, // Intervalo entre ciclos. **Tipo:** Número. Requerido.
        "count": 3 // Número de ciclos. **Tipo:** Número. Requerido.
      }
    }
  }
}
```

Volumen único o repetido:

```
{
  "irrigation": {
    "auto-controller": {
      "type": "volume", // Modo de riego. **Tipo:** Cadena. Requerido.
      "action": {
        "perConsumedVolume": 60, // Volumen consumido por ciclo. **Tipo:** Número. Requerido.
        "intervalDuration": 20, // Intervalo entre ciclos. **Tipo:** Número. Requerido.
        "count": 3 // Número de ciclos. **Tipo:** Número. Requerido.
      }
    }
  }
}
```

**Modos preestablecidos compatibles**

| \*\*Nombres de modo \*\*                                   | \*\*Valores opcionales \*\* |
| ---------------------------------------------------------- | --------------------------- |
| fanLevel (nivel del ventilador)                            | "low"                       |
| "medium"                                                   |                             |
| "high"                                                     |                             |
| thermostatMode (Modo del termostato)                       | "auto"                      |
| "manual"                                                   |                             |
| airConditionerMode >= 1.11.0 (Modo del aire acondicionado) | "cool"                      |
| "heat"                                                     |                             |
| "auto"                                                     |                             |
| "fan"                                                      |                             |
| "dry"                                                      |                             |
| fanMode >= 1.11.0 (Modo del ventilador)                    | "normal"                    |
| "sleep"                                                    |                             |
| "child"                                                    |                             |
| horizontalAngle >= 1.11.0 (Ángulo horizontal)              | "30"                        |
| "60"                                                       |                             |
| "90"                                                       |                             |
| "120"                                                      |                             |
| "180"                                                      |                             |
| "360"                                                      |                             |
| verticalAngle >= 1.11.0 (Ángulo vertical)                  | "30"                        |
| "60"                                                       |                             |
| "90"                                                       |                             |
| "120"                                                      |                             |
| "180"                                                      |                             |
| "360"                                                      |                             |

#### c. Descripción de etiquetas

* La clave especial toggle se utiliza para establecer el nombre del subcomponente toggle.

```
{
    "toggle": {
        '1': 'Canal1',
        '2': 'Canal2',
        '3': 'Canal3',
        '4': 'Canal4',
    },
}
```

* La clave especial temperature\_unit se utiliza para establecer la unidad de temperatura.

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

#### d. Código de error especial y descripción

| **Código de error** | **Descripción**                                                                                              | Versión iHost |
| ------------------- | ------------------------------------------------------------------------------------------------------------ | ------------- |
| 110000              | El subdispositivo/grupo correspondiente al id no existe                                                      | ≥2.1.0        |
| 110001              | La pasarela está en estado de descubrimiento de dispositivos zigbee                                          | ≥2.1.0        |
| 110002              | Los dispositivos en un grupo no tienen una capacidad común                                                   | ≥2.1.0        |
| 110003              | Número incorrecto de dispositivos                                                                            | ≥2.1.0        |
| 110004              | Número incorrecto de grupos                                                                                  | ≥2.1.0        |
| 110005              | Dispositivo fuera de línea                                                                                   | ≥2.1.0        |
| 110006              | Error al actualizar el estado del dispositivo                                                                | ≥2.1.0        |
| 110007              | Error al actualizar el estado del grupo                                                                      | ≥2.1.0        |
| 110008              | Se ha alcanzado el número máximo de grupos. Cree hasta 50 grupos                                             | ≥2.1.0        |
| 110009              | La dirección IP del dispositivo de cámara es incorrecta                                                      | ≥2.1.0        |
| 110010              | Error de autorización de acceso al dispositivo de cámara                                                     | ≥2.1.0        |
| 110011              | Error en la dirección de la transmisión del dispositivo de cámara                                            | ≥2.1.0        |
| 110012              | La codificación de vídeo del dispositivo de cámara no es compatible                                          | ≥2.1.0        |
| 110013              | El dispositivo ya existe                                                                                     | ≥2.1.0        |
| 110014              | La cámara no admite operación sin conexión                                                                   | ≥2.1.0        |
| 110015              | La contraseña de la cuenta no coincide con la contraseña de la cuenta en la dirección de la transmisión RTSP | ≥2.1.0        |
| 110016              | La pasarela está en estado de descubrimiento de cámaras onvif                                                | ≥2.1.0        |
| 110017              | Se excedió el número máximo de cámaras agregadas                                                             | ≥2.1.0        |
| 110018              | La ruta de la cámara ESP es incorrecta                                                                       | ≥2.1.0        |
| 110019              | Error al acceder a la dirección de servicio del dispositivo de terceros                                      | ≥2.1.0        |

#### e. Buscar subdispositivo

Permitir que usuarios autorizados habiliten o deshabiliten la búsqueda de subdispositivos en la pasarela a través de esta interfaz

* 💡Nota: Actualmente solo admite la búsqueda de subdispositivos Zigbee.
* 💡Nota: Los subdispositivos Zigbee se agregarán automáticamente después de la búsqueda. No es necesario usar la interfaz "Agregar subdispositivos manualmente" :::tips
* **URL**：/open-api/V2/rest/devices/discovery
* **Método**: PUT
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                              |
| ------------ | -------- | ------------ | ------------------------------------------------------------ |
| enable       | boolean  | N            | true (Iniciar emparejamiento); false (Pausar emparejamiento) |
| type         | string   | N            | Tipo de búsqueda: Zigbee                                     |

Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\* `200 OK` ::: **Ejemplo de respuesta**:

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

#### f. Agregar manualmente el subdispositivo

Permitir que usuarios autorizados agreguen un **único** subdispositivo a través de esta interfaz.

* Nota: Actualmente solo se admiten Cámara RTSP y Cámara ESP32 :::tips
* **URL**：/open-api/V2/rest/devices
* **Método**：POST
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud:

| **Atributo**      | **Tipo**            | **Opcional** | **Descripción**                                                                                                      |
| ----------------- | ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| name              | string              | N            | Nombre del subdispositivo                                                                                            |
| display\_category | string              | N            | Tipo de dispositivo. Solo admite cámara.                                                                             |
| capabilities      | CapabilityObject\[] | N            | Lista de capacidades. Cuando display\_category = camera, las capacidades solo incluyen capacidades de camera-stream. |
| protocal          | string              | N            | Protocolo del dispositivo. RTSP; ESP32-CAM                                                                           |
| manufacturer      | string              | N            | Fabricante.                                                                                                          |
| model             | string              | N            | Modelo del dispositivo                                                                                               |
| firmware\_version | string              | N            | Versión de firmware del dispositivo                                                                                  |

CapabilityObject

| **Atributo**  | **Tipo**                        | **Opcional** | **Descripción**                                     |
| ------------- | ------------------------------- | ------------ | --------------------------------------------------- |
| capability    | string                          | N            | Nombre de la capacidad. Solo admite "camera-stream" |
| permission    | string                          | N            | Permiso del dispositivo. Solo admite lectura.       |
| configuration | CameraStreamConfigurationObject | Y            | Configuración de transmisión de la cámara.          |

SettingsObject

| **Atributo**  | **Tipo**            | **Opcional** | **Descripción**                           |
| ------------- | ------------------- | ------------ | ----------------------------------------- |
| streamSetting | StreamSettingObject | N            | Configuración del servicio de transmisión |

StreamSettingObject

| **Atributo** | **Tipo**                 | **Opcional** | **Descripción**                                       |
| ------------ | ------------------------ | ------------ | ----------------------------------------------------- |
| type         | string                   | N            | Configuración del servicio de transmisión             |
| permission   | string                   | N            | Permiso de capacidad. Solo admite "11" (modificable). |
| campo        | StreamSettingValueObject | N            | Valores de configuración específicos                  |

StreamSettingValueObject

| **Atributo**                                                                                                                                          | **Tipo** | **Opcional** | **Descripción**               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------------------------- |
| stream\_url                                                                                                                                           | string   | N            | Formato de URL de transmisión |
| Formato:`<schema>://<hostname>:<port>/<username>:<password>@<service_path>`                                                                           |          |              |                               |
| Ejemplo:`rtsp://admin:123456@192.168.10.115:554/streaming/channel01`                                                                                  |          |              |                               |
| Opciones de esquema:                                                                                                                                  |          |              |                               |
| `rtsp` (Protocolo de transmisión en tiempo real)                                                                                                      |          |              |                               |
| `http` (Protocolo de transferencia de hipertexto) — Para dispositivos ESP32-CAM                                                                       |          |              |                               |
| \*Nota: Algunas cámaras pueden no requerir nombre de usuario o contraseña. En tales casos, puede omitir `<username>` y `<password>` campos de la URL. |          |              |                               |

Respuesta de datos exitosa:

| **Atributo**   | **Tipo** | **Opcional** | **Descripción**                       |
| -------------- | -------- | ------------ | ------------------------------------- |
| serial\_number | string   | N            | Número de serie único del dispositivo |

:::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

Respuesta de datos de falla: Objeto vacío :::tips **Condición**：

1. Error de acceso a la dirección de transmisión de la cámara (error de formato, fallo de autorización, excepción de red, etc.)
2. El dispositivo ya existe
3. Si un solo dispositivo no se puede agregar, devuelve que todos los dispositivos no se pudieron agregar.

**Código de estado**: 200 OK **Código de error**： ● 110009 Error de dirección IP de la cámara ● 110010 Error de autorización de acceso a la cámara ● 110011 Error en la dirección de la transmisión de la cámara ● 110012 La codificación de vídeo de la cámara no es compatible ● 110013 El dispositivo ya existe ::: **Ejemplo de respuesta**:

```
{
  "error": 110009,
  "data": {},
  "message": "falló el acceso ip de la cámara" 
}
```

#### g. Obtener lista de subdispositivos

Permitir que usuarios autorizados obtengan la lista de subdispositivos de la pasarela a través de esta interfaz. :::tips

* **URL**：/open-api/V2/rest/devices
* **Método**: GET
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa:

| **Atributo** | **Tipo**                | **Opcional** | **Descripción**       |
| ------------ | ----------------------- | ------------ | --------------------- |
| device\_list | ResponseDeviceObject\[] | N            | Lista de dispositivos |

ResponseDeviceObject

| **Atributo**          | **Tipo**            | **Opcional**                                                          | **Descripción**                                                                                                                                                                                                                                                    |
| --------------------- | ------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| serial\_number        | string              | N                                                                     | Número de serie único del dispositivo                                                                                                                                                                                                                              |
| third\_serial\_number | string              | "N" cuando se conecta un dispositivo de terceros, de lo contrario "Y" | Número de serie único de dispositivo de terceros                                                                                                                                                                                                                   |
| service\_address      | string              | "N" cuando se conecta un dispositivo de terceros, de lo contrario "Y" | Dirección de servicio de terceros                                                                                                                                                                                                                                  |
| name                  | string              | N                                                                     | Nombre del dispositivo; si no se renombra, se mostrará en el front-end según las reglas de visualización predeterminadas.                                                                                                                                          |
| manufacturer          | string              | N                                                                     | Fabricante                                                                                                                                                                                                                                                         |
| model                 | string              | N                                                                     | Modelo del dispositivo                                                                                                                                                                                                                                             |
| firmware\_version     | string              | N                                                                     | Versión de firmware. Puede ser una cadena vacía.                                                                                                                                                                                                                   |
| hostname              | string              | Y                                                                     | Nombre de host del dispositivo                                                                                                                                                                                                                                     |
| mac\_address          | string              | Y                                                                     | Dirección mac del dispositivo                                                                                                                                                                                                                                      |
| app\_name             | string              | Y                                                                     | El nombre de la aplicación a la que pertenece. Si se rellena app\_name al obtener el certificado de interfaz abierta, entonces todos los dispositivos posteriores conectados mediante el certificado se escribirán en este campo.                                  |
| display\_category     | string              | N                                                                     | Categoría del dispositivo                                                                                                                                                                                                                                          |
| capabilities          | CapabilityObject\[] | N                                                                     | Capacidades del dispositivo                                                                                                                                                                                                                                        |
| protocol              | string              | "N" cuando se conecta un dispositivo de terceros, de lo contrario "Y" | Protocolo del dispositivo: zigbee, onvif, rtsp, esp32-cam                                                                                                                                                                                                          |
| state                 | object              | Y                                                                     | Objeto de estado del dispositivo. Para ejemplos de estado de diferentes capacidades, consulte 【Capacidades de dispositivo compatibles】                                                                                                                             |
| etiquetas             | object              | Y                                                                     | Par clave-valor en formato JSON, información personalizada del dispositivo. La función es la siguiente:- Usado para almacenar canales del dispositivo- Usado para almacenar unidades de temperatura- Información personalizada para otros dispositivos de terceros |
| en línea              | boolean             | N                                                                     | Estado en línea: True para en líneaFalse es fuera de línea                                                                                                                                                                                                         |
| subred                | boolean             | Y                                                                     | Si está en la misma subred que la pasarela                                                                                                                                                                                                                         |

CapabilityObject 💡Nota: Consulte los Ejemplos de Capacidades de Dispositivo Compatibles en \[Capacidades de dispositivo compatibles].

| **Atributo**  | **Tipo** | **Opcional** | **Descripción**                                                                                                                              |
| ------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| capability    | string   | N            | Nombre de la capacidad. Para más detalles, consulte \[Capacidades de dispositivo compatibles]                                                |
| permission    | string   | N            | Permiso de la capacidad. Los valores posibles son "read" (lectura), "write" (escritura), "readWrite" (lectura y escritura).                  |
| configuration | object   | Y            | Información de configuración de la capacidad. Actualmente se utiliza camera-stream, consulte \[Capacidades de dispositivo compatibles]       |
| name          | string   | Y            | El campo name en toggle. El número de subcanal usado para identificar dispositivos multicanal. Por ejemplo, si name es 1, significa canal 1. |

:::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

```
{
  "error": 0,
  "data":{
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "Mi dispositivo",
        "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. Actualizar información o estado especificado del dispositivo

Permitir a los usuarios autorizados modificar la información básica del subdispositivo y emitir comandos de control a través de esta interfaz. :::tips

* **URL**：/open-api/V2/rest/devices/{serial\_number}
* **Método**：PUT
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud:

| **Atributo**  | **Tipo** | **Opcional** | **Descripción**                                                                                                                         |
| ------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| name          | string   | Y            | Nombre del dispositivo                                                                                                                  |
| etiquetas     | object   | Y            | Par clave-valor en formato JSON, información personalizada del dispositivo.                                                             |
| state         | object   | Y            | Objeto de estado del dispositivo. Para ejemplos de estado de diferentes capacidades, consulte \[Capacidades de dispositivo compatibles] |
| configuration | object   | Y            | Información de configuración de la capacidad, actualmente solo la capacidad camera\_stream admite modificación.                         |

Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK **Código de error**:

* 110000 El subdispositivo/grupo correspondiente al id no existe ::: **Ejemplo de respuesta**:

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

Permitir a los usuarios autorizados eliminar subdispositivos a través de esta interfaz. :::tips

* **URL**：/open-api/V2/rest/devices/{serial\_number}
* **Método**：DELETE
* **Encabezado**：
  * Content-Type: application/json
  * Autorization: Bearer ::: Parámetros de la solicitud:

| **Atributo** | **Tipo**             | **Opcional** | **Descripción**                                                                                                                                                                       |
| ------------ | -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name         | string               | Y            | Nombre del dispositivo.                                                                                                                                                               |
| etiquetas    | object               | Y            | Pares clave-valor en formato JSON utilizados para almacenar nombres de canales del dispositivo y otra información sobre subdispositivos.                                              |
| state        | object               | Y            | Cambiar el estado del dispositivo; para detalles del protocolo específico, consulte "Capacidades de dispositivo compatibles."                                                         |
| capabilities | CapabilityObject \[] | Y            | Información de configuración de la capacidad; todas las capacidades que admiten establecer configuraciones pueden modificarse. Tenga en cuenta que los permisos no se pueden cambiar. |

Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK **Códigos de error:**

* 110000: El subdispositivo/grupo correspondiente al ID no existe.
* 110006: Falló al actualizar el estado del dispositivo.
* 110019: Falló el acceso a la dirección del servicio del dispositivo de terceros.
* 110024: Falló al actualizar la configuración del dispositivo. ::: **Ejemplo de respuesta**:

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

```javascript
import axios from 'axios';

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

(async function main() {
  // encender dispositivo
  await axios({
    url: `http://<nombre de dominio o dirección 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. Eliminar sub-dispositivo

Permite a usuarios autorizados eliminar subdispositivos a través de esta interfaz.\
:::tips

* **URL**：`/open-api/v2/rest/devices/{serial_number}`
* **Método**：`DELETE`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

#### k. Consultar estado del dispositivo

Permite a usuarios autorizados consultar el estado del dispositivo a través de esta interfaz.\
:::tips

* **URL**：`/open-api/v2/rest/devices/:serial_number/query-state/{capability}`
* **Método**：POST
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                                                   |
| ------------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| query\_state | object   | N            | Consultar estado del dispositivo; para detalles del protocolo, consulte "Capacidades de dispositivo compatibles." |

```javascript
import axios from 'axios';

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

(async function main() {
  // encender dispositivo
  await axios({
    url: `http://<nombre de dominio o dirección 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", // Tipo de estadísticas, requerido
          "timeRange": { // Rango de tiempo para la sumarización, requerido cuando type="summarize"
            "start": "2020-07-05T08:00:00Z", // Hora de inicio para las estadísticas de consumo de energía
            "end": "2020-07-05T09:00:00Z" // Hora de finalización para las estadísticas de consumo de energía; si se omite, por defecto es la hora actual
          }
        }
      }
    });
})()
```

Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

### 3.4 Gestión de seguridad

#### a. Obtener lista de seguridad

Permite a usuarios autorizados modificar la configuración de la pasarela a través de esta interfaz. :::tips

* **URL**：`/open-api/v2/rest/security`
* **Método**：`GET`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa:

| **Atributo**   | **Tipo**                  | **Opcional** | **Descripción**                       |
| -------------- | ------------------------- | ------------ | ------------------------------------- |
| security\_list | ResponseSecurityObject\[] | N            | Lista de dispositivos en la respuesta |

ResponseDeviceObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**     |
| ------------ | -------- | ------------ | ------------------- |
| sid          | int      | N            | id de seguridad     |
| name         | string   | N            | Nombre de seguridad |
| enable       | bool     | N            | Si está habilitado  |

* true Habilitado
* false Deshabilitado |

:::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

```json
{
  "error": 0,
  "data": {
    "security_list":[
      {
        "sid": 1,
        "name": "Modo Hogar",
        "enable": true
      }
    ]
  },
  "message": "success"
}
```

#### b. Habilitar modo de seguridad especificado

Permite a usuarios autorizados habilitar un modo de seguridad especificado a través de esta interfaz.\
:::tips

* **URL**：`/open-api/v2/rest/security/{security_id}/enable`
* **Método**：`PUT`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: Objeto vacío {} :::tips **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

#### c. Deshabilitar modo de seguridad especificado

Permite a usuarios autorizados deshabilitar un modo de seguridad especificado a través de esta interfaz.\
:::tips

* **URL**：`/open-api/v2/rest/security/{security_id}/disable`
* **Método**：`PUT`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: Objeto vacío {} :::tips **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

#### d. Habilitar configuración de seguridad con un clic

Permite a usuarios autorizados habilitar el modo de configuración de seguridad con un clic a través de esta interfaz.\
:::tips

* **URL**：`/open-api/v2/rest/security/enable`
* **Método**：`PUT`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: Objeto vacío {} :::tips **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

#### e. Deshabilitar seguridad

Permite a usuarios autorizados deshabilitar la seguridad a través de esta interfaz.\
:::tips

* **URL**：`/open-api/v2/rest/security/disable`
* **Método**：`PUT`
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: Objeto vacío {} :::tips **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**:

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

## 4. Acceso de dispositivos de terceros

### 4.1 Instrucciones de acceso

#### Acceso de dispositivos

![1.0.jpg](https://cdn.nlark.com/yuque/0/2023/jpeg/26986480/1673333299008-ba3e9361-9530-4c91-9fbb-932c6cef0d74.jpeg#averageHue=%23f7f7f7\&clientId=u094571da-402c-4\&from=ui\&id=uf667dd9b\&originHeight=478\&originWidth=937\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=45101\&status=done\&style=none\&taskId=u38b7b94b-5139-435a-93e9-6818e144116\&title=)

#### Acceso de pasarela de terceros

![2.0.jpg](https://cdn.nlark.com/yuque/0/2023/jpeg/26986480/1673333064090-e22470c9-8cc9-422a-8775-b16ce3c697d1.jpeg#averageHue=%23f5f5f5\&clientId=u094571da-402c-4\&from=ui\&id=u6eba2c0d\&originHeight=561\&originWidth=937\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=56842\&status=done\&style=none\&taskId=ud9dcdaa8-9b98-45f5-a8ae-f4c6dd453f2\&title=)

#### Pasos de acceso

1. Determine la clasificación del dispositivo en la pasarela. Los detalles, por favor consulte \[Tipo de dispositivo compatible].
2. Determine las capacidades a las que el dispositivo puede acceder. Los detalles, por favor consulte \[Capacidades de dispositivo compatibles].
3. Solicite la interfaz \[Discovery Request] para agregar el dispositivo a la pasarela.
   1. *Atención: Necesita proporcionar la dirección del servicio para recibir las instrucciones emitidas por la pasarela, que se utiliza para recibir las instrucciones de control del dispositivo emitidas por la pasarela*.
4. Si el estado del dispositivo de terceros cambia, debe llamar a la interfaz \[Device States Change Report] para enviar el estado más reciente de vuelta a la pasarela.
5. Después de agregar, el dispositivo de terceros aparecerá en la Lista de Dispositivos, con la mayoría de las funciones de la pasarela (otros dispositivos no de terceros). Las interfaces abiertas comunes relacionadas con el dispositivo se pueden usar normalmente.

* Seleccione la categoría de dispositivo adecuada. La clasificación afectará el resultado de la visualización final de la interfaz de usuario después de que el dispositivo se conecte a la pasarela.
* Elija la capacidad de dispositivo correcta. La lista de capacidades determinará el estado del protocolo de estado del dispositivo.

#### Proceso del programa

**a. Acceso de dispositivo**

![3.0.jpg](https://cdn.nlark.com/yuque/0/2023/jpeg/26986480/1673332924656-c92a1364-a2e0-4441-927b-255dbffef49c.jpeg#averageHue=%23f3eec5\&clientId=u094571da-402c-4\&from=ui\&id=u38107bf2\&originHeight=735\&originWidth=724\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=90352\&status=done\&style=none\&taskId=udbf0090d-9371-4b83-8491-bc0bbe4adac\&title=)

**b. Acceso de pasarela de terceros**

![4.0.jpg](https://cdn.nlark.com/yuque/0/2023/jpeg/26986480/1673332935213-b0839fc1-71e3-495d-92d8-161f67b125bf.jpeg#averageHue=%23f6f5ef\&clientId=u094571da-402c-4\&from=ui\&id=u7573ae44\&originHeight=734\&originWidth=775\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=98031\&status=done\&style=none\&taskId=uc50d2370-3065-4e10-99df-5a90b77dc38\&title=)

### 4.2 Ejemplo de acceso

#### Interruptor, Enchufe

**Sincronizar dispositivos de terceros**

```
// Solicitud
URL：/open-api/v2/rest/thirdparty/event
Método：POST
Encabezado：
  Content-Type: application/json
  Autorization: Bearer  <token>
Cuerpo:
{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "2"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "mi enchufe",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission": "1100"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "versión de firmware",
          "service_address": "http://192.168.31.14/webhook"
      	}
      ]
    }
  }
}
```

```
{
  "header": {
    "name": "Response",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "third_serial_number": "third_serial_number",
        "serial_number": "número de serie"
      }
    ]
  }
}
```

**Informar estado del dispositivo**

```
URL：/open-api/V2/rest/thirdparty/event
Método：POST
Encabezado：
  Content-Type: application/json
  Autorization: Bearer  <token>
Cuerpo:

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}
```

```
{
  "header": {
    "name": "Response",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {}
}
```

**Informar fuera de línea/en línea**

```
{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "online": true
    }
  }
}
```

```
{
  "header": {
    "name": "Response",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {}
}
```

**Recibir las instrucciones sobre el control de dispositivos de la pasarela**

```
URL：<dirección del servicio>
Método：POST
Encabezado：
  Content-Type: application/json
B

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "endpoint": {
      "third_serial_number": "third_serial_number",
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}
```

```
{
  "header": {
    "name": "Response",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {}
}
```

**Consultar dispositivo**

```
URL：/open-api/V2/rest/devices
Método：GET
Encabezado：
  Content-Type: application/json
  Autorization: Bearer  <token>
Cuerpo: Ninguno
```

```
{
  "error": 0,
  "data": {
    "device_list": [
      {
        "serial_number": "número de serie",
        "third_serial_number": "third_serial_number",
        "name": "mi enchufe",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "versión de firmware",
        "display_category": "plug",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  },
  "message": "success"
}
```

### 4.3 API web

#### Interfaz de pasarela de solicitud de terceros

**Formato de solicitud**

Permitir a usuarios autorizados enviar solicitudes de eventos a la pasarela a través de esta interfaz. :::tips

* **URL**：/open-api/V2/rest/thirdparty/event
* **Método**：POST
* **Encabezado**：
  * Content-Type: application/json
  * Authorization: Bearer ::: Parámetros de la solicitud:

| **Atributo** | **Tipo**    | **Opcional** | **Descripción**                                 |
| ------------ | ----------- | ------------ | ----------------------------------------------- |
| evento       | EventObject | N            | Estructura del objeto de evento de la solicitud |

EventObject

| **Atributo** | **Tipo**       | **Opcional** | **Descripción**                                                                                                           |
| ------------ | -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
| header       | HeaderObject   | N            | Estructura del encabezado de la solicitud                                                                                 |
| endpoint     | EndpointObject | Y            | Estructura del endpoint de la solicitud Nota: Este campo está vacío cuando se sincroniza una nueva lista de dispositivos. |
| payload      | PayloadObject  | N            | Estructura del payload de la solicitud                                                                                    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                                                                                                                                                                                 |
| ------------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name         | string   | N            | Nombre de la solicitud. Parámetro opcional: DiscoveryRequest: Sincronizar nuevos dispositivos DeviceStatesChangeReport: Informe de actualización de estado del dispositivo DeviceOnlineChangeReport: Informe de estado en línea del dispositivo |
| message\_id  | string   | N            | ID del mensaje de la solicitud, UUID\_V4                                                                                                                                                                                                        |
| version      | string   | N            | Número de versión del protocolo de la solicitud. Actualmente fijo en 1                                                                                                                                                                          |

EndpointObject

| **Atributo**          | **Tipo** | **Opcional** | **Descripción**                                                                                                                                 |
| --------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| serial\_number        | string   | N            | Número de serie único del dispositivo                                                                                                           |
| third\_serial\_number | string   | N            | Número de serie único de dispositivo de terceros                                                                                                |
| etiquetas             | object   | Y            | Par clave-valor en formato JSON, información personalizada del dispositivo. \[Función de gestión de dispositivos] - \[Descripción de etiquetas] |

PayloadObject Según el header.name diferente tiene una estructura de solicitud diferente.

**Formato de respuesta**

:::tips \*\*Código de estado: \*\*200 OK **Parámetros de la respuesta:** :::

| **Atributo** | **Tipo**      | **Opcional** | **Descripción**                                             |
| ------------ | ------------- | ------------ | ----------------------------------------------------------- |
| header       | HeaderObject  | N            | Información de la estructura del encabezado de la respuesta |
| payload      | PayloadObject | N            | Información de la estructura del payload de la respuesta    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                                                                                                                                                                            |
| ------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name         | string   | N            | Nombre del encabezado de respuesta. Parámetros opcionales: Response: Respuesta exitosa ErrorResponse: Respuesta de error                                                                                                                   |
| message\_id  | string   | N            | ID del mensaje del encabezado de la respuesta, UUID\_V4. Pase aquí el header.message\_id del mensaje de la solicitud \*Si el parámetro de entrada de la solicitud carece de message\_id, este campo será una cadena vacía en la respuesta. |
| version      | string   | N            | - Número de versión del protocolo de la solicitud. Actualmente fijo en 1.                                                                                                                                                                  |

> Respuesta exitosa--PayloadObject ：

Dependiendo del tipo de solicitud, la estructura de la respuesta es diferente. Para más detalles, consulte el documento de instrucciones de la solicitud específica.

> Respuesta de fallo--PayloadObject：

| **Atributo** | **Tipo** | **Opcional** | **Descripción** |
| ------------ | -------- | ------------ | --------------- |
| type         | string   | N            | Tipos de error: |

* INVALID\_PARAMETERS: Error de parámetros
* AUTH\_FAILURE: Error de autorización
* INTERNAL\_ERROR: Error interno del servicio | | descripción | string | N | Descripción del error |

**DiscoveryRequest Sincronizar una nueva lista de dispositivos**

* Nota: Después de que el dispositivo se sincroniza con la pasarela, está en línea por defecto, es decir, online=true. Los cambios posteriores en línea dependen completamente de la sincronización con el tercero a través de la interfaz DeviceOnlineChangeReport.

**Parámetros de la solicitud:** EndpointObject\*\*：\*\*Ninguno PayloadObject：

| **Atributo** | **Tipo**          | **Opcional** | **Descripción**       |
| ------------ | ----------------- | ------------ | --------------------- |
| endpoints    | EndpointObject\[] | N            | Lista de dispositivos |

EndpointObject:

| **Atributo**          | **Tipo**            | **Opcional** | **Descripción**                                                                                                                                                                                                |
| --------------------- | ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| third\_serial\_number | string              | N            | Número de serie único de dispositivo de terceros                                                                                                                                                               |
| name                  | string              | N            | Nombre del dispositivo                                                                                                                                                                                         |
| display\_category     | string              | N            | Categoría del dispositivo. Consulte \[Tipo de dispositivo compatible] para más detalles. \*Los dispositivos de terceros no admiten agregar cámaras ahora.                                                      |
| capabilities          | CapabilityObject\[] | N            | Lista de capacidades                                                                                                                                                                                           |
| state                 | object              | N            | Información de estado inicial                                                                                                                                                                                  |
| manufacturer          | string              | N            | Fabricante                                                                                                                                                                                                     |
| model                 | string              | N            | Modelo del dispositivo                                                                                                                                                                                         |
| etiquetas             | object              | Y            | Par clave-valor en formato JSON, información personalizada del dispositivo: Se usa para almacenar canales del dispositivo Se usa para almacenar unidades de temperatura Otros datos personalizados de terceros |
| firmware\_version     | string              | N            | Versión del firmware                                                                                                                                                                                           |
| service\_address      | string              | N            | Dirección del servicio. Por ejemplo <http://192.168.31.14/service_address>                                                                                                                                     |

Ejemplo de solicitud :

```
{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "mi enchufe",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission" "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "versión de firmware",
          "service_address": "http://192.168.31.14/service_address"
        }
      ]
    }
  }
}
```

**Parámetros de la respuesta:** PayloadObject：

| **Atributo** | **Tipo**          | **Opcional** | **Descripción**       |
| ------------ | ----------------- | ------------ | --------------------- |
| endpoints    | EndpointObject\[] | N            | Lista de dispositivos |

EndpointObject:

| **Atributo**          | **Tipo** | **Opcional** | **Descripción**                                  |
| --------------------- | -------- | ------------ | ------------------------------------------------ |
| serial\_number        | string   | N            | Número de serie único del dispositivo            |
| third\_serial\_number | string   | N            | Número de serie único de dispositivo de terceros |

Ejemplo de una respuesta correcta:

```
{
  "header": {
    "name": "Response",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "serial_number": "número de serie",
        "third_serial_number": "third_serial_number"
      }
    ]
  }
}
```

Ejemplo de una respuesta de error:

```
{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "webhook no puede estar vacío" 
  }
}
```

**DeviceStatesChangeReport Informe de cambio de estado del dispositivo**

* Nota: Los informes de estado repetidos pueden activar falsamente escenas asociadas.

**Parámetros de la solicitud:** PayloadObject：

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                              |
| ------------ | -------- | ------------ | -------------------------------------------------------------------------------------------- |
| state        | object   | N            | Estado del dispositivo, consulte \[Capacidades de dispositivo compatibles] para más detalles |

Ejemplo de solicitud :

```
{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}
```

**Parámetros de la respuesta:** PayloadObject: Objeto vacío Ejemplo de una respuesta exitosa:

```
{
  "header": {
    "name": "Response",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {}
}
```

**DeviceOnlineChangeReport Informe de estado en línea del dispositivo**

* Nota: Los informes de estado repetidos pueden activar falsamente escenas asociadas.

**Parámetros de la solicitud:** PayloadObject：

| **Atributo**          | **Tipo** | **Opcional** | **Descripción**                                |
| --------------------- | -------- | ------------ | ---------------------------------------------- |
| en línea              | boolean  | N            | Estado en línea del dispositivo true: En línea |
| false: Fuera de línea |          |              |                                                |

Ejemplo de solicitud :

```
{
  "event": {
    "header": {
      "name": "DeviceOnlineChangeReport",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
       "online": true
    }
  }
}
```

**Parámetros de la respuesta:** PayloadObject: Objeto vacío Ejemplo de una respuesta exitosa:

```
{
  "header": {
    "name": "Response",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {}
}
```

**DeviceInformationUpdatedReport Informe de información del dispositivo actualizado**

* Nota: La actualización puede afectar escenas existentes o funciones de seguridad.

**Parámetros de la solicitud:** PayloadObject：

| **Atributo** | **Tipo** | **Opcional** | **Descripción** |
| ------------ | -------- | ------------ | --------------- |
| capabilities |          |              |                 |

\| CapabilityObject\[]

\| N

\| Lista de capacidades. Los detalles se pueden encontrar en la sección de capacidades de dispositivo compatible. \*\*Nota: \*\*Este parámetro solo actualizará el `campo` del `ajuste` clave dentro del `CapabilityObject`, y las actualizaciones solo están permitidas si el `permission` para la `ajuste` clave es `11` o `01`. Para la definición de estructura específica de la `ajuste` en `CapabilityObject`, consulte la descripción detallada en la sección 2.3 Categorías de visualización de dispositivos y capacidades de dispositivo. | | etiquetas

\| objeto

\| Y

\| Par clave-valor en formato JSON, información personalizada del dispositivo.

* Se puede usar para almacenar canales del dispositivo
* Se puede usar para almacenar unidades de temperatura
* Otros datos personalizados de terceros |

Ejemplo de solicitud :

```json
{
  "event": {
    "header": {
      "name": "DeviceInformationUpdatedReport",
      "message_id": "Identificador único, preferiblemente un UUID versión 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,
            }
          }
        }
      ]
    }
  }
}
```

**parámetros de la respuesta:** PayloadObject: Objeto vacío Ejemplo de una respuesta exitosa:

```json
{
  "header": {
    "name": "Response",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "2"
  },
  "payload": {}
}
```

#### La pasarela envía la interfaz de instrucción a través de la dirección del servicio del dispositivo

* Nota:

1. Las tres partes deben responder a la solicitud de la pasarela dentro de 3 s. De lo contrario, la pasarela juzgará el tiempo de procesamiento del comando como agotado.
2. Si el servicio de terceros está fuera de línea, la pasarela establecerá el dispositivo en un estado fuera de línea, y el servicio de terceros debe informar el estado del dispositivo (DeviceStatesChangeReport) o el estado en línea (DeviceOnlineChangeReport) antes de volver al estado en línea.

**Formato de la solicitud**

La pasarela envía instrucciones al tercero a través de la interfaz de dirección del servicio del dispositivo. :::tips

* **URL**：
* **Método**：POST
* **Encabezado**：
  * Content-Type: application/json ::: Parámetros de la solicitud:

| **Atributo** | **Tipo**        | **Opcional** | **Descripción**                                   |
| ------------ | --------------- | ------------ | ------------------------------------------------- |
| directive    | DirectiveObject | N            | Información de la estructura del objeto Directiva |

DirectiveObject

| **Atributo** | **Tipo**       | **Opcional** | **Descripción**                                           |
| ------------ | -------------- | ------------ | --------------------------------------------------------- |
| header       | HeaderObject   | N            | Estructura del encabezado de la solicitud                 |
| endpoint     | EndpointObject | N            | Información de la estructura del endpoint de la solicitud |
| payload      | PayloadObject  | N            | Estructura del payload de la solicitud                    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                                       |
| ------------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| name         | string   | N            | Nombre de la solicitud. Parámetros opcionales: UpdateDeviceStates: Actualizar estados del dispositivo |
| message\_id  | string   | N            | ID del mensaje de la solicitud, UUID\_V4                                                              |
| version      | string   | N            | Número de versión del protocolo de la solicitud. Actualmente fijo en 1.                               |

EndpointObject

| **Atributo**          | **Tipo** | **Opcional** | **Descripción**                                                                                                                                 |
| --------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| serial\_number        | string   | N            | Número de serie único del dispositivo                                                                                                           |
| third\_serial\_number | string   | N            | Número de serie único de dispositivo de terceros                                                                                                |
| etiquetas             | object   | N            | Par clave-valor en formato JSON, información personalizada del dispositivo. \[Función de gestión de dispositivos] - \[Descripción de etiquetas] |

PayloadObject: Según diferentes `header.name`, existe una estructura de solicitud específica para cada uno.

Ejemplo de solicitud :

```
{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
      "tags": {}
    },
    "payload": {
      "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}
```

**Formato de respuesta**

:::tips \*\*Código de estado HTTP: \*\*200 OK **Atributo de respuesta HTTP：** :::

| **Atributo** | **Tipo**    | **Opcional** | **Descripción**                                      |
| ------------ | ----------- | ------------ | ---------------------------------------------------- |
| evento       | EventObject | N            | Información de la estructura del evento de respuesta |

EventObject

| **Atributo** | **Tipo**      | **Opcional** | **Descripción**                           |
| ------------ | ------------- | ------------ | ----------------------------------------- |
| header       | HeaderObject  | N            | Estructura del encabezado de la solicitud |
| payload      | PayloadObject | N            | Estructura del payload de la solicitud    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                                                                                                             |
| ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name         | string   | N            | Nombre del encabezado de respuesta. Parámetro opcional: UpdateDeviceStatesResponse: Respuesta de actualización de estados del dispositivo ErrorResponse: Respuesta de error |
| message\_id  | string   | N            | ID del mensaje del encabezado de respuesta, UUID\_V4. Pase aquí el header.message\_id del mensaje de la solicitud                                                           |
| version      | string   | N            | Número de versión del protocolo de la solicitud. Actualmente fijo en 1.                                                                                                     |

> Respuesta exitosa--PayloadObject：

Dependiendo del tipo de solicitud, la estructura de la respuesta es diferente. Para más detalles, consulte el documento de instrucciones de la solicitud específica.

> Respuesta de fallo--PayloadObject：

| **Atributo** | **Tipo** | **Opcional** | **Descripción**     |
| ------------ | -------- | ------------ | ------------------- |
| type         | string   | N            | **Tipos de error**: |

* **ENDPOINT\_UNREACHABLE**: El dispositivo es inalcanzable o está fuera de línea
* **ENDPOINT\_LOW\_POWER**: El dispositivo está en modo de bajo consumo y no se puede controlar
* **INVALID\_DIRECTIVE**: Directiva anormal desde la pasarela
* **NO\_SUCH\_ENDPOINT**: El dispositivo no existe
* **NOT\_SUPPORTED\_IN\_CURRENT\_MODE**: El modo actual no admite la operación
* **INTERNAL\_ERROR**: Error interno del servicio
* **REMOTE\_KEY\_CODE\_NOT\_LEARNED**: Código de tecla del control remoto no aprendido |

:::consejos **Condiciones**: Los parámetros de la solicitud son legales. \*\*Código de estado: \*\*200 OK **Parámetros de la respuesta:** :::

```
{
  "event": {
    "header": {
      "name": "UpdateDeviceStatesResponse",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "payload": {}
  }
}
```

```
{
  "event": {
    "header": {
      "name": "ErrorResponse",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE"
    }
  }
}
```

**UpdateDeviceStates**

**Parámetros de la solicitud:** PayloadObject：

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                               |
| ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------- |
| state        | object   | N            | Estado del dispositivo, consulte \[Capacidades de dispositivo compatibles] para más detalles. |

Ejemplo de solicitud :

```
{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}
```

**Parámetros de la respuesta:** PayloadObject：Objeto vacío Ejemplo de respuesta exitosa

```
{
  "header": {
    "name": "Response",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {}
}
```

**QueryDeviceStates**

**Parámetros de la solicitud:** PayloadObject：

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                               |
| ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------- |
| state        | object   | N            | Estado del dispositivo, consulte \[Capacidades de dispositivo compatibles] para más detalles. |

Ejemplo de solicitud :

```json
{
  "directive": {
    "header": {
      "name": "QueryDeviceStates",
      "message_id": "Identificador único, preferiblemente un UUID versión 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", // Hora de inicio para las estadísticas de consumo de energía, requerida.
            "end": "2020-07-05T09:00:00Z"   // Hora de finalización para las estadísticas de consumo de energía, requerida.
          }
        }
      }
    }
  }
}
```

**Parámetros de la respuesta:** PayloadObject：

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                               |
| ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------- |
| state        | object   | N            | Estado del dispositivo, consulte \[Capacidades de dispositivo compatibles] para más detalles. |

**Ejemplo de respuesta:**

```json
{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "2"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "electricityIntervals": [ // Dividido en múltiples registros según la configuración.resolution
            {
              "usage": 26.5, // Valor de consumo de energía, requerido. Tipo: number.
              "start": "2020-07-05T08:00:00Z", // Hora de inicio, requerida. Tipo: date.
              "end": "2020-07-05T09:00:00Z"    // Hora de finalización, requerida. Tipo: date. Si el intervalo entre end y start es menor que resolution, todos los registros informados se consideran inválidos.
            },
            {
              "usage": 26.5, // Valor de consumo de energía, requerido. Tipo: number.
              "start": "2020-07-05T09:00:00Z", // Hora de inicio, requerida. Tipo: date.
              "end": "2020-07-05T10:00:00Z"    // Hora de finalización, requerida. Tipo: date. Si el intervalo entre end y start es menor que resolution, todos los registros informados se consideran inválidos.
            }
          ]
        }
      }
    }
  }
}
```

**Configurar capacidades del dispositivo**

**Parámetros de la solicitud:** PayloadObject：

| **Atributo** | **Tipo**            | **Opcional** | **Descripción**                                                                                                                                                                                                       |
| ------------ | ------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| capabilities | CapabilityObject\[] | N            | Lista de capacidades. Los detalles se pueden ver en la sección de capacidades de dispositivo compatibles. Tenga en cuenta que el campo permission no se puede cambiar, pase el mismo valor durante la sincronización. |

Ejemplo de solicitud :

```json
{
  "directive": {
    "header": {
      "name": "ConfigureDeviceCapabilities",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "thermostat-mode-detect",
          "permission": "0110",
          "name": "temperature", // Tipo de detección de control de temperatura, requerido. Valores opcionales: humidity (detección de humedad), temperature (detección de temperatura)
          "settings": {
            "setpointRange": {
              "permission": "11",
              "type": "object",
              "value": {
                "supported": [ // Configuraciones de detección soportadas, requerido.
                  {
                    "name": "lowerSetpoint", // Valor mínimo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint.
                    "value": { // Rango de detección, opcional. Completar si existen condiciones preestablecidas.
                      "value": 68.0, // Valor de temperatura o humedad, requerido.
                      "scale": "f" // Unidad de temperatura, requerido si name=temperature. Opciones: c (Celsius), f (Fahrenheit)
                    }
                  },
                  {
                    "name": "upperSetpoint", // Valor máximo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint.
                    "value": { // Rango de detección, opcional. Completar si existen condiciones preestablecidas.
                      "value": 68.0, // Valor de temperatura o humedad, requerido.
                      "scale": "f" // Unidad de temperatura, requerido si name=temperature. Opciones: c (Celsius), f (Fahrenheit)
                    }
                  }
                ]
              }
            },
            "supportedModes": {
              "type": "enum",
              "permission": "01",
              "values": [
                "COMFORT",
                "COLD",
                "HOT"
              ]
            }
          }
        }
      ]
    }
  }
}
```

**Parámetros de la respuesta:** PayloadObject：Objeto vacío Ejemplo de respuesta exitosa

```json
{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "2"
    },
    "payload": {}
  }
}
```

## 5. Eventos enviados por el servidor

> Descripción de la interfaz MDN EventSource：<https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events>

### 5.1 Instrucción

La pasarela admite empujar mensajes al cliente usando SSE (Server-sent events). El cliente puede monitorizar mensajes SSE después de obtener las credenciales de acceso y puede analizar el contenido de los mensajes push según el protocolo de notificación de eventos de la interfaz de desarrollo al recibir los mensajes empujados por la pasarela. Cabe señalar que la pasarela actualmente usa el protocolo HTTP1.1, por lo que SSE en el lado del navegador tendrá un máximo de no más de 6 conexiones (Las instrucciones específicas se pueden encontrar en la descripción de la interfaz MDN EventSource.)

### 5.2 Formato común

:::consejos

* **URL**：/open-api/V2/sse/bridge
* **Método**：`GET` ::: Parámetros de la solicitud:

| Nombre        | Tipo   | Opcional | Descripción     |
| ------------- | ------ | -------- | --------------- |
| access\_token | string | N        | Token de acceso |

Nota: Al solicitar una conexión SSE, la pasarela comprobará el access\_token, y devolverá un error de fallo de autenticación si es inválido. { "error": 401, "data": {}, "message": "invalid access\_token"}

> \## Por ejemplo: Nombre del módulo: device Versión: 1,v2,v3 Tipo de mensaje: addDevice

Ejemplo:

```javascript
const evtSource = new EventSource("http://<nombre de dominio o dirección 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 Módulo de dispositivo

#### a. Evento de añadir dispositivo

:::tips Nombre del módulo：device Versión：v2 Tipo de mensaje：addDevice event.data parámetros： :::

| Nombre  | Tipo                                                                          | Opcional | Descripción                 |
| ------- | ----------------------------------------------------------------------------- | -------- | --------------------------- |
| payload | ResponseDeviceObjectObject - Interfaz igual que Obtener lista de dispositivos | N        | información del dispositivo |

Ejemplo:

```json
// event.data
{
  "payload": {
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "Midispositivo",
    "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. Evento de actualización del estado del dispositivo

:::tips Nombre del módulo：device Versión：v2 Tipo de mensaje：updateDeviceState event.data parámetros： :::

| Nombre   | Tipo                                                   | Opcional | Descripción                     |
| -------- | ------------------------------------------------------ | -------- | ------------------------------- |
| endpoint | EndpointObject                                         | N        | Información del dispositivo     |
| payload  | object。 Estructura igual que el estado del dispositivo | N        | Datos de estado del dispositivo |

EndpointObject:

| Parámetro             | Tipo   | Opcional | Descripción                                                                                                                                    |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| serial\_number        | string | N        | Número de serie único del dispositivo                                                                                                          |
| third\_serial\_number | string | Y        | El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio. |

Ejemplo:

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

#### c. Evento de actualización de información del dispositivo

:::tips Nombre del módulo：device Versión：v2 Tipo de mensaje：updateDeviceInfo event.data parámetros： :::

| Nombre   | Tipo               | Opcional | Descripción                     |
| -------- | ------------------ | -------- | ------------------------------- |
| endpoint | EndpointObject     | N        | Información del dispositivo     |
| payload  | DeviceChangeObject | N        | Datos de cambio del dispositivo |

EndpointObject:

| Atributo              | Tipo   | Opcional | Descripción                                                                                                                                    |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| serial\_number        | string | N        | Número de serie único del dispositivo                                                                                                          |
| third\_serial\_number | string | Y        | El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio. |

DeviceChangeObject

| Nombre       | Tipo                 | Opcional | Descripción                                                                                                            |
| ------------ | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| name         | string               | N        | Nombre del dispositivo                                                                                                 |
| capabilities | CapabilityObject \[] | Y        | Lista de capacidades del dispositivo.                                                                                  |
| etiquetas    | object               | Y        | **etiquetas**`object` \| Nullable \| Pares clave-valor en formato JSON para información personalizada del dispositivo. |

* Se puede usar para almacenar canales del dispositivo.
* Se puede usar para almacenar unidades de temperatura.
* Para otros datos personalizados de terceros. |

Ejemplo:

```json
// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "name": "device name",
    "capabilities": [
      {
        "capability": "thermostat-mode-detect",
        "permission": "0110",
        "name": "temperature", // Tipo de detección de control de temperatura, requerido. Valores opcionales: humidity (detección de humedad), temperature (detección de temperatura)
        "settings": {
          "setpointRange": {
            "permission": "11",
            "type": "object",
            "value": {
              "supported": [ // Configuraciones de detección soportadas, requerido.
                {
                  "name": "lowerSetpoint", // Valor mínimo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint.
                  "value": { // Rango de detección, opcional. Completar si existen condiciones preestablecidas.
                    "value": 68.0, // Valor de temperatura o humedad, requerido.
                    "scale": "f" // Unidad de temperatura, requerido si name=temperature. Opciones: c (Celsius), f (Fahrenheit)
                  }
                },
                {
                  "name": "upperSetpoint", // Valor máximo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint.
                  "value": { // Rango de detección, opcional. Completar si existen condiciones preestablecidas.
                    "value": 68.0, // Valor de temperatura o humedad, requerido.
                    "scale": "f" // Unidad de temperatura, requerido si name=temperature. Opciones: c (Celsius), f (Fahrenheit)
                  }
                }
              ]
            }
          },
          "supportedModes": {
            "type": "enum",
            "permission": "01",
            "values": [
              "COMFORT",
              "COLD",
              "HOT"
            ]
          }
        }
      }
    ]
  }
}
```

#### d. Evento de eliminación de dispositivo

:::tips Nombre del módulo：device Versión：v2 Tipo de mensaje：deleteDevice event.data parámetros： :::

| \*\* Nombre \*\* | \*\* Tipo \*\* | \*\* Opcional\*\* | \*\* Descripción \*\*       |
| ---------------- | -------------- | ----------------- | --------------------------- |
| endpoint         | EndpointObject | N                 | Información del dispositivo |

EndpointObject:

| Atributo              | Tipo   | Opcional | Descripción                                                                                                                                    |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| serial\_number        | string | N        | Número de serie único del dispositivo                                                                                                          |
| third\_serial\_number | string | Y        | El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio. |

Ejemplo:

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

#### e. Evento de actualización de estado en línea del dispositivo

:::tips Nombre del módulo：device Versión：v2 Tipo de mensaje：updateDeviceOnline event.data parámetros： :::

| Nombre   | Tipo               | Opcional | Descripción                     |
| -------- | ------------------ | -------- | ------------------------------- |
| endpoint | EndpointObject     | N        | Información del dispositivo     |
| payload  | DeviceChangeObject | N        | Datos de cambio del dispositivo |

EndpointObject:

| Atributo              | Tipo   | Opcional | Descripción                                                                                                                                    |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| serial\_number        | string | N        | Número de serie único del dispositivo                                                                                                          |
| third\_serial\_number | string | Y        | El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio. |

DeviceChangeObject

| Nombre   | Tipo    | Opcional | Descripción                     |
| -------- | ------- | -------- | ------------------------------- |
| en línea | boolean | N        | Estado en línea del dispositivo |

Ejemplo:

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

### 5.4 Módulo de la pasarela

#### a. Evento de actualización del estado de seguridad

:::tips Nombre del módulo：device Versión：v2 Tipo de mensaje：updateDeviceOnline event.data parámetros： :::

| **Atributo** | **Tipo**            | **Opcional** | **Descripción**             |
| ------------ | ------------------- | ------------ | --------------------------- |
| payload      | SecurityStateObject | N            | Información del dispositivo |

SecurityStateObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción** |
| ------------ | -------- | ------------ | --------------- |
| alarm\_state | string   | N            |                 |

* `arming` | Armado
* `disarming` | Desarmado |

Ejemplo:

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

### 5.5 Módulo de seguridad

#### a. Evento de actualización del estado de armado

:::tips Nombre del módulo：device Versión：v2 Tipo de mensaje：updateDeviceOnline event.data parámetros： :::

| **Atributo** | **Tipo**       | **Opcional** | **Descripción**             |
| ------------ | -------------- | ------------ | --------------------------- |
| payload      | ArmStateObject | N            | rm e información de desarme |

ArmStateObject：

| **Atributo**   | **Tipo** | **Opcional** | **Descripción** |
| -------------- | -------- | ------------ | --------------- |
| estado\_alarma | string   | N            |                 |

* `arming` | Armado
* `disarming` | Desarmado | | detalle | ObjetoDetalle | N | Detalles de armar/desarmar |

ObjetoDetalle：

| **Atributo** | **Tipo** | **Opcional** | **Descripción**          |
| ------------ | -------- | ------------ | ------------------------ |
| sid          | int      | N            | ID del modo de seguridad |
| name         | string   | N            | Nombre de seguridad      |

Ejemplo

```json
// event.data
{
  "payload": {
    "arm_state": "arming",
    "detail": {
      "sid": 1,
      "name": "Modo Hogar"
    }
  }
}
```

## 6. TTS (**Función del motor de Texto a Voz)**

### 6.1 Instrucción

#### Rol clave

* Proveedor del servicio TTS: El proveedor del servicio del motor TTS es responsable de registrar el motor TTS en la pasarela y proporcionar servicios TTS
* Servidor de la pasarela：iHost
* Cliente de la API abierta de la pasarela

#### 6.1.1 Registro del servicio del motor TTS

1. 【Proveedor del servicio TTS】Llamar a la interfaz para registrar el motor TTS en la pasarela.
2. 【Servidor de la pasarela】Tras el registro exitoso, la pasarela almacenará la información básica del motor TTS (incluida la dirección del servicio server\_address, y la comunicación posterior entre la pasarela y el proveedor del servicio TTS se realizará a través de la dirección server\_address), y asignará el ID del servicio del motor TTS dentro de la pasarela.

![imagen.png](https://cdn.nlark.com/yuque/0/2023/png/22047218/1682410407751-a42da5c6-8eae-449a-bac8-057062015ee2.png#averageHue=%23f2f2f7\&clientId=u45d44337-5e8d-4\&from=paste\&height=265\&id=u21af0a56\&originHeight=331\&originWidth=773\&originalType=binary\&ratio=1.25\&rotation=0\&showTitle=false\&size=30392\&status=done\&style=none\&taskId=u7246aa77-a552-4d92-b0b6-b7d5b7e917f\&title=\&width=618.4)

#### 6.1.2 Obtener la lista de audios sintetizados

1. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de servicios de motor TTS registrados. Puede obtener la lista actual de motores TTS registrados (incluido el ID del motor TTS asignado por la pasarela).
2. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de audio de un motor TTS especificado. La pasarela emitirá una instrucción síncrona de lista de audio al proveedor de servicio TTS especificado y devolverá el resultado.

![imagen.png](https://cdn.nlark.com/yuque/0/2023/png/22047218/1682410445071-a30a391c-bcc4-47f0-b438-d9e83a0190a1.png#averageHue=%23f8f7f4\&clientId=u45d44337-5e8d-4\&from=paste\&height=496\&id=uc748ab88\&originHeight=620\&originWidth=1329\&originalType=binary\&ratio=1.25\&rotation=0\&showTitle=false\&size=74331\&status=done\&style=none\&taskId=u0c3f72bb-758d-4bc2-96f3-caba827f345\&title=\&width=1063.2)

#### 6.1.3 Síntesis de voz especificando un motor de voz

1. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de servicios de motor TTS registrados. Puede obtener la lista actual de motores TTS registrados (incluido el ID del motor TTS asignado por la pasarela).
2. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de audio de un motor TTS especificado. La pasarela emitirá una instrucción síncrona de lista de audio al proveedor de servicio TTS especificado y devolverá el resultado.

![imagen.png](https://cdn.nlark.com/yuque/0/2023/png/22047218/1682410917361-9964746e-f26f-43a8-b6e6-9fdc954d35b5.png#averageHue=%23f7f6f3\&clientId=ua8ae420e-0ec4-4\&from=paste\&height=497\&id=u9fcd52df\&originHeight=621\&originWidth=1161\&originalType=binary\&ratio=1.25\&rotation=0\&showTitle=false\&size=70309\&status=done\&style=none\&taskId=uc443bebc-76c6-4190-8360-536d864d369\&title=\&width=928.8)

#### 6.1.4 Sintetizar audio y reproducir discurso TTS.

1. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de servicios de motor TTS registrados. Puede obtener la lista actual de motores TTS registrados (incluido el ID del motor TTS asignado por la pasarela).
2. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de audio de un motor TTS especificado. La pasarela emitirá una instrucción síncrona de lista de audio al proveedor de servicio TTS especificado y devolverá el resultado. (incluida la dirección del archivo de audio TTS)
3. 【Cliente de la API abierta de la pasarela】Registrar la dirección del archivo de audio TTS del resultado devuelto en el paso anterior, llamar a la interfaz de reproducir archivo de audio y reproducirlo a través de la pasarela.

### 6.2 Módulo del motor TTS

#### 6.2.1 Capacidades abiertas de la pasarela

**a. Obtener la lista de servicios de motor TTS registrados**

:::consejos

* **URL**：`/open-api/V2/rest/tts/engines`
* **Método**：`GET`
* **Encabezado**：
  * Content-Type: application/json
  * Autorización: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos correcta:

| **Atributo** | **Tipo**         | **Opcional** | **Descripción**                  |
| ------------ | ---------------- | ------------ | -------------------------------- |
| motores      | EngineObject \[] | N            | Lista de motores TTS registrados |

Estructura de EngineObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                       |
| ------------ | -------- | ------------ | ------------------------------------- |
| id           | string   | N            | ID del motor asignado por la pasarela |
| name         | string   | N            | Nombre del servicio del motor TS      |

:::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： :::

```json
{
  "error": 0,
  "data": {
    "engines": [
      {
        "id": "id del motor",
        "name": "nombre del motor"
      }
    ]
  },
  "message": "success"
}
```

**b. Obtener la lista de audio de un motor TTS especificado**

:::consejos

* **URL**：`/open-api/V2/rest/tts/engine/{id}/audio-list`
* **Método**：`GET`
* **Encabezado**：
  * Content-Type: application/json
  * Autorización: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos correcta:

| **Atributo** | **Tipo**        | **Opcional** | **Descripción** |
| ------------ | --------------- | ------------ | --------------- |
| lista\_audio | AudioObject \[] | N            | Lista de audio  |

Estructura de AudioObject

| **Atributo**                                             | **Tipo** | **Opcional** | **Descripción**                        |
| -------------------------------------------------------- | -------- | ------------ | -------------------------------------- |
| url                                                      | string   | N            | URL del archivo de audio, por ejemplo: |
| <https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3> |          |              |                                        |
| etiqueta                                                 | string   | Y            | Etiqueta del archivo de audio          |

:::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` \*\*Código de error: \*\*

* 190000 El motor está funcionando anormalmente

**Ejemplo de respuesta:**： :::

```json
{
  "error": 0,
  "data": {
    "audio_list": [
      {
        "url": "dirección de audio tts", // por ejemplo: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "etiqueta de audio tts"
      }
    ]
  },
  "message": "success"
}
```

**c .Realizar síntesis de voz usando el motor TTS especificado**

:::consejos

* **URL**：`/open-api/V2/rest/tts/engine/{id}/synthesize`
* **Método**：`POST`
* **Encabezado**：
  * Content-Type: application/json
  * Autorización: Bearer ::: Parámetros de la solicitud:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| texto        | string   | N            | Texto usado para sintetizar el audio                                                                                                                                                                                                                                                                                                                                                                                               |
| etiqueta     | string   | Y            | Etiqueta del archivo de audio                                                                                                                                                                                                                                                                                                                                                                                                      |
| idioma       | string   | Y            | Campo transparente. Código de idioma opcional para la solicitud de síntesis de voz. La lista específica de códigos de idioma compatibles la proporciona el proveedor del servicio del motor TTS. Tenga en cuenta que el servicio del motor TTS necesita soportar un idioma predeterminado para la síntesis de voz, lo que significa que si no se pasa el idioma, se utilizará el idioma predeterminado del motor para la síntesis. |
| opciones     | object   | Y            | Campo transparente. Se utiliza para pasar los parámetros de configuración requeridos para la síntesis al servicio del motor de voz TTS.                                                                                                                                                                                                                                                                                            |

Respuesta de datos correcta:

| **Atributo** | **Tipo**    | **Opcional** | **Descripción** |
| ------------ | ----------- | ------------ | --------------- |
| audio        | AudioObject | N            | Lista de audio  |

Estructura de AudioObject

| **Atributo**                                             | **Tipo** | **Opcional** | **Descripción**                        |
| -------------------------------------------------------- | -------- | ------------ | -------------------------------------- |
| url                                                      | string   | N            | URL del archivo de audio, por ejemplo: |
| <https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3> |          |              |                                        |
| etiqueta                                                 | string   | Y            | Etiqueta del archivo de audio          |

:::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` \*\*Código de error: \*\*

* 190000 El motor está funcionando anormalmente

**Ejemplo de respuesta:**： :::

```json
{
  "error": 0,
  "data": {
    "audio": {
        "url": "dirección de audio tts" // por ejemplo, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "etiqueta de audio tts"
    }
  },
  "message": "success"
}
```

#### 6.2.2 Comunicación entre la pasarela y el servicio TTS

**a. Registro del servicio del motor TTS**

> Enviar solicitud a la pasarela por parte del proveedor del servicio TTS

:::consejos

* **URL**：`/open-api/V2/rest/thirdparty/event`
* **Método**：`POST`
* **Encabezado**：
  * Content-Type: application/json
  * Autorización: Bearer ::: Parámetros de la solicitud:

| **Atributo** | **Tipo**    | **Opcional** | **Descripción**                                                |
| ------------ | ----------- | ------------ | -------------------------------------------------------------- |
| evento       | EventObject | N            | Información de la estructura del objeto de evento de solicitud |

EventObject

| **Atributo** | **Tipo**      | **Opcional** | **Descripción**                           |
| ------------ | ------------- | ------------ | ----------------------------------------- |
| header       | HeaderObject  | N            | Estructura del encabezado de la solicitud |
| payload      | PayloadObject | N            | Estructura del payload de la solicitud    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                             |
| ------------ | -------- | ------------ | ------------------------------------------- |
| name         | string   | N            | Nombre de la solicitud. Parámetro opcional. |

* RegisterTTSEngine | | message\_id | string | N | ID del mensaje de la solicitud, UUID\_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

PayloadObject

| **Atributo**     | **Tipo** | **Opcional** | **Descripción**                                |
| ---------------- | -------- | ------------ | ---------------------------------------------- |
| service\_address | string   | N            | Dirección del servicio. Por ejemplo, http\:/// |
| name             | string   | N            | Nombre del servicio                            |

Ejemplo de solicitud:

```json
{
  "event": {
    "header": {
      "name": "RegisterTTSEngine",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "payload": {
        "service_address": "service_address",
        "name": "nombre del servicio tts"
    }
  }
}
```

\*\*Parámetros de respuesta correctos: \*\*

| **Atributo** | **Tipo**      | **Opcional** | **Descripción**                           |
| ------------ | ------------- | ------------ | ----------------------------------------- |
| header       | HeaderObject  | N            | Estructura del encabezado de la solicitud |
| payload      | PayloadObject | N            | Estructura del payload de la solicitud    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                            |
| ------------ | -------- | ------------ | ---------------------------------------------------------- |
| name         | string   | N            | Nombre del encabezado de la respuesta. Parámetro opcional: |

* Respuesta (Respuesta exitosa)
* ErrorResponse (Respuesta de error) | | message\_id | string | N | ID del mensaje del encabezado de la respuesta, UUID\_V4. Mensaje de la solicitud entrante aquí: header.message\_id | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

PayloadObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                       |
| ------------ | -------- | ------------ | ------------------------------------- |
| engine\_id   | string   | N            | ID del motor asignado por la pasarela |

:::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： ::: Ejemplo de respuesta correcta:：

```json
{
    "header": {
      "name": "Response",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "payload": {
      "engine_id": "id del motor"
    }
  }
```

\*\*Parámetros de respuesta anormales: \*\*

| **Atributo** | **Tipo** | **Opcional** | **Descripción** |
| ------------ | -------- | ------------ | --------------- |
| type         | string   | N            | Tipo de error   |

* INVALID\_PARAMETERS (Error de parámetros)
* AUTH\_FAILURE (Fallo de autenticación)
* INTERNAL\_ERROR (Error interno del servicio) | | description | string | N | Descripción del error |

Ejemplo de respuesta de error:：

```json
{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address no puede estar vacío" 
  }
}
```

**b. Comando de sincronización de la lista de audio**

> Enviar comando al proveedor del servicio TTS por parte de la pasarela.

:::consejos

* **URL**：`<dirección del servicio>`
* **Método**：`POST`
* **Encabezado**：
  * Content-Type: application/json ::: Parámetros de la solicitud:

| **Atributo** | **Tipo**        | **Opcional** | **Descripción**                                        |
| ------------ | --------------- | ------------ | ------------------------------------------------------ |
| directive    | DirectiveObject | N            | Información de la estructura del objeto de instrucción |

DirectiveObject

| **Atributo** | **Tipo**      | **Opcional** | **Descripción**                           |
| ------------ | ------------- | ------------ | ----------------------------------------- |
| header       | HeaderObject  | N            | Estructura del encabezado de la solicitud |
| payload      | PayloadObject | N            | Estructura del payload de la solicitud    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                             |
| ------------ | -------- | ------------ | ------------------------------------------- |
| name         | string   | N            | Nombre de la solicitud. Parámetro opcional: |

* SyncTTSAudioList | | message\_id | string | N | ID del mensaje de la solicitud, UUID\_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

Ejemplo de solicitud:

```json
{
  "directive": {
    "header": {
      "name": "SyncTTSAudioList",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "payload": {}
  }
}
```

\*\*Parámetros de respuesta correctos: \*\*

| **Atributo** | **Tipo**      | **Opcional** | **Descripción**                           |
| ------------ | ------------- | ------------ | ----------------------------------------- |
| header       | HeaderObject  | N            | Estructura del encabezado de la solicitud |
| payload      | PayloadObject | N            | Estructura del payload de la solicitud    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                            |
| ------------ | -------- | ------------ | ---------------------------------------------------------- |
| name         | string   | N            | Nombre del encabezado de la respuesta. Parámetro opcional: |

* Respuesta (Respuesta exitosa)
* ErrorResponse (Respuesta de error) | | message\_id | string | N | ID del mensaje del encabezado de la respuesta, UUID\_V4. Mensaje de la solicitud entrante aquí: header.message\_id | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

Objeto Payload:

| **Atributo** | **Tipo**        | **Opcional** | **Descripción**    |
| ------------ | --------------- | ------------ | ------------------ |
| lista\_audio | AudioObject \[] | N            | Lista de audio TTS |

Estructura de AudioObject

| **Atributo**                                             | **Tipo** | **Opcional** | **Descripción**                        |
| -------------------------------------------------------- | -------- | ------------ | -------------------------------------- |
| url                                                      | string   | N            | URL del archivo de audio, por ejemplo: |
| <https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3> |          |              |                                        |
| etiqueta                                                 | string   | Y            | Etiqueta del archivo de audio          |

:::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： ::: Ejemplo de respuesta correcta:：

```json
{
    "header": {
      "name": "Response",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "payload": {
      "audio_list": [
        {
            "url": "url de audio tts",
            "label": "etiqueta de audio tts"
        }
      ]
    }
}
```

\*\*Parámetros de respuesta anormales: \*\*

| **Atributo** | **Tipo** | **Opcional** | **Descripción** |
| ------------ | -------- | ------------ | --------------- |
| type         | string   | N            | Tipo de error   |

* INVALID\_PARAMETERS (Error de parámetros)
* AUTH\_FAILURE (Fallo de autenticación)
* INTERNAL\_ERROR (Error interno del servicio) | | description | string | N | Descripción del error |

Ejemplo de respuesta de error:：

```json
{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address no puede estar vacío" 
  }
}
```

**c. Comando de síntesis de voz**

> Enviar comando al proveedor del servicio TTS por parte de la pasarela.

:::consejos

* **URL**：`<dirección del servicio>`
* **Método**：`POST`
* **Encabezado**：
  * Content-Type: application/json ::: Parámetros de la solicitud:

| **Atributo** | **Tipo**        | **Opcional** | **Descripción**                                        |
| ------------ | --------------- | ------------ | ------------------------------------------------------ |
| directive    | DirectiveObject | N            | Información de la estructura del objeto de instrucción |

DirectiveObject

| **Atributo** | **Tipo**      | **Opcional** | **Descripción**                           |
| ------------ | ------------- | ------------ | ----------------------------------------- |
| header       | HeaderObject  | N            | Estructura del encabezado de la solicitud |
| payload      | PayloadObject | N            | Estructura del payload de la solicitud    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                             |
| ------------ | -------- | ------------ | ------------------------------------------- |
| name         | string   | N            | Nombre de la solicitud. Parámetro opcional: |

* SynthesizeSpeech | | message\_id | string | N | ID del mensaje de la solicitud: UUID\_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

PayloadObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| texto        | string   | N            | Texto usado para sintetizar el audio                                                                                                                                                                                                                                                                                                                                                                                               |
| etiqueta     | string   | Y            | Etiqueta del archivo de audio                                                                                                                                                                                                                                                                                                                                                                                                      |
| idioma       | string   | Y            | Campo transparente. Código de idioma opcional para la solicitud de síntesis de voz. La lista específica de códigos de idioma compatibles la proporciona el proveedor del servicio del motor TTS. Tenga en cuenta que el servicio del motor TTS necesita soportar un idioma predeterminado para la síntesis de voz, lo que significa que si no se pasa el idioma, se utilizará el idioma predeterminado del motor para la síntesis. |
| opciones     | object   | Y            | Campo transparente. Se utiliza para pasar los parámetros de configuración requeridos para la síntesis al servicio del motor de voz TTS.                                                                                                                                                                                                                                                                                            |

Ejemplo de solicitud:

```json
{
    "directive": {
        "header": {
            "name": "SynthesizeSpeech",
            "message_id": "Identificador único, preferiblemente un UUID versión 4",
            "version": "1"
        },
        "payload": {
            "text": "Texto de entrada para sintetizar.",
            "label": "etiqueta de audio tts"
        }
    }
}
```

\*\*Parámetros de respuesta correctos: \*\*

| **Atributo** | **Tipo**      | **Opcional** | **Descripción**                           |
| ------------ | ------------- | ------------ | ----------------------------------------- |
| header       | HeaderObject  | N            | Estructura del encabezado de la solicitud |
| payload      | PayloadObject | N            | Estructura del payload de la solicitud    |

HeaderObject

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                            |
| ------------ | -------- | ------------ | ---------------------------------------------------------- |
| name         | string   | N            | Nombre del encabezado de la respuesta. Parámetro opcional: |

* Respuesta (Respuesta exitosa)
* ErrorResponse (Respuesta de error) | | message\_id | string | N | ID del mensaje del encabezado de la respuesta, UUID\_V4. Mensaje de la solicitud entrante aquí: header.message\_id | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

PayloadObject

| **Atributo** | **Tipo**    | **Opcional** | **Descripción** |
| ------------ | ----------- | ------------ | --------------- |
| audio        | AudioObject | N            | Audio TTS       |

Estructura de AudioObject

| **Atributo**                                             | **Tipo** | **Opcional** | **Descripción**                        |
| -------------------------------------------------------- | -------- | ------------ | -------------------------------------- |
| url                                                      | string   | N            | URL del archivo de audio, por ejemplo: |
| <https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3> |          |              |                                        |
| etiqueta                                                 | string   | Y            | Etiqueta del archivo de audio          |

:::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： ::: Ejemplo de respuesta correcta:：

```json
{
    "header": {
      "name": "Response",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "1"
    },
    "payload": {
      "audio": {
        "url": "url de audio tts",
        "label": "etiqueta de audio tts"
      }
    }
}
```

\*\*Parámetros de respuesta anormales: \*\*

| **Atributo** | **Tipo** | **Opcional** | **Descripción** |
| ------------ | -------- | ------------ | --------------- |
| type         | string   | N            | Tipo de error   |

* INVALID\_PARAMETERS (Error de parámetros)
* AUTH\_FAILURE (Fallo de autenticación)
* INTERNAL\_ERROR (Error interno del servicio) | | description | string | N | Descripción del error |

Ejemplo de respuesta de error:：

```json
{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Identificador único, preferiblemente un UUID versión 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address no puede estar vacío" 
  }
}
```

## 7. Módulo multimedia

### 7.1 Reproducir archivo de audio

:::consejos

* **URL**：`/open-api/V2/rest/media/audio-player`
* **Método**：`POST`
* **Encabezado**：
  * Content-Type: application/json
  * Autorización: Bearer ::: Parámetros de la solicitud:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**         |
| ------------ | -------- | ------------ | ----------------------- |
| audio\_url   | string   | N            | Dirección URL del audio |

Respuesta de datos correcta: :::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： :::

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

## 8. Tarjeta de UI personalizada

Las tarjetas de UI personalizadas le permiten mostrar cualquier contenido que desee dentro de la tarjeta. Este contenido puede ser una página web, una imagen o cualquier servicio con una interfaz de usuario. Solo necesita proporcionar la URL del contenido que desea mostrar. La tarjeta de UI ajustará automáticamente su ancho y alto, y el contenido se renderizará usando un iFrame.

### 8.1 Instrucción

#### Rol clave

* **Proveedor de servicio UI**: El proveedor responsable de crear tarjetas de UI personalizadas en la pasarela.
* **Servidor de la pasarela**: El servidor de la pasarela (iHost).
* **Cliente de la API abierta de la pasarela**: El cliente Open API para la pasarela.

#### 8.1.1 Crear una tarjeta de UI personalizada

* **\[Proveedor de servicio UI]**: Llama a la API para crear una tarjeta de UI personalizada en la pasarela.
* **\[Servidor de la pasarela]**: Tras el registro exitoso, la pasarela almacena la información básica de la tarjeta de UI (incluida la configuración de tamaño y la URL del recurso de la tarjeta) y asigna un ID interno de tarjeta de UI dentro de la pasarela.

![imagen.png](https://cdn.nlark.com/yuque/0/2024/png/22047218/1724982838404-2b695ed3-7a2b-47d2-ac65-c39a5d3fe1d0.png#averageHue=%23c9a16f\&clientId=u439c4629-8156-4\&from=paste\&height=291\&id=ub19948aa\&originHeight=364\&originWidth=780\&originalType=binary\&ratio=1.25\&rotation=0\&showTitle=false\&size=26903\&status=done\&style=none\&taskId=uf73f6593-c0ac-42a2-8bac-b2a16ce816f\&title=\&width=624)

#### 8.1.2 Recuperar la lista de tarjetas de UI

* **\[Proveedor de servicio UI]**: Llama a la API para recuperar la lista de tarjetas de UI.
* **\[Servidor de la pasarela]**: Devuelve la lista de tarjetas de UI almacenadas en la pasarela, incluidas las tarjetas de UI personalizadas no creadas por el llamador.

![imagen.png](https://cdn.nlark.com/yuque/0/2024/png/22047218/1724983804263-a22d3cb4-fdd4-4755-8acd-0206663abb1a.png#averageHue=%23c69e6e\&clientId=u439c4629-8156-4\&from=paste\&height=255\&id=ufd03ef34\&originHeight=364\&originWidth=876\&originalType=binary\&ratio=1.25\&rotation=0\&showTitle=false\&size=30872\&status=done\&style=none\&taskId=ua6dd934e-3968-463c-9ffc-0399969518e\&title=\&width=612.7999877929688)

#### 8.1.3 Modificar la configuración de una tarjeta de UI especificada

* **\[Proveedor de servicio UI]**: Llama a la API para modificar la configuración de una tarjeta de UI especificada, como la configuración de tamaño y la URL del recurso.
* **\[Servidor de la pasarela]**: Tras la modificación exitosa, la pasarela almacena la información actualizada de la tarjeta de UI, incluida la nueva configuración de tamaño y la URL del recurso.

![imagen.png](https://cdn.nlark.com/yuque/0/2024/png/22047218/1724984308463-64009770-d1f2-4a0e-b5fa-e86e5d47f31f.png#averageHue=%23c8a071\&clientId=u439c4629-8156-4\&from=paste\&height=284\&id=u52ce1bea\&originHeight=355\&originWidth=826\&originalType=binary\&ratio=1.25\&rotation=0\&showTitle=false\&size=30728\&status=done\&style=none\&taskId=u59a577f7-7b46-4b6c-93c4-46c12a3a11a\&title=\&width=660.8)

#### 8.1.4 Eliminar una tarjeta de UI personalizada

1. **\[Proveedor de servicio UI]**: Llama a la API para eliminar una tarjeta de UI personalizada especificada.
2. **\[Servidor de la pasarela]**: La pasarela eliminará toda la información relacionada con la tarjeta de UI especificada.

![imagen.png](https://cdn.nlark.com/yuque/0/2024/png/22047218/1724984941140-e2007862-1585-48cc-8c7b-21a5029bcf00.png#averageHue=%23d9b884\&clientId=u439c4629-8156-4\&from=paste\&height=289\&id=ud6455daf\&originHeight=361\&originWidth=690\&originalType=binary\&ratio=1.25\&rotation=0\&showTitle=false\&size=25122\&status=done\&style=none\&taskId=ua34f780d-7908-45b8-8a25-77faaaecc25\&title=\&width=552)

### 8.2 Módulo de tarjeta de UI personalizada

#### 8.2.1 Crear una tarjeta de UI personalizada

> El proveedor de servicio UI envía una solicitud a la pasarela para crear una tarjeta de UI personalizada.

:::consejos

* **URL**：`/open-api/v2/rest/ui/cards`
* **Método**：`POST`
* **Encabezado**：
  * Content-Type: application/json
  * Autorización: Bearer ::: Parámetros de la solicitud:

| **Atributo**          | **Tipo**           | **Opcional** | **Descripción**                                                                          |
| --------------------- | ------------------ | ------------ | ---------------------------------------------------------------------------------------- |
| etiqueta              | string             | Y            | Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Es el alias de la tarjeta. |
| configuraciones\_cast | CastSettingsObject | Y            | Configuración de tarjeta Cast: Ajustes de configuración para tarjetas cast.              |
| configuraciones\_web  | WebSettingsObject  | N            | Configuración de tarjeta Web: Ajustes de configuración para tarjetas web.                |

CastSettingsObject:

| **Atributo** | **Tipo**            | **Opcional** | **Descripción**                                                                                                  |
| ------------ | ------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------- |
| dimensiones  | DimensionObject \[] | N            | Configuración de tamaño: Debe incluir al menos una configuración.                                                |
| default      | string              | N            | Especificación predeterminada: La especificación de tamaño predeterminada se usa, con parámetros opcionales: 2x2 |

WebSettingsObject:

| **Atributo**      | **Tipo**            | **Opcional** | **Descripción**                                                   |
| ----------------- | ------------------- | ------------ | ----------------------------------------------------------------- |
| dimensiones       | DimensionObject \[] | N            | Configuración de tamaño: Debe incluir al menos una configuración. |
| componente\_cajón | DrawerObject        | Y            | Ajustes de visualización del componente cajón.                    |
| default           | string              | N            | Especificación predeterminada:                                    |

* 1x1
* 2x1 |

DimensionObject:

| **Atributo**                                 | **Tipo** | **Opcional** | **Descripción**                                     |
| -------------------------------------------- | -------- | ------------ | --------------------------------------------------- |
| src                                          | string   | N            | URL del recurso: Por ejemplo: <http://example.html> |
| tamaño                                       | string   | N            | Especificaciones de tamaño:                         |
| Parámetros opcionales de CastSettingsObject: |          |              |                                                     |

* 2×2

Parámetros opcionales de WebSettingsObject:

* 1x1
* 2x1 |

DrawerObject:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                     |
| ------------ | -------- | ------------ | --------------------------------------------------- |
| src          | string   | N            | URL del recurso: Por ejemplo: <http://example.html> |

Respuesta de datos exitosa:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**           |
| ------------ | -------- | ------------ | ------------------------- |
| id           | string   | N            | ID único de la tarjeta UI |

:::consejos **Condiciones**: Los parámetros de la solicitud son legales y se ha pasado la verificación de identidad del usuario. \*\*Código de estado: \*\* `200 OK` ::: Ejemplo de solicitud：

```json
{
  "label": "tarjeta ewelink cube",
  "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"
  }
}
```

Ejemplo de respuesta:

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

#### 8.2.2 Recuperar la lista de tarjetas UI

:::consejos

* **URL**：`/open-api/v2/rest/ui/cards`
* **Método**：`GET`
* **Encabezado**：
  * Content-Type: application/json
  * Autorización: Bearer ::: Parámetros de la solicitud: Ninguno Parámetros de respuesta:

| **Atributo** | **Tipo**      | **Opcional** | **Descripción**      |
| ------------ | ------------- | ------------ | -------------------- |
| data         | CardObject\[] | N            | Lista de tarjetas UI |

Objeto CardObjec:

| **Atributo**          | **Tipo**           | **Opcional** | **Descripción**                                                                                        |
| --------------------- | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------ |
| id                    | string             | N            | ID de la tarjeta: Un identificador único para la tarjeta.                                              |
| etiqueta              | string             | Y            | Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Sirve como alias o nombre de la tarjeta. |
| configuraciones\_cast | CastSettingsObject | Y            | Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Es el alias de la tarjeta.               |
| configuraciones\_web  | WebSettingsObject  | N            | Configuración de tarjeta Cast: Ajustes de configuración para tarjetas cast.                            |
| app\_name             | string             | Y            | Configuración de tarjeta Web: Ajustes de configuración para tarjetas web.                              |

CastSettingsObject:

| **Atributo**            | **Tipo**            | **Opcional** | **Descripción**                                                   |
| ----------------------- | ------------------- | ------------ | ----------------------------------------------------------------- |
| dimensiones             | DimensionObject \[] | N            | Configuración de tamaño: Debe incluir al menos una configuración. |
| default                 | string              | N            | Especificación predeterminada:                                    |
| Parámetro opcional: 2x2 |                     |              |                                                                   |
| usado                   | string              | N            | Especificación actual:                                            |
| Parámetro opcional: 2x2 |                     |              |                                                                   |

WebSettingsObject:

| **Atributo**        | **Tipo**            | **Opcional** | **Descripción**                                                   |
| ------------------- | ------------------- | ------------ | ----------------------------------------------------------------- |
| dimensiones         | DimensionObject \[] | N            | Configuración de tamaño: Debe incluir al menos una configuración. |
| componente\_cajón   | DrawerObject        | Y            | Ajustes de visualización del componente cajón.                    |
| default             | string              | N            | Especificación predeterminada:                                    |
| Parámetro opcional: |                     |              |                                                                   |

* 1x1
* 2x1 | | used | string | N | Especificación actual: Parámetro opcional:
* 1x1
* 2x1 |

DimensionObject:

| **Atributo**        | **Tipo** | **Opcional** | **Descripción**                                     |
| ------------------- | -------- | ------------ | --------------------------------------------------- |
| src                 | string   | N            | URL del recurso: Por ejemplo: <http://example.html> |
| tamaño              | string   | N            | Especificaciones de tamaño:                         |
| Parámetro opcional: |          |              |                                                     |

* 1x1
* 2x1

**Nota**: Actualmente, las tarjetas cast solo admiten la especificación 2x2. La especificación 2x2 no tendrá efecto. |

DrawerObject:

| **Atributo** | **Tipo** | **Opcional** | **Descripción**                                     |
| ------------ | -------- | ------------ | --------------------------------------------------- |
| src          | string   | N            | URL del recurso: Por ejemplo: <http://example.html> |

Ejemplo de respuesta:

```json
{
  "error": 0,
  "data": [
    {
      "id": "72cc5a4a-f486-4287-857f-b482d7818b16",
      "label": "tarjeta ewelink cube",
      "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 Modificar la configuración de una tarjeta UI especificada

> Los usuarios autorizados pueden modificar la configuración de una tarjeta UI existente a través de esta interfaz. Los proveedores de servicios de tarjetas personalizadas solo pueden modificar las tarjetas UI que ellos hayan creado.

:::consejos

* **URL**：`/open-api/v2/rest/ui/cards/{id}`
* **Método**：`PUT`
* **Encabezado**：
  * Content-Type: application/json
  * Autorización: Bearer ::: Parámetros de la solicitud:

| **Atributo**          | **Tipo**           | **Opcional** | **Descripción**                                             |
| --------------------- | ------------------ | ------------ | ----------------------------------------------------------- |
| etiqueta              | string             | Y            | Usado para describir la tarjeta. Es el alias de la tarjeta. |
| configuraciones\_cast | CastSettingsObject | Y            | Configuración de tarjeta Cast                               |
| configuraciones\_web  | WebSettingsObject  | Y            | Configuración de tarjeta Web                                |

CastSettingsObject:

| **Atributo**        | **Tipo** | **Opcional**                                                                                          | **Descripción**        |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------- | ---------------------- |
| usado               | string   | Y, Cualquiera `usado` o `src` debe proporcionarse, pero se requiere al menos uno de estos parámetros. | Especificación actual: |
| Parámetro opcional: |          |                                                                                                       |                        |

* 2x2

\| | src | string | Y, Cualquiera `usado` o `src` debe proporcionarse, pero se requiere al menos uno de estos parámetros. | URL del recurso: <http://example.html> |

WebSettingsObject:

| **Atributo**        | **Tipo** | **Opcional**                                                                                          | **Descripción**        |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------- | ---------------------- |
| usado               | string   | Y, Cualquiera `usado` o `src` debe proporcionarse, pero se requiere al menos uno de estos parámetros. | Especificación actual: |
| Parámetro opcional: |          |                                                                                                       |                        |

* 1x1
* 2x1 | | src | string | Y, Cualquiera `usado` o `src` debe proporcionarse, pero se requiere al menos uno de estos parámetros. | URL del recurso: <http://example.html> |

Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. La tarjeta UI que se está modificando debe haber sido creada por el proveedor de tarjeta UI personalizada que llama a la interfaz. \*\*Código de estado: \*\* `200 OK` **Código de error:**

* **406**: Sin permiso para acceder a este recurso ::: \*\*Ejemplo de respuesta: \*\*

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

\*\*Ejemplo de solicitud: \*\*

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

#### 8.2.4 Eliminar tarjeta UI personalizada

> Los usuarios autorizados pueden eliminar una tarjeta UI existente utilizando esta interfaz. Los proveedores de tarjetas personalizadas solo pueden eliminar las tarjetas UI que hayan creado.

:::consejos

* **URL**：`/open-api/v2/rest/ui/cards/{id}`
* **Método**：`DELETE`
* **Encabezado**：
  * Content-Type: application/json
  * Autorización: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. La tarjeta UI que se está modificando debe haber sido creada por el proveedor de tarjeta UI personalizada que llama a la interfaz. \*\*Código de estado: \*\* `200 OK` **Código de error:**
* **406**: Sin permiso para acceder a este recurso. ::: \*\*Ejemplo de respuesta: \*\*

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