Guía para desarrolladores y 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.

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

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 Comenzar

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

// 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 <Hecho> y llame de nuevo a la interfaz [Access Token]. La respuesta es exitosa y se obtiene el token.

// 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"
}

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

// 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], la página de la consola web de CUBE mostrará un cuadro emergente global que solicita al usuario confirmar la adquisición de las credenciales de llamada de 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 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 API web de la pasarela tiene dos métodos de acceso (basado en IP o nombre de dominio), usualmente 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 utiliza 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. Como control de energía, 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 único a nivel global y de tipo cadena. Varias palabras en inglés deben separarse con guiones ("-"). Por ejemplo: "thermostat-target-setpoint".

  • name: Describe la categoría dentro de la capacidad, también de tipo cadena. Varias palabras en inglés deben separarse con guiones ("-"). Por ejemplo: "auto-mode", "manual-mode".

  • permission: Describe los permisos asociados con la capacidad. El tipo es cadena, formateado en un código binario 8421. Ejemplos incluyen:

    • Dispositivo controlable: "1000"

    • Dispositivo configurable: "0010"

    • Dispositivo controlable y configurable: "1010"

    • Dispositivo controlable e informable: "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

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 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"

Pautas 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 por defecto del elemento de configuración) y values (que describe los valores seleccionables para el elemento de configuración) son campos opcionales.

2. Cuando **type = numeric**:

   • El campo value 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 por defecto)

3. Cuando **type = object**:

   • El campo value 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 value 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 value el campo es obligatorio si permission permite la modificación ("10" o "11").

   • El default el campo es opcional. |

// 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 en coma flotante de doble precisión de 64 bits IEEE 754
int	Tipo de dato entero.
object	Tipo de dato objeto. Objeto compatible con JSON
string[]	Array de strings
int[]	Array de enteros
object[]	Array 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:

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

{
  "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 (Dispositivo descubierto)

• system Armed (Sistema armado habilitado)

• system Disarmed (Sistema armado deshabilitado)

• factoryReset (Restablecer dispositivo) |

3.1 La función de la pasarela

a. Token de acceso

Permite a los usuarios obtener el token de acceso.

• Aviso: El token se borrará después del reinicio del dispositivo.

• Aviso: Después de obtener el token, debe presionar el botón nuevamente 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 largo 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:

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

Respuesta de datos en caso de fallo：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:

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

b. Obtener el estado de la pasarela

Permite a los usuarios autorizados obtener el estado de la pasarela a través de esta interfaz :::consejos

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

• Método：GET

• Encabezado：

  • Content-Type: application/json

  • Autorization: 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	La ú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 posición decimal de precisión
*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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

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

Permite a los usuarios autorizados configurar la pasarela a través de esta interfaz :::consejos

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

  • Autorization: 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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

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

d. Obtener la información de la pasarela

Permite a los usuarios autorizados obtener la información de la pasarela a través de 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 de 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:

{
  "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 a través de 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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

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

f. Quitar silencio de la pasarela

Permite a los usuarios autorizados quitar el silencio de la pasarela a través de 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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

{
  "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 a través de 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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

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

3.2 Función de hardware

a. Reiniciar la pasarela

Permite al usuario autorizado reiniciar la pasarela a través de esta interfaz :::consejos

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

  • Autorization: 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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK :::

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

b. Control del altavoz

Permite a los usuarios autorizados controlar el altavoz a través de 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: segundos. [0,1799]

BeepObject

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

Respuesta de datos exitosa: Objeto vacío {} :::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:

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

3.3 Función de gestión de dispositivos

a. Tipos de dispositivos compatibles

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
Ventilador-luz	fanLight	≥ 2.1.0
Aire acondicionado	airConditioner	≥ 2.1.0
Ventilador	fan	≥ 2.1.0
Termostato	thermostat	≥ 2.1.0

b. Capacidades de dispositivo compatibles

Interruptor de encendido (power):

Ejemplo de declaración de capacidad:

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

Atributo de estado:

{
  "powerState": "on", // El campo powerState indica el estado de encendido/apagado. Obligatorio. **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, 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}. Obligatorio. **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"
    }
  }
}

Inching 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 inching está habilitada. **Tipo:** Boolean. Obligatorio.
              "inchingSwitch": "off", // Configuración del interruptor inching. **Tipo:** String. Obligatorio. "off" (apagado), "on" (encendido)
              "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Obligatorio.
              "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 inching está habilitada. **Tipo:** Boolean. Obligatorio.
              "inchingSwitch": "off", // Configuración del interruptor inching. **Tipo:** String. Obligatorio. "off" (apagado), "on" (encendido)
              "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Obligatorio.
              "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 inching está habilitada. **Tipo:** Boolean. Obligatorio.
              "inchingSwitch": "off", // Configuración del interruptor inching. **Tipo:** String. Obligatorio. "off" (apagado), "on" (encendido)
              "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Obligatorio.
              "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 inching está habilitada. **Tipo:** Boolean. Obligatorio.
              "inchingSwitch": "off", // Configuración del interruptor inching. **Tipo:** String. Obligatorio. "off" (apagado), "on" (encendido)
              "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Obligatorio.
              "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 el más claro.)

json
复制代码
{
  "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 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 color rojo en el espacio de color RGB. Obligatorio. **Tipo:** Number. Rango: 0-255.
  "green": 0, // El campo green representa el color verde en el espacio de color RGB. Obligatorio. **Tipo:** Number. Rango: 0-255.
  "blue": 255 // El campo blue representa el color azul en el espacio de color RGB. Obligatorio. **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 por porcentaje (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. Obligatorio. **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. Obligatorio. **Tipo:** Boolean. true indica avance, false indica reverso.
}

Protocolo (Consulta de estado e instrucciones de control):

Configurar motor hacia adelante:

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

Calibración del 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. Obligatorio. **Tipo:** String. "normal" indica modo normal (calibrado), "calibration" indica calibración en curso.
}

