Desarrollador y guía de API

1. Comenzar a usar

1.1 Preparación

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

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

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

1. Inicie sesión en su router inalámbrico y verifique la dirección IP de la pasarela en DHCP.

2. CUBE admite el descubrimiento local a través de mDNS.

1.2 Empezar

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

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

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

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

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

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

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

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

// Respuesta
{
  "error": 0,
  "data": {
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "device name",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  }
  "message": "success"
}

• Método para obtener el token de acceso de CUBE: después de llamar a la interfaz [Access Token], el cuadro emergente global de la página de la consola web de CUBE solicita al usuario confirmar la adquisición de las credenciales para llamar a la interfaz.

• Nota: Si abre más de una página de la consola web de CUBE, el cuadro emergente de confirmación aparecerá en varias páginas de la consola web al mismo tiempo, y el cuadro emergente de las otras páginas se cerrará después de hacer clic en la confirmación en una de las páginas.

2. Concepto central

2.1 Dirección de la interfaz de desarrollo

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

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

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

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

• **Categoría de visualización del dispositivo (DisplayCategory). **La categoría de visualización del dispositivo se usa para identificar categorías específicas (del dispositivo), como switch, plug, light, etc. Esta información determinará el efecto de visualización de la interfaz de usuario del dispositivo en la pasarela.

• **Capacidad del dispositivo. **La capacidad del dispositivo se usa para describir las subfunciones específicas del dispositivo. Por ejemplo, control de alimentación, control de brillo, control de temperatura de color, etc. Un solo dispositivo puede soportar 1 o más capacidades.

  • capability: Describe el nombre de la capacidad, que debe ser globalmente único y de tipo cadena. Varias palabras en inglés deben separarse por guiones ("-"). Por ejemplo: "thermostat-target-setpoint".

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

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

    • Controlable por dispositivo: "1000"

    • Configurable por dispositivo: "0010"

    • Controlable y configurable por dispositivo: "1010"

    • Controlable y que puede informar por dispositivo: "1100"

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

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

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

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

• Permitir la modificación de este elemento de configuración: "10"

• Permitir la visualización de este elemento de configuración: "01"

• Permitir tanto la modificación como la visualización de este elemento de configuración: "11"

Explicación de los bits:

1. Bit 0: Permite la visualización de este elemento de configuración

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

• "enum"

• "numeric"

• "object"

• "boolean"

• "string"

Directrices específicas por tipo:

1. Cuando **type = enum**:

   • El campo value (que describe el valor del elemento de configuración) es obligatorio si permission permite la modificación ("10" o "11").

   • El default (que describe el valor predeterminado del elemento de configuración) y values (que describe los valores seleccionables para el elemento de configuración) los campos son opcionales.

2. Cuando **type = numeric**:

   • El campo el campo es obligatorio si permission permite la modificación ("10" o "11").

   • Los siguientes campos son opcionales:

     • min (que describe el valor mínimo del elemento de configuración)

     • max (que describe el valor máximo del elemento de configuración)

     • step (que describe el valor de paso para el elemento de configuración)

     • precision (que describe la precisión)

     • unit (que describe la unidad del elemento de configuración)

     • default (que describe el valor predeterminado)

3. Cuando **type = object**:

   • El campo el campo es obligatorio si permission permite la modificación ("10" o "11").

   • El default el campo es opcional.

4. Cuando **type = boolean**:

   • El campo el campo es obligatorio si permission permite la modificación ("10" o "11").

   • El default el campo es opcional.

5. Cuando **type = string**:

   • El campo el campo es obligatorio si permission permite la modificación ("10" o "11").

   • El default el campo es opcional. |

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

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

3. API Web

Tipo de datos

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

Resultados genéricos de la respuesta

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

Ejemplo de respuesta:

