# Guía para desarrolladores y API ## 1. Comenzar a usar ### 1.1 Preparación Paso 1. Asegúrese de que la pasarela esté encendida y funcione correctamente. Paso 2. Asegúrese de que la pasarela y el PC estén conectados a la misma LAN. Luego ingrese la URL de CUBE en su navegador. Aviso: Si tiene varias pasarelas, puede obtener la dirección IP correspondiente para acceder a la pasarela especificada de las dos maneras siguientes. 1. Inicie sesión en su router inalámbrico y verifique la dirección IP de la pasarela en DHCP. 2. CUBE admite el descubrimiento local a través de mDNS. ### 1.2 Comenzar * Llame a la interfaz \[Access Token] y obtenga una respuesta de error que indique hacer clic <**Hecho**>. Tenga en cuenta que después de presionar, el acceso a la interfaz es válido por no más de 5 minutos. ```json // Solicitud curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Respuesta { "error": 401, "data": {}, "message": "link button not pressed" } ``` * Haga clic <**Hecho**> y llame de nuevo a la interfaz \[Access Token]. La respuesta es exitosa y se obtiene el token. ```json // Solicitud curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Respuesta { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` * Verificar el token. Llame a la interfaz \[Get Device List]. La respuesta es exitosa y se obtiene la lista de dispositivos. ```json // Solicitud curl --location --request GET 'http:///open-api/V2/rest/devices' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d' // Respuesta { "error": 0, "data": { "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "device name", "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "readWrite" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ] } "message": "success" } ``` * Método para obtener el token de acceso de CUBE: después de llamar a la interfaz \[Access Token], la página de la consola web de CUBE mostrará un cuadro emergente global que solicita al usuario confirmar la adquisición de las credenciales de llamada de la interfaz. * Nota: Si abre más de una página de la consola web de CUBE, el cuadro emergente de confirmación aparecerá en varias páginas de la consola web al mismo tiempo, y el cuadro emergente de otras páginas se cerrará después de hacer clic en la confirmación en una de las páginas. ## 2. Concepto central ### 2.1 Dirección de la interfaz de desarrollo La API web de la pasarela tiene dos métodos de acceso (basado en IP o nombre de dominio), usualmente la ruta raíz es /open-api/V2/rest/< módulo funcional específico > // Acceso por IP http\:///open-api/V2/rest/bridge // Acceso por nombre de dominio http\:///open-api/V2/rest/bridge ### 2.2 Categoría de visualización del dispositivo y capacidades * \*\*Categoría de visualización del dispositivo (DisplayCategory). \*\*La categoría de visualización del dispositivo se utiliza para identificar categorías específicas (del dispositivo), como switch, plug, light, etc. **Esta información determinará el efecto de visualización de la interfaz de usuario del dispositivo en la pasarela**. * \*\*Capacidad del dispositivo. \*\*La capacidad del dispositivo se usa para describir las subfunciones específicas del dispositivo. Como control de energía, control de brillo, control de temperatura de color, etc. **Un solo dispositivo puede soportar 1 o más capacidades**. * **capability:** Describe el nombre de la capacidad, que debe ser único a nivel global y de tipo cadena. Varias palabras en inglés deben separarse con guiones ("-"). Por ejemplo: `"thermostat-target-setpoint"`. * **name:** Describe la categoría dentro de la capacidad, también de tipo cadena. Varias palabras en inglés deben separarse con guiones ("-"). Por ejemplo: `"auto-mode"`, `"manual-mode"`. * **permission:** Describe los permisos asociados con la capacidad. El tipo es cadena, formateado en un código binario 8421. Ejemplos incluyen: * Dispositivo controlable: `"1000"` * Dispositivo configurable: `"0010"` * Dispositivo controlable y configurable: `"1010"` * Dispositivo controlable e informable: `"1100"` El significado de cada bit, de derecha a izquierda, es el siguiente: ⅰ. Bit 0: Permite consultar el dispositivo ⅱ. Bit 1: Permite configurar el dispositivo ⅲ. Bit 2: Permite que el dispositivo informe datos ⅳ. Bit 3: Permite controlar el dispositivo ```javascript const permission = { "update": "1000", "updated": "0100", "configure": "0010", "query": "0001", "update-updated": "1100", "update-query": "1001", "update-updated-configure": "1110", "updated-configure":"0110", "update-updated-query":"1101" } ``` **settings:** Describe los elementos de configuración para la capacidad, que son de tipo objeto e incluyen una descripción de cada elemento de configuración. ⅰ. **key:** Describe el nombre del elemento de configuración, que es de tipo cadena. Varias palabras en inglés deben expresarse en camelCase. Por ejemplo: `"temperatureUnit"`. ⅱ. **value:** Describe el contenido del elemento de configuración. Las especificaciones concretas se detallan en la tabla a continuación. | Atributo | Tipo | Opcional | Descripción | | ----------------------- | ------ | -------- | -------------------------------------------------------- | | permission | string | N | Describe los permisos para el elemento de configuración. | | **Valores opcionales:** | | | | * Permitir la modificación de este elemento de configuración: `"10"` * Permitir la visualización de este elemento de configuración: `"01"` * Permitir tanto la modificación como la visualización de este elemento de configuración: `"11"` **Explicación de bits:** 1. **Bit 0:** Permite la visualización de este elemento de configuración 2. **Bit 1:** Permite la modificación de este elemento de configuración | | tipo | string | N | Describe el tipo de datos del valor del elemento de configuración. **Valores opcionales:** * `"enum"` * `"numeric"` * `"object"` * `"boolean"` * `"string"` **Pautas específicas por tipo:** 1. **Cuando `**type = enum**`:** * El `campo value` (que describe el valor del elemento de configuración) es obligatorio si `permission` permite la modificación (`"10"` o `"11"`). * El `default` (que describe el valor por defecto del elemento de configuración) y `values` (que describe los valores seleccionables para el elemento de configuración) son campos opcionales. 2. **Cuando `**type = numeric**`:** * El `campo value` el campo es obligatorio si `permission` permite la modificación (`"10"` o `"11"`). * Los siguientes campos son opcionales: * `min` (que describe el valor mínimo del elemento de configuración) * `max` (que describe el valor máximo del elemento de configuración) * `step` (que describe el valor de paso para el elemento de configuración) * `precision` (que describe la precisión) * `unit` (que describe la unidad del elemento de configuración) * `default` (que describe el valor por defecto) 3. **Cuando `**type = object**`:** * El `campo value` el campo es obligatorio si `permission` permite la modificación (`"10"` o `"11"`). * El `default` el campo es opcional. 4. **Cuando `**type = boolean**`:** * El `campo value` el campo es obligatorio si `permission` permite la modificación (`"10"` o `"11"`). * El `default` el campo es opcional. 5. **Cuando `**type = string**`:** * El `campo value` el campo es obligatorio si `permission` permite la modificación (`"10"` o `"11"`). * El `default` el campo es opcional. | ```javascript // type = enum { "settings":{ "temperatureUnit": { "type": "enum", "permission": "11", "values": ["c", "f"], "default": "c", "value": "f" } } } // type = numeric { "settings": { "setpointRange": { "type": "numeric", "permission": "01", "min": 4, "max": 35, "default": 20, "step": 0.5, "precision": 0.01 "unit": "c" } } } // type = object { "settings":{ "weeklySchedule":{ "type": "object", "permission": "11", "value": { "maxEntryPerDay": 2, "Monday": [ { "startTimeInMinutes": 440, "upperSetpoint": 36.5 }, { "startTimeInMinutes": 900, "upperSetpoint": 26.5 } ]， "Tuesday": [...], "Wednesday": [...], "Thursday": [...], "Friday": [...], "Saturday": [...], "Sunday": [...], } } } } ``` ## 3. API web ### Tipo de datos | Tipo | Descripción | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | string | Tipo de dato string. Codificado en UTF8. | | number | Tipo de dato numérico. [formato binario en coma flotante de doble precisión de 64 bits IEEE 754](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) | | int | Tipo de dato entero. | | object | Tipo de dato objeto. Objeto compatible con JSON | | string\[] | Array de strings | | int\[] | Array de enteros | | object\[] | Array de objetos | | bool | Booleano | | date | Cadena de tiempo. Cadena en formato ISO (Formato extendido ISO 8601): YYYY-MM-DDTHH:mm:ss.sssZ. La zona horaria siempre es UTC (Tiempo Universal Coordinado), identificada por el sufijo "Z". | ### Resultados genéricos de la respuesta | Atributo | Tipo | Opcional | Descripción | | ------------------------------------------------------------------------------------------------- | ------ | -------- | ------------------------------- | | error | int | N | Código de error: | | 0: Éxito | | | | | 400: Error de parámetro | | | | | 401: Autenticación fallida | | | | | 500: Excepción del servidor | | | | | data | object | N | Cuerpo de datos de la respuesta | | message | string | N | Descripción de la respuesta: | | Cuando error es igual a 0, el contenido es success | | | | | Cuando error no es igual a 0, es una cadena no vacía y el contenido es una descripción del error. | | | | **Ejemplo de respuesta**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` ```json { "error": 400, "data": {}, "message": "invalid parameters" } ``` ### Lista de recursos | Tipo | Descripción | | ------------------- | ----------------------------- | | Sonidos compatibles | - alert1 (Sonido de alarma 1) | * alert2 (Sonido de alarma 2) * alert3 (Sonido de alarma 3) * alert4 (Sonido de alarma 4) * alert5 (Sonido de alarma 5) * doorbell1 (Sonido de timbre 1) * doorbell2 (Sonido de timbre 2) * doorbell3 (Sonido de timbre 3) * doorbell4 (Sonido de timbre 4) * doorbell5 (Sonido de timbre 5) * alarm1 (Sonido de alarma 1) * alarm2 (Sonido de alarma 2) * alarm3 (Sonido de alarma 3) * alarm4 (Sonido de alarma 4) * alarm5 (Sonido de alarma 5) | | Deep compatibles | - bootComplete (Inicio del sistema completado) * networkConnected (Red conectada) * networkDisconnected (Red desconectada) * systemShutdown (Apagado del sistema) -deviceDiscovered (Dispositivo descubierto) * system Armed (Sistema armado habilitado) * system Disarmed (Sistema armado deshabilitado) * factoryReset (Restablecer dispositivo) | ### 3.1 La función de la pasarela #### a. Token de acceso Permite a los usuarios obtener el token de acceso. * Aviso: El token se borrará después del reinicio del dispositivo. * Aviso: Después de obtener el token, debe presionar el botón nuevamente para obtener con éxito un nuevo token. :::consejos * **URL**：`/open-api/V2/rest/bridge/access_token` * **Método**：`GET` * **Encabezado**： * Content-Type: application/json ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ---------------------------------------- | | app\_name | string | Y | Descripción del nombre de la aplicación. | Respuesta de datos exitosa: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------------------------------------------------------------------------- | | token | string | N | El token de acceso de la interfaz. Es válido por largo tiempo, por favor guárdelo | | app\_name | string | Y | Descripción del nombre de la aplicación. | :::consejos **Condición**: El usuario activa la < tecla de comando > y accede a esta interfaz dentro del tiempo válido. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` Respuesta de datos en caso de fallo：Objeto vacío :::consejos **Condiciones**：El usuario no ha activado la < tecla de comando >, o el tiempo válido ha expirado. \*\*Código de estado: \*\* `200 OK` ::: **Ejemplo de respuesta**: ```json { "error": 401, "data": {}, "message": "link button not pressed" } ``` #### b. Obtener el estado de la pasarela Permite a los usuarios autorizados obtener el estado de la pasarela a través de esta interfaz :::consejos * **URL**：`/open-api/V2/rest/bridge/runtime` * **Método**：`GET` * **Encabezado**： * Content-Type: application/json * Autorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------- | | ram\_used | int | N | Porcentaje de uso de RAM. \[0-100] | | cpu\_used | int | N | Porcentaje de uso de CPU. \[0-100] | | power\_up\_time | date | N | La última hora de encendido | | cpu\_temp | int | N | Temperatura de la CPU: | | Unidad: Celsius | | | | | cpu\_temp\_unit | string | N | Unidad de temperatura de la CPU: | | Opcional | | | | | valores:`'c'`, `'f'` | | | | | sd\_card\_used | int | Y | Uso de la tarjeta SD (porcentaje): | | Rango:`[0-100]` con una posición decimal de precisión | | | | | \*Nota: Si la tarjeta SD no está insertada o no está formateada, el valor está vacío. | | | | :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": { "ram_used": 40, "cpu_used": 30, "power_up_time": "2022-10-12T02:58:09.989Z", "cpu_temp": 51, "cpu_temp_unit": "c", "sd_card_used" : "12" }, "message": "success" } ``` #### c. Configurar la pasarela Permite a los usuarios autorizados configurar la pasarela a través de esta interfaz :::consejos * **URL**：`/open-api/V2/rest/bridge/config` * **Método**：`PUT` * **Encabezado**： * Content-Type: application/json * Autorization: Bearer ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ----------------------------- | | volume | int | Y | Volumen del sistema. \[0-100] | Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Obtener la información de la pasarela Permite a los usuarios autorizados obtener la información de la pasarela a través de esta interfaz :::consejos * **URL**：`/open-api/V2/rest/bridge` * **Método**：`GET` * **Encabezado**： * Content-Type: application/json ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ----------------------------------- | | ip | string | N | dirección ip | | mac | string | N | dirección mac | | domain | string | Y | Dominio del servicio de la pasarela | | fw\_version | string | N | Versión de firmware | | name | string | N | Nombre del dispositivo | Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Ninguno \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": { "ip": "192.168.31.25", "mac": "00:0A:02:0B:03:0C", "domain": "ihost.local", "fw_version": "1.9.0", "name": "iHost" }, "message": "success" } ``` #### e. Silenciar la pasarela Permite a los usuarios autorizados silenciar la pasarela a través de esta interfaz. :::consejos * **URL**：`/open-api/v2/rest/bridge/mute` * **Método**：`PUT` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### f. Quitar silencio de la pasarela Permite a los usuarios autorizados quitar el silencio de la pasarela a través de esta interfaz.\ :::consejos * **URL**：`/open-api/v2/rest/bridge/unmute` * **Método**：`PUT` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### g. Cancelar la alarma de la pasarela Permite a los usuarios autorizados desactivar el estado de sonido de alarma en la pasarela a través de esta interfaz. :::consejos * **URL**：`/open-api/v2/rest/bridge/cancel_alarm` * **Método**：`PUT` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.2 Función de hardware #### a. Reiniciar la pasarela Permite al usuario autorizado reiniciar la pasarela a través de esta interfaz :::consejos * **URL**：`/open-api/V2/rest/hardware/reboot` * **Método**：`POST` * **Encabezado**： * Content-Type: application/json * Autorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: ```json { "error": 0, "data": {}, "message": "success" } ``` #### b. Control del altavoz Permite a los usuarios autorizados controlar el altavoz a través de esta interfaz :::consejos * **URL**：`/open-api/V2/rest/hardware/speaker` * **Método**：`POST` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ----------- | ----------------------------- | ----------------------------------------------------------------------------------------------- | | type | string | N | Parámetros opcionales: 1.play\_sound (reproducir el sonido) 2.play\_beep (reproducir el pitido) | | sound | SoundObject | Y (N si type es play\_sound.) | El sonido. | | beep | BeepObject | Y (N si type es play\_beep.) | El pitido | SoundObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | El nombre del sonido. Los valores compatibles se pueden consultar en \[Resource List - Supported sound] | | volume | int | N | El volumen del sonido. \[0-100] | | countdown | int | N | La duración durante la cual el altavoz reproducirá el sonido, y dejará de reproducir automáticamente cuando termine el tiempo. Unidad: segundos. \[0,1799] | BeepObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------- | | name | string | N | El nombre del deep. Los valores compatibles se pueden consultar en \[Resource List - Supported deep] | | volume | int | N | El volumen del deep. \[0-100] | Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\* `200 OK` ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.3 Función de gestión de dispositivos #### a. Tipos de dispositivos compatibles | **Tipo de dispositivo** | **Valor** | Versión iHost | | ------------------------------- | ---------------------------- | ------------- | | Enchufe | plug | ≥ 2.1.0 | | Interruptor | switch | ≥ 2.1.0 | | Luz | light | ≥ 2.1.0 | | Cortina | curtain | ≥ 2.1.0 | | Sensor de puerta/ventana | contactSensor | ≥ 2.1.0 | | Sensor de movimiento | motionSensor | ≥ 2.1.0 | | Sensor de temperatura | temperatureSensor | ≥ 2.1.0 | | Sensor de humedad | humiditySensor | ≥ 2.1.0 | | Sensor de temperatura y humedad | temperatureAndHumiditySensor | ≥ 2.1.0 | | Detector de fugas de agua | waterLeakDetector | ≥ 2.1.0 | | Detector de humo | smokeDetector | ≥ 2.1.0 | | Botón inalámbrico | button | ≥ 2.1.0 | | Cámara | camera | ≥ 2.1.0 | | Sensor general | sensor | ≥ 2.1.0 | | Sensor general | sensor | ≥ 2.1.0 | | Ventilador-luz | fanLight | ≥ 2.1.0 | | Aire acondicionado | airConditioner | ≥ 2.1.0 | | Ventilador | fan | ≥ 2.1.0 | | Termostato | thermostat | ≥ 2.1.0 | #### b. Capacidades de dispositivo compatibles **Interruptor de encendido (power):** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "power", // Nombre de la capacidad "permission": "1100", // ihost no admite configurar arranque/parada suave, por lo tanto no hay campo configure } ] ``` **Atributo de estado:** ``` { "powerState": "on", // El campo powerState indica el estado de encendido/apagado. Obligatorio. **Tipo:** string. "on" indica encendido, "off" indica apagado, "toggle" indica alternar. } ``` **Protocolo (Consulta de estado e instrucciones de control):** **Encender:** ``` { "power": { "powerState": "on" } } ``` **Apagar:** ``` { "power": { "powerState": "off" } } ``` **Interruptor de canal (toggle):** **Ejemplo de declaración de capacidad:** Ejemplo de componente único: ``` [ { "capability": "toggle", // Nombre de la capacidad "permission": "1100", // Permiso "name": "1", // Nombre del componente, **Tipo:** String. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4), u otros valores que contengan letras mayúsculas, minúsculas y números } ] ``` Ejemplo de componentes múltiples: ``` [ { "capability": "toggle", "permission": "1100", "name": "1" }, { "capability": "toggle", "permission": "1100", "name": "2" } ] ``` **Atributo de estado:** ``` { "toggleState": "on", // El campo toggleState indica el estado de alternancia del atributo {name} del {device_id}. Obligatorio. **Tipo:** String. "on" indica habilitado, "off" indica deshabilitado, "toggle" indica alternar. } ``` **Protocolo (Consulta de estado e instrucciones de control):** Formato de alternancia: ``` { [capability]: { [toggle-name]: { [toggleState]: [value] } } } Componente 1 encendido, Componente 2 apagado: { "toggle": { "1": { "toggleState": "on" }, "2": { "toggleState": "off" } } } ``` **Inching de canal (toggle-inching):** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "toggle-inching", // Nombre de la capacidad "permission": "0010", // Permiso "settings": { "toggleInchingSetting": { "permission": "11", "type": "object", "value": { "supported": { "1": { // Nombre del componente "enable": true, // Si la función inching está habilitada. **Tipo:** Boolean. Obligatorio. "inchingSwitch": "off", // Configuración del interruptor inching. **Tipo:** String. Obligatorio. "off" (apagado), "on" (encendido) "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Obligatorio. "min_delay": 500, // Tiempo mínimo de retardo "max_delay": 100000 // Tiempo máximo de retardo }, "2": { // Nombre del componente "enable": true, // Si la función inching está habilitada. **Tipo:** Boolean. Obligatorio. "inchingSwitch": "off", // Configuración del interruptor inching. **Tipo:** String. Obligatorio. "off" (apagado), "on" (encendido) "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Obligatorio. "min_delay": 500, // Tiempo mínimo de retardo "max_delay": 100000 // Tiempo máximo de retardo }, "3": { // Nombre del componente "enable": true, // Si la función inching está habilitada. **Tipo:** Boolean. Obligatorio. "inchingSwitch": "off", // Configuración del interruptor inching. **Tipo:** String. Obligatorio. "off" (apagado), "on" (encendido) "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Obligatorio. "min_delay": 500, // Tiempo mínimo de retardo "max_delay": 100000 // Tiempo máximo de retardo }, "4": { // Nombre del componente "enable": true, // Si la función inching está habilitada. **Tipo:** Boolean. Obligatorio. "inchingSwitch": "off", // Configuración del interruptor inching. **Tipo:** String. Obligatorio. "off" (apagado), "on" (encendido) "delay": 1000, // Tiempo de retardo de inching en milisegundos. **Tipo:** Integer. Obligatorio. "min_delay": 500, // Tiempo mínimo de retardo "max_delay": 100000 // Tiempo máximo de retardo } } } } } } ] ``` **Atributo de estado** Ninguno **Protocolo (Consulta de estado e instrucciones de control)** Ninguno **Ajuste de brillo (brightness):** **Ejemplo de declaración de capacidad:** ``` { "capability": "brightness", // Nombre de la capacidad "permission": "1100" // Permiso } ``` **Atributo de estado:** ``` { "brightness": 100, // El campo brightness indica el porcentaje de brillo. Elija entre brightness o brightnessDelta. **Tipo:** Number. Rango: 0-100. } ``` **Protocolo (Consulta de estado e instrucciones de control):** Establecer brillo al 80%. (0 es el más oscuro y 100 el más claro.) ``` json 复制代码 { "brightness": { "brightness": 80 } } ``` **Ajuste de temperatura de color (color-temperature):** **Ejemplo de declaración de capacidad:** ``` { "capability": "color-temperature", // Nombre de la capacidad "permission": "1100" // Permiso } ``` **Atributo de estado:** ``` { "colorTemperature": 100, // El campo colorTemperature indica el porcentaje de temperatura de color. Elija entre colorTemperature o colorTemperatureDelta. **Tipo:** Number. Rango: 0-100. 0 indica luz cálida, 50 indica luz neutra, 100 indica luz fría. } ``` **Protocolo (Consulta de estado e instrucciones de control):** Ajustar temperatura de color al 50%: ``` json { "color-temperature": { "colorTemperature": 50 } } ``` **Ajuste de color (color-rgb):** **Ejemplo de declaración de capacidad:** ``` { "capability": "color-rgb", // Nombre de la capacidad "permission": "1100" // Permiso } ``` **Atributo de estado:** ``` { "red": 255, // El campo red representa el color rojo en el espacio de color RGB. Obligatorio. **Tipo:** Number. Rango: 0-255. "green": 0, // El campo green representa el color verde en el espacio de color RGB. Obligatorio. **Tipo:** Number. Rango: 0-255. "blue": 255 // El campo blue representa el color azul en el espacio de color RGB. Obligatorio. **Tipo:** Number. Rango: 0-255. } ``` **Protocolo (Consulta de estado e instrucciones de control):** Establecer color a púrpura: ``` { "color-rgb": { "red": 255, "green": 0, "blue": 255 } } ``` **Ajuste por porcentaje (percentage):** **Ejemplo de declaración de capacidad:** ``` { "capability": "percentage", "permission": "1100", "settings": { // Opcional "percentageRange": { "permission": "01", "type": "numeric", "min": 0, "max": 100, "step": 5 } } } ``` **Atributo de estado:** ``` { "percentage": 100, // El campo percentage indica un valor porcentual. Elija entre percentage o percentageDelta. **Tipo:** Number. Rango: 0-100. } ``` **Protocolo (Consulta de estado e instrucciones de control):** Ajustar al 40%: ``` { "percentage": { "percentage": 40 } } ``` **Control de motor (motor-control):** **Ejemplo de declaración de capacidad:** ``` { "capability": "motor-control", "permission": "1100" } ``` **Atributo de estado:** ``` json { "motorControl": "stop", // El campo motorControl indica el estado del motor. Obligatorio. **Tipo:** String. Valores posibles: "open" (abrir), "close" (cerrar), "stop" (detener), "lock" (bloquear). } ``` **Protocolo (Consulta de estado e instrucciones de control):** Abrir motor: ``` { "motor-control": { "motorControl": "open" } } ``` **Inversión de motor (motor-reverse):** **Ejemplo de declaración de capacidad:** ``` { "capability": "motor-reverse", "permission": "1100" } ``` **Atributo de estado:** ``` { "motorReverse": true, // El campo motorReverse indica la configuración de dirección del motor. Obligatorio. **Tipo:** Boolean. true indica avance, false indica reverso. } ``` **Protocolo (Consulta de estado e instrucciones de control):** Configurar motor hacia adelante: ``` { "motor-reverse": { "motorReverse": true } } ``` **Calibración del motor (motor-clb)** **Ejemplo de declaración de capacidad:** ``` { "capability": "motor-clb", "permission": "0100" } ``` **Atributos (Estado):** ``` { "motorClb": "calibration" // El campo motorClb indica el estado de calibración del motor. Obligatorio. **Tipo:** String. "normal" indica modo normal (calibrado), "calibration" indica calibración en curso. } ``` **Protocolo (Reporte de estado):** Informar que el motor está siendo calibrado: ``` { "motor-clb": { "motorClb": "calibration" } } ``` **Estado de encendido al iniciar (startup)** **Ejemplo de declaración de capacidad:** ``` { "capability": "startup", "permission": "1100" } ``` **Atributos (Estado):** ``` { "startup": "on" // Estado de energía al iniciar. **Tipo:** String. Obligatorio. Valores opcionales: "on" (encendido), "stay" (mantener encendido), "off" (apagado), "toggle" (invertir estado de energía). } ``` **Protocolo (Consulta de estado e instrucciones de control):** Establecer estado de encendido siempre activado: ``` { "startup": { "startup": "on" } } ``` *** **Activación de despertador (identify)** **Ejemplo de declaración de capacidad:** ``` { "capability": "identify", "permission": "0100" } ``` **Atributos (Estado):** ``` { "identify": true // Indica si el dispositivo informa activamente resultados de reconocimiento o está activado. } ``` **Protocolo (Reporte de estado e instrucciones de control):** Establecer tiempo de activación del despertador: ``` { "identify": { "countdown": 180 // El campo countdown indica el tiempo de cuenta regresiva. Obligatorio. **Tipo:** Number. Unidad: segundos. } } ``` Informar estado de activación: ``` { "identify": { "identify": true // Indica si el dispositivo informa activamente resultados de reconocimiento o está activado. } } ``` **Estadísticas de consumo de energía en tiempo real (power-consumption)** **Ejemplo de declaración de capacidad:** ``` { "capability": "power-consumption", "permission": "1101", "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ``` **Atributos (Estado):** Iniciar/Detener estadísticas en tiempo real: ``` { "rlSummarize": true, // Iniciar/detener estadísticas en tiempo real. **Tipo:** Boolean. Obligatorio. "timeRange": { // Rango de tiempo resumido. Obligatorio. "start": "2020-07-05T08:00:00Z", // Hora de inicio de las estadísticas de consumo de energía. **Tipo:** String. Obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin de las estadísticas de consumo de energía. **Tipo:** String. Obligatorio. } } ``` Consultar consumo de energía por rango de tiempo: ``` { "type": "summarize", // Tipo de estadísticas. **Tipo:** String. Obligatorio. Valores opcionales: "rlSummarize" (resumen en tiempo real), "summarize" (resumen actual). "timeRange": { // Rango de tiempo resumido. Obligatorio si type es "summarize". "start": "2020-07-05T08:00:00Z", // Hora de inicio de las estadísticas de consumo de energía. **Tipo:** String. Obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin de las estadísticas de consumo de energía. **Tipo:** String. Opcional. Si se omite, indica la hora actual. } } ``` Responder con el resultado de estadísticas dentro del rango de tiempo: ``` json { "type": "summarize", // Tipo de estadísticas. **Tipo:** String. Obligatorio. Valores opcionales: "rlSummarize" (resumen en tiempo real), "summarize" (resumen actual). "rlSummarize": 50.0, // Consumo total de energía. **Tipo:** Number. Unidad: 0.01 kWh. Opcional. "electricityIntervals": [ // Múltiples registros de estadísticas divididos según configuration.resolution. Opcional. No presente cuando type es "rlSummarize". { "usage": 26.5, // Consumo de energía. **Tipo:** Number. Unidad: 0.01 kWh. Obligatorio. "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Date. Obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Date. Obligatorio. Si el intervalo entre end y start es menor que resolution, todos los registros informados se consideran inválidos. }, { "usage": 26.5, // Consumo de energía. **Tipo:** Number. Unidad: 0.01 kWh. Obligatorio. "start": "2020-07-05T09:00:00Z", // Hora de inicio. **Tipo:** Date. Obligatorio. "end": "2020-07-05T10:00:00Z" // Hora de fin. **Tipo:** Date. Obligatorio. Si el intervalo entre end y start es menor que resolution, todos los registros informados se consideran inválidos. } ] } ``` **Protocolo (Reporte de estado e instrucciones de control):** Iniciar estadísticas en tiempo real: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Detener estadísticas en tiempo real: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Obtener consumo de energía histórico: ``` json { "power-consumption": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } ``` Obtener consumo de energía en tiempo real: ``` json { "power-consumption": { "powerConsumption": { "type": "rlSummarize" } } } ``` **Detección de modo de temperatura y humedad (thermostat-mode-detect)** **Ejemplo de declaración de capacidad:** ``` { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Tipo de detección de control de temperatura. **Tipo:** String. Obligatorio. Valores opcionales: "humidity" (detección de humedad), "temperature" (detección de temperatura). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Ajustes de detección compatibles. Obligatorio. { "name": "lowerSetpoint", // El valor detectado debe estar por encima de este punto de ajuste. Se requiere al menos uno de lowerSetpoint o upperSetpoint. "value": { // Rango de detección. Opcional. Especificar si existen condiciones preestablecidas. "value": 68.0, // Valor de temperatura. **Tipo:** Number. Obligatorio. "scale": "f" // Unidad de temperatura. Obligatorio cuando name=temperature. Valores opcionales: "c" (Celsius), "f" (Fahrenheit). } }, { "name": "upperSetpoint", // El valor detectado debe estar por debajo de este punto de ajuste. Se requiere al menos uno de lowerSetpoint o upperSetpoint. "value": { // Rango de detección. Opcional. Especificar si existen condiciones preestablecidas. "value": 68.0, // Valor de temperatura. **Tipo:** Number. Obligatorio. "scale": "f" // Unidad de temperatura. Obligatorio cuando name=temperature. Valores opcionales: "c" (Celsius), "f" (Fahrenheit). } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } { "capability": "thermostat-mode-detect", "permission": "0110", "name": "humidity", // Tipo de detección de control de temperatura. **Tipo:** String. Obligatorio. Valores opcionales: "humidity" (detección de humedad), "temperature" (detección de temperatura). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Ajustes de detección compatibles. Obligatorio. { "name": "lowerSetpoint", // El valor detectado debe estar por encima de este punto de ajuste. Se requiere al menos uno de lowerSetpoint o upperSetpoint. "value": { // Rango de detección. Opcional. Especificar si existen condiciones preestablecidas. "value": 68.0, // Valor de humedad. **Tipo:** Number. Obligatorio } }, { "name": "upperSetpoint", // El valor detectado debe estar por debajo de este punto de ajuste. Se requiere al menos uno de lowerSetpoint o upperSetpoint. "value": { // Rango de detección. Opcional. Especificar si existen condiciones preestablecidas. "value": 68.0, // Valor de humedad. **Tipo:** Number. Obligatorio } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ``` **Atributos (Estado):** ``` { "mode": "COMFORT" // ID de modo. Opcional. Valores compatibles: "COMFORT" (Modo Confort), "COLD" (Modo Frío), "HOT" (Modo Calor), "DRY" (Modo Seco), "WET" (Modo Húmedo). } ``` **Protocolo (Consulta de estado e instrucciones de control):** Formato: ``` { [capability] :{ [mode name] :{ "mode": [value] } } } ``` Ejemplo: ``` { "thermostat-mode-detect": { "humidity": { "mode": "COMFORT" } } } ``` **Modo del termostato (thermostat-mode)** **Ejemplo de declaración de capacidad:** ``` { "capability": "thermostat", "permission": "1100", "name": "thermostat-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", "AUTO", "ECO" ] } } } ``` **Atributos (Estado):** ``` { "thermostatMode": "MANUAL" // Modo de funcionamiento del termostato. **Tipo:** String. Valores opcionales: "MANUAL", "AUTO", "ECO". } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "thermostat": { "thermostat-mode": { "thermostatMode": "MANUAL" } } } ``` **Estado de recuperación adaptativa del termostato (thermostat/adaptive-recovery-status)** **Ejemplo de declaración de capacidad:** ``` { "capability": "thermostat", "permission": "0100", "name": "adaptive-recovery-status" // Estado de recuperación adaptativa del termostato } ``` **Atributos (Estado):** ``` { "adaptiveRecoveryStatus": "HEATING" // Estado de recuperación adaptativa del termostato. **Tipo:** String. Valores opcionales: "HEATING", "INACTIVE". } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "thermostat": { "adaptive-recovery-status": { "adaptiveRecoveryStatus": "HEATING" } } } ``` **Configuración de temperatura objetivo del modo del termostato (thermostat-target-setpoint)** **Ejemplo de declaración de capacidad:** ``` [[ { "capability": "thermostat-target-setpoint", "name": "manual-mode", "permission": "1110", "settings": { "temperatureUnit":{ "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange":{ "type": "numeric", "permission": "01", "min": 4, "max": 35, "step": 0.5 } } }, { "capability": "thermostat-target-setpoint", "name": "eco-mode", "permission": "1110", "settings": { "temperatureUnit":{ "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange":{ "type": "numeric", "permission": "01", "min": 4, "max": 35, "step": 0.5 } } }, { "capability": "thermostat-target-setpoint", "name": "auto-mode", "permission": "0110", "settings": { "temperatureUnit":{ "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange":{ "type": "numeric", "permission": "01", "min": 4, "max": 35, "step": 0.5 }, "weeklySchedule":{ "type": "object", "permission": "11", "value": { "maxEntryPerDay": 2, "Monday": [ { "startTimeInMinutes": 440, // Hora de inicio en minutos. **Tipo:** int. P. ej., 7:20 AM = 440 minutos. "upperSetpoint": 36.5, // Temperatura objetivo máxima. **Tipo:** number. "lowerSetpoint": 20 // Temperatura objetivo mínima. **Tipo:** number. }, { "startTimeInMinutes": 900, // Hora de inicio en minutos. P. ej., 3:00 PM = 900 minutos. "upperSetpoint": 26.5, // Temperatura objetivo máxima. **Tipo:** number. "lowerSetpoint": 21 // Temperatura objetivo mínima. **Tipo:** number. } ], "Tuesday": [... ], "Wednesday": [... ], "Thursday": [... ], "Friday": [... ], "Saturday": [... ], "Sunday": [... ], } } } } ] ``` **Atributos (Estado):** ``` { "targetSetpoint": 30 // Temperatura objetivo para el modo especificado. **Tipo:** number, en la unidad especificada por temperatureUnit. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "thermostat-target-setpoint": { "manual-mode": { "targetSetpoint": 30 }, "auto-mode": { "targetSetpoint": 30 } } } ``` **Detección de sensor (detect)** **Ejemplo de declaración de capacidad:** ``` { "capability": "detect", "permission": "0110", "settings": { // Opcional "detectInterval": { "permission": "11", "type": "numeric", "value": 300 }, "detectSensitivity": { "permission": "11", "type": "numeric", "value": 1000 } } } ``` **Atributos (Estado):** ``` { "detected": true // Resultado de detección. **Tipo:** Boolean. `true` indica detección, `false` indica sin detección. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "detect": { "detected": true } } ``` **Detección de temperatura (temperature)** **Ejemplo de declaración de capacidad:** ``` { "capability": "temperature", "permission": "0110", "settings": { // Opcional "temperatureCalibration": { // Calibración de temperatura opcional "type": "numeric", "permission": "11", "min": -7, // Valor mínimo "max": 7, // Valor máximo "step": 0.2, // Paso de ajuste de temperatura, unidad igual a temperatureUnit "value": 5.2 // Valor actual de calibración de temperatura. **Tipo:** number. }, "temperatureUnit": { // Unidad de temperatura opcional "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange": { // Rango de detección de temperatura opcional "type": "numeric", "permission": "01", "min": -40, "max": 80 } } } ``` **Atributos (Estado):** ``` json 复制代码 { "temperature": 26.5 // Temperatura actual. **Tipo:** Number, en Celsius. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "temperature": { "temperature": 20 } } ``` **Detección de humedad (humidity)** **Ejemplo de declaración de capacidad:** ``` { "capability": "humidity", "permission": "0100", "settings": { // Rango de detección de humedad opcional. "humidityRange": { "type": "numeric", "permission": "01", "min": 0, "max": 100 } } } ``` **Atributos (Estado):** ``` { "humidity": 50 // Humedad relativa actual (porcentaje). **Tipo:** Number, rango 0-100. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "humidity": { "humidity": 20 } } ``` **Detección de batería (battery)** **Ejemplo de declaración de capacidad:** ``` { "capability": "battery", "permission": "0100" } ``` **Atributos (Estado):** ``` { "battery": 95 // Porcentaje de batería restante. **Tipo:** Number, rango -1 a 100. Nota: -1 indica nivel de batería desconocido. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "battery": { "battery": 40 } } ``` **Detección de botón único (press)** **Ejemplo de declaración de capacidad:** ``` { "capability": "press", "permission": "1100", "settings": { // Opcional "actions": { // Acciones del botón, opcional. "type": "enum", "permission": "01", "values": [ // Acciones del botón opcionales. Los valores predeterminados son "singlePress", "doublePress", "longPress". Las acciones configuradas reemplazan los valores predeterminados. ] } } } ``` **Atributos (Estado):** ``` { "press": "singlePress" // Tipo de pulsación del botón. **Tipo:** String. Valores estándar: "singlePress" (pulsación única o corta), "doublePress" (doble pulsación), "longPress" (pulsación larga). } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "press": { "press": "singlePress" } } ``` **Detección de múltiples pulsaciones (multi-press)** **Ejemplo de declaración de capacidad:** ``` { "capability": "multi-press", "permission": "0100", "name": "1", // Nombre del atributo multi-press. **Tipo:** String. Solo se permiten caracteres alfanuméricos. "settings": { // Opcional "actions": { // Acciones del botón, opcional. "type": "enum", "permission": "01", "values": [ // Acciones del botón opcionales. Los valores predeterminados son "singlePress", "doublePress", "longPress". Las acciones configuradas reemplazan los valores predeterminados. ] } } } ``` **Atributos (Estado):** ``` { "press": "singlePress" // Tipo de pulsación del botón. **Tipo:** String. Valores estándar: "singlePress" (pulsación única o corta), "doublePress" (doble pulsación), "longPress" (pulsación larga). } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { [capability] :{ [multi-press-name]：{ press:[value] } } } ejemplo: { "multi-press": { "1": { "press": "singlePress" }, "2": { "press": "doublePress" } } } ``` **Detección de intensidad de señal (rssi)** **Ejemplo de declaración de capacidad:** ``` { "capability": "rssi", "permission": "0100" } ``` **Atributos (Estado):** ``` { "rssi": -65 // Intensidad de la señal inalámbrica (Indicador de intensidad de señal recibida). **Tipo:** Number, unidad dBm, valores enteros negativos. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "rssi": { "rssi": -65 } } ``` **Detección de manipulación (tamper-alert)** **Ejemplo de declaración de capacidad:** ``` { "capability": "tamper-alert", "permission": "0100" } ``` **Atributos (Estado):** ``` { "tamper": "clear" // Estado de manipulación. **Tipo:** String. Valores posibles: "clear" (no manipulado), "detected" (manipulado). } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "tamper-alert": { "tamper": "clear" // Estado de manipulación. **Tipo:** String. Valores posibles: "clear" (no manipulado), "detected" (manipulado). } } ``` **Detección de nivel de iluminación (illumination-level)** **Ejemplo de declaración de capacidad:** ``` { "capability": "illumination-level", "permission": "0100" } ``` **Atributos (Estado):** ``` { "level": "brighter" // Nivel de luminosidad. **Tipo:** String. Valores posibles: "brighter" (más brillante), "darker" (más oscuro). } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "illumination-level": { "level": "brighter" } } ``` **Detección de voltaje (voltage)** **Ejemplo de declaración de capacidad:** ``` { "capability": "voltage", "permission": "0100" } ``` **Atributos (Estado):** ``` { "voltage": 50 // Valor de voltaje actual, en unidades de 0.01V. **Tipo:** Number, valores no negativos. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "voltage": { "voltage": 50 } } ``` **Detección de corriente eléctrica (electric-current)** **Ejemplo de declaración de capacidad:** ``` { "capability": "electric-current", "permission": "0100" } ``` **Atributos (Estado):** ``` { "electric-current": 50 // Valor de corriente actual, en unidades de 0.01A. **Tipo:** Number, valores enteros no negativos. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "electric-current": { "electric-current": 50 } } ``` **Detección de potencia eléctrica (electric-power)** **Ejemplo de declaración de capacidad:** ``` { "capability": "electric-power", "permission": "0100" } ``` **Atributos (Estado):** ``` { "electric-power": 50 // Valor de potencia actual, en unidades de 0.01W. **Tipo:** Number, valores enteros no negativos. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "electric-power": { "electric-power": 50 } } ``` **Detección de fallos (fault)** **Ejemplo de declaración de capacidad:** ``` { "capability": "fault", "permission": "0100" } ``` **Atributos (Estado):** ``` { "fault": "none" // Estado de fallo. **Tipo:** String. Valores posibles: "none" (sin fallo), "detected" (fallo detectado). } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "fault": { "fault": "none" } } ``` **Disyuntor de umbral (threshold-breaker)** **Ejemplo de declaración de capacidad:** ``` { "capability": "threshold-breaker", "permission": "0010", "settings": { "supportedSetting": { "type": "object", "permission": "11", "value": { "supported": [ { "name": "lowerPower", // Disyuntor de umbral de baja potencia "value": { "value": 50, // Valor de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0. "min_range": 10, // Valor mínimo de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0. "max_range": 3500 // Valor máximo de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0. } }, { "name": "upperPower", // Disyuntor de umbral de alta potencia "value": { "value": 50, // Valor de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0. "min_range": 10, // Valor mínimo de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0. "max_range": 3500 // Valor máximo de potencia de detección, en unidades de 0.01W. **Tipo:** Integer. Rango: >=0. } }, { "name": "lowerElectricCurrent", // Disyuntor de umbral de baja corriente "value": { "value": 50, // Valor de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0. "min_range": 10, // Valor mínimo de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0. "max_range": 1500 // Valor máximo de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0. } }, { "name": "upperElectricCurrent", // Disyuntor de umbral de alta corriente "value": { "value": 50, // Valor de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0. "min_range": 10, // Valor mínimo de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0. "max_range": 1500 // Valor máximo de corriente de detección, en unidades de 0.01A. **Tipo:** Integer. Rango: >=0. } }, { "name": "lowerVoltage", // Disyuntor de umbral de bajo voltaje "value": { "value": 50, // Valor de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0. "min_range": 10, // Valor mínimo de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0. "max_range": 24000 // Valor máximo de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0. } }, { "name": "upperVoltage", // Disyuntor de umbral de alto voltaje "value": { "value": 50, // Valor de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0. "min_range": 10, // Valor mínimo de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0. "max_range": 24000 // Valor máximo de voltaje de detección, en unidades de 0.01V. **Tipo:** Integer. Rango: >=0. } } ] } } } } ``` **Atributos (Estado)** * Ninguno **Protocolo (Consulta de estado e instrucciones de control)** * Ninguno **Función Inch (inching)** **Ejemplo de declaración de capacidad:** ``` { "capability": "inching", "permission": "0010", "settings": { "inchingEnable": { // Configuración de habilitación de la función inch "permission": "11", "type": "boolean", "value": false }, "inchingSwitch": { // Configuración de la acción inch "type": "enum", "permission": "11", "value": "on", "values": ["on", "off"] }, "inchingDelay": { // Configuración del tiempo de inch "type": "numeric", "permission": "11", "min": 500, "max": 100000, "value": 1000, "unit": "ms" } } } ``` **Atributos (Estado):** * Ninguno **Protocolo (Consulta de estado e instrucciones de control):** * Ninguno **Transmisión de cámara (camera-stream)** **Ejemplo de declaración de capacidad:** ``` { "capability": "camera-stream", "permission": "0010", "settings": { "streamSetting": { "type": "object", "permission": "11", "value": { "username": "String", // Cuenta de acceso. **Tipo:** String. Obligatorio. "password": "String", // Contraseña de acceso. **Tipo:** String. Obligatorio. "streamUrl": "rtsp://:@:/streaming/channel01", // URL de transmisión. **Tipo:** String. Obligatorio. "videoCodec": "", // Códec de video. **Tipo:** String. Obligatorio. Parámetros opcionales a definir. "resolution": { // Resolución de video. Obligatorio. "width": 1080, // Ancho. **Tipo:** Number. Obligatorio. "height": 720 // Alto. **Tipo:** Number. Obligatorio. }, "keyFrameInterval": 5, // Intervalo de fotograma clave. **Tipo:** String. Obligatorio. "audioCodec": "G711", // Códec de audio. **Tipo:** String. Obligatorio. Parámetros opcionales a definir. "samplingRate": 50, // Tasa de muestreo de audio, en Hz. **Tipo:** Number. Obligatorio. Parámetros opcionales a definir. "dataRate": 50 // Tasa de bits. **Tipo:** Number. Obligatorio. Unidad: kb/s. } } } } ``` **Atributos (Estado):** * Ninguno **Protocolo (Consulta de estado e instrucciones de control):** * Ninguno **Control de modo (mode)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "mode", "name": "fanLevel", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["low", "medium", "high"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados. } } }, { "capability": "mode", "name": "thermostatMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["auto", "manual"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados. } } }, { "capability": "mode", "name": "airConditionerMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["cool", "heat", "auto", "fan", "dry"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados. } } }, { "capability": "mode", "name": "fanMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["normal", "sleep", "child"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados. } } }, { "capability": "mode", "name": "horizontalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados. } } }, { "capability": "mode", "name": "verticalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Valores de modo personalizados. Los valores configurados reemplazan los predeterminados. } } } ] ``` **Atributos (Estado):** ``` { "modeValue": "low" // Valor de modo. **Tipo:** String. Obligatorio. Consulte los modos preestablecidos compatibles. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "mode": { "fanLevel": { "modeValue": "low" } } } ``` **Detección de dióxido de carbono (co2)** **Ejemplo de declaración de capacidad:** ``` { "capability": "co2", "permission": "0100", "settings": { "co2Range": { "type": "numeric", "permission": "01", "min": 400, "max": 10000 } } } ``` **Atributos (Estado):** ``` { "co2": 111 // Concentración de dióxido de carbono. **Tipo:** Integer. Unidad: ppm. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "co2": { "co2": 500 } } ``` **Detección de iluminación (illumination)** **Ejemplo de declaración de capacidad:** ``` { "capability": "illumination", "permission": "0100", "settings": { "illuminationRange": { "type": "numeric", "permission": "01", "min": 0, "max": 160000 } } } ``` **Atributos (Estado):** ``` { "illumination": 11 // Nivel de iluminación. **Tipo:** Integer. Unidad: lux. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "illumination": { "illumination": 50 } } ``` **Detección de humo (smoke)** **Ejemplo de declaración de capacidad:** ``` { "capability": "smoke", "permission": "0100" } ``` **Atributos (Estado):** ``` { "smoke": true // Resultado de detección. **Tipo:** Boolean. `true` indica detección, `false` indica sin detección. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "smoke": { "smoke": true } } ``` **Detección de apertura/cierre por imán de puerta (contacto)** **Ejemplo de declaración de capacidad:** ``` { "capability": "contact", "permission": "0100" } ``` **Atributos (Estado):** ``` { "contact": true // Resultado de detección. **Tipo:** Booleano. `true` indica detección, `false` indica sin detección. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "contact": { "contact": true } } ``` **Detección de movimiento (motion)** **Ejemplo de declaración de capacidad:** ``` { "capability": "motion", "permission": "0110", "settings": { "motionInterval": { "type": "numeric", "permission": "11", "value": 300 }, "motionSensitivity": { "type": "numeric", "permission": "11", "value": 1000 } } } ``` **Atributos (Estado):** ``` { "motion": true // Resultado de detección. **Tipo:** Booleano. `true` indica detección, `false` indica sin detección. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "motion": { "motion": true } } ``` **Detección de fugas de agua (water-leak)** **Ejemplo de declaración de capacidad:** ``` { "capability": "water-leak", "permission": "0100" } ``` **Atributos (Estado):** ``` { "waterLeak": true // El campo `waterLeak` indica el resultado actual de la detección. **Tipo:** Booleano. `true` indica detección, `false` indica sin detección. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "water-leak": { "waterLeak": true } } ``` **Interruptor de detección de ventana (window-detection)** **Ejemplo de declaración de capacidad:** ``` { "capability": "window-detection", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica que la alimentación está encendida, `off` indica que la alimentación está apagada. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "window-detection": { "powerState": "on" } } ``` **Bloqueo infantil (child-lock)** **Ejemplo de declaración de capacidad:** ``` { "capability": "child-lock", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica que la alimentación está encendida, `off` indica que la alimentación está apagada. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "child-lock": { "powerState": "on" } } ``` **Interruptor anti-soplado directo (anti-direct-blow)** **Ejemplo de declaración de capacidad:** ``` { "capability": "anti-direct-blow", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica que la alimentación está encendida, `off` indica que la alimentación está apagada. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "anti-direct-blow": { "powerState": "on" } } ``` **Interruptor de oscilación horizontal (horizontal-swing)** **Ejemplo de declaración de capacidad:** ``` { "capability": "horizontal-swing", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica que la alimentación está encendida, `off` indica que la alimentación está apagada. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "horizontal-swing": { "powerState": "on" } } ``` **Interruptor de oscilación vertical (vertical-swing)** **Ejemplo de declaración de capacidad:** ``` { "capability": "vertical-swing", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica que la alimentación está encendida, `off` indica que la alimentación está apagada. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "vertical-swing": { "powerState": "on" } } ``` **Modo ECO (eco)** **Ejemplo de declaración de capacidad:** ``` { "capability": "eco", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // El campo `powerState` indica el estado de alimentación. **Tipo:** Cadena. `on` indica que la alimentación está encendida, `off` indica que la alimentación está apagada. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "eco": { "powerState": "on" } } ``` **Alternar inicio (toggle-startup)** **Ejemplo de declaración de capacidad:** ``` { "capability": "toggle-startup", "permission": "1100", "name": "1" // El campo `name` especifica el nombre del atributo para `toggle-startup`. **Tipo:** Cadena. Solo se permiten letras y números. } ``` **Atributos (Estado):** ``` { "startup": "on" // **Tipo:** Cadena. Opciones: `on` (encender), `stay` (mantener encendido), `off` (apagar). } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "toggle-startup": { "1": { "startup": "on" }, "2": { "startup": "off" } } } ``` **Detección de retención (detect-hold)** **Ejemplo de declaración de capacidad:** ``` { "capability": "detect-hold", "permission": "0100", "settings": { "detectHoldEnable": { // Configuración de habilitar detección de retención "permission": "01", "type": "boolean", "value": false }, "detectHoldSwitch": { // Configuración de acción de detección de retención "type": "enum", "permission": "01", "value": "on", "values": ["on", "off"] }, "detectHoldTime": { // Configuración de tiempo de detección de retención "type": "numeric", "permission": "01", "min": 1, "max": 359, "value": 5, "unit": "minute" } } } ``` **Atributos (Estado):** ``` { "detectHold": "on" // El campo `detectHold` indica el estado de la retención de detección. **Tipo:** Cadena. `on` significa que la retención de detección está activa, `off` significa que está inactiva. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "detect-hold": { "detectHold": "on" } } ``` **Alternar identificar/activar (toggle-identify)** **Ejemplo de declaración de capacidad:** ``` { "capability": "toggle-identify", "permission": "1100", // Nota: Esta capacidad no se usa para reportes en la versión actual (V1.13.7) en ihost. "name": "1" // Nombre del componente. **Tipo:** Cadena. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). } ``` **Atributos (Estado):** ``` { "identify": true, // Indica que el dispositivo ha reportado activamente identificación o activación. "countdown": 180 // El campo `countdown` indica la duración de la activación. **Tipo:** Número. Unidad: segundos. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "toggle-identify": { "1": { "countdown": 180 // Activar el dispositivo durante 180 segundos. } } } // El dispositivo reporta autoactivación { "toggle-identify": { "1": { "identify": true } } } ``` **Detección de voltaje alterno (toggle-voltage)** **Ejemplo de declaración de capacidad:** ``` { "capability": "toggle-voltage", "permission": "1100" } ``` **Atributos (Estado):** ``` { "voltage": 230 // El campo `voltage` indica el voltaje detectado. **Tipo:** Número. Unidad: Voltios. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "toggle-voltage": { "voltage": 230 } } ``` **Detección de corriente eléctrica de subcomponente (toggle-electric-current)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "toggle-electric-current", "permission": "0100", "name": "1" // Nombre del componente. **Tipo:** Cadena. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). } ] ``` **Atributos (Estado):** ``` { "electricCurrent": 50 // El campo `electricCurrent` representa el valor de corriente. **Unidad:** 0.01 A. **Tipo:** Entero. El valor debe ser mayor o igual a 0. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "toggle-electric-current": { "1": { "electricCurrent": 50 } } } ``` **Detección de potencia de subcomponente (toggle-electric-power)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "toggle-electric-power", "permission": "0100", "name": "1" // Nombre del componente. **Tipo:** Cadena. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). } ] ``` **Atributos (Estado):** ``` { "electricPower": 50, // El campo `electricPower` representa el valor actual de potencia. **Unidad:** 0.01 W. **Tipo:** Entero. El valor debe ser mayor o igual a 0. "reactivePower": 50, // El campo `reactivePower` representa el valor actual de potencia reactiva. **Unidad:** 0.01 W. **Tipo:** Entero. Opcional. "activePower": 50, // El campo `activePower` representa el valor actual de potencia activa. **Unidad:** 0.01 W. **Tipo:** Entero. Opcional. "apparentPower": 50 // El campo `apparentPower` representa el valor actual de potencia aparente. **Unidad:** 0.01 W. **Tipo:** Entero. Opcional. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "toggle-electric-power": { "1": { "electricPower": 50, "reactivePower": 50, "activePower": 50, "apparentPower": 50 } } } ``` **Estadísticas de consumo de energía de subcomponentes (toggle-power-consumption)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "toggle-power-consumption", "permission": "1101", "name": "1", // Nombre del componente. **Tipo:** Cadena. Valores opcionales: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ] ``` **Atributos (Estado):** Iniciar/Detener estadísticas en tiempo real: ``` { "rlSummarize": true, // Iniciar o detener estadísticas en tiempo real. **Tipo:** Booleano. Obligatorio. "timeRange": { // Rango de tiempo para resumen. Obligatorio. "start": "2020-07-05T08:00:00Z", // Hora de inicio del consumo de energía. **Tipo:** Cadena. Obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin del consumo de energía. **Tipo:** Cadena. Obligatorio. } } ``` Consultar consumo de energía por rango de tiempo: ``` { "type": "summarize", // Tipo de resumen. **Tipo:** Cadena. Obligatorio. Opciones: "rlSummarize" (resumen en tiempo real), "summarize" (resumen actual). "timeRange": { // Rango de tiempo para resumen, obligatorio cuando el tipo es "summarize". "start": "2020-07-05T08:00:00Z", // Hora de inicio del consumo de energía. **Tipo:** Cadena. Obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin del consumo de energía. **Tipo:** Cadena. Opcional. Si no se proporciona, por defecto es la hora actual. } } ``` Respuesta para consumo de energía dentro del rango de tiempo: ``` { "type": "summarize", // Tipo de resumen. **Tipo:** Cadena. Obligatorio. "rlSummarize": 50.0, // Consumo total de energía. **Unidad:** 0.01 kWh. **Tipo:** Número. Opcional. "electricityIntervals": [ // Dividido por `configuration.resolution` en múltiples registros. Opcional. No presente cuando el tipo es "rlSummarize". { "usage": 26.5, // Consumo de energía. **Unidad:** 0.01 kWh. **Tipo:** Número. Obligatorio. "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Cadena. Obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Cadena. Obligatorio. Los registros con intervalos más cortos que la resolución se consideran inválidos. }, { "usage": 26.5, // Consumo de energía. **Unidad:** 0.01 kWh. **Tipo:** Número. Obligatorio. "start": "2020-07-05T09:00:00Z", // Hora de inicio. **Tipo:** Cadena. Obligatorio. "end": "2020-07-05T10:00:00Z" // Hora de fin. **Tipo:** Cadena. Obligatorio. Los registros con intervalos más cortos que la resolución se consideran inválidos. } ] } ``` **Protocolo (Consulta de estado e instrucciones de control):** Iniciar estadísticas en tiempo real: ``` { "toggle-power-consumption": { "1": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Detener estadísticas en tiempo real: ``` { "toggle-power-consumption": { "1": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Obtener consumo de energía histórico: ``` { "toggle-power-consumption": { "1": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Obtener consumo de energía en tiempo real: ``` { "toggle-power-consumption": { "1": { "type": "rlSummarize" } } } ``` **Indicador de calidad de enlace (lqi)** **Ejemplo de declaración de capacidad:** ``` { "capability": "lqi", "permission": "0100" } ``` **Atributos (Estado):** ``` { "lqi": 60 // El campo `lqi` representa el indicador de calidad de enlace. **Tipo:** Número. Rango de valores: 0 a 255. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "lqi": { "lqi": 60 } } ``` **Configuración funcional (configuration)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "configuration", "permission": "1100" } ] ``` **Atributos (Estado):** ``` { "deviceConfiguration": { // Configuración funcional relacionada con el dispositivo "defaultResolution": 300, // Resolución predeterminada para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio. "maxResolution": 86400, // Resolución máxima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio. "minResolution": 60 // Resolución mínima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio. } } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "configuration": { "deviceConfiguration": { // Configuración funcional relacionada con el dispositivo "defaultResolution": 300, // Resolución predeterminada para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio. "maxResolution": 86400, // Resolución máxima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio. "minResolution": 60 // Resolución mínima para leer datos de saturación de humedad. **Tipo:** Entero. **Unidad:** Segundos. Obligatorio. } } } ``` **Sistema (system)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "system", "permission": "1000" } ] ``` **Atributos (Estado):** ``` { "restart": true // Comando para reiniciar el dispositivo. **Tipo:** Booleano. Obligatorio. El valor debe ser `true`. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "system": { // Configuración relacionada con la capacidad. Opcional. "restart": true } } ``` **Humedad (moisture)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "moisture", "permission": "0100" } ] ``` **Atributos (Estado):** ``` { "moisture": 55.5 // El campo `moisture` representa el porcentaje de saturación de humedad. **Tipo:** Número. Obligatorio. Rango: 0 a 100. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "moisture": { "moisture": 55.5 } } ``` **Presión barométrica (barometric-pressure)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "barometric-pressure", "permission": "0100", "settings": { "barometricPressureRange": { "type": "numeric", "permission": "01", "min": 540, // Valor mínimo. **Tipo:** Entero. Obligatorio. Debe ser menor que `max`. "max": 1100 // Valor máximo. **Tipo:** Entero. Obligatorio. Debe ser mayor que `min`. } } } ] ``` **Atributos (Estado):** ``` { "barometricPressure": 50 // Valor de presión barométrica. **Tipo:** Entero. Obligatorio. **Unidad:** hPa. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "barometric-pressure": { "barometricPressure": 50 } } ``` **Velocidad del viento (wind-speed)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "wind-speed", "permission": "0100", "settings": { "windSpeedRange": { "type": "numeric", "permission": "01", "min": 0, // Valor mínimo. **Tipo:** Número. Obligatorio. Debe ser menor que `max`. "max": 50 // Valor máximo. **Tipo:** Número. Obligatorio. Debe ser mayor que `min`. } } } ] ``` **Atributos (Estado):** ``` { "windSpeed": 50 // Valor de velocidad del viento. **Tipo:** Número. Obligatorio. **Unidad:** m/s (metros por segundo). } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "wind-speed": { "windSpeed": 50 } } ``` **Dirección del viento (wind-direction)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "wind-direction", "permission": "0100" } ] ``` **Atributos (Estado):** ``` { "windDirection": 10 // Dirección del viento. **Tipo:** Entero. Obligatorio. **Unidad:** Grados. Rango: 0 a 360 grados (dirección en sentido horario). } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "wind-direction": { "windDirection": 10 } } ``` **Precipitación (rainfall)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "rainfall", "permission": "0100", "settings": { "rainfallRange": { "type": "numeric", "permission": "01", "min": 0, // Valor mínimo. **Tipo:** Número. Obligatorio. Debe ser menor que `max`. "max": 450 // Valor máximo. **Tipo:** Número. Obligatorio. Debe ser mayor que `min`. } } } ] ``` **Atributos (Estado):** ``` { "rainfall": 11.11 // Valor de precipitación. **Tipo:** Número. Obligatorio. **Unidad:** mm/h (milímetros por hora). } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "rainfall": { "rainfall": 11.11 } } ``` **Índice ultravioleta (ultraviolet-index)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "ultraviolet-index", "permission": "0100", "settings": { "ultravioletIndexRange": { "type": "numeric", "permission": "01", "min": 0, // Valor mínimo. **Tipo:** Número. Obligatorio. Debe ser menor que `max`. "max": 16 // Valor máximo. **Tipo:** Número. Obligatorio. Debe ser mayor que `min`. } } } ] ``` **Atributos (Estado):** ``` { "ultravioletIndex": 11.1 // Índice ultravioleta. **Tipo:** Número. Obligatorio. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "ultraviolet-index": { "ultravioletIndex": 11.1 } } ``` **Conductividad eléctrica (electrical-conductivity)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "electrical-conductivity", "permission": "0100", "settings": { "electricalConductivityRange": { "type": "numeric", "permission": "01", "min": 0, // Valor mínimo. **Tipo:** Número. Obligatorio. Debe ser menor que `max`. "max": 23 // Valor máximo. **Tipo:** Número. Obligatorio. Debe ser mayor que `min`. } } } ] ``` **Atributos (Estado):** ``` { "electricalConductivity": 11.11 // Valor de conductividad eléctrica. **Tipo:** Número. Obligatorio. **Unidad:** dS/m. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "electrical-conductivity": { "electricalConductivity": 11.11 } } ``` **Potencia de transmisión (transmit-power)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "transmit-power", "permission": "1100" } ] ``` **Atributos (Estado):** ``` { "transmitPower": 9 // Valor de potencia de transmisión del dispositivo. **Tipo:** Entero. Obligatorio. **Unidad:** dBm. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "transmit-power": { "transmitPower": 9 } } ``` **Detección PM2.5 (pm25)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "pm25", "permission": "0100" } ] ``` **Atributos (Estado):** ``` { "pm25": 10 // Concentración de PM2.5 en el aire. **Tipo:** Número. Obligatorio. **Unidad:** µg/m³. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "pm25": { "pm25": 10 } } ``` **Índice VOC (voc-index)** **Ejemplo de declaración de capacidad:** ``` { "capability": "voc-index", "permission": "0100" } ``` **Atributos (Estado):** ``` { "vocIndex": 10 // Índice VOC que refleja el nivel de contaminación por gases nocivos. **Tipo:** Número. Obligatorio. **Unidad:** µg/m³. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "voc-index": { "vocIndex": 10 } } ``` **Detección de gas natural (gas)** **Ejemplo de declaración de capacidad:** ``` { "capability": "gas", "permission": "0100" } ``` **Atributos (Estado):** ``` { "gas": true // Indica si se detecta fuga de gas natural. **Tipo:** Booleano. Obligatorio. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "gas": { "gas": true } } ``` **Estado de trabajo de riego (irrigation/work-status)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "irrigation", "permission": "0101", "name": "work-status", "settings": { "volumeUnit": { "type": "enum", "permission": "01", "values": ["L"], "value": "L" } } } ] ``` **Atributos (Estado):** ``` { "realTimeVolume": 20, // Volumen de riego en tiempo real. **Tipo:** Número. Opcional. **Unidad:** L. "start": "2020-07-05T08:00:00Z", // Hora de inicio del riego. **Tipo:** Fecha. Opcional. "end": "2020-07-05T09:00:00Z", // Hora de fin del riego. **Tipo:** Fecha. Opcional. "dailyVolume": 20 // Volumen de riego diario. **Tipo:** Número. Opcional. **Unidad:** L. } ``` **Protocolo (Consulta de estado e instrucciones de control):** Reporte de estado de trabajo: ``` { "irrigation": { "work-status": { "realTimeVolume": 20, "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z", "dailyVolume": 20 } } } ``` Consulta de estado de trabajo: ``` { "irrigation": { "type": "oneDay", // Tipo de agregación. **Tipo:** Cadena. Obligatorio. Opciones: "oneDay", "30Days", "180Days". "timeRange": { // Rango de tiempo para agregación. **Tipo:** Objeto. Obligatorio. "start": "2020-07-05T08:00:00Z", // Hora de inicio para la agregación de datos de riego. **Tipo:** Cadena. Obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin para la agregación de datos de riego. **Tipo:** Cadena. Opcional. Si se omite, se usa la hora actual. } } } ``` Resultado de la consulta de estado de trabajo: ``` { "irrigation": { "type": "oneDay", // Tipo de agregación. **Tipo:** Cadena. Obligatorio. "irrigationIntervals": [ { "volume": 6500, // Volumen de riego. **Tipo:** Número. Obligatorio. **Unidad:** L. "duration": 30, // Duración del riego. **Tipo:** Número. Obligatorio. **Unidad:** minutos. "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Cadena. Obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Cadena. Obligatorio. }, { "volume": 6500, // Volumen de riego. **Tipo:** Número. Obligatorio. **Unidad:** L. "duration": 30, // Duración del riego. **Tipo:** Número. Obligatorio. **Unidad:** minutos. "start": "2020-07-05T08:00:00Z", // Hora de inicio. **Tipo:** Cadena. Obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin. **Tipo:** Cadena. Obligatorio. } ] } } ``` **Modo de trabajo de riego (irrigation/work-mode)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "irrigation", "permission": "0100", "name": "work-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", // Modo manual "TIMER", // Programación de un solo tiempo "CYCLE-TIMER", // Programación repetida "VOLUME", // Volumen único "CYCLE-VOLUME" // Volumen repetido ] } } } ] ``` **Atributos (Estado):** ``` { "workMode": "MANUAL" // Modo de trabajo de riego. **Tipo:** Cadena. Opcional. Los valores deben provenir de `settings.supportedModes`. } ``` **Protocolo (Consulta de estado e instrucciones de control):** ``` { "irrigation": { "work-mode": "MANUAL" } } ``` **Controlador automático de riego (irrigation/auto-controller)** **Ejemplo de declaración de capacidad:** ``` [ { "capability": "irrigation", "permission": "1100", "name": "auto-controller", "settings": { "volumeRange": { // Rango de volumen "type": "enum", "permission": "01", "min": 0, "max": 6500, "unit": "L" }, "timeRange": { // Rango de tiempo "type": "enum", "permission": "01", "min": 1, "max": 86400, "unit": "second" }, "cycleCountRange": { // Rango de conteo de ciclos "type": "enum", "permission": "01", "min": 1, "max": 100, "step": 1 } } } ] ``` **Atributos (Estado):** Programación de un solo tiempo o repetida: ``` { "type": "time", // Modo de riego. **Tipo:** Cadena. Obligatorio. Opciones: "volume", "time". "action": { "perDuration": 60, // Duración por ciclo de riego. **Tipo:** Número. Obligatorio. "intervalDuration": 20, // Intervalo entre ciclos de riego. **Tipo:** Número. Obligatorio. "count": 3 // Número de ciclos de riego. **Tipo:** Número. Obligatorio. } } ``` Volumen único o repetido: ``` { "type": "volume", // Modo de riego. **Tipo:** Cadena. Obligatorio. Opciones: "volume", "time". "action": { "perConsumedVolume": 60, // Volumen consumido por ciclo de riego. **Tipo:** Número. Obligatorio. "intervalDuration": 20, // Intervalo entre ciclos de riego. **Tipo:** Número. Obligatorio. "count": 3 // Número de ciclos de riego. **Tipo:** Número. Obligatorio. } } ``` **Protocolo (Consulta de estado e instrucciones de control):** Programación de un solo tiempo o repetida: ``` { "irrigation": { "auto-controller": { "type": "time", // Modo de riego. **Tipo:** Cadena. Obligatorio. "action": { "perDuration": 60, // Duración por ciclo de riego. **Tipo:** Número. Obligatorio. "intervalDuration": 20, // Intervalo entre ciclos. **Tipo:** Número. Obligatorio. "count": 3 // Número de ciclos. **Tipo:** Número. Obligatorio. } } } } ``` Volumen único o repetido: ``` { "irrigation": { "auto-controller": { "type": "volume", // Modo de riego. **Tipo:** Cadena. Obligatorio. "action": { "perConsumedVolume": 60, // Volumen consumido por ciclo. **Tipo:** Número. Obligatorio. "intervalDuration": 20, // Intervalo entre ciclos. **Tipo:** Número. Obligatorio. "count": 3 // Número de ciclos. **Tipo:** Número. Obligatorio. } } } } ``` **Modos preestablecidos compatibles** | \*\*Nombres de modo \*\* | \*\*Valores opcionales \*\* | | ---------------------------------------------------------- | --------------------------- | | fanLevel (nivel de ventilador) | "low" | | "medium" | | | "high" | | | thermostatMode (modo del termostato) | "auto" | | "manual" | | | airConditionerMode >= 1.11.0 (modo del aire acondicionado) | "cool" | | "heat" | | | "auto" | | | "fan" | | | "dry" | | | fanMode >= 1.11.0 (modo de ventilador) | "normal" | | "sleep" | | | "child" | | | horizontalAngle >= 1.11.0 (ángulo horizontal) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | | verticalAngle >= 1.11.0 (ángulo vertical) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | #### c. Descripción de etiquetas * La clave especial toggle se usa para establecer el nombre del subcomponente toggle. ``` { "toggle": { '1': 'Canal1', '2': 'Canal2', '3': 'Canal3', '4': 'Canal4', }, } ``` * La clave especial temperature\_unit se usa para establecer la unidad de temperatura. ``` { "temperature_unit":'c' // c-Celsius; f-Fahrenheit } ``` #### d. Código de error especial y descripción | **Código de error** | **Descripción** | Versión iHost | | ------------------- | --------------------------------------------------------------------------------------------------- | ------------- | | 110000 | El subdispositivo/grupo correspondiente al id no existe | ≥2.1.0 | | 110001 | La pasarela está en estado de descubrimiento de dispositivos zigbee | ≥2.1.0 | | 110002 | Los dispositivos de un grupo no tienen una capacidad común | ≥2.1.0 | | 110003 | Número incorrecto de dispositivos | ≥2.1.0 | | 110004 | Número incorrecto de grupos | ≥2.1.0 | | 110005 | Dispositivo desconectado | ≥2.1.0 | | 110006 | Error al actualizar el estado del dispositivo | ≥2.1.0 | | 110007 | Error al actualizar el estado del grupo | ≥2.1.0 | | 110008 | Se ha alcanzado el número máximo de grupos. Cree hasta 50 grupos | ≥2.1.0 | | 110009 | La dirección IP del dispositivo de la cámara es incorrecta | ≥2.1.0 | | 110010 | Error de autorización de acceso al dispositivo de la cámara | ≥2.1.0 | | 110011 | Error en la dirección de flujo de la cámara | ≥2.1.0 | | 110012 | La codificación de video de la cámara no es compatible | ≥2.1.0 | | 110013 | El dispositivo ya existe | ≥2.1.0 | | 110014 | La cámara no admite operación sin conexión | ≥2.1.0 | | 110015 | La contraseña de la cuenta no coincide con la contraseña de la cuenta en la dirección de flujo RTSP | ≥2.1.0 | | 110016 | La pasarela está en estado de descubrimiento de cámaras onvif | ≥2.1.0 | | 110017 | Se excedió el número máximo de cámaras agregadas | ≥2.1.0 | | 110018 | La ruta de la cámara ESP es incorrecta | ≥2.1.0 | | 110019 | Error al acceder a la dirección del servicio del dispositivo de terceros | ≥2.1.0 | #### e. Buscar subdispositivo Permitir a usuarios autorizados habilitar o deshabilitar la búsqueda de subdispositivos en la pasarela a través de esta interfaz * 💡Nota: Actualmente solo se admite la búsqueda de subdispositivos Zigbee. * 💡Nota: Los subdispositivos Zigbee se agregarán automáticamente después de la búsqueda. No es necesario usar la interfaz "Agregar subdispositivos manualmente" :::tips * **URL**：/open-api/V2/rest/devices/discovery * **Método**: PUT * **Encabezado**： * Content-Type: application/json * Autorization: Bearer ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------------------------ | | habilitar | boolean | N | true (Iniciar emparejamiento); false (Pausar emparejamiento) | | type | string | N | Tipo de búsqueda: Zigbee | Respuesta de datos exitosa: Objeto vacío {} :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\* `200 OK` ::: **Ejemplo de respuesta**: ``` { "error": 0, "data": {}, "message": "success" } ``` #### f. Agregar manualmente el subdispositivo Permitir a usuarios autorizados agregar un **único** subdispositivo a través de esta interfaz. * Nota: Actualmente solo se admiten Cámara RTSP y Cámara ESP32 :::tips * **URL**：/open-api/V2/rest/devices * **Método**：POST * **Encabezado**： * Content-Type: application/json * Autorization: Bearer ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ----------------- | ------------------- | ------------ | ----------------------------------------------------------------------------------------------------- | | name | string | N | Nombre del subdispositivo | | display\_category | string | N | Tipo de dispositivo. Solo admite cámara. | | capabilities | CapabilityObject\[] | N | Lista de capacidades. Cuando display\_category = camera, las capacidades solo incluyen camera-stream. | | protocal | string | N | Protocolo del dispositivo. RTSP; ESP32-CAM | | manufacturer | string | N | Fabricante. | | model | string | N | Modelo del dispositivo | | firmware\_version | string | N | Versión del firmware del dispositivo | CapabilityObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------- | ------------------------------- | ------------ | --------------------------------------------------- | | capability | string | N | Nombre de la capacidad. Solo admite "camera-stream" | | permission | string | N | Permiso del dispositivo. Solo admite lectura. | | configuration | CameraStreamConfigurationObject | Y | Configuración de flujo de cámara. | SettingsObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------- | ------------------- | ------------ | ----------------------------------------- | | streamSetting | StreamSettingObject | N | Configuración del servicio de transmisión | StreamSettingObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------------------ | ------------ | ----------------------------------------------------- | | type | string | N | Configuración del servicio de transmisión | | permission | string | N | Permiso de capacidad. Solo admite "11" (modificable). | | campo value | StreamSettingValueObject | N | Valores de configuración específicos | StreamSettingValueObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------------------- | | stream\_url | string | N | Formato de URL de flujo | | Formato:`://:/:@` | | | | | Ejemplo:`rtsp://admin:123456@192.168.10.115:554/streaming/channel01` | | | | | Opciones de esquema: | | | | | `rtsp` (Protocolo de transmisión en tiempo real) | | | | | `http` (Protocolo de transferencia de hipertexto) — Para dispositivos ESP32-CAM | | | | | \*Nota: Algunas cámaras pueden no requerir nombre de usuario o contraseña. En esos casos, puede omitir el `` y `` campos de la URL. | | | | Respuesta de datos exitosa: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------- | -------- | ------------ | ------------------------------------- | | serial\_number | string | N | Número de serie único del dispositivo | :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ``` { "error": 0, "data": { "serial_number": "serial_number" }, "message": "success" } ``` Respuesta de datos de falla: Objeto vacío :::tips **Condición**： 1. Error de acceso a la dirección de flujo de la cámara (error de formato, fallo de autorización, excepción de red, etc.) 2. El dispositivo ya existe 3. Si falla la adición de un solo dispositivo, devuelve que todos los dispositivos fallaron al agregarse. **Código de estado**: 200 OK **Código de error**： ● 110009 Error en la dirección IP de la cámara ● 110010 Error de autorización de acceso a la cámara ● 110011 Error en la dirección de flujo de la cámara ● 110012 La codificación de video de la cámara no es compatible ● 110013 El dispositivo ya existe ::: **Ejemplo de respuesta**: ``` { "error": 110009, "data": {}, "message": "error de acceso ip de la cámara" } ``` #### g. Obtener lista de subdispositivos Permitir a usuarios autorizados obtener la lista de subdispositivos de la pasarela a través de esta interfaz. :::tips * **URL**：/open-api/V2/rest/devices * **Método**: GET * **Encabezado**： * Content-Type: application/json * Autorization: Bearer ::: Parámetros de la solicitud: ninguno Respuesta de datos exitosa: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ----------------------- | ------------ | --------------------- | | device\_list | ResponseDeviceObject\[] | N | Lista de dispositivos | ResponseDeviceObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | --------------------- | ------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de serie único del dispositivo | | third\_serial\_number | string | "N" cuando se conecta un dispositivo de terceros, de lo contrario "Y" | Número de serie único del dispositivo de terceros | | service\_address | string | "N" cuando se conecta un dispositivo de terceros, de lo contrario "Y" | Dirección del servicio de terceros | | name | string | N | Nombre del dispositivo, si no se renombra, será mostrado por el frontend según las reglas de visualización predeterminadas. | | manufacturer | string | N | Fabricante | | model | string | N | Modelo del dispositivo | | firmware\_version | string | N | Versión del firmware. Puede ser una cadena vacía. | | hostname | string | Y | Nombre de host del dispositivo | | mac\_address | string | Y | Dirección MAC del dispositivo | | app\_name | string | Y | El nombre de la aplicación a la que pertenece. Si se completa app\_name al obtener el certificado de la interfaz abierta, entonces todos los dispositivos posteriores conectados mediante el certificado se escribirán en este campo. | | display\_category | string | N | Categoría del dispositivo | | capabilities | CapabilityObject\[] | N | Capacidades del dispositivo | | protocol | string | "N" cuando se conecta un dispositivo de terceros, de lo contrario "Y" | Protocolo del dispositivo: zigbee, onvif, rtsp, esp32-cam | | estado | object | Y | Objeto de estado del dispositivo. Para ejemplos de estado de diferentes capacidades, consulte 【Dispositivos compatibles】 | | etiquetas | object | Y | Clave-valor en formato JSON, información personalizada del dispositivo. La función es la siguiente:- Usado para almacenar canales del dispositivo- Usado para almacenar unidades de temperatura- Información personalizada para otros dispositivos de terceros | | en línea | boolean | N | Estado en línea: True para en líneaFalse es fuera de línea | | subred | boolean | Y | Si está en la misma subred que la pasarela | CapabilityObject 💡Nota: Por favor consulte los Ejemplos de Capacidades de Dispositivos Compatibles en \[Capacidades de Dispositivos Compatibles]. | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | capability | string | N | Nombre de la capacidad. Para más detalles, consulte \[Capacidades de Dispositivos Compatibles] | | permission | string | N | Permiso de la capacidad. Los valores posibles son "read" (lectura), "write" (escritura), "readWrite" (lectura y escritura). | | configuration | object | Y | Información de configuración de la capacidad. Actualmente se usa camera-stream, consulte \[Capacidades de Dispositivos Compatibles] | | name | string | Y | Campo name en toggle. El número de subcanal usado para identificar dispositivos multicanal. Por ejemplo, si name es 1, significa canal 1. | :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ``` { "error": 0, "data":{ "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "Mi dispositivo", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "readWrite" }, { "capability": "rssi", "permission": "read" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ], } "message": "success" } ``` #### h. Actualizar Información o Estado Específico del Dispositivo Permite a usuarios autorizados modificar la información básica del subdispositivo y emitir comandos de control a través de esta interfaz. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Método**：PUT * **Encabezado**： * Content-Type: application/json * Autorization: Bearer ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Y | Nombre del dispositivo | | etiquetas | object | Y | Clave-valor en formato JSON, información personalizada del dispositivo. | | estado | object | Y | Objeto de estado del dispositivo. Para ejemplos de estado de diferentes capacidades, consulte \[Capacidades de Dispositivos Compatibles] | | configuration | object | Y | Información de configuración de la capacidad, actualmente solo la capacidad camera\_stream admite modificación. | Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK **Código de error**: * 110000 El subdispositivo/grupo correspondiente al id no existe ::: **Ejemplo de respuesta**: ``` { "error": 0, "data":{ "serial_number": "ABCDEFGHIJK", "third_serial_number": "third_serial_number", "name": "我的设备", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "1100" }, { "capability": "rssi", "permission": "0100" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true }, "message": "success" } ``` #### i. Eliminar Subdispositivo Permite a usuarios autorizados eliminar subdispositivos a través de esta interfaz. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Método**：DELETE * **Encabezado**： * Content-Type: application/json * Autorization: Bearer ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Y | Nombre del dispositivo. | | etiquetas | object | Y | Pares clave-valor en formato JSON usados para almacenar nombres de canales del dispositivo y otra información sobre subdispositivos. | | estado | object | Y | Cambiar estado del dispositivo; para detalles del protocolo específico, consulte "Capacidades de Dispositivos Compatibles." | | capabilities | CapabilityObject \[] | Y | Información de configuración de la capacidad; todas las capacidades que admiten establecer configuraciones pueden modificarse. Tenga en cuenta que los permisos no se pueden cambiar. | Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK **Códigos de error:** * 110000: El subdispositivo/grupo correspondiente al ID no existe. * 110006: Error al actualizar el estado del dispositivo. * 110019: Error al acceder a la dirección del servicio del dispositivo de terceros. * 110024: Error al actualizar la configuración del dispositivo. ::: **Ejemplo de respuesta**: ``` { "error": 0, "data": {}, "message": "success" } ``` ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // encender dispositivo await axios({ url: `http:///open-api/v2/rest/devices/${serial_number}`, method: 'PUT', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${access_token}` }, data: { state: { power: { powerState: 'on' } } } }); })() ``` #### j. Eliminar Subdispositivo Permite a usuarios autorizados eliminar subdispositivos a través de esta interfaz.\ :::tips * **URL**：`/open-api/v2/rest/devices/{serial_number}` * **Método**：`DELETE` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### k. Consultar Estado del Dispositivo Permite a usuarios autorizados consultar el estado del dispositivo a través de esta interfaz.\ :::tips * **URL**：`/open-api/v2/rest/devices/:serial_number/query-state/{capability}` * **Método**：POST * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | query\_state | object | N | Consultar estado del dispositivo; para detalles del protocolo específico, consulte "Capacidades de Dispositivos Compatibles." | ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // encender dispositivo await axios({ url: `http:///open-api/v2/rest/devices/${serial_number}/query-state/power-consumption`, method: 'PUT', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${access_token}` }, data: { "query_state":{ "power-consumption":{ "type": "summarize", // Tipo de estadísticas, obligatorio "timeRange": { // Rango de tiempo para la resumición, obligatorio cuando type="summarize" "start": "2020-07-05T08:00:00Z", // Hora de inicio para las estadísticas de consumo de energía "end": "2020-07-05T09:00:00Z" // Hora de fin para las estadísticas de consumo de energía; si se omite, por defecto es la hora actual } } } }); })() ``` Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.4 Gestión de Seguridad #### a. Obtener Lista de Seguridad Permite a usuarios autorizados modificar la configuración de la pasarela a través de esta interfaz. :::tips * **URL**：`/open-api/v2/rest/security` * **Método**：`GET` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------- | ------------------------- | ------------ | ---------------------------------- | | security\_list | ResponseSecurityObject\[] | N | Lista de dispositivos de respuesta | ResponseDeviceObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------- | | sid | int | N | id de seguridad | | name | string | N | Nombre de seguridad | | habilitar | bool | N | Si está habilitado | * true Habilitado * false Deshabilitado | :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": { "security_list":[ { "sid": 1, "name": "Modo Hogar", "enable": true } ] }, "message": "success" } ``` #### b. Habilitar Modo de Seguridad Específico Permite a usuarios autorizados habilitar un modo de seguridad específico a través de esta interfaz.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/enable` * **Método**：`PUT` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: Objeto vacío {} :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### c. Deshabilitar Modo de Seguridad Específico Permite a usuarios autorizados deshabilitar un modo de seguridad específico a través de esta interfaz.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/disable` * **Método**：`PUT` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: Objeto vacío {} :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Habilitar Configuración de Seguridad con Un Clic Permite a usuarios autorizados habilitar el modo de configuración de seguridad con un clic a través de esta interfaz.\ :::tips * **URL**：`/open-api/v2/rest/security/enable` * **Método**：`PUT` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: Objeto vacío {} :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### e. Deshabilitar Seguridad Permite a usuarios autorizados deshabilitar la seguridad a través de esta interfaz.\ :::tips * **URL**：`/open-api/v2/rest/security/disable` * **Método**：`PUT` * **Encabezado**： * Content-Type: application/json * Authorization: Bearer ::: Parámetros de la solicitud: Ninguno Respuesta de datos exitosa: Objeto vacío {} :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*200 OK ::: **Ejemplo de respuesta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 4. Acceso de Dispositivos de Terceros ### 4.1 Instrucciones de Acceso #### Acceso de Dispositivo
#### Acceso de pasarela de terceros
#### Pasos de acceso 1. Determine la clasificación del dispositivo en la pasarela. Los detalles, consulte \[Tipo de Dispositivo Compatible]. 2. Determine las capacidades que el dispositivo puede acceder. Los detalles, consulte \[Capacidades de Dispositivos Compatibles]. 3. Solicite la interfaz \[Discovery Request] para agregar el dispositivo a la pasarela. 1. *Atención: Necesita proporcionar la dirección de servicio para recibir las instrucciones emitidas por la pasarela, que se utiliza para recibir las instrucciones de control del dispositivo emitidas por la pasarela*. 4. Si el estado del dispositivo de terceros cambia, debe llamar a la interfaz \[Device States Change Report] para enviar el estado más reciente a la pasarela. 5. Después de agregar, el dispositivo de terceros aparecerá en la Lista de Dispositivos, con la mayoría de las funciones de la pasarela (otros dispositivos no terceros). Las interfaces abiertas comunes relacionadas con el dispositivo se pueden usar con normalidad. * Seleccione la categoría de dispositivo adecuada. La clasificación afectará el resultado final de la interfaz de usuario después de que el dispositivo se conecte a la pasarela. * Elija la capacidad de dispositivo correcta. La lista de capacidades determinará el estado del protocolo de estado del dispositivo. #### Proceso del Programa **a. Acceso de Dispositivo**
**b. Acceso de Pasarela de Terceros**
### 4.2 Ejemplo de Acceso #### Interruptor, Enchufe **Sincronizar dispositivos de terceros** ``` // Solicitud URL：/open-api/v2/rest/thirdparty/event Método：POST Encabezado： Content-Type: application/json Autorization: Bearer Cuerpo: { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "2" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "mi enchufe", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "1100" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "versión de firmware", "service_address": "http://192.168.31.14/webhook" } ] } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number", "serial_number": "serial number" } ] } } ``` **Informar estado del dispositivo** ``` URL：/open-api/V2/rest/thirdparty/event Método：POST Encabezado： Content-Type: application/json Autorization: Bearer Cuerpo: { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": {} } ``` **Informar fuera de línea/en línea** ``` {  "event": {    "header": {      "name": "DeviceStatesChangeReport",      "message_id": "Identificador único, preferiblemente un UUID versión 4",      "version": "1"   },    "endpoint": {      "serial_number": "serial_number"   },    "payload": {       "online": true   } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": {} } ``` **Recibir las instrucciones sobre el control del dispositivo por la pasarela** ``` URL： 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   Cuerpo: Ninguno ``` ``` { "error": 0, "data": { "device_list": [ { "serial_number": "serial number", "third_serial_number": "third_serial_number", "name": "mi enchufe", "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "versión de firmware", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ] }, "message": "success" } ``` ### 4.3 API Web #### Interfaz de Solicitud de Pasarela de Terceros **Formato de Solicitud** Permite a usuarios autorizados enviar solicitudes de eventos a la pasarela a través de esta interfaz. :::tips * **URL**：/open-api/V2/rest/thirdparty/event * **Método**：POST * **Encabezado**： * Content-Type: application/json * Autorization: Bearer ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ----------- | ------------ | ----------------------------------------------------------------- | | evento | EventObject | N | Información de la estructura del objeto de evento de la solicitud | EventObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la solicitud | | endpoint | EndpointObject | Y | Información de la estructura del endpoint de la solicitud Nota: Este campo está vacío cuando se sincroniza una nueva lista de dispositivos. | | payload | PayloadObject | N | Información de la estructura del payload de la solicitud | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nombre de la solicitud. parámetro opcional: DiscoveryRequest: Sincronizar nuevos dispositivos DeviceStatesChangeReport: Informe de actualización de estado del dispositivo DeviceOnlineChangeReport: Informe de estado en línea del dispositivo | | message\_id | string | N | ID de mensaje de la solicitud, UUID\_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 | EndpointObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | --------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de serie único del dispositivo | | third\_serial\_number | string | N | Número de serie único del dispositivo de terceros | | etiquetas | object | Y | Clave-valor en formato JSON, información personalizada del dispositivo. \[Función de Gestión de Dispositivos] - \[Descripción de Etiquetas] | PayloadObject Según el header.name diferente tienen diferente estructura de solicitud. **Formato de Respuesta** :::tips \*\*Código de Estado: \*\*200 OK **Parámetros de la respuesta:** ::: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------- | ------------ | ----------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la respuesta | | payload | PayloadObject | N | Información de la estructura del payload de la respuesta | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nombre del encabezado de la respuesta. parámetros opcionales:Response: Respuesta exitosa ErrorResponse: Respuesta de error | | message\_id | string | N | ID de mensaje del encabezado de la respuesta, UUID\_V4. Pase aquí el header.message\_id del mensaje de la solicitud \*Si la entrada de la solicitud carece de message\_id, este campo será una cadena vacía al responder. | | version | string | N | - Número de versión del protocolo de la solicitud. Actualmente fijo en 1. | > Respuesta exitosa--PayloadObject ： Dependiendo del tipo de solicitud, la estructura de la respuesta es diferente. Para más detalles, consulte el documento de instrucción de la solicitud específica. > Respuesta de fallo--PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------- | | type | string | N | Tipos de error: | * INVALID\_PARAMETERS: Error de parámetros * AUTH\_FAILURE: Error de autorización * INTERNAL\_ERROR: Error interno del servicio | | descripción | string | N | Descripción del error | **DiscoveryRequest Sincronizar una nueva lista de dispositivos** * Nota: Después de que el dispositivo se sincronice con la pasarela, está en línea por defecto, es decir, online=true. Los cambios posteriores de estado en línea dependen completamente de la sincronización con el tercero a través de la interfaz DeviceOnlineChangeReport. **Parámetros de la solicitud:** EndpointObject\*\*：\*\*Ninguno PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ----------------- | ------------ | --------------------- | | endpoints | EndpointObject\[] | N | Lista de Dispositivos | EndpointObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | --------------------- | ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | third\_serial\_number | string | N | Número de serie único del dispositivo de terceros | | name | string | N | Nombre del dispositivo | | display\_category | string | N | Categoría del Dispositivo. Consulte \[Tipo de Dispositivo Compatible] para más detalles. \*Los dispositivos de terceros no admiten agregar cámaras ahora. | | capabilities | CapabilityObject\[] | N | Lista de capacidades | | estado | object | N | Información de estado inicial | | manufacturer | string | N | Fabricante | | model | string | N | Modelo del dispositivo | | etiquetas | object | Y | Clave-valor en formato JSON, información personalizada del dispositivo:Se usa para almacenar canales del dispositivoSe usa para almacenar unidades de temperaturaOtros datos personalizados de terceros | | firmware\_version | string | N | Versión de firmware | | service\_address | string | N | Dirección del servicio. Tal como | Ejemplo de Solicitud : ``` { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "mi enchufe", "display_category": "plug", "capabilities": [ { "capability": "power", "permission" "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "versión de firmware", "service_address": "http://192.168.31.14/service_address" } ] } } } ``` **Parámetros de la respuesta:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ----------------- | ------------ | --------------------- | | endpoints | EndpointObject\[] | N | Lista de dispositivos | EndpointObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | --------------------- | -------- | ------------ | ------------------------------------------------- | | serial\_number | string | N | Número de serie único del dispositivo | | third\_serial\_number | string | N | Número de serie único del dispositivo de terceros | Ejemplo de una respuesta correcta: ``` { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "endpoints": [ { "serial_number": "serial number", "third_serial_number": "third_serial_number" } ] } } ``` Ejemplo de una respuesta de error: ``` { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "webhook cannot be empty" } } ``` **DeviceStatesChangeReport Informe de cambio de estado del dispositivo** * Nota: Los informes de estado repetidos pueden activar falsamente escenas asociadas. **Parámetros de la solicitud:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | -------------------------------------------------------------------------------------------- | | estado | object | N | Estado del dispositivo, consulte \[Capacidades de dispositivo compatibles] para más detalles | Ejemplo de Solicitud : ``` { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Parámetros de la respuesta:** PayloadObject: Objeto vacío Ejemplo de una respuesta exitosa: ``` { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": {} } ``` **DeviceOnlineChangeReport Informe de estado en línea del dispositivo** * Nota: Los informes de estado repetidos pueden activar falsamente escenas asociadas. **Parámetros de la solicitud:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | --------------------- | -------- | ------------ | ---------------------------------------------- | | en línea | boolean | N | Estado en línea del dispositivo true: En línea | | false: Fuera de línea | | | | Ejemplo de Solicitud : ``` { "event": { "header": { "name": "DeviceOnlineChangeReport", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": true } } } ``` **Parámetros de la respuesta:** PayloadObject: Objeto vacío Ejemplo de una respuesta exitosa: ``` { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": {} } ``` **DeviceInformationUpdatedReport Informe de Información del Dispositivo Actualizada** * Nota: La actualización puede afectar escenas existentes o funciones de seguridad. **Parámetros de la solicitud:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------- | | capabilities | | | | \| CapabilityObject\[] \| N \| Lista de capacidades. Los detalles se pueden encontrar en la sección de capacidades de dispositivos compatibles. \*\*Nota: \*\*Este parámetro solo actualizará el `campo value` de la `configuración` clave dentro de la `CapabilityObject`, y las actualizaciones solo están permitidas si la `permission` para la `configuración` clave es `11` o `01`. Para la definición de estructura específica de la `configuración` en `CapabilityObject`, consulte la descripción detallada en la sección 2.3 Categorías de Visualización de Dispositivos y Capacidades del Dispositivo. | | etiquetas \| objeto \| Y \| Clave-valor en formato JSON, información personalizada del dispositivo. * Puede utilizarse para almacenar canales del dispositivo * Puede utilizarse para almacenar unidades de temperatura * Otros datos personalizados de terceros | Ejemplo de Solicitud : ```json { "event": { "header": { "name": "DeviceInformationUpdatedReport", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "capabilities": [ { "capability": "detect", "permission": "0110", "settings":{ "detectInterval":{ "permission": "11", "type": "numeric", "value": 300, }, "detectSensitivity":{ "permission": "11", "type": "numeric", "value": 1000, } } } ] } } } ``` **esponse parameters:** PayloadObject: Objeto vacío Ejemplo de una respuesta exitosa: ```json { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "2" }, "payload": {} } ``` #### La pasarela envía la interfaz de instrucción a través de la dirección de servicio del dispositivo * Nota: 1. Los terceros deben responder a la solicitud de la pasarela dentro de 3s. De lo contrario, la pasarela juzgará que el procesamiento del comando ha excedido el tiempo. 2. Si el servicio de terceros está fuera de línea, la pasarela establecerá el dispositivo en estado fuera de línea, y el servicio de terceros necesita informar el estado del dispositivo (DeviceStatesChangeReport) o el estado en línea (DeviceOnlineChangeReport) antes de volver al estado en línea. **Formato de la solicitud** La pasarela envía instrucciones al tercero a través de la interfaz de la dirección de servicio del dispositivo. :::tips * **URL**： * **Método**：POST * **Encabezado**： * Content-Type: application/json ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | --------------- | ------------ | ------------------------------------------------- | | directiva | DirectiveObject | N | Información de la estructura del objeto directiva | DirectiveObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------------- | ------------ | ----------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la solicitud | | endpoint | EndpointObject | N | Información de la estructura del endpoint de la solicitud | | payload | PayloadObject | N | Información de la estructura del payload de la solicitud | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------- | | name | string | N | Nombre de la solicitud. Parámetros opcionales:UpdateDeviceStates: Actualizar estados del dispositivo | | message\_id | string | N | ID de mensaje de la solicitud, UUID\_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1. | EndpointObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | --------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de serie único del dispositivo | | third\_serial\_number | string | N | Número de serie único del dispositivo de terceros | | etiquetas | object | N | Clave-valor en formato JSON, información personalizada del dispositivo. \[Función de Gestión de Dispositivos] - \[Descripción de Etiquetas] | PayloadObject: Según diferentes `header.name`, existe una estructura de solicitud específica para cada uno. Ejemplo de Solicitud : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", "tags": {} }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Formato de respuesta** :::tips \*\*Código de estado HTTP: \*\*200 OK **Atributo de respuesta HTTP：** ::: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ----------- | ------------ | ---------------------------------------------------- | | evento | EventObject | N | Información de la estructura del evento de respuesta | EventObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------- | ------------ | ----------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la solicitud | | payload | PayloadObject | N | Información de la estructura del payload de la solicitud | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nombre del encabezado de respuesta. Parámetro opcional: UpdateDeviceStatesResponse: Respuesta de actualización de estados del dispositivo ErrorResponse: Respuesta de error | | message\_id | string | N | ID de mensaje del encabezado de la respuesta, UUID\_V4. Pase aquí el header.message\_id del mensaje de la solicitud | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1. | > Respuesta exitosa--PayloadObject： Dependiendo del tipo de solicitud, la estructura de la respuesta es diferente. Para más detalles, consulte el documento de instrucción de la solicitud específica. > Respuesta de fallo--PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------- | | type | string | N | **Tipos de error**: | * **ENDPOINT\_UNREACHABLE**: Dispositivo inalcanzable o fuera de línea * **ENDPOINT\_LOW\_POWER**: El dispositivo está en modo de baja energía y no se puede controlar * **INVALID\_DIRECTIVE**: Directiva anormal desde la pasarela * **NO\_SUCH\_ENDPOINT**: El dispositivo no existe * **NOT\_SUPPORTED\_IN\_CURRENT\_MODE**: El modo actual no admite la operación * **INTERNAL\_ERROR**: Error interno del servicio * **REMOTE\_KEY\_CODE\_NOT\_LEARNED**: Código de tecla del control remoto no aprendido | :::consejos **Condiciones**: Los parámetros de la solicitud son legales. \*\*Código de estado: \*\*200 OK **Parámetros de la respuesta:** ::: ``` { "event": { "header": { "name": "UpdateDeviceStatesResponse", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": {} } } ``` ``` { "event": { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "type": "ENDPOINT_UNREACHABLE" } } } ``` **UpdateDeviceStates** **Parámetros de la solicitud:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------- | | estado | object | N | Estado del dispositivo, consulte \[Capacidades de dispositivo compatibles] para más detalles. | Ejemplo de Solicitud : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": : { "power": { "powerState": "on" } } } } } ``` **Parámetros de la respuesta:** PayloadObject：Objeto vacío Ejemplo de Respuesta Exitosa ``` { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": {} } ``` **QueryDeviceStates** **Parámetros de la solicitud:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------- | | estado | object | N | Estado del dispositivo, consulte \[Capacidades de dispositivo compatibles] para más detalles. | Ejemplo de Solicitud : ```json { "directive": { "header": { "name": "QueryDeviceStates", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "state": { "power-consumption": { "timeRange": { "start": "2020-07-05T08:00:00Z", // Hora de inicio para las estadísticas de consumo de energía, obligatorio. "end": "2020-07-05T09:00:00Z" // Hora de fin para las estadísticas de consumo de energía, obligatorio. } } } } } } ``` **Parámetros de la respuesta:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------- | | estado | object | N | Estado del dispositivo, consulte \[Capacidades de dispositivo compatibles] para más detalles. | **Ejemplo de respuesta:** ```json { "event": { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "2" }, "payload": { "state": { "power-consumption": { "electricityIntervals": [ // Dividido en múltiples registros según configuration.resolution { "usage": 26.5, // Valor de consumo de energía, obligatorio. Tipo: number. "start": "2020-07-05T08:00:00Z", // Hora de inicio, obligatorio. Tipo: date. "end": "2020-07-05T09:00:00Z" // Hora de fin, obligatorio. Tipo: date. Si el intervalo entre end y start es menor que resolution, todos los registros reportados se consideran inválidos. }, { "usage": 26.5, // Valor de consumo de energía, obligatorio. Tipo: number. "start": "2020-07-05T09:00:00Z", // Hora de inicio, obligatorio. Tipo: date. "end": "2020-07-05T10:00:00Z" // Hora de fin, obligatorio. Tipo: date. Si el intervalo entre end y start es menor que resolution, todos los registros reportados se consideran inválidos. } ] } } } } } ``` **ConfigureDeviceCapabilities** **Parámetros de la solicitud:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | capabilities | CapabilityObject\[] | N | Lista de capacidades. Los detalles pueden verse en la sección de capacidades de dispositivo compatibles. Tenga en cuenta, el campo permission no se puede cambiar, pase el mismo valor al sincronizar. | Ejemplo de Solicitud : ```json { "directive": { "header": { "name": "ConfigureDeviceCapabilities", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "2" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Tipo de detección de control de temperatura, obligatorio. Valores opcionales: humidity (detección de humedad), temperature (detección de temperatura) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Ajustes de detección soportados, obligatorio. { "name": "lowerSetpoint", // Valor mínimo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint. "value": { // Rango de detección, opcional. Rellenar si existen condiciones preestablecidas. "value": 68.0, // Valor de temperatura o humedad, obligatorio. "scale": "f" // Unidad de temperatura, obligatorio si name=temperature. Opciones: c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Valor máximo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint. "value": { // Rango de detección, opcional. Rellenar si existen condiciones preestablecidas. "value": 68.0, // Valor de temperatura o humedad, obligatorio. "scale": "f" // Unidad de temperatura, obligatorio si name=temperature. Opciones: c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } } ``` **Parámetros de la respuesta:** PayloadObject：Objeto vacío Ejemplo de Respuesta Exitosa ```json { "event": { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "2" }, "payload": {} } } ``` ## 5. Eventos enviados por el servidor > Descripción de la interfaz MDN EventSource： ### 5.1 Instrucción La pasarela admite enviar mensajes al cliente usando SSE (Server-sent events). El cliente puede monitorear los mensajes SSE después de obtener las credenciales de acceso y puede analizar el contenido de los mensajes push según el protocolo de notificación de eventos de la interfaz de desarrollo al recibir los mensajes enviados por la pasarela. Cabe señalar que la pasarela actualmente usa el protocolo HTTP1.1, por lo que SSE en el lado del navegador tendrá un límite máximo de no más de 6 conexiones (Las instrucciones específicas se pueden encontrar en la descripción de la interfaz MDN EventSource.) ### 5.2 Formato Común :::consejos * **URL**：/open-api/V2/sse/bridge * **Método**：`GET` ::: Parámetros de la solicitud: | Nombre | Tipo | Opcional | Descripción | | ------------- | ------ | -------- | --------------- | | access\_token | string | N | Token de Acceso | Nota: Al solicitar una conexión SSE, la pasarela comprobará el access\_token y devolverá un error de fallo de autenticación si es inválido. { "error": 401, "data": {}, "message": "invalid access\_token"} > \## Por ejemplo: Nombre del Módulo: device Versión: 1,v2,v3 Tipo de Mensaje: addDevice Ejemplo: ```javascript const evtSource = new EventSource("http:///open-api/v2/sse/bridge?access_token=xxxxxx"); evtSource.addEventListener('device#v2#addDevice',function (event) { try { const data = JSON.parse(event.data); console.log('data', data); } catch (error) { console.error(`parse error`,error); } } ``` ### 5.3 Módulo de Dispositivo #### a. Evento Agregar Dispositivo :::tips Nombre del Módulo：device Versión：v2 Tipo de Mensaje：addDevice event.data parámetros： ::: | Nombre | Tipo | Opcional | Descripción | | ------- | ----------------------------------------------------------------------------- | -------- | --------------------------- | | payload | ResponseDeviceObjectObject - Interfaz igual que Obtener Lista de Dispositivos | N | información del dispositivo | Ejemplo: ```json // event.data { "payload": { "serial_number": "ABCDEFGHIJK", "third_serial_number": "third_serial_number", "name": "Midispositivo", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "1100" }, { "capability": "rssi", "permission": "0100" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } } ``` #### b. Evento Actualizar Estado del Dispositivo :::tips Nombre del Módulo：device Versión：v2 Tipo de Mensaje：updateDeviceState event.data parámetros： ::: | Nombre | Tipo | Opcional | Descripción | | -------- | ------------------------------------------------------ | -------- | ------------------------------- | | endpoint | EndpointObject | N | Información del Dispositivo | | payload | object。 Estructura igual que el estado del dispositivo | N | Datos de Estado del Dispositivo | EndpointObject: | Parámetro | Tipo | Opcional | Descripción | | --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de serie único del dispositivo | | third\_serial\_number | string | Y | El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio. | Ejemplo: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "power": { "powerState": "on" }, "brightness": { "brightness": 100 } } } ``` #### c. Evento Actualizar Información del Dispositivo :::tips Nombre del Módulo：device Versión：v2 Tipo de Mensaje：updateDeviceInfo event.data parámetros： ::: | Nombre | Tipo | Opcional | Descripción | | -------- | ------------------ | -------- | ------------------------------- | | endpoint | EndpointObject | N | Información del Dispositivo | | payload | DeviceChangeObject | N | Datos de Cambio del Dispositivo | EndpointObject: | Atributo | Tipo | Opcional | Descripción | | --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de serie único del dispositivo | | third\_serial\_number | string | Y | El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio. | DeviceChangeObject | Nombre | Tipo | Opcional | Descripción | | ------------ | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nombre del Dispositivo | | capabilities | CapabilityObject \[] | Y | Lista de capacidades del dispositivo. | | etiquetas | object | Y | **etiquetas**`object` \| Nullable \| Pares clave-valor en formato JSON para información personalizada del dispositivo. | * Puede utilizarse para almacenar canales del dispositivo. * Puede utilizarse para almacenar unidades de temperatura. * Para otros datos personalizados de terceros. | Ejemplo: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "name": "device name", "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Tipo de detección de control de temperatura, obligatorio. Valores opcionales: humidity (detección de humedad), temperature (detección de temperatura) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Ajustes de detección soportados, obligatorio. { "name": "lowerSetpoint", // Valor mínimo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint. "value": { // Rango de detección, opcional. Rellenar si existen condiciones preestablecidas. "value": 68.0, // Valor de temperatura o humedad, obligatorio. "scale": "f" // Unidad de temperatura, obligatorio si name=temperature. Opciones: c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Valor máximo que la detección debe mantener. Debe proporcionarse lowerSetpoint o upperSetpoint. "value": { // Rango de detección, opcional. Rellenar si existen condiciones preestablecidas. "value": 68.0, // Valor de temperatura o humedad, obligatorio. "scale": "f" // Unidad de temperatura, obligatorio si name=temperature. Opciones: c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } ``` #### d. Evento Eliminar Dispositivo :::tips Nombre del Módulo：device Versión：v2 Tipo de Mensaje：deleteDevice event.data parámetros： ::: | \*\* Nombre \*\* | \*\* Tipo \*\* | \*\* Opcional\*\* | \*\* Descripción \*\* | | ---------------- | -------------- | ----------------- | --------------------------- | | endpoint | EndpointObject | N | Información del Dispositivo | EndpointObject: | Atributo | Tipo | Opcional | Descripción | | --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de serie único del dispositivo | | third\_serial\_number | string | Y | El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio. | Ejemplo: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" } } ``` #### e. Evento Actualizar Estado en Línea del Dispositivo :::tips Nombre del Módulo：device Versión：v2 Tipo de Mensaje：updateDeviceOnline event.data parámetros： ::: | Nombre | Tipo | Opcional | Descripción | | -------- | ------------------ | -------- | ------------------------------- | | endpoint | EndpointObject | N | Información del Dispositivo | | payload | DeviceChangeObject | N | Datos de Cambio del Dispositivo | EndpointObject: | Atributo | Tipo | Opcional | Descripción | | --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de serie único del dispositivo | | third\_serial\_number | string | Y | El número de serie único del dispositivo de terceros. Para dispositivos conectados a través de interfaces abiertas, este campo es obligatorio. | DeviceChangeObject | Nombre | Tipo | Opcional | Descripción | | -------- | ------- | -------- | ------------------------------- | | en línea | boolean | N | Estado en Línea del Dispositivo | Ejemplo: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": false } } ``` ### 5.4 Módulo de Pasarela #### a. Evento de Actualización del Estado de Seguridad :::tips Nombre del Módulo：device Versión：v2 Tipo de Mensaje：updateDeviceOnline event.data parámetros： ::: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------------- | ------------ | --------------------------- | | payload | SecurityStateObject | N | Información del Dispositivo | SecurityStateObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------- | | alarm\_state | string | N | | * `arming` | Armado * `disarming` | Desarmado | Ejemplo: ```json // event.data { "payload": { "alarm_state": "alarming" } } ``` ### 5.5 Módulo de Seguridad #### a. Evento de Actualización del Estado de Armado :::tips Nombre del Módulo：device Versión：v2 Tipo de Mensaje：updateDeviceOnline event.data parámetros： ::: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------------- | ------------ | --------------------------- | | payload | ArmStateObject | N | rm e información de desarme | ArmStateObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------- | | arm\_state | string | N | | * `arming` | Armado * `disarming` | Desarmado | | detalle | DetailObject | N | Detalles de armado/desarme | DetailObject： | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ----------------------- | | sid | int | N | id de modo de seguridad | | name | string | N | Nombre de seguridad | Ejemplo ```json // event.data { "payload": { "arm_state": "arming", "detail": { "sid": 1, "name": "Home Mode" } } } ``` ## 6. TTS (**Función del motor de texto a voz** ### 6.1 Instrucción #### Papel clave * Proveedor de Servicios TTS: El proveedor del servicio del motor TTS es responsable de registrar el motor TTS en la pasarela y proporcionar servicios TTS * Servidor de la pasarela：iHost * Cliente de la API abierta de la pasarela #### 6.1.1 Registro del servicio del motor TTS 1. 【Proveedor de Servicio TTS】Llamar a la interfaz para registrar el motor TTS en la pasarela. 2. 【Servidor de la pasarela】Tras el registro exitoso, la pasarela almacenará la información básica del motor TTS (incluida la dirección del servicio server\_address, y la comunicación posterior entre la pasarela y el Proveedor de Servicio TTS se realizará a través de la dirección server\_address), y asignará el ID del servicio del motor TTS dentro de la pasarela.
#### 6.1.2 Obtener la lista de audios sintetizados 1. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de servicios de motor TTS registrados. Puede obtener la lista actual de motores TTS registrados (incluido el ID del motor TTS asignado por la pasarela). 2. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de audios de un motor TTS especificado. La pasarela emitirá una instrucción síncrona de lista de audio al Proveedor de Servicio TTS especificado y devolverá el resultado.
#### 6.1.3 Síntesis de voz especificando un motor de voz 1. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de servicios de motor TTS registrados. Puede obtener la lista actual de motores TTS registrados (incluido el ID del motor TTS asignado por la pasarela). 2. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de audios de un motor TTS especificado. La pasarela emitirá una instrucción síncrona de lista de audio al Proveedor de Servicio TTS especificado y devolverá el resultado.
#### 6.1.4 Sintetizar audio y reproducir discurso TTS. 1. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de servicios de motor TTS registrados. Puede obtener la lista actual de motores TTS registrados (incluido el ID del motor TTS asignado por la pasarela). 2. 【Cliente de la API abierta de la pasarela】Llamar a la interfaz para obtener la lista de audios de un motor TTS especificado. La pasarela emitirá una instrucción síncrona de lista de audio al Proveedor de Servicio TTS especificado y devolverá el resultado. (incluida la dirección del archivo de audio TTS) 3. 【Cliente de la API abierta de la pasarela】Registrar la dirección del archivo de audio TTS a partir del resultado devuelto en el paso anterior, llamar a la interfaz de reproducción de archivos de audio y reproducirlo a través de la pasarela. ### 6.2 Módulo del motor TTS #### 6.2.1 Capacidades abiertas de la pasarela **a. Obtener la lista de servicios de motor TTS registrados** :::consejos * **URL**：`/open-api/V2/rest/tts/engines` * **Método**：`GET` * **Encabezado**： * Content-Type: application/json * Autorización: Bearer ::: Parámetros de solicitud: ninguno Respuesta de datos correcta: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ---------------- | ------------ | -------------------------------- | | motores | EngineObject \[] | N | Lista de motores TTS registrados | Estructura de EngineObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------- | | id | string | N | ID del motor asignado por la pasarela | | name | string | N | Nombre del servicio del motor TS | :::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： ::: ```json { "error": 0, "data": { "engines": [ { "id": "engine id", "name": "engine name" } ] }, "message": "success" } ``` **b. Obtener la lista de audios de un motor TTS especificado** :::consejos * **URL**：`/open-api/V2/rest/tts/engine/{id}/audio-list` * **Método**：`GET` * **Encabezado**： * Content-Type: application/json * Autorización: Bearer ::: Parámetros de solicitud: ninguno Respuesta de datos correcta: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | --------------- | ------------ | --------------- | | audio\_list | AudioObject \[] | N | Lista de audios | Estructura de AudioObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------------------------------------------------- | -------- | ------------ | -------------------------------------- | | url | string | N | URL del archivo de audio, por ejemplo: | | | | | | | etiqueta | string | Y | Etiqueta del archivo de audio | :::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` \*\*Código de error: \*\* * 190000 El motor está funcionando de forma anormal **Ejemplo de respuesta:**： ::: ```json { "error": 0, "data": { "audio_list": [ { "url": "dirección de audio tts", // por ejemplo: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "etiqueta de audio tts" } ] }, "message": "success" } ``` **c .Realizar síntesis de voz usando el motor TTS especificado** :::consejos * **URL**：`/open-api/V2/rest/tts/engine/{id}/synthesize` * **Método**：`POST` * **Encabezado**： * Content-Type: application/json * Autorización: Bearer ::: Parámetros de solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | text | string | N | Texto usado para sintetizar el audio | | etiqueta | string | Y | Etiqueta del archivo de audio | | language | string | Y | Campo transparente. Código de idioma opcional para la solicitud de síntesis de voz. La lista específica de códigos de idioma compatibles la proporciona el proveedor del servicio del motor de voz TTS. Tenga en cuenta que el servicio del motor TTS debe admitir un idioma predeterminado para la síntesis de voz, lo que significa que si no se pasa el idioma, se utilizará el idioma predeterminado del motor para la síntesis. | | options | object | Y | Campo transparente. Se utiliza para pasar los parámetros de configuración requeridos para la síntesis al servicio del motor de voz TTS. | Respuesta de datos correcta: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ----------- | ------------ | --------------- | | audio | AudioObject | N | Lista de audios | Estructura de AudioObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------------------------------------------------- | -------- | ------------ | -------------------------------------- | | url | string | N | URL del archivo de audio, por ejemplo: | | | | | | | etiqueta | string | Y | Etiqueta del archivo de audio | :::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` \*\*Código de error: \*\* * 190000 El motor está funcionando de forma anormal **Ejemplo de respuesta:**： ::: ```json { "error": 0, "data": { "audio": { "url": "dirección de audio tts" // por ejemplo, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "etiqueta de audio tts" } }, "message": "success" } ``` #### 6.2.2 Comunicación entre la pasarela y el servicio TTS **a. Registro del servicio del motor TTS** > Enviar solicitud a la pasarela por parte del Proveedor de Servicio TTS :::consejos * **URL**：`/open-api/V2/rest/thirdparty/event` * **Método**：`POST` * **Encabezado**： * Content-Type: application/json * Autorización: Bearer ::: Parámetros de solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ----------- | ------------ | ----------------------------------------------------------- | | evento | EventObject | N | Estructura de información del objeto de evento de solicitud | EventObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------- | ------------ | ----------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la solicitud | | payload | PayloadObject | N | Información de la estructura del payload de la solicitud | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------- | | name | string | N | Nombre de la solicitud. Parámetro opcional. | * RegisterTTSEngine | | message\_id | string | N | ID del mensaje de la solicitud, UUID\_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 | PayloadObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ---------------- | -------- | ------------ | ---------------------------------------------- | | service\_address | string | N | Dirección del servicio. Por ejemplo, http\:/// | | name | string | N | Nombre del servicio | Ejemplo de solicitud: ```json { "event": { "header": { "name": "RegisterTTSEngine", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "service_address": "service_address", "name": "nombre del servicio tts" } } } ``` \*\*Parámetros de respuesta correctos: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------- | ------------ | ----------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la solicitud | | payload | PayloadObject | N | Información de la estructura del payload de la solicitud | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------------------- | | name | string | N | Nombre del encabezado de respuesta. Parámetro opcional: | * Respuesta (Respuesta exitosa) * ErrorResponse (Respuesta de error) | | message\_id | string | N | ID del mensaje del encabezado de respuesta, UUID\_V4. Mensaje de solicitud entrante aquí: header.message\_id | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 | PayloadObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------- | | engine\_id | string | N | ID del motor asignado por la pasarela | :::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： ::: Ejemplo de respuesta correcta:： ```json { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "engine_id": "engine id" } } ``` \*\*Parámetros de respuesta anormales: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------- | | type | string | N | Tipo de error | * INVALID\_PARAMETERS (Error de parámetros) * AUTH\_FAILURE (Fallo de autenticación) * INTERNAL\_ERROR (Error interno del servicio) | | description | string | N | Descripción del error | Ejemplo de respuesta de error:： ```json { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address no puede estar vacío" } } ``` **b. Comando para sincronizar la lista de audios** > Enviar comando al Proveedor de Servicio TTS por la pasarela. :::consejos * **URL**：`` * **Método**：`POST` * **Encabezado**： * Content-Type: application/json ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | --------------- | ------------ | ------------------------------------------------------ | | directiva | DirectiveObject | N | Información de la estructura del objeto de instrucción | DirectiveObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------- | ------------ | ----------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la solicitud | | payload | PayloadObject | N | Información de la estructura del payload de la solicitud | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------- | | name | string | N | Nombre de la solicitud. Parámetro opcional: | * SyncTTSAudioList | | message\_id | string | N | ID del mensaje de la solicitud, UUID\_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 | Ejemplo de solicitud: ```json { "directive": { "header": { "name": "SyncTTSAudioList", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": {} } } ``` \*\*Parámetros de respuesta correctos: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------- | ------------ | ----------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la solicitud | | payload | PayloadObject | N | Información de la estructura del payload de la solicitud | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------------------- | | name | string | N | Nombre del encabezado de respuesta. Parámetro opcional: | * Respuesta (Respuesta exitosa) * ErrorResponse (Respuesta de error) | | message\_id | string | N | ID del mensaje del encabezado de respuesta, UUID\_V4. Mensaje de solicitud entrante aquí: header.message\_id | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 | PayloadObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | --------------- | ------------ | ------------------ | | audio\_list | AudioObject \[] | N | Lista de audio TTS | Estructura de AudioObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------------------------------------------------- | -------- | ------------ | -------------------------------------- | | url | string | N | URL del archivo de audio, por ejemplo: | | | | | | | etiqueta | string | Y | Etiqueta del archivo de audio | :::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： ::: Ejemplo de respuesta correcta:： ```json { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "audio_list": [ { "url": "url de audio tts", "label": "etiqueta de audio tts" } ] } } ``` \*\*Parámetros de respuesta anormales: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------- | | type | string | N | Tipo de error | * INVALID\_PARAMETERS (Error de parámetros) * AUTH\_FAILURE (Fallo de autenticación) * INTERNAL\_ERROR (Error interno del servicio) | | description | string | N | Descripción del error | Ejemplo de respuesta de error:： ```json { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address no puede estar vacío" } } ``` **c. Comando de síntesis de voz** > Enviar comando al Proveedor de Servicio TTS por la pasarela. :::consejos * **URL**：`` * **Método**：`POST` * **Encabezado**： * Content-Type: application/json ::: Parámetros de la solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | --------------- | ------------ | ------------------------------------------------------ | | directiva | DirectiveObject | N | Información de la estructura del objeto de instrucción | DirectiveObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------- | ------------ | ----------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la solicitud | | payload | PayloadObject | N | Información de la estructura del payload de la solicitud | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------- | | name | string | N | Nombre de la solicitud. Parámetro opcional: | * SynthesizeSpeech | | message\_id | string | N | ID del mensaje de la solicitud: UUID\_V4 | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 | PayloadObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | text | string | N | Texto usado para sintetizar el audio | | etiqueta | string | Y | Etiqueta del archivo de audio | | language | string | Y | Campo transparente. Código de idioma opcional para la solicitud de síntesis de voz. La lista específica de códigos de idioma compatibles la proporciona el proveedor del servicio del motor de voz TTS. Tenga en cuenta que el servicio del motor TTS debe admitir un idioma predeterminado para la síntesis de voz, lo que significa que si no se pasa el idioma, se utilizará el idioma predeterminado del motor para la síntesis. | | options | object | Y | Campo transparente. Se utiliza para pasar los parámetros de configuración requeridos para la síntesis al servicio del motor de voz TTS. | Ejemplo de solicitud: ```json { "directive": { "header": { "name": "SynthesizeSpeech", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "text": "Texto de entrada para sintetizar.", "label": "etiqueta de audio tts" } } } ``` \*\*Parámetros de respuesta correctos: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------- | ------------ | ----------------------------------------------------------- | | header | HeaderObject | N | Información de la estructura del encabezado de la solicitud | | payload | PayloadObject | N | Información de la estructura del payload de la solicitud | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ------------------------------------------------------- | | name | string | N | Nombre del encabezado de respuesta. Parámetro opcional: | * Respuesta (Respuesta exitosa) * ErrorResponse (Respuesta de error) | | message\_id | string | N | ID del mensaje del encabezado de respuesta, UUID\_V4. Mensaje de solicitud entrante aquí: header.message\_id | | version | string | N | Número de versión del protocolo de la solicitud. Actualmente fijo en 1 | PayloadObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ----------- | ------------ | --------------- | | audio | AudioObject | N | Audio TTS | Estructura de AudioObject | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------------------------------------------------- | -------- | ------------ | -------------------------------------- | | url | string | N | URL del archivo de audio, por ejemplo: | | | | | | | etiqueta | string | Y | Etiqueta del archivo de audio | :::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： ::: Ejemplo de respuesta correcta:： ```json { "header": { "name": "Response", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "audio": { "url": "url de audio tts", "label": "etiqueta de audio tts" } } } ``` \*\*Parámetros de respuesta anormales: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------- | | type | string | N | Tipo de error | * INVALID\_PARAMETERS (Error de parámetros) * AUTH\_FAILURE (Fallo de autenticación) * INTERNAL\_ERROR (Error interno del servicio) | | description | string | N | Descripción del error | Ejemplo de respuesta de error:： ```json { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferiblemente un UUID versión 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address no puede estar vacío" } } ``` ## 7. Módulo multimedia ### 7.1 Reproducir archivo de audio :::consejos * **URL**：`/open-api/V2/rest/media/audio-player` * **Método**：`POST` * **Encabezado**： * Content-Type: application/json * Autorización: Bearer ::: Parámetros de solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ----------------------- | | audio\_url | string | N | Dirección URL del audio | Respuesta de datos correcta: :::consejos Condiciones: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\*`200 OK` **Ejemplo de respuesta:**： ::: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 8. Tarjeta de interfaz de usuario personalizada Las tarjetas de interfaz de usuario personalizadas le permiten mostrar cualquier contenido que desee dentro de la tarjeta. Este contenido puede ser una página web, una imagen o cualquier servicio con una interfaz de usuario. Solo necesita proporcionar la URL del contenido que desea mostrar. La tarjeta de UI adaptará automáticamente su ancho y alto, y el contenido se representará usando un iFrame. ### 8.1 Instrucción #### Papel clave * **Proveedor de servicios de UI**: El proveedor responsable de crear tarjetas de UI personalizadas en la pasarela. * **Servidor de la pasarela**: El servidor de la pasarela (iHost). * **Cliente de la API abierta de la pasarela**: El cliente de la API abierta para la pasarela. #### 8.1.1 Creación de una tarjeta de UI personalizada * **\[Proveedor de servicios UI]**: Llama a la API para crear una tarjeta de UI personalizada en la pasarela. * **\[Servidor de la pasarela]**: Tras el registro exitoso, la pasarela almacena la información básica de la tarjeta de UI (incluida la configuración de tamaño y la URL del recurso de la tarjeta) y asigna un ID interno de tarjeta de UI dentro de la pasarela.
#### 8.1.2 Recuperación de la lista de tarjetas de UI * **\[Proveedor de servicios UI]**: Llama a la API para recuperar la lista de tarjetas de UI. * **\[Servidor de la pasarela]**: Devuelve la lista de tarjetas de UI almacenadas en la pasarela, incluidas las tarjetas de UI personalizadas no creadas por el llamante.
#### 8.1.3 Modificación de la configuración de una tarjeta de UI especificada * **\[Proveedor de servicios UI]**: Llama a la API para modificar la configuración de una tarjeta de UI especificada, como la configuración de tamaño y la URL del recurso. * **\[Servidor de la pasarela]**: Tras la modificación exitosa, la pasarela almacena la información actualizada de la tarjeta de UI, incluida la nueva configuración de tamaño y la URL del recurso.
#### 8.1.4 Eliminación de una tarjeta de UI personalizada 1. **\[Proveedor de servicios UI]**: Llama a la API para eliminar una tarjeta de UI personalizada especificada. 2. **\[Servidor de la pasarela]**: La pasarela eliminará toda la información relacionada con la tarjeta de UI especificada.
### 8.2 Módulo de tarjeta de UI personalizada #### 8.2.1 Creación de una tarjeta de UI personalizada > El proveedor de servicios UI envía una solicitud a la pasarela para crear una tarjeta de UI personalizada. :::consejos * **URL**：`/open-api/v2/rest/ui/cards` * **Método**：`POST` * **Encabezado**： * Content-Type: application/json * Autorización: Bearer ::: Parámetros de solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------- | ------------------ | ------------ | ---------------------------------------------------------------------------------------- | | etiqueta | string | Y | Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Es el alias de la tarjeta. | | cast\_settings | CastSettingsObject | Y | Configuración de la tarjeta Cast: Ajustes de configuración para tarjetas cast. | | web\_settings | WebSettingsObject | N | Configuración de la tarjeta web: Ajustes de configuración para tarjetas web. | CastSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configuración de tamaño: Debe incluir al menos una configuración. | | default | string | N | Especificación predeterminada: Se utiliza la especificación de tamaño predeterminada, con parámetros opcionales: 2x2 | WebSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ----------------- | ------------------- | ------------ | ----------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configuración de tamaño: Debe incluir al menos una configuración. | | drawer\_component | DrawerObject | Y | Ajustes de visualización del componente Drawer. | | default | string | N | Especificación predeterminada: | * 1x1 * 2x1 | DimensionObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------------------------------------- | -------- | ------------ | --------------------------------------------------- | | src | string | N | URL del recurso: Por ejemplo: | | size | string | N | Especificaciones de tamaño: | | Parámetros opcionales de CastSettingsObject: | | | | * 2×2 Parámetros opcionales de WebSettingsObject: * 1x1 * 2x1 | DrawerObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------------------------------------------- | | src | string | N | URL del recurso: Por ejemplo: | Respuesta de datos exitosa: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | ---------------------------- | | id | string | N | ID único de la tarjeta de UI | :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. \*\*Código de estado: \*\* `200 OK` ::: Ejemplo de solicitud： ```json { "label": "ewelink cube card", "cast_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×2" } ], "default": "2×2" }, "web_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×1" }, { "src": "https://ewelink.cc/ewelink-cube/", "size": "1×1" } ], "drawer_component": { "src": "https://ewelink.cc/ewelink-cube/" }, "default": "2×1" } } ``` Ejemplo de respuesta: ```json { "error": 0, "data": { "id": "72cc5a4a-f486-4287-857f-b482d7818b16" }, "message": "success" } ``` #### 8.2.2 Recuperar la lista de tarjetas de UI :::consejos * **URL**：`/open-api/v2/rest/ui/cards` * **Método**：`GET` * **Encabezado**： * Content-Type: application/json * Autorización: Bearer ::: Parámetros de solicitud: Ninguno Parámetros de respuesta: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | ------------- | ------------ | ----------------------- | | data | CardObject\[] | N | Lista de tarjetas de UI | Objeto CardObjec: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------- | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------ | | id | string | N | ID de la tarjeta: Un identificador único para la tarjeta. | | etiqueta | string | Y | Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Sirve como alias o nombre de la tarjeta. | | cast\_settings | CastSettingsObject | Y | Etiqueta de la tarjeta: Se utiliza para describir la tarjeta. Es el alias de la tarjeta. | | web\_settings | WebSettingsObject | N | Configuración de la tarjeta Cast: Ajustes de configuración para tarjetas cast. | | app\_name | string | Y | Configuración de la tarjeta web: Ajustes de configuración para tarjetas web. | CastSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ----------------------- | ------------------- | ------------ | ----------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configuración de tamaño: Debe incluir al menos una configuración. | | default | string | N | Especificación predeterminada: | | Parámetro opcional: 2x2 | | | | | usado | string | N | Especificación actual: | | Parámetro opcional: 2x2 | | | | WebSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------------- | ------------------- | ------------ | ----------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configuración de tamaño: Debe incluir al menos una configuración. | | drawer\_component | DrawerObject | Y | Ajustes de visualización del componente Drawer. | | default | string | N | Especificación predeterminada: | | Parámetro opcional: | | | | * 1x1 * 2x1 | | usado | string | N | Especificación actual: Parámetro opcional: * 1x1 * 2x1 | DimensionObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------------- | -------- | ------------ | --------------------------------------------------- | | src | string | N | URL del recurso: Por ejemplo: | | size | string | N | Especificaciones de tamaño: | | Parámetro opcional: | | | | * 1x1 * 2x1 **Nota**: Actualmente, las tarjetas cast solo admiten la especificación 2x2. La especificación 2x2 no será efectiva. | DrawerObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------ | -------- | ------------ | --------------------------------------------------- | | src | string | N | URL del recurso: Por ejemplo: | Ejemplo de respuesta: ```json { "error": 0, "data": [ { "id": "72cc5a4a-f486-4287-857f-b482d7818b16", "label": "ewelink cube card", "cast_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×2" } ], "default": "2×2", "used": "2×2" }, "web_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×1" }, { "src": "https://ewelink.cc/ewelink-cube/", "size": "1×1" } ], "drawer_component": { "src": "https://ewelink.cc/ewelink-cube/" }, "default": "2×1", "used": "2×1" }, "appName": "ewelink-cube" } ], "message": "success" } ``` #### 8.2.3 Modificar la configuración de una tarjeta de UI especificada > Los usuarios autorizados pueden modificar la configuración de una tarjeta de UI existente a través de esta interfaz. Los proveedores de servicios de tarjetas personalizadas solo pueden modificar las tarjetas de UI que hayan creado. :::consejos * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Método**：`PUT` * **Encabezado**： * Content-Type: application/json * Autorización: Bearer ::: Parámetros de solicitud: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | -------------- | ------------------ | ------------ | ---------------------------------------------------------------- | | etiqueta | string | Y | Se utiliza para describir la tarjeta. Es el alias de la tarjeta. | | cast\_settings | CastSettingsObject | Y | Configuración de tarjeta Cast | | web\_settings | WebSettingsObject | Y | Configuración de tarjeta web | CastSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------- | | usado | string | Y, Cualquiera de los dos `usado` o `src` debe proporcionarse, pero se requiere al menos uno de estos parámetros. | Especificación actual: | | Parámetro opcional: | | | | * 2x2 \| | src | string | Y, Cualquiera de los dos `usado` o `src` debe proporcionarse, pero se requiere al menos uno de estos parámetros. | URL del recurso: | WebSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descripción** | | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------- | | usado | string | Y, Cualquiera de los dos `usado` o `src` debe proporcionarse, pero se requiere al menos uno de estos parámetros. | Especificación actual: | | Parámetro opcional: | | | | * 1x1 * 2x1 | | src | string | Y, Cualquiera de los dos `usado` o `src` debe proporcionarse, pero se requiere al menos uno de estos parámetros. | URL del recurso: | Respuesta de datos exitosa: :::tips **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. La tarjeta de UI que se modifica debe haber sido creada por el proveedor de tarjetas de UI personalizadas que llama a la interfaz. \*\*Código de estado: \*\* `200 OK` **Código de error:** * **406**: No tiene permiso para acceder a este recurso ::: \*\*Ejemplo de respuesta: \*\* ```json { "error": 0, "data": {}, "message": "success" } ``` \*\*Ejemplo de solicitud: \*\* ```json { "cast_settings": { "used": "2×2" }, "web_settings": { "used": "1×1" } } ``` #### 8.2.4 Eliminar tarjeta de UI personalizada > Los usuarios autorizados están permitidos a eliminar una tarjeta de UI existente usando esta interfaz. Los proveedores de tarjetas personalizadas solo pueden eliminar las tarjetas de UI que hayan creado. :::consejos * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Método**：`DELETE` * **Encabezado**： * Content-Type: application/json * Autorización: Bearer ::: Parámetros de solicitud: Ninguno Respuesta de datos exitosa: :::consejos **Condiciones**: Los parámetros de la solicitud son legales y la verificación de identidad del usuario ha pasado. La tarjeta de UI que se modifica debe haber sido creada por el proveedor de tarjetas de UI personalizadas que llama a la interfaz. \*\*Código de estado: \*\* `200 OK` **Código de error:** * **406**: No tiene permiso para acceder a este recurso. ::: \*\*Ejemplo de respuesta: \*\* ```json { "error": 0, "data": {}, "message": "success" } ```