Protocolo (Reporte de estado):

Informar que el motor está siendo calibrado:

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

Estado de encendido al iniciar (startup)

Ejemplo de declaración de capacidad:

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

Atributos (Estado):

{
  "startup": "on" // Estado de energía al iniciar. **Tipo:** String. Obligatorio. 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 encendido siempre activado:

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

---

Activación de despertador (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 del despertador:

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

Informar estado de activación:

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

Estadísticas de consumo de energía 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. Obligatorio.
  "timeRange": { // Rango de tiempo resumido. Obligatorio.
    "start": "2020-07-05T08:00:00Z", // Hora de inicio de las estadísticas de consumo de energía. **Tipo:** String. Obligatorio.
    "end": "2020-07-05T09:00:00Z" // Hora de fin de las estadísticas de consumo de energía. **Tipo:** String. Obligatorio.
  }
}

Consultar consumo de energía por rango de tiempo:

{
  "type": "summarize", // Tipo de estadísticas. **Tipo:** String. Obligatorio. Valores opcionales: "rlSummarize" (resumen en tiempo real), "summarize" (resumen actual).
  "timeRange": { // Rango de tiempo resumido. Obligatorio si type es "summarize".
    "start": "2020-07-05T08:00:00Z", // Hora de inicio de las estadísticas de consumo de energía. **Tipo:** String. Obligatorio.
    "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 el resultado de estadísticas dentro del rango de tiempo:

json
 
{
  "type": "summarize", // Tipo de estadísticas. **Tipo:** String. Obligatorio. 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. Obligatorio.
      "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Date. Obligatorio.
      "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Date. Obligatorio. 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. Obligatorio.
      "start": "2020-07-05T09:00:00Z", // Hora de inicio. **Tipo:** Date. Obligatorio.
      "end": "2020-07-05T10:00:00Z" // Hora de fin. **Tipo:** Date. Obligatorio. 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 de energía histórico:

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. Obligatorio. Valores opcionales: "humidity" (detección de humedad), "temperature" (detección de temperatura).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Ajustes de detección compatibles. Obligatorio.
          {
            "name": "lowerSetpoint", // El valor detectado debe estar por encima de este punto de ajuste. Se requiere al menos uno de lowerSetpoint o upperSetpoint.
            "value": { // Rango de detección. Opcional. Especificar si existen condiciones preestablecidas.
              "value": 68.0, // Valor de temperatura. **Tipo:** Number. Obligatorio.
              "scale": "f" // Unidad de temperatura. Obligatorio 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 uno de lowerSetpoint o upperSetpoint.
            "value": { // Rango de detección. Opcional. Especificar si existen condiciones preestablecidas.
              "value": 68.0, // Valor de temperatura. **Tipo:** Number. Obligatorio.
              "scale": "f" // Unidad de temperatura. Obligatorio 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. Obligatorio. Valores opcionales: "humidity" (detección de humedad), "temperature" (detección de temperatura).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Ajustes de detección compatibles. Obligatorio.
          {
            "name": "lowerSetpoint", // El valor detectado debe estar por encima de este punto de ajuste. Se requiere al menos uno de lowerSetpoint o upperSetpoint.
            "value": { // Rango de detección. Opcional. Especificar si existen condiciones preestablecidas.
              "value": 68.0, // Valor de humedad. **Tipo:** Number. Obligatorio
            }
          },
          {
            "name": "upperSetpoint", // El valor detectado debe estar por debajo de este punto de ajuste. Se requiere al menos uno de lowerSetpoint o upperSetpoint.
            "value": { // Rango de detección. Opcional. Especificar si existen condiciones preestablecidas.
              "value": 68.0, // Valor de humedad. **Tipo:** Number. Obligatorio
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

Atributos (Estado):

{
  "mode": "COMFORT" // ID de 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 del 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. P. ej., 7:20 AM = 440 minutos.
            "upperSetpoint": 36.5, // Temperatura objetivo máxima. **Tipo:** number.
            "lowerSetpoint": 20 // Temperatura objetivo mínima. **Tipo:** number.
          },
          {
            "startTimeInMinutes": 900, // Hora de inicio en minutos. P. ej., 3:00 PM = 900 minutos.
            "upperSetpoint": 26.5, // Temperatura objetivo máxima. **Tipo:** number.
            "lowerSetpoint": 21 // Temperatura objetivo mínima. **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 sin 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
复制代码
{
  "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 del 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 única o corta), "doublePress" (doble pulsación), "longPress" (pulsación larga).
}

Protocolo (Consulta de estado e instrucciones de control):

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

Detección de múltiples pulsaciones (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 del 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 única o corta), "doublePress" (doble pulsación), "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 la 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 luminosidad. **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 fallos (fault)

Ejemplo de declaración de capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de estado e instrucciones de control):

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

Disyuntor 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", // Disyuntor 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", // Disyuntor 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", // Disyuntor 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", // Disyuntor 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", // Disyuntor 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", // Disyuntor 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": { // Configuración de habilitación de la función inch
      "permission": "11",
      "type": "boolean",
      "value": false
    },
    "inchingSwitch": { // Configuración de la acción inch
      "type": "enum",
      "permission": "11",
      "value": "on",
      "values": ["on", "off"]
    },
    "inchingDelay": { // Configuración del 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. Obligatorio.
        "password": "String", // Contraseña de acceso. **Tipo:** String. Obligatorio.
        "streamUrl": "rtsp://<username>:<password>@<hostname>:<port>/streaming/channel01", // URL de transmisión. **Tipo:** String. Obligatorio.
        "videoCodec": "", // Códec de video. **Tipo:** String. Obligatorio. Parámetros opcionales a definir.
        "resolution": { // Resolución de video. Obligatorio.
          "width": 1080, // Ancho. **Tipo:** Number. Obligatorio.
          "height": 720 // Alto. **Tipo:** Number. Obligatorio.
        },
        "keyFrameInterval": 5, // Intervalo de fotograma clave. **Tipo:** String. Obligatorio.
        "audioCodec": "G711", // Códec de audio. **Tipo:** String. Obligatorio. Parámetros opcionales a definir.
        "samplingRate": 50, // Tasa de muestreo de audio, en Hz. **Tipo:** Number. Obligatorio. Parámetros opcionales a definir.
        "dataRate": 50 // Tasa de bits. **Tipo:** Number. Obligatorio. 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 de modo. **Tipo:** String. Obligatorio. 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 sin 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 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 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 que la alimentación está encendida, `off` indica que la alimentación está apagada.
}

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 que la alimentación está encendida, `off` indica que la alimentación está apagada.
}

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 que la alimentación está encendida, `off` indica que la alimentación está apagada.
}

Protocolo (Consulta de estado e instrucciones de control):

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

Interruptor de 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 que la alimentación está encendida, `off` indica que la alimentación está apagada.
}

Protocolo (Consulta de estado e instrucciones de control):

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

Interruptor de 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 que la alimentación está encendida, `off` indica que la alimentación está apagada.
}

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 que la alimentación está encendida, `off` indica que la alimentación está apagada.
}

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 habilitar 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 de 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 reporta autoactivación
{
  "toggle-identify": {
    "1": {
      "identify": true
    }
  }
}

Detección de voltaje alterno (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 de 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 de 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 actual de potencia. **Unidad:** 0.01 W. **Tipo:** Entero. El valor debe ser mayor o igual a 0.
  "reactivePower": 50, // El campo `reactivePower` representa el valor actual de potencia reactiva. **Unidad:** 0.01 W. **Tipo:** Entero. Opcional.
  "activePower": 50, // El campo `activePower` representa el valor actual de potencia activa. **Unidad:** 0.01 W. **Tipo:** Entero. Opcional.
  "apparentPower": 50 // El campo `apparentPower` representa el valor actual de potencia aparente. **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 de subcomponentes (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. Obligatorio.
  "timeRange": { // Rango de tiempo para resumen. Obligatorio.
    "start": "2020-07-05T08:00:00Z", // Hora de inicio del consumo de energía. **Tipo:** Cadena. Obligatorio.
    "end": "2020-07-05T09:00:00Z" // Hora de fin del consumo de energía. **Tipo:** Cadena. Obligatorio.
  }
}

Consultar consumo de energía por rango de tiempo:

{
  "type": "summarize", // Tipo de resumen. **Tipo:** Cadena. Obligatorio. Opciones: "rlSummarize" (resumen en tiempo real), "summarize" (resumen actual).
  "timeRange": { // Rango de tiempo para resumen, obligatorio cuando el tipo es "summarize".
    "start": "2020-07-05T08:00:00Z", // Hora de inicio del consumo de energía. **Tipo:** Cadena. Obligatorio.
    "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. Obligatorio.
  "rlSummarize": 50.0, // Consumo total de energía. **Unidad:** 0.01 kWh. **Tipo:** Número. Opcional.
  "electricityIntervals": [ // Dividido por `configuration.resolution` en múltiples registros. Opcional. No presente cuando el tipo es "rlSummarize".
    {
      "usage": 26.5, // Consumo de energía. **Unidad:** 0.01 kWh. **Tipo:** Número. Obligatorio.
      "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Cadena. Obligatorio.
      "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Cadena. Obligatorio. 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. Obligatorio.
      "start": "2020-07-05T09:00:00Z", // Hora de inicio. **Tipo:** Cadena. Obligatorio.
      "end": "2020-07-05T10:00:00Z" // Hora de fin. **Tipo:** Cadena. Obligatorio. 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 de energía histórico:

{
  "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 valores: 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. Obligatorio.
    "maxResolution": 86400, // Resolución máxima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio.
    "minResolution": 60 // Resolución mínima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio.
  }
}

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. Obligatorio.
      "maxResolution": 86400, // Resolución máxima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio.
      "minResolution": 60 // Resolución mínima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio.
    }
  }
}

Sistema (system)

Ejemplo de declaración de capacidad:

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

Atributos (Estado):

{
  "restart": true // Comando para reiniciar el dispositivo. **Tipo:** Booleano. Obligatorio. 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. Obligatorio. 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. Obligatorio. Debe ser menor que `max`.
        "max": 1100 // Valor máximo. **Tipo:** Entero. Obligatorio. Debe ser mayor que `min`.
      }
    }
  }
]