{
  "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 (Descubrir dispositivo)

• system Armed (Sistema armado habilitado)

• system Disarmed (Sistema armado deshabilitado)

• factoryReset (Restablecer dispositivo) |

3.1 Función de la pasarela

a. Token de acceso

Permitir a los usuarios obtener el token de acceso.

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

• Aviso: Después de obtener el token, debe volver a presionar el botón para obtener con éxito un nuevo token.

:::consejos

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

• Método：GET

• Encabezado：

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

Atributo	Tipo	Opcional	Descripción
app_name	string	Y	Descripción del nombre de la aplicación.

Respuesta de datos exitosa:

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

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

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

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

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

b. Obtener el estado de la pasarela

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

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

• Método：GET

• Encabezado：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa:

Atributo	Tipo	Opcional	Descripción
ram_used	int	N	Porcentaje de uso de RAM. [0-100]
cpu_used	int	N	Porcentaje de uso de CPU. [0-100]
power_up_time	date	N	Última hora de encendido
cpu_temp	int	N	Temperatura de la CPU:
Unidad: Celsius
cpu_temp_unit	string	N	Unidad de temperatura de la CPU:
Opcional
valores:'c', 'f'
sd_card_used	int	Y	Uso de la tarjeta SD (porcentaje):
Rango:[0-100] con una precisión de un decimal
*Nota: Si la tarjeta SD no está insertada o no está formateada, el valor está vacío.

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

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

c. Configurar la pasarela

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

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

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

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

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

d. Obtener la información de la pasarela

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

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

• Método：GET

• Encabezado：

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

Atributo	Tipo	Opcional	Descripción
ip	string	N	dirección ip
mac	string	N	dirección mac
domain	string	Y	Dominio del servicio de la pasarela
fw_version	string	N	Versión del firmware
name	string	N	Nombre del dispositivo

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

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

e. Silenciar la pasarela

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

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

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

f. Quitar silencio de la pasarela

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

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

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

g. Cancelar la alarma de la pasarela

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

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

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

3.2 Función de hardware

a. Reiniciar la pasarela

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

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

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

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

b. Control del altavoz

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

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

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

Atributo	Tipo	Opcional	Descripción
type	string	N	Parámetros opcionales: 1.play_sound (reproducir el sonido) 2.play_beep (reproducir el pitido)
sound	SoundObject	Y (N si type es play_sound.)	El sonido.
beep	BeepObject	Y (N si type es play_beep.)	El pitido

SoundObject

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

BeepObject

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

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

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

3.3 Función de gestión de dispositivos

a. Tipo de dispositivo compatible

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

b. Capacidades de Dispositivo Soportadas

Interruptor de alimentación (power):

Ejemplo de Declaración de Capacidad:

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

Atributo de Estado:

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Encender:

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

Apagar:

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

Interruptor de Canal (toggle):

Ejemplo de Declaración de Capacidad:

Ejemplo de Componente Único:

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

Ejemplo de Componentes Múltiples:

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

Atributo de Estado:

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Formato de Alternancia:

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

Inchamiento de Canal (toggle-inching):

Ejemplo de Declaración de Capacidad:

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

Atributo de Estado

Ninguno

Protocolo (Consulta de Estado e Instrucciones de Control)

Ninguno

Ajuste de Brillo (brightness):

Ejemplo de Declaración de Capacidad:

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

Atributo de Estado:

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ajuste de Temperatura de Color (color-temperature):

Ejemplo de Declaración de Capacidad:

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

Atributo de Estado:

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Ajustar la temperatura de color al 50%:

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

Ajuste de Color (color-rgb):

Ejemplo de Declaración de Capacidad:

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

Atributo de Estado:

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Establecer color a púrpura:

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

Ajuste Porcentual (percentage):

Ejemplo de Declaración de Capacidad:

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

Atributo de Estado:

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Ajustar al 40%:

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

Control de Motor (motor-control):

Ejemplo de Declaración de Capacidad:

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

Atributo de Estado:

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Abrir Motor:

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

Inversión de Motor (motor-reverse):

Ejemplo de Declaración de Capacidad:

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

Atributo de Estado:

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Configurar Motor a Avance:

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

Calibración de Motor (motor-clb)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Reporte de Estado):

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

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

Estado al Encender (startup)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Establecer Estado de Energía Siempre Encendido:

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

---

Activación de Despertar (identify)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Reporte de Estado e Instrucciones de Control):

Establecer Tiempo de Activación de Despertar:

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

Informar Estado de Activación:

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

Iniciar/Detener Estadísticas en Tiempo Real:

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

Consultar Consumo de Energía por Rango de Tiempo:

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

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

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

Protocolo (Reporte de Estado e Instrucciones de Control):

Iniciar Estadísticas en Tiempo Real:

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

Detener Estadísticas en Tiempo Real:

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

Obtener Consumo Histórico de Energía:

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

Obtener Consumo de Energía en Tiempo Real:

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

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

Ejemplo de Declaración de Capacidad:

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

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Formato:

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

Ejemplo:

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

Modo del Termostato (thermostat-mode)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

[[
  {
    "capability": "thermostat-target-setpoint",
    "name": "manual-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "eco-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "auto-mode",
    "permission": "0110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      },
      "weeklySchedule":{
        "type": "object",
        "permission": "11",
        "value": {
          "maxEntryPerDay": 2,
          "Monday": [
          {
            "startTimeInMinutes": 440, // Hora de inicio en minutos. **Tipo:** int. Ej.: 7:20 AM = 440 minutos.
            "upperSetpoint": 36.5, // Temperatura máxima objetivo. **Tipo:** number.
            "lowerSetpoint": 20 // Temperatura mínima objetivo. **Tipo:** number.
          },
          {
            "startTimeInMinutes": 900, // Hora de inicio en minutos. Ej.: 3:00 PM = 900 minutos.
            "upperSetpoint": 26.5, // Temperatura máxima objetivo. **Tipo:** number.
            "lowerSetpoint": 21 // Temperatura mínima objetivo. **Tipo:** number.
          }
        ],
          "Tuesday": [...
          ],
          "Wednesday": [...
          ],
          "Thursday": [...
          ],
          "Friday": [...
          ],
          "Saturday": [...
          ],
          "Sunday": [...
          ],
        }
      }
    }
  }
]

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de Sensor (detect)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de Temperatura (temperature)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de Humedad (humidity)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de Batería (battery)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de Voltaje (voltage)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de Fallas (fault)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Interruptor de Umbral (threshold-breaker)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado)

• Ninguno

Protocolo (Consulta de Estado e Instrucciones de Control)

• Ninguno

Función Inch (inching)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

• Ninguno

Protocolo (Consulta de Estado e Instrucciones de Control):

• Ninguno

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

• Ninguno

Protocolo (Consulta de Estado e Instrucciones de Control):

• Ninguno

Control de Modo (mode)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de Iluminación (illumination)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de Humo (smoke)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de movimiento (motion)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Bloqueo infantil (child-lock)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Oscilación horizontal (horizontal-swing)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Oscilación vertical (vertical-swing)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Modo ECO (eco)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Alternar inicio (toggle-startup)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Alternar Identificar/Activar (toggle-identify)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Detección de voltaje alternable (toggle-voltage)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

Iniciar/Detener Estadísticas en Tiempo Real:

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

Consultar Consumo de Energía por Rango de Tiempo:

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

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

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Iniciar Estadísticas en Tiempo Real:

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

Detener Estadísticas en Tiempo Real:

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

Obtener Consumo Histórico de Energía:

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

Obtener Consumo de Energía en Tiempo Real:

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

Indicador de calidad de enlace (lqi)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Configuración funcional (configuration)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Sistema (system)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Humedad (moisture)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Presión barométrica (barometric-pressure)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Velocidad del viento (wind-speed)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Dirección del viento (wind-direction)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Precipitación (rainfall)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Índice ultravioleta (ultraviolet-index)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Conductividad eléctrica (electrical-conductivity)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Potencia de transmisión (transmit-power)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección PM2.5 (pm25)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Índice VOC (voc-index)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

Detección de gas natural (gas)

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Reporte de estado de trabajo:

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

Consulta de estado de trabajo:

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

Resultado de la consulta de estado de trabajo:

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

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

Protocolo (Consulta de Estado e Instrucciones de Control):

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

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

Ejemplo de Declaración de Capacidad:

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

Atributos (Estado):

Programación única o repetida:

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

Volumen único o repetido:

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

Protocolo (Consulta de Estado e Instrucciones de Control):

Programación única o repetida:

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

Volumen único o repetido:

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

Modos preestablecidos compatibles

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

c. Descripción de etiquetas

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

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

• La clave especial temperature_unit se utiliza para establecer la unidad de temperatura.

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

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

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

e. Buscar subdispositivo

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

• 💡Nota: Actualmente solo admite la búsqueda de subdispositivos Zigbee.

• 💡Nota: Los subdispositivos Zigbee se agregarán automáticamente después de la búsqueda. No es necesario usar la interfaz "Agregar subdispositivos manualmente" :::tips

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

• Método: PUT

• Encabezado：

  • Content-Type: application/json

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

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

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

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

f. Agregar manualmente el subdispositivo

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

• Nota: Actualmente solo se admiten Cámara RTSP y Cámara ESP32 :::tips

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

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

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

CapabilityObject

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

SettingsObject

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

StreamSettingObject

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

StreamSettingValueObject

Atributo	Tipo	Opcional	Descripción
stream_url	string	N	Formato de URL de transmisión
Formato:<schema>://<hostname>:<port>/<username>:<password>@<service_path>
Ejemplo:rtsp://admin:[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 tales casos, puede omitir <username> y <password> campos de la URL.

Respuesta de datos exitosa:

Atributo	Tipo	Opcional	Descripción
serial_number	string	N	Número de serie único del dispositivo

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

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

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

1. Error de acceso a la dirección de transmisión de la cámara (error de formato, fallo de autorización, excepción de red, etc.)

2. El dispositivo ya existe

3. Si un solo dispositivo no se puede agregar, devuelve que todos los dispositivos no se pudieron agregar.

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

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

g. Obtener lista de subdispositivos

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

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

• Método: GET

• Encabezado：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa:

Atributo	Tipo	Opcional	Descripción
device_list	ResponseDeviceObject[]	N	Lista de dispositivos

ResponseDeviceObject

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

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

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

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

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

h. Actualizar información o estado especificado del dispositivo

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

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

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

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

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

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

i. Eliminar subdispositivo

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

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

• Método：DELETE

• Encabezado：

  • Content-Type: application/json

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

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

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

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

• 110006: Falló al actualizar el estado del dispositivo.

• 110019: Falló el acceso a la dirección del servicio del dispositivo de terceros.

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

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

import axios from 'axios';

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

(async function main() {
  // encender dispositivo
  await axios({
    url: `http://<nombre de dominio o dirección ip>/open-api/v2/rest/devices/${serial_number}`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      state: {
        power: {
          powerState: 'on'
        }
      }
    }
  });
})()

j. Eliminar sub-dispositivo

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

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

• Método：DELETE

• Encabezado：

  • Content-Type: application/json

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

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

k. Consultar estado del dispositivo

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

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

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

Atributo	Tipo	Opcional	Descripción
query_state	object	N	Consultar estado del dispositivo; para detalles del protocolo, consulte "Capacidades de dispositivo compatibles."

import axios from 'axios';

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