Atributos (Estado):

{
  "barometricPressure": 50 // Valor de presión barométrica. **Tipo:** Entero. Obligatorio. **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. Obligatorio. Debe ser menor que `max`.
        "max": 50 // Valor máximo. **Tipo:** Número. Obligatorio. Debe ser mayor que `min`.
      }
    }
  }
]

Atributos (Estado):

{
  "windSpeed": 50 // Valor de velocidad del viento. **Tipo:** Número. Obligatorio. **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. Obligatorio. **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. Obligatorio. Debe ser menor que `max`.
        "max": 450 // Valor máximo. **Tipo:** Número. Obligatorio. Debe ser mayor que `min`.
      }
    }
  }
]

Atributos (Estado):

{
  "rainfall": 11.11 // Valor de precipitación. **Tipo:** Número. Obligatorio. **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. Obligatorio. Debe ser menor que `max`.
        "max": 16 // Valor máximo. **Tipo:** Número. Obligatorio. Debe ser mayor que `min`.
      }
    }
  }
]

Atributos (Estado):

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

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. Obligatorio. Debe ser menor que `max`.
        "max": 23 // Valor máximo. **Tipo:** Número. Obligatorio. Debe ser mayor que `min`.
      }
    }
  }
]

Atributos (Estado):

{
  "electricalConductivity": 11.11 // Valor de conductividad eléctrica. **Tipo:** Número. Obligatorio. **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. Obligatorio. **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. Obligatorio. **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. Obligatorio. **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. Obligatorio.
}

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. Obligatorio. Opciones: "oneDay", "30Days", "180Days".
    "timeRange": { // Rango de tiempo para agregación. **Tipo:** Objeto. Obligatorio.
      "start": "2020-07-05T08:00:00Z", // Hora de inicio para la agregación de datos de riego. **Tipo:** Cadena. Obligatorio.
      "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. Obligatorio.
    "irrigationIntervals": [
      {
        "volume": 6500, // Volumen de riego. **Tipo:** Número. Obligatorio. **Unidad:** L.
        "duration": 30, // Duración del riego. **Tipo:** Número. Obligatorio. **Unidad:** minutos.
        "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Cadena. Obligatorio.
        "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Cadena. Obligatorio.
      },
      {
        "volume": 6500, // Volumen de riego. **Tipo:** Número. Obligatorio. **Unidad:** L.
        "duration": 30, // Duración del riego. **Tipo:** Número. Obligatorio. **Unidad:** minutos.
        "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Cadena. Obligatorio.
        "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Cadena. Obligatorio.
      }
    ]
  }
}

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 de un solo 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 de un solo tiempo o repetida:

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