(async function main() {
  // encender dispositivo
  await axios({
    url: `http://<nombre de dominio o dirección ip>/open-api/v2/rest/devices/${serial_number}/query-state/power-consumption`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      "query_state":{
        "power-consumption":{
          "type": "summarize", // Tipo de estadísticas, requerido
          "timeRange": { // Rango de tiempo para la sumarización, requerido cuando type="summarize"
            "start": "2020-07-05T08:00:00Z", // Hora de inicio para las estadísticas de consumo de energía
            "end": "2020-07-05T09:00:00Z" // Hora de finalización para las estadísticas de consumo de energía; si se omite, por defecto es la hora actual
          }
        }
      }
    });
})()

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

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

3.4 Gestión de seguridad

a. Obtener lista de seguridad

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

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

• Método：GET

• Encabezado：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa:

Atributo	Tipo	Opcional	Descripción
security_list	ResponseSecurityObject[]	N	Lista de dispositivos en la respuesta

ResponseDeviceObject

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

• true Habilitado

• false Deshabilitado |

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

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

b. Habilitar modo de seguridad especificado

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

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

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

c. Deshabilitar modo de seguridad especificado

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

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

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

d. Habilitar configuración de seguridad con un clic

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

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

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

e. Deshabilitar seguridad

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

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

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

4. Acceso de dispositivos de terceros

4.1 Instrucciones de acceso

Acceso de dispositivos

1.0.jpg

Acceso de pasarela de terceros

2.0.jpg

Pasos de acceso

1. Determine la clasificación del dispositivo en la pasarela. Los detalles, por favor consulte [Tipo de dispositivo compatible].

2. Determine las capacidades a las que el dispositivo puede acceder. Los detalles, por favor consulte [Capacidades de dispositivo compatibles].

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

   1. Atención: Necesita proporcionar la dirección del servicio para recibir las instrucciones emitidas por la pasarela, que se utiliza para recibir las instrucciones de control del dispositivo emitidas por la pasarela.

4. Si el estado del dispositivo de terceros cambia, debe llamar a la interfaz [Device States Change Report] para enviar el estado más reciente de vuelta a la pasarela.

5. Después de agregar, el dispositivo de terceros aparecerá en la Lista de Dispositivos, con la mayoría de las funciones de la pasarela (otros dispositivos no de terceros). Las interfaces abiertas comunes relacionadas con el dispositivo se pueden usar normalmente.

• Seleccione la categoría de dispositivo adecuada. La clasificación afectará el resultado de la visualización final de la interfaz de usuario después de que el dispositivo se conecte a la pasarela.

• Elija la capacidad de dispositivo correcta. La lista de capacidades determinará el estado del protocolo de estado del dispositivo.

Proceso del programa

a. Acceso de dispositivo

3.0.jpg

b. Acceso de pasarela de terceros

4.0.jpg

4.2 Ejemplo de acceso

Interruptor, Enchufe

Sincronizar dispositivos de terceros

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

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

Informar estado del dispositivo

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

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

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

Informar fuera de línea/en línea

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

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

Recibir las instrucciones sobre el control de dispositivos de la pasarela

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

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

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

Consultar dispositivo

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

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

4.3 API web

Interfaz de pasarela de solicitud de terceros

Formato de solicitud

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

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

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

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

EventObject

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

HeaderObject

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

EndpointObject

Atributo	Tipo	Opcional	Descripción
serial_number	string	N	Número de serie único del dispositivo
third_serial_number	string	N	Número de serie único de dispositivo de terceros
etiquetas	object	Y	Par clave-valor en formato JSON, información personalizada del dispositivo. [Función de gestión de dispositivos] - [Descripción de etiquetas]

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

Formato de respuesta

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

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

HeaderObject

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

Respuesta exitosa--PayloadObject ：

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

Respuesta de fallo--PayloadObject：

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

• INVALID_PARAMETERS: Error de parámetros

• AUTH_FAILURE: Error de autorización

• INTERNAL_ERROR: Error interno del servicio | | descripción | string | N | Descripción del error |

DiscoveryRequest Sincronizar una nueva lista de dispositivos

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

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

Atributo	Tipo	Opcional	Descripción
endpoints	EndpointObject[]	N	Lista de dispositivos

EndpointObject:

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

Ejemplo de solicitud :

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

Parámetros de la respuesta: PayloadObject：

Atributo	Tipo	Opcional	Descripción
endpoints	EndpointObject[]	N	Lista de dispositivos

EndpointObject:

Atributo	Tipo	Opcional	Descripción
serial_number	string	N	Número de serie único del dispositivo
third_serial_number	string	N	Número de serie único de dispositivo de terceros

Ejemplo de una respuesta correcta:

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

Ejemplo de una respuesta de error:

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

DeviceStatesChangeReport Informe de cambio de estado del dispositivo

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

Parámetros de la solicitud: PayloadObject：

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

Ejemplo de solicitud :

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

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

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

DeviceOnlineChangeReport Informe de estado en línea del dispositivo

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

Parámetros de la solicitud: PayloadObject：

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

Ejemplo de solicitud :

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

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

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

DeviceInformationUpdatedReport Informe de información del dispositivo actualizado

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

Parámetros de la solicitud: PayloadObject：

Atributo	Tipo	Opcional	Descripción
capabilities

| CapabilityObject[]

| N

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

| objeto

| Y

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

• Se puede usar para almacenar canales del dispositivo

• Se puede usar para almacenar unidades de temperatura

• Otros datos personalizados de terceros |

Ejemplo de solicitud :

{
  "event": {
    "header": {
      "name": "DeviceInformationUpdatedReport",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "detect",
          "permission": "0110",
          "settings":{
            "detectInterval":{
              "permission": "11",
              "type": "numeric",
              "value": 300,
            },
            "detectSensitivity":{
              "permission": "11",
              "type": "numeric",
              "value": 1000,
            }
          }
        }
      ]
    }
  }
}

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

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

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

• Nota:

1. Las tres partes deben responder a la solicitud de la pasarela dentro de 3 s. De lo contrario, la pasarela juzgará el tiempo de procesamiento del comando como agotado.

2. Si el servicio de terceros está fuera de línea, la pasarela establecerá el dispositivo en un estado fuera de línea, y el servicio de terceros debe informar el estado del dispositivo (DeviceStatesChangeReport) o el estado en línea (DeviceOnlineChangeReport) antes de volver al estado en línea.

Formato de la solicitud

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

• URL：

• Método：POST

• Encabezado：

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

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

DirectiveObject

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

HeaderObject

Atributo	Tipo	Opcional	Descripción
name	string	N	Nombre de la solicitud. Parámetros opcionales: UpdateDeviceStates: Actualizar estados del dispositivo
message_id	string	N	ID del mensaje de la solicitud, UUID_V4
version	string	N	Número de versión del protocolo de la solicitud. Actualmente fijo en 1.

EndpointObject

Atributo	Tipo	Opcional	Descripción
serial_number	string	N	Número de serie único del dispositivo
third_serial_number	string	N	Número de serie único de dispositivo de terceros
etiquetas	object	N	Par clave-valor en formato JSON, información personalizada del dispositivo. [Función de gestión de dispositivos] - [Descripción de etiquetas]

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

Ejemplo de solicitud :

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

Formato de respuesta

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

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

EventObject

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

HeaderObject

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

Respuesta exitosa--PayloadObject：

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

Respuesta de fallo--PayloadObject：

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

• ENDPOINT_UNREACHABLE: El dispositivo es inalcanzable o está fuera de línea

• ENDPOINT_LOW_POWER: El dispositivo está en modo de bajo consumo y no se puede controlar

• INVALID_DIRECTIVE: Directiva anormal desde la pasarela

• NO_SUCH_ENDPOINT: El dispositivo no existe

• NOT_SUPPORTED_IN_CURRENT_MODE: El modo actual no admite la operación

• INTERNAL_ERROR: Error interno del servicio

• REMOTE_KEY_CODE_NOT_LEARNED: Código de tecla del control remoto no aprendido |

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

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

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

UpdateDeviceStates

Parámetros de la solicitud: PayloadObject：

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

Ejemplo de solicitud :

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

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

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

QueryDeviceStates

Parámetros de la solicitud: PayloadObject：

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

Ejemplo de solicitud :

{
  "directive": {
    "header": {
      "name": "QueryDeviceStates",
      "message_id": "Identificador único, preferiblemente un UUID versión 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "timeRange": {
            "start": "2020-07-05T08:00:00Z", // Hora de inicio para las estadísticas de consumo de energía, requerida.
            "end": "2020-07-05T09:00:00Z"   // Hora de finalización para las estadísticas de consumo de energía, requerida.
          }
        }
      }
    }
  }
}

Parámetros de la respuesta: PayloadObject：

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

Ejemplo de respuesta:

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

Configurar capacidades del dispositivo

Parámetros de la solicitud: PayloadObject：

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

Ejemplo de solicitud :

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

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

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

5. Eventos enviados por el servidor

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

5.1 Instrucción

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

5.2 Formato común

:::consejos

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

• Método：GET ::: Parámetros de la solicitud:

Nombre	Tipo	Opcional	Descripción
access_token	string	N	Token de acceso

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

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

Ejemplo:

const evtSource = new EventSource("http://<nombre de dominio o dirección ip>/open-api/v2/sse/bridge?access_token=xxxxxx");

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

5.3 Módulo de dispositivo

a. Evento de añadir dispositivo

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

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

Ejemplo:

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

b. Evento de actualización del estado del dispositivo

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

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

EndpointObject:

Parámetro	Tipo	Opcional	Descripción
serial_number	string	N	Número de serie único del dispositivo
third_serial_number	string	Y	El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio.

Ejemplo:

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

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

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

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

EndpointObject:

Atributo	Tipo	Opcional	Descripción
serial_number	string	N	Número de serie único del dispositivo
third_serial_number	string	Y	El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio.

DeviceChangeObject

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

• Se puede usar para almacenar canales del dispositivo.

• Se puede usar para almacenar unidades de temperatura.

• Para otros datos personalizados de terceros. |

Ejemplo:

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

d. Evento de eliminación de dispositivo

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

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

EndpointObject:

Atributo	Tipo	Opcional	Descripción
serial_number	string	N	Número de serie único del dispositivo
third_serial_number	string	Y	El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio.

Ejemplo:

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

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

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

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

EndpointObject:

Atributo	Tipo	Opcional	Descripción
serial_number	string	N	Número de serie único del dispositivo
third_serial_number	string	Y	El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio.