Volumen único o repetido:

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

Protocolo (Consulta de estado e instrucciones de control):

Programación de un solo tiempo o repetida:

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

Volumen único o repetido:

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

Modos preestablecidos compatibles

**Nombres de modo **	**Valores opcionales **
fanLevel (nivel de 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 de 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 usa para establecer el nombre del subcomponente toggle.

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

• La clave especial temperature_unit se usa 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 de 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 desconectado	≥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 la cámara es incorrecta	≥2.1.0
110010	Error de autorización de acceso al dispositivo de la cámara	≥2.1.0
110011	Error en la dirección de flujo de la cámara	≥2.1.0
110012	La codificación de video de la 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 flujo 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 del servicio del dispositivo de terceros	≥2.1.0

e. Buscar subdispositivo

Permitir a usuarios autorizados habilitar o deshabilitar la búsqueda de subdispositivos en la pasarela a través de esta interfaz

• 💡Nota: Actualmente solo se 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

  • Autorization: Bearer ::: Parámetros de la solicitud:

Atributo	Tipo	Opcional	Descripción
habilitar	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 la verificación de identidad del usuario ha pasado. **Código de estado: ** 200 OK ::: Ejemplo de respuesta:

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

f. Agregar manualmente el subdispositivo

Permitir a usuarios autorizados agregar 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

  • Autorization: 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 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 del 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 flujo de 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 value	StreamSettingValueObject	N	Valores de configuración específicos

StreamSettingValueObject

Atributo	Tipo	Opcional	Descripción
stream_url	string	N	Formato de URL de flujo
Formato:<schema>://<hostname>:<port>/<username>:<password>@<service_path>
Ejemplo:rtsp://admin:[email protected]: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 esos casos, puede omitir el <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 la verificación de identidad del usuario ha pasado. **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 flujo de la cámara (error de formato, fallo de autorización, excepción de red, etc.)

2. El dispositivo ya existe

3. Si falla la adición de un solo dispositivo, devuelve que todos los dispositivos fallaron al agregarse.

Código de estado: 200 OK Código de error： ● 110009 Error en la 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 flujo de la cámara ● 110012 La codificación de video de la cámara no es compatible ● 110013 El dispositivo ya existe ::: Ejemplo de respuesta:

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

g. Obtener lista de subdispositivos

Permitir a usuarios autorizados obtener 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

  • Autorization: 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 del dispositivo de terceros
service_address	string	"N" cuando se conecta un dispositivo de terceros, de lo contrario "Y"	Dirección del servicio de terceros
name	string	N	Nombre del dispositivo, si no se renombra, será mostrado por el frontend según las reglas de visualización predeterminadas.
manufacturer	string	N	Fabricante
model	string	N	Modelo del dispositivo
firmware_version	string	N	Versión del 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 completa app_name al obtener el certificado de la 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
estado	object	Y	Objeto de estado del dispositivo. Para ejemplos de estado de diferentes capacidades, consulte 【Dispositivos compatibles】
etiquetas	object	Y	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: Por favor consulte los Ejemplos de Capacidades de Dispositivos Compatibles en [Capacidades de Dispositivos Compatibles].

Atributo	Tipo	Opcional	Descripción
capability	string	N	Nombre de la capacidad. Para más detalles, consulte [Capacidades de Dispositivos 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 usa camera-stream, consulte [Capacidades de Dispositivos Compatibles]
name	string	Y	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 la verificación de identidad del usuario ha pasado. **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 Específico del Dispositivo

Permite a 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

  • Autorization: Bearer ::: Parámetros de la solicitud:

Atributo	Tipo	Opcional	Descripción
name	string	Y	Nombre del dispositivo
etiquetas	object	Y	Clave-valor en formato JSON, información personalizada del dispositivo.
estado	object	Y	Objeto de estado del dispositivo. Para ejemplos de estado de diferentes capacidades, consulte [Capacidades de Dispositivos 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 la verificación de identidad del usuario ha pasado. **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

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

  • 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 usados para almacenar nombres de canales del dispositivo y otra información sobre subdispositivos.
estado	object	Y	Cambiar estado del dispositivo; para detalles del protocolo específico, consulte "Capacidades de Dispositivos 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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK Códigos de error:

• 110000: El subdispositivo/grupo correspondiente al ID no existe.

• 110006: Error al actualizar el estado del dispositivo.

• 110019: Error al acceder a la dirección del servicio del dispositivo de terceros.

• 110024: Error al actualizar la configuración del dispositivo. ::: Ejemplo de respuesta:

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

import axios from 'axios';

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

(async function main() {
  // encender dispositivo
  await axios({
    url: `http://<domain name or ip address>/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 Subdispositivo

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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

{
  "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 específico, consulte "Capacidades de Dispositivos Compatibles."

import axios from 'axios';

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

(async function main() {
  // encender dispositivo
  await axios({
    url: `http://<domain name or ip address>/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, obligatorio
          "timeRange": { // Rango de tiempo para la resumición, obligatorio 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 fin 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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

{
  "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 de respuesta

ResponseDeviceObject

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

• true Habilitado

• false Deshabilitado |

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

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

b. Habilitar Modo de Seguridad Específico

Permite a usuarios autorizados habilitar un modo de seguridad específico 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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

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

c. Deshabilitar Modo de Seguridad Específico

Permite a usuarios autorizados deshabilitar un modo de seguridad específico 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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

{
  "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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

{
  "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 la verificación de identidad del usuario ha pasado. **Código de estado: **200 OK ::: Ejemplo de respuesta:

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

4. Acceso de Dispositivos de Terceros

4.1 Instrucciones de Acceso

Acceso de Dispositivo

Acceso de pasarela de terceros

Pasos de acceso

1. Determine la clasificación del dispositivo en la pasarela. Los detalles, consulte [Tipo de Dispositivo Compatible].

2. Determine las capacidades que el dispositivo puede acceder. Los detalles, consulte [Capacidades de Dispositivos Compatibles].

3. Solicite la interfaz [Discovery Request] para agregar el dispositivo a la pasarela.

   1. Atención: Necesita proporcionar la dirección de 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 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 terceros). Las interfaces abiertas comunes relacionadas con el dispositivo se pueden usar con normalidad.

• Seleccione la categoría de dispositivo adecuada. La clasificación afectará el resultado 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

b. Acceso de Pasarela de Terceros

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": "serial number"
      }
    ]
  }
}

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 del dispositivo por la pasarela

URL：<service address>
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": "serial number",
        "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 Solicitud de Pasarela de Terceros

Formato de Solicitud

Permite 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

  • Autorization: Bearer ::: Parámetros de la solicitud:

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

EventObject

Atributo	Tipo	Opcional	Descripción
header	HeaderObject	N	Información de la estructura del encabezado de la solicitud
endpoint	EndpointObject	Y	Información de la estructura del endpoint de la solicitud Nota: Este campo está vacío cuando se sincroniza una nueva lista de dispositivos.
payload	PayloadObject	N	Información de la 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 de 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 del dispositivo de terceros
etiquetas	object	Y	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 tienen diferente estructura de solicitud.

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 la respuesta. parámetros opcionales:Response: Respuesta exitosa ErrorResponse: Respuesta de error
message_id	string	N	ID de mensaje del encabezado de la respuesta, UUID_V4. Pase aquí el header.message_id del mensaje de la solicitud *Si la entrada de la solicitud carece de message_id, este campo será una cadena vacía al responder.
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 instrucción 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 sincronice con la pasarela, está en línea por defecto, es decir, online=true. Los cambios posteriores de estado 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 del 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
estado	object	N	Información de estado inicial
manufacturer	string	N	Fabricante
model	string	N	Modelo del dispositivo
etiquetas	object	Y	Clave-valor en formato JSON, información personalizada del dispositivo:Se usa para almacenar canales del dispositivoSe usa para almacenar unidades de temperaturaOtros datos personalizados de terceros
firmware_version	string	N	Versión de firmware
service_address	string	N	Dirección del servicio. Tal como 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 del 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": "serial number",
        "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 cannot be empty" 
  }
}

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
estado	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 Actualizada

• 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 dispositivos compatibles. **Nota: **Este parámetro solo actualizará el campo value de la configuración clave dentro de la CapabilityObject, y las actualizaciones solo están permitidas si la permission para la configuración clave es 11 o 01. Para la definición de estructura específica de la configuración en CapabilityObject, consulte la descripción detallada en la sección 2.3 Categorías de Visualización de Dispositivos y Capacidades del Dispositivo. | | etiquetas

| objeto

| Y

| Clave-valor en formato JSON, información personalizada del dispositivo.

• Puede utilizarse para almacenar canales del dispositivo

• Puede utilizarse para almacenar unidades de temperatura

• Otros datos personalizados de terceros |

Ejemplo de Solicitud :

{
  "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,
            }
          }
        }
      ]
    }
  }
}