DeviceChangeObject

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

Ejemplo:

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

5.4 Módulo de la pasarela

a. Evento de actualización del estado de seguridad

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

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

SecurityStateObject

Atributo	Tipo	Opcional	Descripción
alarm_state	string	N

• arming | Armado

• disarming | Desarmado |

Ejemplo:

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

5.5 Módulo de seguridad

a. Evento de actualización del estado de armado

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

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

ArmStateObject：

Atributo	Tipo	Opcional	Descripción
estado_alarma	string	N

• arming | Armado

• disarming | Desarmado | | detalle | ObjetoDetalle | N | Detalles de armar/desarmar |

ObjetoDetalle：

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

Ejemplo

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

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

6.1 Instrucción

Rol clave

• Proveedor del servicio TTS: El proveedor del servicio del motor TTS es responsable de registrar el motor TTS en la pasarela y proporcionar servicios TTS

• Servidor de la pasarela：iHost

• Cliente de la API abierta de la pasarela

6.1.1 Registro del servicio del motor TTS

1. 【Proveedor del servicio TTS】Llamar a la interfaz para registrar el motor TTS en la pasarela.

2. 【Servidor de la pasarela】Tras el registro exitoso, la pasarela almacenará la información básica del motor TTS (incluida la dirección del servicio server_address, y la comunicación posterior entre la pasarela y el proveedor del servicio TTS se realizará a través de la dirección server_address), y asignará el ID del servicio del motor TTS dentro de la pasarela.

imagen.png

6.1.2 Obtener la lista de audios sintetizados

1. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de servicios de motor TTS registrados. Puede obtener la lista actual de motores TTS registrados (incluido el ID del motor TTS asignado por la pasarela).

2. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de audio de un motor TTS especificado. La pasarela emitirá una instrucción síncrona de lista de audio al proveedor de servicio TTS especificado y devolverá el resultado.

imagen.png

6.1.3 Síntesis de voz especificando un motor de voz

1. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de servicios de motor TTS registrados. Puede obtener la lista actual de motores TTS registrados (incluido el ID del motor TTS asignado por la pasarela).

2. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de audio de un motor TTS especificado. La pasarela emitirá una instrucción síncrona de lista de audio al proveedor de servicio TTS especificado y devolverá el resultado.

imagen.png

6.1.4 Sintetizar audio y reproducir discurso TTS.

1. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de servicios de motor TTS registrados. Puede obtener la lista actual de motores TTS registrados (incluido el ID del motor TTS asignado por la pasarela).

2. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de audio de un motor TTS especificado. La pasarela emitirá una instrucción síncrona de lista de audio al proveedor de servicio TTS especificado y devolverá el resultado. (incluida la dirección del archivo de audio TTS)

3. 【Cliente de la API abierta de la pasarela】Registrar la dirección del archivo de audio TTS del resultado devuelto en el paso anterior, llamar a la interfaz de reproducir archivo de audio y reproducirlo a través de la pasarela.

6.2 Módulo del motor TTS

6.2.1 Capacidades abiertas de la pasarela

a. Obtener la lista de servicios de motor TTS registrados

:::consejos

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

• Método：GET

• Encabezado：

  • Content-Type: application/json

  • Autorización: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos correcta:

Atributo	Tipo	Opcional	Descripción
motores	EngineObject []	N	Lista de motores TTS registrados

Estructura de EngineObject

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

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

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

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

:::consejos

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

• Método：GET

• Encabezado：

  • Content-Type: application/json

  • Autorización: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos correcta:

Atributo	Tipo	Opcional	Descripción
lista_audio	AudioObject []	N	Lista de audio

Estructura de AudioObject

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

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

• 190000 El motor está funcionando anormalmente

Ejemplo de respuesta:： :::

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

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

:::consejos

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

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

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

Respuesta de datos correcta:

Atributo	Tipo	Opcional	Descripción
audio	AudioObject	N	Lista de audio

Estructura de AudioObject

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

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

• 190000 El motor está funcionando anormalmente

Ejemplo de respuesta:： :::

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

6.2.2 Comunicación entre la pasarela y el servicio TTS

a. Registro del servicio del motor TTS

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

:::consejos

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

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

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

EventObject

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

HeaderObject

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

• RegisterTTSEngine | | message_id | string | N | ID del mensaje de la solicitud, UUID_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

PayloadObject

Atributo	Tipo	Opcional	Descripción
service_address	string	N	Dirección del servicio. Por ejemplo, http:///
name	string	N	Nombre del servicio

Ejemplo de solicitud:

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

**Parámetros de respuesta correctos: **

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

HeaderObject

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

• Respuesta (Respuesta exitosa)

• ErrorResponse (Respuesta de error) | | message_id | string | N | ID del mensaje del encabezado de la respuesta, UUID_V4. Mensaje de la solicitud entrante aquí: header.message_id | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

PayloadObject

Atributo	Tipo	Opcional	Descripción
engine_id	string	N	ID del motor asignado por la pasarela

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

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

**Parámetros de respuesta anormales: **

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

• INVALID_PARAMETERS (Error de parámetros)

• AUTH_FAILURE (Fallo de autenticación)