esponse parameters: PayloadObject: Objeto vacío Ejemplo de una respuesta exitosa:

{
  "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 de servicio del dispositivo

• Nota:

1. Los terceros deben responder a la solicitud de la pasarela dentro de 3s. De lo contrario, la pasarela juzgará que el procesamiento del comando ha excedido el tiempo.

2. Si el servicio de terceros está fuera de línea, la pasarela establecerá el dispositivo en estado fuera de línea, y el servicio de terceros necesita 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 la dirección de servicio del dispositivo. :::tips

• URL：

• Método：POST

• Encabezado：

  • Content-Type: application/json ::: Parámetros de la solicitud:

Atributo	Tipo	Opcional	Descripción
directiva	DirectiveObject	N	Información de la estructura del objeto directiva

DirectiveObject

Atributo	Tipo	Opcional	Descripción
header	HeaderObject	N	Información de la estructura del encabezado de la solicitud
endpoint	EndpointObject	N	Información de la estructura del endpoint de la solicitud
payload	PayloadObject	N	Información de la 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 de 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 del dispositivo de terceros
etiquetas	object	N	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	Información de la estructura del encabezado de la solicitud
payload	PayloadObject	N	Información de la 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 de mensaje del encabezado de la 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 instrucción de la solicitud específica.

Respuesta de fallo--PayloadObject：

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

• ENDPOINT_UNREACHABLE: Dispositivo inalcanzable o fuera de línea

• ENDPOINT_LOW_POWER: El dispositivo está en modo de baja energía 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
estado	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
estado	object	N	Estado del dispositivo, consulte [Capacidades de dispositivo compatibles] para más detalles.

Ejemplo de Solicitud :

{
  "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, obligatorio.
            "end": "2020-07-05T09:00:00Z"   // Hora de fin para las estadísticas de consumo de energía, obligatorio.
          }
        }
      }
    }
  }
}

Parámetros de la respuesta: PayloadObject：

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

Ejemplo de respuesta:

{
  "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 configuration.resolution
            {
              "usage": 26.5, // Valor de consumo de energía, obligatorio. Tipo: number.
              "start": "2020-07-05T08:00:00Z", // Hora de inicio, obligatorio. Tipo: date.
              "end": "2020-07-05T09:00:00Z"    // Hora de fin, obligatorio. Tipo: date. Si el intervalo entre end y start es menor que resolution, todos los registros reportados se consideran inválidos.
            },
            {
              "usage": 26.5, // Valor de consumo de energía, obligatorio. Tipo: number.
              "start": "2020-07-05T09:00:00Z", // Hora de inicio, obligatorio. Tipo: date.
              "end": "2020-07-05T10:00:00Z"    // Hora de fin, obligatorio. Tipo: date. Si el intervalo entre end y start es menor que resolution, todos los registros reportados se consideran inválidos.
            }
          ]
        }
      }
    }
  }
}

ConfigureDeviceCapabilities

Parámetros de la solicitud: PayloadObject：

Atributo	Tipo	Opcional	Descripción
capabilities	CapabilityObject[]	N	Lista de capacidades. Los detalles pueden verse en la sección de capacidades de dispositivo compatibles. Tenga en cuenta, el campo permission no se puede cambiar, pase el mismo valor al sincronizar.

Ejemplo de Solicitud :