• INTERNAL_ERROR (Error interno del servicio) | | description | string | N | Descripción del error |

Ejemplo de respuesta de error:：

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

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

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

:::consejos

• URL：<dirección del servicio>

• Método：POST

• Encabezado：

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

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

DirectiveObject

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

HeaderObject

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

• SyncTTSAudioList | | message_id | string | N | ID del mensaje de la solicitud, UUID_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

Ejemplo de solicitud:

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

**Parámetros de respuesta correctos: **

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

HeaderObject

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

• Respuesta (Respuesta exitosa)

• ErrorResponse (Respuesta de error) | | message_id | string | N | ID del mensaje del encabezado de la respuesta, UUID_V4. Mensaje de la solicitud entrante aquí: header.message_id | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

Objeto Payload:

Atributo	Tipo	Opcional	Descripción
lista_audio	AudioObject []	N	Lista de audio TTS

Estructura de AudioObject

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

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

{
    "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 del servicio TTS por parte de la pasarela.

:::consejos

• URL：<dirección del servicio>

• Método：POST

• Encabezado：

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

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

DirectiveObject

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

HeaderObject

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

• SynthesizeSpeech | | message_id | string | N | ID del mensaje de la solicitud: UUID_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

PayloadObject

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

Ejemplo de solicitud:

{
    "directive": {
        "header": {
            "name": "SynthesizeSpeech",
            "message_id": "Identificador único, preferiblemente un UUID versión 4",
            "version": "1"
        },
        "payload": {
            "text": "Texto de entrada para sintetizar.",
            "label": "etiqueta de audio tts"
        }
    }
}

**Parámetros de respuesta correctos: **

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

HeaderObject

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

• Respuesta (Respuesta exitosa)

• ErrorResponse (Respuesta de error) | | message_id | string | N | ID del mensaje del encabezado de la respuesta, UUID_V4. Mensaje de la solicitud entrante aquí: header.message_id | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 |

PayloadObject

Atributo	Tipo	Opcional	Descripción
audio	AudioObject	N	Audio TTS

Estructura de AudioObject

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

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

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

Atributo	Tipo	Opcional	Descripción
audio_url	string	N	Dirección URL del audio

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

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

8. Tarjeta de UI personalizada

Las tarjetas de UI personalizadas le permiten mostrar cualquier contenido que desee dentro de la tarjeta. Este contenido puede ser una página web, una imagen o cualquier servicio con una interfaz de usuario. Solo necesita proporcionar la URL del contenido que desea mostrar. La tarjeta de UI ajustará automáticamente su ancho y alto, y el contenido se renderizará usando un iFrame.

8.1 Instrucción

Rol clave

• Proveedor de servicio UI: El proveedor responsable de crear tarjetas de UI personalizadas en la pasarela.

• Servidor de la pasarela: El servidor de la pasarela (iHost).

• Cliente de la API abierta de la pasarela: El cliente Open API para la pasarela.

8.1.1 Crear una tarjeta de UI personalizada

• [Proveedor de servicio UI]: Llama a la API para crear una tarjeta de UI personalizada en la pasarela.

• [Servidor de la pasarela]: Tras el registro exitoso, la pasarela almacena la información básica de la tarjeta de UI (incluida la configuración de tamaño y la URL del recurso de la tarjeta) y asigna un ID interno de tarjeta de UI dentro de la pasarela.

imagen.png

8.1.2 Recuperar la lista de tarjetas de UI

• [Proveedor de servicio UI]: Llama a la API para recuperar la lista de tarjetas de UI.

• [Servidor de la pasarela]: Devuelve la lista de tarjetas de UI almacenadas en la pasarela, incluidas las tarjetas de UI personalizadas no creadas por el llamador.

imagen.png

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

• [Proveedor de servicio UI]: Llama a la API para modificar la configuración de una tarjeta de UI especificada, como la configuración de tamaño y la URL del recurso.

• [Servidor de la pasarela]: Tras la modificación exitosa, la pasarela almacena la información actualizada de la tarjeta de UI, incluida la nueva configuración de tamaño y la URL del recurso.

imagen.png

8.1.4 Eliminar una tarjeta de UI personalizada

1. [Proveedor de servicio UI]: Llama a la API para eliminar una tarjeta de UI personalizada especificada.

2. [Servidor de la pasarela]: La pasarela eliminará toda la información relacionada con la tarjeta de UI especificada.

imagen.png

8.2 Módulo de tarjeta de UI personalizada

8.2.1 Crear una tarjeta de UI personalizada

El proveedor de servicio UI envía una solicitud a la pasarela para crear una tarjeta de UI personalizada.

:::consejos

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

• Método：POST

• Encabezado：

  • Content-Type: application/json

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

Atributo	Tipo	Opcional	Descripción
etiqueta	string	Y	Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Es el alias de la tarjeta.
configuraciones_cast	CastSettingsObject	Y	Configuración de tarjeta Cast: Ajustes de configuración para tarjetas cast.
configuraciones_web	WebSettingsObject	N	Configuración de tarjeta Web: Ajustes de configuración para tarjetas web.

CastSettingsObject:

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

WebSettingsObject:

Atributo	Tipo	Opcional	Descripción
dimensiones	DimensionObject []	N	Configuración de tamaño: Debe incluir al menos una configuración.
componente_cajón	DrawerObject	Y	Ajustes de visualización del componente cajón.
default	string	N	Especificación predeterminada:

• 1x1

• 2x1 |

DimensionObject:

Atributo	Tipo	Opcional	Descripción
src	string	N	URL del recurso: Por ejemplo: http://example.html
tamaño	string	N	Especificaciones de tamaño:
Parámetros opcionales de CastSettingsObject:

• 2×2

Parámetros opcionales de WebSettingsObject:

• 1x1

• 2x1 |

DrawerObject:

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

Respuesta de datos exitosa:

Atributo	Tipo	Opcional	Descripción
id	string	N	ID único de la tarjeta UI

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

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

Ejemplo de respuesta:

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

8.2.2 Recuperar la lista de tarjetas UI

:::consejos

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

• Método：GET

• Encabezado：

  • Content-Type: application/json

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

Atributo	Tipo	Opcional	Descripción
data	CardObject[]	N	Lista de tarjetas UI

Objeto CardObjec:

Atributo	Tipo	Opcional	Descripción
id	string	N	ID de la tarjeta: Un identificador único para la tarjeta.
etiqueta	string	Y	Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Sirve como alias o nombre de la tarjeta.
configuraciones_cast	CastSettingsObject	Y	Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Es el alias de la tarjeta.
configuraciones_web	WebSettingsObject	N	Configuración de tarjeta Cast: Ajustes de configuración para tarjetas cast.
app_name	string	Y	Configuración de tarjeta Web: Ajustes de configuración para tarjetas web.

CastSettingsObject:

Atributo	Tipo	Opcional	Descripción
dimensiones	DimensionObject []	N	Configuración de tamaño: Debe incluir al menos una configuración.
default	string	N	Especificación predeterminada:
Parámetro opcional: 2x2
usado	string	N	Especificación actual:
Parámetro opcional: 2x2

WebSettingsObject:

Atributo	Tipo	Opcional	Descripción
dimensiones	DimensionObject []	N	Configuración de tamaño: Debe incluir al menos una configuración.
componente_cajón	DrawerObject	Y	Ajustes de visualización del componente cajón.
default	string	N	Especificación predeterminada:
Parámetro opcional:

• 1x1

• 2x1 | | used | string | N | Especificación actual: Parámetro opcional:

• 1x1

• 2x1 |

DimensionObject:

Atributo	Tipo	Opcional	Descripción
src	string	N	URL del recurso: Por ejemplo: http://example.html
tamaño	string	N	Especificaciones de tamaño:
Parámetro opcional:

• 1x1

• 2x1

Nota: Actualmente, las tarjetas cast solo admiten la especificación 2x2. La especificación 2x2 no tendrá efecto. |

DrawerObject:

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

Ejemplo de respuesta:

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

8.2.3 Modificar la configuración de una tarjeta UI especificada

Los usuarios autorizados pueden modificar la configuración de una tarjeta UI existente a través de esta interfaz. Los proveedores de servicios de tarjetas personalizadas solo pueden modificar las tarjetas UI que ellos hayan creado.

:::consejos

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

• Método：PUT

• Encabezado：

  • Content-Type: application/json

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

Atributo	Tipo	Opcional	Descripción
etiqueta	string	Y	Usado para describir la tarjeta. Es el alias de la tarjeta.
configuraciones_cast	CastSettingsObject	Y	Configuración de tarjeta Cast
configuraciones_web	WebSettingsObject	Y	Configuración de tarjeta Web

CastSettingsObject:

Atributo	Tipo	Opcional	Descripción
usado	string	Y, Cualquiera usado o src debe proporcionarse, pero se requiere al menos uno de estos parámetros.	Especificación actual:
Parámetro opcional:

• 2x2

| | src | string | Y, Cualquiera usado o src debe proporcionarse, pero se requiere al menos uno de estos parámetros. | URL del recurso: http://example.html |

WebSettingsObject:

Atributo	Tipo	Opcional	Descripción
usado	string	Y, Cualquiera usado o src debe proporcionarse, pero se requiere al menos uno de estos parámetros.	Especificación actual:
Parámetro opcional:

• 1x1

• 2x1 | | src | string | Y, Cualquiera usado o src debe proporcionarse, pero se requiere al menos uno de estos parámetros. | URL del recurso: http://example.html |

Respuesta de datos exitosa: :::tips Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. La tarjeta UI que se está modificando debe haber sido creada por el proveedor de tarjeta UI personalizada que llama a la interfaz. **Código de estado: ** 200 OK Código de error:

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

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

**Ejemplo de solicitud: **

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

8.2.4 Eliminar tarjeta UI personalizada

Los usuarios autorizados pueden eliminar una tarjeta UI existente utilizando esta interfaz. Los proveedores de tarjetas personalizadas solo pueden eliminar las tarjetas UI que hayan creado.

:::consejos

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

• Método：DELETE

• Encabezado：

  • Content-Type: application/json

  • Autorización: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: :::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. La tarjeta UI que se está modificando debe haber sido creada por el proveedor de tarjeta UI personalizada que llama a la interfaz. **Código de estado: ** 200 OK Código de error:

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

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