{
  "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, obligatorio. Valores opcionales: humidity (detección de humedad), temperature (detección de temperatura)
          "settings": {
            "setpointRange": {
              "permission": "11",
              "type": "object",
              "value": {
                "supported": [ // Ajustes de detección soportados, obligatorio.
                  {
                    "name": "lowerSetpoint", // Valor mínimo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint.
                    "value": { // Rango de detección, opcional. Rellenar si existen condiciones preestablecidas.
                      "value": 68.0, // Valor de temperatura o humedad, obligatorio.
                      "scale": "f" // Unidad de temperatura, obligatorio 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. Rellenar si existen condiciones preestablecidas.
                      "value": 68.0, // Valor de temperatura o humedad, obligatorio.
                      "scale": "f" // Unidad de temperatura, obligatorio 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

{
  "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 enviar mensajes al cliente usando SSE (Server-sent events). El cliente puede monitorear los 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 enviados 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 límite 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:

const evtSource = new EventSource("http://<domain name or ip address>/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 Agregar 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:

// 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 Actualizar 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:

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

c. Evento Actualizar 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	etiquetasobject | Nullable | Pares clave-valor en formato JSON para información personalizada del dispositivo.

• Puede utilizarse para almacenar canales del dispositivo.

• Puede utilizarse para almacenar unidades de temperatura.

• Para otros datos personalizados de terceros. |

Ejemplo:

// 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, obligatorio. Valores opcionales: humidity (detección de humedad), temperature (detección de temperatura)
        "settings": {
          "setpointRange": {
            "permission": "11",
            "type": "object",
            "value": {
              "supported": [ // Ajustes de detección soportados, obligatorio.
                {
                  "name": "lowerSetpoint", // Valor mínimo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint.
                  "value": { // Rango de detección, opcional. Rellenar si existen condiciones preestablecidas.
                    "value": 68.0, // Valor de temperatura o humedad, obligatorio.
                    "scale": "f" // Unidad de temperatura, obligatorio 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. Rellenar si existen condiciones preestablecidas.
                    "value": 68.0, // Valor de temperatura o humedad, obligatorio.
                    "scale": "f" // Unidad de temperatura, obligatorio si name=temperature. Opciones: c (Celsius), f (Fahrenheit)
                  }
                }
              ]
            }
          },
          "supportedModes": {
            "type": "enum",
            "permission": "01",
            "values": [
              "COMFORT",
              "COLD",
              "HOT"
            ]
          }
        }
      }
    ]
  }
}

d. Evento Eliminar 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:

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

e. Evento Actualizar 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:

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

5.4 Módulo de 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:

// 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
arm_state	string	N

• arming | Armado

• disarming | Desarmado | | detalle | DetailObject | N | Detalles de armado/desarme |

DetailObject：

Atributo	Tipo	Opcional	Descripción
sid	int	N	id de modo de seguridad
name	string	N	Nombre de seguridad

Ejemplo

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

6. TTS (Función del motor de texto a voz

6.1 Instrucción

Papel clave

• Proveedor de Servicios 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 de 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 de 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.

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

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

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 audios 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 a partir del resultado devuelto en el paso anterior, llamar a la interfaz de reproducción de archivos 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 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:： :::

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

b. Obtener la lista de audios 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 solicitud: ninguno Respuesta de datos correcta:

Atributo	Tipo	Opcional	Descripción
audio_list	AudioObject []	N	Lista de audios

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 de forma anormal

Ejemplo de respuesta:： :::

{
  "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 solicitud:

Atributo	Tipo	Opcional	Descripción
text	string	N	Texto usado para sintetizar el audio
etiqueta	string	Y	Etiqueta del archivo de audio
language	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 de voz TTS. Tenga en cuenta que el servicio del motor TTS debe admitir 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.
options	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 audios

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 de forma anormal

Ejemplo de respuesta:： :::

{
  "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 de Servicio TTS

:::consejos

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

  • Autorización: Bearer ::: Parámetros de solicitud:

Atributo	Tipo	Opcional	Descripción
evento	EventObject	N	Estructura de información del objeto de evento de solicitud

EventObject

Atributo	Tipo	Opcional	Descripción
header	HeaderObject	N	Información de la estructura del encabezado de la solicitud
payload	PayloadObject	N	Información de la 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:

{
  "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	Información de la estructura del encabezado de la solicitud
payload	PayloadObject	N	Información de la estructura del payload de la solicitud

HeaderObject

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

• Respuesta (Respuesta exitosa)

• ErrorResponse (Respuesta de error) | | message_id | string | N | ID del mensaje del encabezado de respuesta, UUID_V4. Mensaje de 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:：

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

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

{
  "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 para sincronizar la lista de audios

Enviar comando al Proveedor de Servicio TTS por 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
directiva	DirectiveObject	N	Información de la estructura del objeto de instrucción

DirectiveObject

Atributo	Tipo	Opcional	Descripción
header	HeaderObject	N	Información de la estructura del encabezado de la solicitud
payload	PayloadObject	N	Información de la 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:

{
  "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	Información de la estructura del encabezado de la solicitud
payload	PayloadObject	N	Información de la estructura del payload de la solicitud

HeaderObject

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

• Respuesta (Respuesta exitosa)

• ErrorResponse (Respuesta de error) | | message_id | string | N | ID del mensaje del encabezado de respuesta, UUID_V4. Mensaje de 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_list	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:：

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

{
  "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 de Servicio TTS por 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
directiva	DirectiveObject	N	Información de la estructura del objeto de instrucción

DirectiveObject

Atributo	Tipo	Opcional	Descripción
header	HeaderObject	N	Información de la estructura del encabezado de la solicitud
payload	PayloadObject	N	Información de la 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
text	string	N	Texto usado para sintetizar el audio
etiqueta	string	Y	Etiqueta del archivo de audio
language	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 de voz TTS. Tenga en cuenta que el servicio del motor TTS debe admitir 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.
options	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:

{
    "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	Información de la estructura del encabezado de la solicitud
payload	PayloadObject	N	Información de la estructura del payload de la solicitud

HeaderObject

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

• Respuesta (Respuesta exitosa)

• ErrorResponse (Respuesta de error) | | message_id | string | N | ID del mensaje del encabezado de respuesta, UUID_V4. Mensaje de 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:：

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

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

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

8. Tarjeta de interfaz de usuario personalizada

Las tarjetas de interfaz de usuario 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 adaptará automáticamente su ancho y alto, y el contenido se representará usando un iFrame.

8.1 Instrucción

Papel clave

• Proveedor de servicios de 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 de la API abierta para la pasarela.

8.1.1 Creación de una tarjeta de UI personalizada

• [Proveedor de servicios 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.

8.1.2 Recuperación de la lista de tarjetas de UI

• [Proveedor de servicios 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 llamante.

8.1.3 Modificación de la configuración de una tarjeta de UI especificada

• [Proveedor de servicios 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.

8.1.4 Eliminación de una tarjeta de UI personalizada

1. [Proveedor de servicios 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.

8.2 Módulo de tarjeta de UI personalizada

8.2.1 Creación de una tarjeta de UI personalizada

El proveedor de servicios 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 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.
cast_settings	CastSettingsObject	Y	Configuración de la tarjeta Cast: Ajustes de configuración para tarjetas cast.
web_settings	WebSettingsObject	N	Configuración de la tarjeta web: Ajustes de configuración para tarjetas web.

CastSettingsObject:

Atributo	Tipo	Opcional	Descripción
dimensions	DimensionObject []	N	Configuración de tamaño: Debe incluir al menos una configuración.
default	string	N	Especificación predeterminada: Se utiliza la especificación de tamaño predeterminada, con parámetros opcionales: 2x2

WebSettingsObject:

Atributo	Tipo	Opcional	Descripción
dimensions	DimensionObject []	N	Configuración de tamaño: Debe incluir al menos una configuración.
drawer_component	DrawerObject	Y	Ajustes de visualización del componente Drawer.
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
size	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 de UI

:::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 solicitud：

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

Ejemplo de respuesta:

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

8.2.2 Recuperar la lista de tarjetas de UI

:::consejos

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

• Método：GET

• Encabezado：

  • Content-Type: application/json

  • Autorización: Bearer ::: Parámetros de solicitud: Ninguno Parámetros de respuesta:

Atributo	Tipo	Opcional	Descripción
data	CardObject[]	N	Lista de tarjetas de 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.
cast_settings	CastSettingsObject	Y	Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Es el alias de la tarjeta.
web_settings	WebSettingsObject	N	Configuración de la tarjeta Cast: Ajustes de configuración para tarjetas cast.
app_name	string	Y	Configuración de la tarjeta web: Ajustes de configuración para tarjetas web.

CastSettingsObject:

Atributo	Tipo	Opcional	Descripción
dimensions	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
dimensions	DimensionObject []	N	Configuración de tamaño: Debe incluir al menos una configuración.
drawer_component	DrawerObject	Y	Ajustes de visualización del componente Drawer.
default	string	N	Especificación predeterminada:
Parámetro opcional:

• 1x1

• 2x1 | | usado | 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
size	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 será efectiva. |

DrawerObject:

Atributo	Tipo	Opcional	Descripción
src	string	N	URL del recurso: Por ejemplo: http://example.html

Ejemplo de respuesta:

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

8.2.3 Modificar la configuración de una tarjeta de UI especificada

Los usuarios autorizados pueden modificar la configuración de una tarjeta de UI existente a través de esta interfaz. Los proveedores de servicios de tarjetas personalizadas solo pueden modificar las tarjetas de UI que 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 solicitud:

Atributo	Tipo	Opcional	Descripción
etiqueta	string	Y	Se utiliza para describir la tarjeta. Es el alias de la tarjeta.
cast_settings	CastSettingsObject	Y	Configuración de tarjeta Cast
web_settings	WebSettingsObject	Y	Configuración de tarjeta web

CastSettingsObject:

Atributo	Tipo	Opcional	Descripción
usado	string	Y, Cualquiera de los dos 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 de los dos 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 de los dos 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 de los dos 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 de UI que se modifica debe haber sido creada por el proveedor de tarjetas de UI personalizadas que llama a la interfaz. **Código de estado: ** 200 OK Código de error:

• 406: No tiene permiso para acceder a este recurso ::: **Ejemplo de respuesta: **

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

**Ejemplo de solicitud: **

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

8.2.4 Eliminar tarjeta de UI personalizada

Los usuarios autorizados están permitidos a eliminar una tarjeta de UI existente usando esta interfaz. Los proveedores de tarjetas personalizadas solo pueden eliminar las tarjetas de 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 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 de UI que se modifica debe haber sido creada por el proveedor de tarjetas de UI personalizadas que llama a la interfaz. **Código de estado: ** 200 OK Código de error:

• 406: No tiene permiso para acceder a este recurso. ::: **Ejemplo de respuesta: **

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