# Guia do Desenvolvedor & API ## 1. Começando a usar ### 1.1 Preparação Passo 1. Por favor, certifique-se de que o gateway está ligado e funcionando corretamente. Passo 2. Certifique-se de que o gateway e o PC estão conectados à mesma LAN. Em seguida, insira a URL do CUBE no seu navegador. Aviso: Se você tiver vários gateways, pode obter o endereço IP correspondente para acessar o gateway especificado de duas maneiras abaixo. 1. Faça login no seu roteador sem fio e verifique o endereço IP do gateway em DHCP. 2. O CUBE suporta descoberta local via mDNS. ### 1.2 Começar * Chame a interface \[Access Token] e obtenha uma resposta de erro, solicitando clicar <**Concluído**>. Observe que após pressionar, o acesso da interface é válido por no máximo 5 minutos. ```json // Requisição curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Resposta { "error": 401, "data": {}, "message": "link button not pressed" } ``` * Clique <**Concluído**> e chame a interface \[Access Token] novamente. A resposta é bem-sucedida e o token é obtido. ```json // Requisição curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Resposta { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` * Verifique o token. Chame a interface \[Get Device List]. A resposta foi bem-sucedida e a lista de dispositivos foi obtida. ```json // Requisição curl --location --request GET 'http:///open-api/V2/rest/devices' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d' // Resposta { "error": 0, "data": { "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "nome do dispositivo", "manufacturer": "nome do fabricante", "model": "nome do modelo", "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 obter token de acesso do CUBE: Após chamar a interface \[Access Token], a caixa de pop-up global da página do console Web do CUBE solicita ao usuário confirmar a aquisição das credenciais da chamada da interface. * Observação: Se você abrir mais de uma página do console Web do CUBE, a caixa de confirmação aparecerá em várias páginas do console ao mesmo tempo, e a caixa pop-up das outras páginas do console será fechada após clicar na confirmação em uma das páginas do console. ## 2. Conceito principal ### 2.1 Endereço da interface de desenvolvimento A interface Web API do gateway tem dois métodos de acesso (baseado em IP ou nome de domínio), geralmente o caminho raiz é /open-api/V2/rest/< módulo de função específico > // Acesso por IP http\:///open-api/V2/rest/bridge // Acesso por nome de domínio http\:///open-api/V2/rest/bridge ### 2.2 Categoria de exibição do dispositivo & Capacidades * \*\*Categoria de exibição do dispositivo (DisplayCategory). \*\*A categoria de exibição do dispositivo é usada para identificar categorias específicas (do dispositivo), como switch, plug, light, etc. **Esta informação determinará o efeito de exibição da IU do dispositivo no gateway**. * \*\*Capacidade do dispositivo. \*\*A capacidade do dispositivo é usada para descrever as subfunções específicas do dispositivo, como controle de energia, controle de brilho, controle de temperatura de cor, etc. **Um único dispositivo pode suportar 1 ou mais capacidades**. * **capability:** Descreve o nome da capacidade, que deve ser globalmente único e do tipo string. Múltiplas palavras em inglês devem ser separadas por hífens ("-"). Por exemplo: `"thermostat-target-setpoint"`. * **name:** Descreve a categoria sob a capacidade, também do tipo string. Múltiplas palavras em inglês devem ser separadas por hífens ("-"). Por exemplo: `"auto-mode"`, `"manual-mode"`. * **permission:** Descreve as permissões associadas à capacidade. O tipo é string, formatado em código binário 8421. Exemplos incluem: * Dispositivo controlável: `"1000"` * Dispositivo configurável: `"0010"` * Dispositivo controlável e configurável: `"1010"` * Dispositivo controlável e que reporta: `"1100"` O significado de cada bit, da direita para a esquerda, é o seguinte: ⅰ. Bit 0: Permite consultar o dispositivo ⅱ. Bit 1: Permite configurar o dispositivo ⅲ. Bit 2: Permite que o dispositivo reporte dados ⅳ. Bit 3: Permite controlar o 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:** Descreve os itens de configuração para a capacidade, que são do tipo objeto e incluem uma descrição de cada item de configuração. ⅰ. **key:** Descreve o nome do item de configuração, que é do tipo string. Múltiplas palavras em inglês devem ser expressas em camelCase. Por exemplo: `"temperatureUnit"`. ⅱ. **value:** Descreve o conteúdo do item de configuração. As especificações detalhadas estão na tabela abaixo. | Atributo | Tipo | Opcional | Descrição | | ---------------------- | ------ | -------- | --------------------------------------------------- | | permission | string | N | Descreve as permissões para o item de configuração. | | **Valores opcionais:** | | | | * Permite modificação deste item de configuração: `"10"` * Permite visualização deste item de configuração: `"01"` * Permite tanto modificação quanto visualização deste item de configuração: `"11"` **Explicação dos bits:** 1. **Bit 0:** Permite visualização deste item de configuração 2. **Bit 1:** Permite modificação deste item de configuração | | tipo | string | N | Descreve o tipo de dado do valor do item de configuração. **Valores opcionais:** * `"enum"` * `"numeric"` * `"object"` * `"boolean"` * `"string"` **Diretrizes específicas por tipo:** 1. **Quando `**type = enum**`:** * O `campo value` (descrevendo o valor do item de configuração) é obrigatório se `permission` permite modificação (`"10"` ou `"11"`). * O `default` (descrevendo o valor padrão do item de configuração) e `values` (descrevendo os valores selecionáveis para o item de configuração) os campos são opcionais. 2. **Quando `**type = numeric**`:** * O `campo value` o campo é obrigatório se `permission` permite modificação (`"10"` ou `"11"`). * Os seguintes campos são opcionais: * `min` (descrevendo o valor mínimo do item de configuração) * `max` (descrevendo o valor máximo do item de configuração) * `step` (descrevendo o valor de passo para o item de configuração) * `precision` (descrevendo a precisão) * `unit` (descrevendo a unidade do item de configuração) * `default` (descrevendo o valor padrão) 3. **Quando `**type = object**`:** * O `campo value` o campo é obrigatório se `permission` permite modificação (`"10"` ou `"11"`). * O `default` o campo é opcional. 4. **Quando `**type = boolean**`:** * O `campo value` o campo é obrigatório se `permission` permite modificação (`"10"` ou `"11"`). * O `default` o campo é opcional. 5. **Quando `**type = string**`:** * O `campo value` o campo é obrigatório se `permission` permite modificação (`"10"` ou `"11"`). * O `default` o campo é 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. Web API ### Tipo de dado | Tipo | Descrição | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | string | Tipo de dado string. Codificado em UTF8. | | number | Tipo de dado numérico. [formato binário IEEE 754 de dupla precisão de 64 bits](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) | | int | Tipo de dado integral. | | object | Tipo de dado objeto. Objeto compatível com JSON | | string\[] | Array de strings | | int\[] | Array de inteiros | | object\[] | Array de objetos | | bool | Booleano | | date | String de tempo. String no formato ISO (Formato Estendido ISO 8601): YYYY-MM-DDTHH:mm:ss.sssZ. O fuso horário é sempre UTC (Tempo Universal Coordenado), identificado por um sufixo "Z". | ### Resultados de resposta genéricos | Atributo | Tipo | Opcional | Descrição | | --------------------------------------------------------------------------------------------- | ------ | -------- | -------------------------- | | error | int | N | Código de erro: | | 0: Sucesso | | | | | 400: Erro de parâmetro | | | | | 401: Falha de autenticação | | | | | 500: Exceção do servidor | | | | | data | object | N | Corpo de dados da resposta | | message | string | N | Descrição da resposta: | | Quando error for igual a 0, o conteúdo é success | | | | | Quando error não for igual a 0, é uma string não vazia, e o conteúdo é uma descrição do erro. | | | | **Exemplo de resposta**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` ```json { "error": 400, "data": {}, "message": "invalid parameters" } ``` ### Lista de recursos | Tipo | Descrição | | ------------- | -------------------------- | | Som suportado | - alert1 (Som de alarme 1) | * alert2 (Som de alarme 2) * alert3 (Som de alarme 3) * alert4 (Som de alarme 4) * alert5 (Som de alarme 5) * doorbell1 (Som de campainha 1) * doorbell2 (Som de campainha 2) * doorbell3 (Som de campainha 3) * doorbell4 (Som de campainha 4) * doorbell5 (Som de campainha 5) * alarm1 (Som de alarme 1) * alarm2 (Som de alarme 2) * alarm3 (Som de alarme 3) * alarm4 (Som de alarme 4) * alarm5 (Som de alarme 5) | | Suporte a deep | - bootComplete (Inicialização do sistema concluída) * networkConnected (Rede conectada) * networkDisconnected (Rede desconectada) * systemShutdown (Desligamento do sistema) -deviceDiscovered (Descobrir dispositivo) * system Armed (Sistema armado habilitado) * system Disarmed (Sistema armado desabilitado) * factoryReset (Redefinir dispositivo) | ### 3.1 A função do Gateway #### a. Access Token Permitir que os usuários obtenham o token de acesso. * Aviso: O token será limpo após a redefinição do dispositivo. * Aviso: Após obter o token, você precisa pressionar o botão novamente para obter com sucesso um novo token. :::dicas * **URL**：`/open-api/V2/rest/bridge/access_token` * **Método**：`GET` * **Cabeçalho**： * Content-Type: application/json ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------------------------- | | app\_name | string | Y | Descrição do nome do aplicativo. | Resposta de dados bem-sucedida: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------------------------------------------------------------------------- | | token | string | N | O token de acesso da interface. É válido por um longo período, por favor salve-o | | app\_name | string | Y | Descrição do nome do aplicativo. | :::dicas **Condição**: Usuário dispara a < tecla de comando > e acessa esta interface dentro do tempo válido. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` Resposta de dados de falha：Objeto vazio :::dicas **Condições**：O usuário não acionou a < tecla de comando >, ou o tempo válido expirou. \*\*Código de status: \*\* `200 OK` ::: **Exemplo de resposta**: ```json { "error": 401, "data": {}, "message": "link button not pressed" } ``` #### b. Obter o estado do Gateway Permitir que usuários autorizados obtenham o status do gateway através desta interface :::dicas * **URL**：`/open-api/V2/rest/bridge/runtime` * **Método**：`GET` * **Cabeçalho**： * Content-Type: application/json * Autorization: Bearer ::: Parâmetros da requisição: nenhum Resposta de dados bem-sucedida: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------------------------------- | | ram\_used | int | N | Porcentagem de uso de RAM. \[0-100] | | cpu\_used | int | N | Porcentagem de uso da CPU. \[0-100] | | power\_up\_time | date | N | A última vez de ligar | | cpu\_temp | int | N | Temperatura da CPU: | | Unidade: Celsius | | | | | cpu\_temp\_unit | string | N | Unidade de temperatura da CPU: | | Opcional | | | | | values:`'c'`, `'f'` | | | | | sd\_card\_used | int | Y | Uso do cartão SD (porcentagem): | | Intervalo:`[0-100]` com uma casa decimal de precisão | | | | | \*Observação: Se o cartão SD não estiver inserido ou não estiver formatado, o valor estará vazio. | | | | :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```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 o Gateway Permitir que usuários autorizados configurem o gateway através desta interface :::dicas * **URL**：`/open-api/V2/rest/bridge/config` * **Método**：`PUT` * **Cabeçalho**： * Content-Type: application/json * Autorization: Bearer ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | --------------------------- | | volume | int | Y | Volume do sistema. \[0-100] | Resposta de dados bem-sucedida: Objeto vazio {} :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Obter informações do Gateway Permitir que usuários autorizados obtenham as informações do gateway através desta interface :::dicas * **URL**：`/open-api/V2/rest/bridge` * **Método**：`GET` * **Cabeçalho**： * Content-Type: application/json ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ----------------------------- | | ip | string | N | endereço ip | | mac | string | N | endereço mac | | domain | string | Y | Domínio de serviço do Gateway | | fw\_version | string | N | Versão do firmware | | name | string | N | Nome do dispositivo | Resposta de dados bem-sucedida: Objeto vazio {} :::dicas **Condições**: Nenhum \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```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 o Gateway Permite que usuários autorizados silenciem o gateway através desta interface. :::dicas * **URL**：`/open-api/v2/rest/bridge/mute` * **Método**：`PUT` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da requisição: nenhum Resposta de dados bem-sucedida: Objeto vazio {} :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### f. Desmutar o Gateway Permite que usuários autorizados desmutem o gateway através desta interface.\ :::dicas * **URL**：`/open-api/v2/rest/bridge/unmute` * **Método**：`PUT` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da requisição: nenhum Resposta de dados bem-sucedida: Objeto vazio {} :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### g. Cancelar o alarme do Gateway Permite que usuários autorizados desativem o estado de som de alarme no gateway através desta interface. :::dicas * **URL**：`/open-api/v2/rest/bridge/cancel_alarm` * **Método**：`PUT` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da requisição: nenhum Resposta de dados bem-sucedida: Objeto vazio {} :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.2 Função de hardware #### a. Reiniciar o Gateway Permitir que o usuário autorizado reinicie o gateway através desta interface :::dicas * **URL**：`/open-api/V2/rest/hardware/reboot` * **Método**：`POST` * **Cabeçalho**： * Content-Type: application/json * Autorization: Bearer ::: Parâmetros da requisição: nenhum Resposta de dados bem-sucedida: Objeto vazio {} :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: ```json { "error": 0, "data": {}, "message": "success" } ``` #### b. Controle do alto-falante Permitir que usuários autorizados controlem o alto-falante através desta interface :::dicas * **URL**：`/open-api/V2/rest/hardware/speaker` * **Método**：`POST` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ----------- | ------------------------------ | ----------------------------------------------------------------------------- | | type | string | N | Parâmetros opcionais: 1.play\_sound (tocar o som) 2.play\_beep (tocar o bipe) | | sound | SoundObject | Y (N se type for play\_sound.) | O som. | | beep | BeepObject | Y (N se type for play\_beep.) | O bipe | SoundObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- | | name | string | N | O nome do som. Os valores suportados podem ser verificados em \[Lista de recursos - Som suportado] | | volume | int | N | O volume do som. \[0-100] | | countdown | int | N | A duração para o alto-falante tocar o som, e ele parará automaticamente quando o tempo expirar. Unidade: segundo. \[0,1799] | BeepObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------- | | name | string | N | O nome do deep. Os valores suportados podem ser verificados em \[Lista de recursos - Suporte a deep] | | volume | int | N | O volume do deep. \[0-100] | Resposta de dados bem-sucedida: Objeto vazio {} :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\* `200 OK` ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.3 Função de gerenciamento de dispositivos #### a. Tipo de dispositivo suportado | **Tipo de dispositivo** | **Valor** | Versão do iHost | | ------------------------------- | ---------------------------- | --------------- | | Plug | plug | ≥ 2.1.0 | | Switch | switch | ≥ 2.1.0 | | Light | light | ≥ 2.1.0 | | Cortina | curtain | ≥ 2.1.0 | | Sensor de porta/janela | contactSensor | ≥ 2.1.0 | | Sensor de movimento | motionSensor | ≥ 2.1.0 | | Sensor de temperatura | temperatureSensor | ≥ 2.1.0 | | Sensor de umidade | humiditySensor | ≥ 2.1.0 | | Sensor de temperatura e umidade | temperatureAndHumiditySensor | ≥ 2.1.0 | | Detector de vazamento de água | waterLeakDetector | ≥ 2.1.0 | | Detector de fumaça | smokeDetector | ≥ 2.1.0 | | Botão sem fio | button | ≥ 2.1.0 | | Câmera | camera | ≥ 2.1.0 | | Sensor geral | sensor | ≥ 2.1.0 | | Sensor geral | sensor | ≥ 2.1.0 | | Luminária de ventilador | fanLight | ≥ 2.1.0 | | Ar Condicionado | airConditioner | ≥ 2.1.0 | | Ventilador | fan | ≥ 2.1.0 | | Termostato | thermostat | ≥ 2.1.0 | #### b. Capacidades de Dispositivo Suportadas **Interruptor de Energia (power):** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "power", // Nome da capacidade "permission": "1100", // ihost não suporta configurar partida/parada suave, portanto não há campo configure } ] ``` **Atributo de Estado:** ``` { "powerState": "on", // O campo powerState indica o estado ligado/desligado da energia. Obrigatório. **Tipo:** string. "on" indica ligado, "off" indica desligado, "toggle" indica alternar. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** **Ligar:** ``` { "power": { "powerState": "on" } } ``` **Desligar:** ``` { "power": { "powerState": "off" } } ``` **Interruptor de Canal (toggle):** **Exemplo de Declaração de Capacidade:** Exemplo de Componente Único: ``` [ { "capability": "toggle", // Nome da capacidade "permission": "1100", // Permissão "name": "1", // Nome do componente, **Tipo:** String. Valores opcionais: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4), ou outros valores contendo letras maiúsculas e minúsculas e números } ] ``` Exemplo de Múltiplos Componentes: ``` [ { "capability": "toggle", "permission": "1100", "name": "1" }, { "capability": "toggle", "permission": "1100", "name": "2" } ] ``` **Atributo de Estado:** ``` { "toggleState": "on", // O campo toggleState indica o estado de alternância do atributo {name} do {device_id}. Obrigatório. **Tipo:** String. "on" indica habilitado, "off" indica desabilitado, "toggle" indica alternar. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Formato de Alternância: ``` { [capability]: { [toggle-name]: { [toggleState]: [value] } } } Componente 1 Ligado, Componente 2 Desligado: { "toggle": { "1": { "toggleState": "on" }, "2": { "toggleState": "off" } } } ``` **Inching de Canal (toggle-inching):** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "toggle-inching", // Nome da capacidade "permission": "0010", // Permissão "settings": { "toggleInchingSetting": { "permission": "11", "type": "object", "value": { "supported": { "1": { // Nome do componente "enable": true, // Se a função inching está habilitada. **Tipo:** Boolean. Obrigatório. "inchingSwitch": "off", // Configuração do interruptor inching. **Tipo:** String. Obrigatório. "off" (desligado), "on" (ligado) "delay": 1000, // Tempo de atraso do inching em milissegundos. **Tipo:** Integer. Obrigatório. "min_delay": 500, // Tempo mínimo de atraso "max_delay": 100000 // Tempo máximo de atraso }, "2": { // Nome do componente "enable": true, // Se a função inching está habilitada. **Tipo:** Boolean. Obrigatório. "inchingSwitch": "off", // Configuração do interruptor inching. **Tipo:** String. Obrigatório. "off" (desligado), "on" (ligado) "delay": 1000, // Tempo de atraso do inching em milissegundos. **Tipo:** Integer. Obrigatório. "min_delay": 500, // Tempo mínimo de atraso "max_delay": 100000 // Tempo máximo de atraso }, "3": { // Nome do componente "enable": true, // Se a função inching está habilitada. **Tipo:** Boolean. Obrigatório. "inchingSwitch": "off", // Configuração do interruptor inching. **Tipo:** String. Obrigatório. "off" (desligado), "on" (ligado) "delay": 1000, // Tempo de atraso do inching em milissegundos. **Tipo:** Integer. Obrigatório. "min_delay": 500, // Tempo mínimo de atraso "max_delay": 100000 // Tempo máximo de atraso }, "4": { // Nome do componente "enable": true, // Se a função inching está habilitada. **Tipo:** Boolean. Obrigatório. "inchingSwitch": "off", // Configuração do interruptor inching. **Tipo:** String. Obrigatório. "off" (desligado), "on" (ligado) "delay": 1000, // Tempo de atraso do inching em milissegundos. **Tipo:** Integer. Obrigatório. "min_delay": 500, // Tempo mínimo de atraso "max_delay": 100000 // Tempo máximo de atraso } } } } } } ] ``` **Atributo de Estado** Nenhum **Protocolo (Consulta de Status e Instruções de Controle)** Nenhum **Ajuste de Brilho (brightness):** **Exemplo de Declaração de Capacidade:** ``` { "capability": "brightness", // Nome da capacidade "permission": "1100" // Permissão } ``` **Atributo de Estado:** ``` { "brightness": 100, // O campo brightness indica a porcentagem de brilho. Escolha entre brightness ou brightnessDelta. **Tipo:** Number. Faixa: 0-100. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Definir Brilho para 80%. (0 é o mais escuro e 100 é o mais claro.) ``` json copiar código { "brightness": { "brightness": 80 } } ``` **Ajuste de Temperatura de Cor (color-temperature):** **Exemplo de Declaração de Capacidade:** ``` { "capability": "color-temperature", // Nome da capacidade "permission": "1100" // Permissão } ``` **Atributo de Estado:** ``` { "colorTemperature": 100, // O campo colorTemperature indica a porcentagem da temperatura de cor. Escolha entre colorTemperature ou colorTemperatureDelta. **Tipo:** Number. Faixa: 0-100. 0 indica luz quente, 50 indica luz neutra, 100 indica luz fria. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Ajustar Temperatura de Cor para 50%: ``` json { "color-temperature": { "colorTemperature": 50 } } ``` **Ajuste de Cor (color-rgb):** **Exemplo de Declaração de Capacidade:** ``` { "capability": "color-rgb", // Nome da capacidade "permission": "1100" // Permissão } ``` **Atributo de Estado:** ``` { "red": 255, // O campo red representa a cor vermelha no espaço de cor RGB. Obrigatório. **Tipo:** Number. Faixa: 0-255. "green": 0, // O campo green representa a cor verde no espaço de cor RGB. Obrigatório. **Tipo:** Number. Faixa: 0-255. "blue": 255 // O campo blue representa a cor azul no espaço de cor RGB. Obrigatório. **Tipo:** Number. Faixa: 0-255. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Definir Cor para Roxo: ``` { "color-rgb": { "red": 255, "green": 0, "blue": 255 } } ``` **Ajuste por Porcentagem (percentage):** **Exemplo de Declaração de Capacidade:** ``` { "capability": "percentage", "permission": "1100", "settings": { // Opcional "percentageRange": { "permission": "01", "type": "numeric", "min": 0, "max": 100, "step": 5 } } } ``` **Atributo de Estado:** ``` { "percentage": 100, // O campo percentage indica um valor percentual. Escolha entre percentage ou percentageDelta. **Tipo:** Number. Faixa: 0-100. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Ajustar para 40%: ``` { "percentage": { "percentage": 40 } } ``` **Controle de Motor (motor-control):** **Exemplo de Declaração de Capacidade:** ``` { "capability": "motor-control", "permission": "1100" } ``` **Atributo de Estado:** ``` json { "motorControl": "stop", // O campo motorControl indica o estado do motor. Obrigatório. **Tipo:** String. Valores possíveis: "open" (abrir), "close" (fechar), "stop" (parar), "lock" (travar). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Abrir Motor: ``` { "motor-control": { "motorControl": "open" } } ``` **Reversão de Motor (motor-reverse):** **Exemplo de Declaração de Capacidade:** ``` { "capability": "motor-reverse", "permission": "1100" } ``` **Atributo de Estado:** ``` { "motorReverse": true, // O campo motorReverse indica a configuração da direção do motor. Obrigatório. **Tipo:** Boolean. true indica para frente, false indica reverso. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Definir Motor para Direção para Frente: ``` { "motor-reverse": { "motorReverse": true } } ``` **Calibração de Motor (motor-clb)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "motor-clb", "permission": "0100" } ``` **Atributos (Estado):** ``` { "motorClb": "calibration" // O campo motorClb indica o status de calibração do motor. Obrigatório. **Tipo:** String. "normal" indica modo normal (calibrado), "calibration" indica calibração em andamento. } ``` **Protocolo (Relatório de Status):** Relatar que o Status do Motor Está Sendo Calibrado: ``` { "motor-clb": { "motorClb": "calibration" } } ``` **Estado ao Ligar (startup)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "startup", "permission": "1100" } ``` **Atributos (Estado):** ``` { "startup": "on" // Estado de energia na inicialização. **Tipo:** String. Obrigatório. Valores opcionais: "on" (ligado), "stay" (manter ligado), "off" (desligado), "toggle" (inverter estado de energia). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Definir Estado de Energia para Sempre Ligado: ``` { "startup": { "startup": "on" } } ``` *** **Ativação de Despertar (identify)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "identify", "permission": "0100" } ``` **Atributos (Estado):** ``` { "identify": true // Indica se o dispositivo relata ativamente resultados de reconhecimento ou está ativado. } ``` **Protocolo (Relatório de Status e Instruções de Controle):** Definir Tempo de Ativação de Despertar: ``` { "identify": { "countdown": 180 // O campo countdown indica o tempo de contagem regressiva. Obrigatório. **Tipo:** Number. Unidade: segundos. } } ``` Relatar Status de Ativação: ``` { "identify": { "identify": true // Indica se o dispositivo relata ativamente resultados de reconhecimento ou está ativado. } } ``` **Comutador de Estatísticas de Consumo de Energia em Tempo Real (power-consumption)** **Exemplo de Declaração de Capacidade:** ``` { "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/Parar Estatísticas em Tempo Real: ``` { "rlSummarize": true, // Iniciar/parar estatísticas em tempo real. **Tipo:** Boolean. Obrigatório. "timeRange": { // Intervalo de tempo resumido. Obrigatório. "start": "2020-07-05T08:00:00Z", // Hora de início das estatísticas de consumo de energia. **Tipo:** String. Obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término das estatísticas de consumo de energia. **Tipo:** String. Obrigatório. } } ``` Consultar Consumo de Energia por Intervalo de Tempo: ``` { "type": "summarize", // Tipo de estatísticas. **Tipo:** String. Obrigatório. Valores opcionais: "rlSummarize" (resumo em tempo real), "summarize" (resumo atual). "timeRange": { // Intervalo de tempo resumido. Obrigatório se type for "summarize". "start": "2020-07-05T08:00:00Z", // Hora de início das estatísticas de consumo de energia. **Tipo:** String. Obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término das estatísticas de consumo de energia. **Tipo:** String. Opcional. Se omitido, indica o horário atual. } } ``` Responder com Resultado das Estatísticas dentro do Intervalo de Tempo: ``` json { "type": "summarize", // Tipo de estatísticas. **Tipo:** String. Obrigatório. Valores opcionais: "rlSummarize" (resumo em tempo real), "summarize" (resumo atual). "rlSummarize": 50.0, // Consumo total de energia. **Tipo:** Number. Unidade: 0.01 kWh. Opcional. "electricityIntervals": [ // Vários registros de estatísticas divididos de acordo com configuration.resolution. Opcional. Não presente quando type é "rlSummarize". { "usage": 26.5, // Consumo de energia. **Tipo:** Number. Unidade: 0.01 kWh. Obrigatório. "start": "2020-07-05T08:00:00Z", // Hora de início. **Tipo:** Date. Obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término. **Tipo:** Date. Obrigatório. Se o intervalo entre end e start for menor que resolution, todos os registros relatados são considerados inválidos. }, { "usage": 26.5, // Consumo de energia. **Tipo:** Number. Unidade: 0.01 kWh. Obrigatório. "start": "2020-07-05T09:00:00Z", // Hora de início. **Tipo:** Date. Obrigatório. "end": "2020-07-05T10:00:00Z" // Hora de término. **Tipo:** Date. Obrigatório. Se o intervalo entre end e start for menor que resolution, todos os registros relatados são considerados inválidos. } ] } ``` **Protocolo (Relatório de Status e Instruções de Controle):** Iniciar Estatísticas em Tempo Real: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Parar Estatísticas em Tempo Real: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Obter Consumo de Energia Histórico: ``` json { "power-consumption": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } ``` Obter Consumo de Energia em Tempo Real: ``` json { "power-consumption": { "powerConsumption": { "type": "rlSummarize" } } } ``` **Detecção de Modo de Temperatura e Umidade (thermostat-mode-detect)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Tipo de detecção de controle de temperatura. **Tipo:** String. Obrigatório. Valores opcionais: "humidity" (detecção de umidade), "temperature" (detecção de temperatura). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Configurações de detecção suportadas. Obrigatório. { "name": "lowerSetpoint", // O valor de detecção deve estar acima deste ponto de ajuste. Pelo menos um de lowerSetpoint ou upperSetpoint é obrigatório. "value": { // Faixa de detecção. Opcional. Especifique se existirem condições predefinidas. "value": 68.0, // Valor de temperatura. **Tipo:** Number. Obrigatório. "scale": "f" // Unidade de temperatura. Obrigatório quando name=temperature. Valores opcionais: "c" (Celsius), "f" (Fahrenheit). } }, { "name": "upperSetpoint", // O valor de detecção deve estar abaixo deste ponto de ajuste. Pelo menos um de lowerSetpoint ou upperSetpoint é obrigatório. "value": { // Faixa de detecção. Opcional. Especifique se existirem condições predefinidas. "value": 68.0, // Valor de temperatura. **Tipo:** Number. Obrigatório. "scale": "f" // Unidade de temperatura. Obrigatório quando name=temperature. Valores opcionais: "c" (Celsius), "f" (Fahrenheit). } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } { "capability": "thermostat-mode-detect", "permission": "0110", "name": "humidity", // Tipo de detecção de controle de temperatura. **Tipo:** String. Obrigatório. Valores opcionais: "humidity" (detecção de umidade), "temperature" (detecção de temperatura). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Configurações de detecção suportadas. Obrigatório. { "name": "lowerSetpoint", // O valor de detecção deve estar acima deste ponto de ajuste. Pelo menos um de lowerSetpoint ou upperSetpoint é obrigatório. "value": { // Faixa de detecção. Opcional. Especifique se existirem condições predefinidas. "value": 68.0, // Valor de umidade. **Tipo:** Number. Obrigatório } }, { "name": "upperSetpoint", // O valor de detecção deve estar abaixo deste ponto de ajuste. Pelo menos um de lowerSetpoint ou upperSetpoint é obrigatório. "value": { // Faixa de detecção. Opcional. Especifique se existirem condições predefinidas. "value": 68.0, // Valor de umidade. **Tipo:** Number. Obrigatório } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ``` **Atributos (Estado):** ``` { "mode": "COMFORT" // ID do modo. Opcional. Valores suportados: "COMFORT" (Modo Conforto), "COLD" (Modo Frio), "HOT" (Modo Quente), "DRY" (Modo Seco), "WET" (Modo Úmido). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Formato: ``` { [capability] :{ [mode name] :{ "mode": [value] } } } ``` Exemplo: ``` { "thermostat-mode-detect": { "humidity": { "mode": "COMFORT" } } } ``` **Modo do Termostato (thermostat-mode)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "thermostat", "permission": "1100", "name": "thermostat-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", "AUTO", "ECO" ] } } } ``` **Atributos (Estado):** ``` { "thermostatMode": "MANUAL" // Modo de operação do termostato. **Tipo:** String. Valores opcionais: "MANUAL", "AUTO", "ECO". } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "thermostat": { "thermostat-mode": { "thermostatMode": "MANUAL" } } } ``` **Status de Recuperação Adaptativa do Termostato (thermostat/adaptive-recovery-status)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "thermostat", "permission": "0100", "name": "adaptive-recovery-status" // Status de recuperação adaptativa do termostato } ``` **Atributos (Estado):** ``` { "adaptiveRecoveryStatus": "HEATING" // Status de recuperação adaptativa do termostato. **Tipo:** String. Valores opcionais: "HEATING", "INACTIVE". } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "thermostat": { "adaptive-recovery-status": { "adaptiveRecoveryStatus": "HEATING" } } } ``` **Configuração de Temperatura Alvo do Modo do Termostato (thermostat-target-setpoint)** **Exemplo de Declaração de Capacidade:** ``` [[ { "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 início em minutos. **Tipo:** int. Ex.: 7:20 AM = 440 minutos. "upperSetpoint": 36.5, // Temperatura máxima alvo. **Tipo:** number. "lowerSetpoint": 20 // Temperatura mínima alvo. **Tipo:** number. }, { "startTimeInMinutes": 900, // Hora de início em minutos. Ex.: 3:00 PM = 900 minutos. "upperSetpoint": 26.5, // Temperatura máxima alvo. **Tipo:** number. "lowerSetpoint": 21 // Temperatura mínima alvo. **Tipo:** number. } ], "Tuesday": [... ], "Wednesday": [... ], "Thursday": [... ], "Friday": [... ], "Saturday": [... ], "Sunday": [... ], } } } } ] ``` **Atributos (Estado):** ``` { "targetSetpoint": 30 // Temperatura alvo para o modo especificado. **Tipo:** number, na unidade especificada por temperatureUnit. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "thermostat-target-setpoint": { "manual-mode": { "targetSetpoint": 30 }, "auto-mode": { "targetSetpoint": 30 } } } ``` **Detecção de Sensor (detect)** **Exemplo de Declaração de Capacidade:** ``` { "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 da detecção. **Tipo:** Boolean. `true` indica detecção, `false` indica sem detecção. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "detect": { "detected": true } } ``` **Detecção de Temperatura (temperature)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "temperature", "permission": "0110", "settings": { // Opcional "temperatureCalibration": { // Calibração de temperatura opcional "type": "numeric", "permission": "11", "min": -7, // Valor mínimo "max": 7, // Valor máximo "step": 0.2, // Passo de ajuste de temperatura, unidade igual a temperatureUnit "value": 5.2 // Valor atual de calibração de temperatura. **Tipo:** number. }, "temperatureUnit": { // Unidade de temperatura opcional "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange": { // Faixa de detecção de temperatura opcional "type": "numeric", "permission": "01", "min": -40, "max": 80 } } } ``` **Atributos (Estado):** ``` json copiar código { "temperature": 26.5 // Temperatura atual. **Tipo:** Number, em Celsius. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "temperature": { "temperature": 20 } } ``` **Detecção de Umidade (humidity)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "humidity", "permission": "0100", "settings": { // Faixa de detecção de umidade opcional. "humidityRange": { "type": "numeric", "permission": "01", "min": 0, "max": 100 } } } ``` **Atributos (Estado):** ``` { "humidity": 50 // Umidade relativa atual (porcentagem). **Tipo:** Number, faixa 0-100. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "humidity": { "humidity": 20 } } ``` **Detecção de Bateria (battery)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "battery", "permission": "0100" } ``` **Atributos (Estado):** ``` { "battery": 95 // Porcentagem de bateria restante. **Tipo:** Number, faixa -1 a 100. Observação: -1 indica nível de bateria desconhecido. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "battery": { "battery": 40 } } ``` **Detecção de Botão Único (press)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "press", "permission": "1100", "settings": { // Opcional "actions": { // Ações do botão, opcionais. "type": "enum", "permission": "01", "values": [ // Ações do botão opcionais. Valores padrão são "singlePress", "doublePress", "longPress". Ações configuradas substituem os padrões. ] } } } ``` **Atributos (Estado):** ``` { "press": "singlePress" // Tipo de pressão do botão. **Tipo:** String. Valores padrão: "singlePress" (pressione simples ou curto), "doublePress" (duplo clique), "longPress" (pressione longo). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "press": { "press": "singlePress" } } ``` **Detecção de Multi-Botão (multi-press)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "multi-press", "permission": "0100", "name": "1", // Nome do atributo multi-press. **Tipo:** String. Apenas caracteres alfanuméricos permitidos. "settings": { // Opcional "actions": { // Ações do botão, opcionais. "type": "enum", "permission": "01", "values": [ // Ações do botão opcionais. Valores padrão são "singlePress", "doublePress", "longPress". Ações configuradas substituem os padrões. ] } } } ``` **Atributos (Estado):** ``` { "press": "singlePress" // Tipo de pressão do botão. **Tipo:** String. Valores padrão: "singlePress" (pressione simples ou curto), "doublePress" (duplo clique), "longPress" (pressione longo). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { [capability] :{ [multi-press-name]：{ press:[value] } } } exemplo: { "multi-press": { "1": { "press": "singlePress" }, "2": { "press": "doublePress" } } } ``` **Detecção de Intensidade de Sinal (rssi)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "rssi", "permission": "0100" } ``` **Atributos (Estado):** ``` { "rssi": -65 // Intensidade do sinal sem fio (Indicador de Intensidade de Sinal Recebido). **Tipo:** Number, unidade dBm, valores inteiros negativos. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "rssi": { "rssi": -65 } } ``` **Detecção de Violação (tamper-alert)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "tamper-alert", "permission": "0100" } ``` **Atributos (Estado):** ``` { "tamper": "clear" // Status de violação. **Tipo:** String. Valores possíveis: "clear" (não violado), "detected" (violado). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "tamper-alert": { "tamper": "clear" // Status de violação. **Tipo:** String. Valores possíveis: "clear" (não violado), "detected" (violado). } } ``` **Detecção de Nível de Iluminação (illumination-level)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "illumination-level", "permission": "0100" } ``` **Atributos (Estado):** ``` { "level": "brighter" // Nível de brilho. **Tipo:** String. Valores possíveis: "brighter" (mais claro), "darker" (mais escuro). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "illumination-level": { "level": "brighter" } } ``` **Detecção de Voltagem (voltage)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "voltage", "permission": "0100" } ``` **Atributos (Estado):** ``` { "voltage": 50 // Valor de voltagem atual, em unidades de 0.01V. **Tipo:** Number, valores não negativos. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "voltage": { "voltage": 50 } } ``` **Detecção de Corrente Elétrica (electric-current)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "electric-current", "permission": "0100" } ``` **Atributos (Estado):** ``` { "electric-current": 50 // Valor de corrente atual, em unidades de 0.01A. **Tipo:** Number, valores inteiros não negativos. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "electric-current": { "electric-current": 50 } } ``` **Detecção de Potência Elétrica (electric-power)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "electric-power", "permission": "0100" } ``` **Atributos (Estado):** ``` { "electric-power": 50 // Valor de potência atual, em unidades de 0.01W. **Tipo:** Number, valores inteiros não negativos. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "electric-power": { "electric-power": 50 } } ``` **Detecção de Falhas (fault)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "fault", "permission": "0100" } ``` **Atributos (Estado):** ``` { "fault": "none" // Status de falha. **Tipo:** String. Valores possíveis: "none" (sem falha), "detected" (falha detectada). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "fault": { "fault": "none" } } ``` **Interruptor de Limite (threshold-breaker)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "threshold-breaker", "permission": "0010", "settings": { "supportedSetting": { "type": "object", "permission": "11", "value": { "supported": [ { "name": "lowerPower", // Interruptor de limite de baixa potência "value": { "value": 50, // Valor de potência de detecção, em unidades de 0.01W. **Tipo:** Integer. Faixa: >=0. "min_range": 10, // Valor mínimo de detecção de potência, em unidades de 0.01W. **Tipo:** Integer. Faixa: >=0. "max_range": 3500 // Valor máximo de detecção de potência, em unidades de 0.01W. **Tipo:** Integer. Faixa: >=0. } }, { "name": "upperPower", // Interruptor de limite de alta potência "value": { "value": 50, // Valor de potência de detecção, em unidades de 0.01W. **Tipo:** Integer. Faixa: >=0. "min_range": 10, // Valor mínimo de detecção de potência, em unidades de 0.01W. **Tipo:** Integer. Faixa: >=0. "max_range": 3500 // Valor máximo de detecção de potência, em unidades de 0.01W. **Tipo:** Integer. Faixa: >=0. } }, { "name": "lowerElectricCurrent", // Interruptor de limite de baixa corrente "value": { "value": 50, // Valor de detecção de corrente, em unidades de 0.01A. **Tipo:** Integer. Faixa: >=0. "min_range": 10, // Valor mínimo de detecção de corrente, em unidades de 0.01A. **Tipo:** Integer. Faixa: >=0. "max_range": 1500 // Valor máximo de detecção de corrente, em unidades de 0.01A. **Tipo:** Integer. Faixa: >=0. } }, { "name": "upperElectricCurrent", // Interruptor de limite de alta corrente "value": { "value": 50, // Valor de detecção de corrente, em unidades de 0.01A. **Tipo:** Integer. Faixa: >=0. "min_range": 10, // Valor mínimo de detecção de corrente, em unidades de 0.01A. **Tipo:** Integer. Faixa: >=0. "max_range": 1500 // Valor máximo de detecção de corrente, em unidades de 0.01A. **Tipo:** Integer. Faixa: >=0. } }, { "name": "lowerVoltage", // Interruptor de limite de baixa voltagem "value": { "value": 50, // Valor de detecção de voltagem, em unidades de 0.01V. **Tipo:** Integer. Faixa: >=0. "min_range": 10, // Valor mínimo de detecção de voltagem, em unidades de 0.01V. **Tipo:** Integer. Faixa: >=0. "max_range": 24000 // Valor máximo de detecção de voltagem, em unidades de 0.01V. **Tipo:** Integer. Faixa: >=0. } }, { "name": "upperVoltage", // Interruptor de limite de alta voltagem "value": { "value": 50, // Valor de detecção de voltagem, em unidades de 0.01V. **Tipo:** Integer. Faixa: >=0. "min_range": 10, // Valor mínimo de detecção de voltagem, em unidades de 0.01V. **Tipo:** Integer. Faixa: >=0. "max_range": 24000 // Valor máximo de detecção de voltagem, em unidades de 0.01V. **Tipo:** Integer. Faixa: >=0. } } ] } } } } ``` **Atributos (Estado)** * Nenhum **Protocolo (Consulta de Status e Instruções de Controle)** * Nenhum **Função Inch (inching)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "inching", "permission": "0010", "settings": { "inchingEnable": { // Configuração de habilitar função inch "permission": "11", "type": "boolean", "value": false }, "inchingSwitch": { // Configuração de ação inch "type": "enum", "permission": "11", "value": "on", "values": ["on", "off"] }, "inchingDelay": { // Configuração do tempo de inch "type": "numeric", "permission": "11", "min": 500, "max": 100000, "value": 1000, "unit": "ms" } } } ``` **Atributos (Estado):** * Nenhum **Protocolo (Consulta de Status e Instruções de Controle):** * Nenhum **Transmissão de Câmera (camera-stream)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "camera-stream", "permission": "0010", "settings": { "streamSetting": { "type": "object", "permission": "11", "value": { "username": "String", // Conta de acesso. **Tipo:** String. Obrigatório. "password": "String", // Senha de acesso. **Tipo:** String. Obrigatório. "streamUrl": "rtsp://:@:/streaming/channel01", // URL do stream. **Tipo:** String. Obrigatório. "videoCodec": "", // Codec de vídeo. **Tipo:** String. Obrigatório. Parâmetros opcionais a serem definidos. "resolution": { // Resolução de vídeo. Obrigatório. "width": 1080, // Largura. **Tipo:** Number. Obrigatório. "height": 720 // Altura. **Tipo:** Number. Obrigatório. }, "keyFrameInterval": 5, // Intervalo de key frame. **Tipo:** String. Obrigatório. "audioCodec": "G711", // Codec de áudio. **Tipo:** String. Obrigatório. Parâmetros opcionais a serem definidos. "samplingRate": 50, // Taxa de amostragem de áudio, em Hz. **Tipo:** Number. Obrigatório. Parâmetros opcionais a serem definidos. "dataRate": 50 // Taxa de bits. **Tipo:** Number. Obrigatório. Unidade: kb/s. } } } } ``` **Atributos (Estado):** * Nenhum **Protocolo (Consulta de Status e Instruções de Controle):** * Nenhum **Controle de Modo (mode)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "mode", "name": "fanLevel", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["low", "medium", "high"] // Valores de modo personalizados. Valores configurados substituem os padrões. } } }, { "capability": "mode", "name": "thermostatMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["auto", "manual"] // Valores de modo personalizados. Valores configurados substituem os padrões. } } }, { "capability": "mode", "name": "airConditionerMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["cool", "heat", "auto", "fan", "dry"] // Valores de modo personalizados. Valores configurados substituem os padrões. } } }, { "capability": "mode", "name": "fanMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["normal", "sleep", "child"] // Valores de modo personalizados. Valores configurados substituem os padrões. } } }, { "capability": "mode", "name": "horizontalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Valores de modo personalizados. Valores configurados substituem os padrões. } } }, { "capability": "mode", "name": "verticalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Valores de modo personalizados. Valores configurados substituem os padrões. } } } ] ``` **Atributos (Estado):** ``` { "modeValue": "low" // Valor do modo. **Tipo:** String. Obrigatório. Consulte os modos predefinidos suportados. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "mode": { "fanLevel": { "modeValue": "low" } } } ``` **Detecção de Dióxido de Carbono (co2)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "co2", "permission": "0100", "settings": { "co2Range": { "type": "numeric", "permission": "01", "min": 400, "max": 10000 } } } ``` **Atributos (Estado):** ``` { "co2": 111 // Concentração de dióxido de carbono. **Tipo:** Integer. Unidade: ppm. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "co2": { "co2": 500 } } ``` **Detecção de Iluminação (illumination)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "illumination", "permission": "0100", "settings": { "illuminationRange": { "type": "numeric", "permission": "01", "min": 0, "max": 160000 } } } ``` **Atributos (Estado):** ``` { "illumination": 11 // Nível de iluminação. **Tipo:** Integer. Unidade: lux. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "illumination": { "illumination": 50 } } ``` **Detecção de Fumaça (smoke)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "smoke", "permission": "0100" } ``` **Atributos (Estado):** ``` { "smoke": true // Resultado da detecção. **Tipo:** Boolean. `true` indica detecção, `false` indica sem detecção. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "smoke": { "smoke": true } } ``` **Detecção de Abertura/Fechamento do Ímã da Porta (contact)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "contact", "permission": "0100" } ``` **Atributos (Estado):** ``` { "contact": true // Resultado da detecção. **Tipo:** Boolean. `true` indica detecção, `false` indica ausência de detecção. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "contact": { "contact": true } } ``` **Detecção de Movimento (motion)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "motion", "permission": "0110", "settings": { "motionInterval": { "type": "numeric", "permission": "11", "value": 300 }, "motionSensitivity": { "type": "numeric", "permission": "11", "value": 1000 } } } ``` **Atributos (Estado):** ``` { "motion": true // Resultado da detecção. **Tipo:** Boolean. `true` indica detecção, `false` indica ausência de detecção. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "motion": { "motion": true } } ``` **Detecção de Vazamento de Água (water-leak)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "water-leak", "permission": "0100" } ``` **Atributos (Estado):** ``` { "waterLeak": true // O campo `waterLeak` indica o resultado atual da detecção. **Tipo:** Boolean. `true` indica detecção, `false` indica ausência de detecção. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "water-leak": { "waterLeak": true } } ``` **Interruptor de Detecção de Janela (window-detection)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "window-detection", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // O campo `powerState` indica o estado de energia. **Tipo:** String. `on` indica energia ligada, `off` indica energia desligada. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "window-detection": { "powerState": "on" } } ``` **Bloqueio Infantil (child-lock)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "child-lock", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // O campo `powerState` indica o estado de energia. **Tipo:** String. `on` indica energia ligada, `off` indica energia desligada. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "child-lock": { "powerState": "on" } } ``` **Interruptor Anti-Sopro Direto (anti-direct-blow)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "anti-direct-blow", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // O campo `powerState` indica o estado de energia. **Tipo:** String. `on` indica energia ligada, `off` indica energia desligada. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "anti-direct-blow": { "powerState": "on" } } ``` **Oscilação Horizontal (horizontal-swing)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "horizontal-swing", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // O campo `powerState` indica o estado de energia. **Tipo:** String. `on` indica energia ligada, `off` indica energia desligada. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "horizontal-swing": { "powerState": "on" } } ``` **Oscilação Vertical (vertical-swing)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "vertical-swing", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // O campo `powerState` indica o estado de energia. **Tipo:** String. `on` indica energia ligada, `off` indica energia desligada. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "vertical-swing": { "powerState": "on" } } ``` **Modo ECO (eco)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "eco", "permission": "1100" } ``` **Atributos (Estado):** ``` { "powerState": "on" // O campo `powerState` indica o estado de energia. **Tipo:** String. `on` indica energia ligada, `off` indica energia desligada. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "eco": { "powerState": "on" } } ``` **Alternar Inicialização (toggle-startup)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "toggle-startup", "permission": "1100", "name": "1" // O campo `name` especifica o nome do atributo para `toggle-startup`. **Tipo:** String. Apenas letras e números são permitidos. } ``` **Atributos (Estado):** ``` { "startup": "on" // **Tipo:** String. Opções: `on` (ligar), `stay` (manter), `off` (desligar). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "toggle-startup": { "1": { "startup": "on" }, "2": { "startup": "off" } } } ``` **Detectar Manutenção (detect-hold)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "detect-hold", "permission": "0100", "settings": { "detectHoldEnable": { // Configuração de habilitar detect hold "permission": "01", "type": "boolean", "value": false }, "detectHoldSwitch": { // Configuração de ação detect hold "type": "enum", "permission": "01", "value": "on", "values": ["on", "off"] }, "detectHoldTime": { // Configuração de tempo detect hold "type": "numeric", "permission": "01", "min": 1, "max": 359, "value": 5, "unit": "minute" } } } ``` **Atributos (Estado):** ``` { "detectHold": "on" // O campo `detectHold` indica o estado de manutenção da detecção. **Tipo:** String. `on` significa que a manutenção de detecção está ativa, `off` significa que está inativa. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "detect-hold": { "detectHold": "on" } } ``` **Alternar Identificar/Ativar (toggle-identify)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "toggle-identify", "permission": "1100", // Observação: Esta capacidade não é usada para relatório na versão atual (V1.13.7) no ihost. "name": "1" // Nome do componente. **Tipo:** String. Valores opcionais: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). } ``` **Atributos (Estado):** ``` { "identify": true, // Indica que o dispositivo relatou ativamente identificação ou ativação. "countdown": 180 // O campo `countdown` indica a duração da ativação. **Tipo:** Number. Unidade: segundos. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "toggle-identify": { "1": { "countdown": 180 // Ativar dispositivo por 180 segundos. } } } // Dispositivo relata auto-ativação { "toggle-identify": { "1": { "identify": true } } } ``` **Detecção de Tensão Alternável (toggle-voltage)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "toggle-voltage", "permission": "1100" } ``` **Atributos (Estado):** ``` { "voltage": 230 // O campo `voltage` indica a tensão detectada. **Tipo:** Number. Unidade: Volts. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "toggle-voltage": { "voltage": 230 } } ``` **Detecção de Corrente Elétrica por Subcomponente (toggle-electric-current)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "toggle-electric-current", "permission": "0100", "name": "1" // Nome do componente. **Tipo:** String. Valores opcionais: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). } ] ``` **Atributos (Estado):** ``` { "electricCurrent": 50 // O campo `electricCurrent` representa o valor da corrente. **Unidade:** 0.01 A. **Tipo:** Integer. O valor deve ser maior ou igual a 0. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "toggle-electric-current": { "1": { "electricCurrent": 50 } } } ``` **Detecção de Potência por Subcomponente (toggle-electric-power)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "toggle-electric-power", "permission": "0100", "name": "1" // Nome do componente. **Tipo:** String. Valores opcionais: "1" (Canal 1), "2" (Canal 2), "3" (Canal 3), "4" (Canal 4). } ] ``` **Atributos (Estado):** ``` { "electricPower": 50, // O campo `electricPower` representa o valor de potência atual. **Unidade:** 0.01 W. **Tipo:** Integer. O valor deve ser maior ou igual a 0. "reactivePower": 50, // O campo `reactivePower` representa o valor de potência reativa atual. **Unidade:** 0.01 W. **Tipo:** Integer. Opcional. "activePower": 50, // O campo `activePower` representa o valor de potência ativa atual. **Unidade:** 0.01 W. **Tipo:** Integer. Opcional. "apparentPower": 50 // O campo `apparentPower` representa o valor de potência aparente atual. **Unidade:** 0.01 W. **Tipo:** Integer. Opcional. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "toggle-electric-power": { "1": { "electricPower": 50, "reactivePower": 50, "activePower": 50, "apparentPower": 50 } } } ``` **Estatísticas de Consumo de Energia por Subcomponente (toggle-power-consumption)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "toggle-power-consumption", "permission": "1101", "name": "1", // Nome do componente. **Tipo:** String. Valores opcionais: "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/Parar Estatísticas em Tempo Real: ``` { "rlSummarize": true, // Iniciar ou parar estatísticas em tempo real. **Tipo:** Boolean. Obrigatório. "timeRange": { // Intervalo de tempo do resumo. Obrigatório. "start": "2020-07-05T08:00:00Z", // Hora de início do consumo de energia. **Tipo:** String. Obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término do consumo de energia. **Tipo:** String. Obrigatório. } } ``` Consultar Consumo de Energia por Intervalo de Tempo: ``` { "type": "summarize", // Tipo de resumo. **Tipo:** String. Obrigatório. Opções: "rlSummarize" (Resumo em tempo real), "summarize" (Resumo atual). "timeRange": { // Intervalo de tempo do resumo, obrigatório quando o tipo é "summarize". "start": "2020-07-05T08:00:00Z", // Hora de início do consumo de energia. **Tipo:** String. Obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término do consumo de energia. **Tipo:** String. Opcional. Se não fornecido, padrão é a hora atual. } } ``` Resposta para Consumo de Energia dentro do Intervalo de Tempo: ``` { "type": "summarize", // Tipo de resumo. **Tipo:** String. Obrigatório. "rlSummarize": 50.0, // Consumo total de energia. **Unidade:** 0.01 kWh. **Tipo:** Number. Opcional. "electricityIntervals": [ // Dividido por `configuration.resolution` em múltiplos registros. Opcional. Não presente quando o tipo é "rlSummarize". { "usage": 26.5, // Consumo de energia. **Unidade:** 0.01 kWh. **Tipo:** Number. Obrigatório. "start": "2020-07-05T08:00:00Z", // Hora de início. **Tipo:** String. Obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término. **Tipo:** String. Obrigatório. Registros com intervalos menores que a resolução são considerados inválidos. }, { "usage": 26.5, // Consumo de energia. **Unidade:** 0.01 kWh. **Tipo:** Number. Obrigatório. "start": "2020-07-05T09:00:00Z", // Hora de início. **Tipo:** String. Obrigatório. "end": "2020-07-05T10:00:00Z" // Hora de término. **Tipo:** String. Obrigatório. Registros com intervalos menores que a resolução são considerados inválidos. } ] } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Iniciar Estatísticas em Tempo Real: ``` { "toggle-power-consumption": { "1": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Parar Estatísticas em Tempo Real: ``` { "toggle-power-consumption": { "1": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Obter Consumo de Energia Histórico: ``` { "toggle-power-consumption": { "1": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Obter Consumo de Energia em Tempo Real: ``` { "toggle-power-consumption": { "1": { "type": "rlSummarize" } } } ``` **Indicador de Qualidade de Link (lqi)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "lqi", "permission": "0100" } ``` **Atributos (Estado):** ``` { "lqi": 60 // O campo `lqi` representa o indicador de qualidade do link. **Tipo:** Number. Faixa de valores: 0 a 255. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "lqi": { "lqi": 60 } } ``` **Configuração Funcional (configuration)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "configuration", "permission": "1100" } ] ``` **Atributos (Estado):** ``` { "deviceConfiguration": { // Configuração funcional relacionada ao dispositivo "defaultResolution": 300, // Resolução padrão para leitura de dados de saturação de umidade. **Tipo:** Integer. **Unidade:** Segundos. Obrigatório. "maxResolution": 86400, // Resolução máxima para leitura de dados de saturação de umidade. **Tipo:** Integer. **Unidade:** Segundos. Obrigatório. "minResolution": 60 // Resolução mínima para leitura de dados de saturação de umidade. **Tipo:** Integer. **Unidade:** Segundos. Obrigatório. } } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "configuration": { "deviceConfiguration": { // Configuração funcional relacionada ao dispositivo "defaultResolution": 300, // Resolução padrão para leitura de dados de saturação de umidade. **Tipo:** Integer. **Unidade:** Segundos. Obrigatório. "maxResolution": 86400, // Resolução máxima para leitura de dados de saturação de umidade. **Tipo:** Integer. **Unidade:** Segundos. Obrigatório. "minResolution": 60 // Resolução mínima para leitura de dados de saturação de umidade. **Tipo:** Integer. **Unidade:** Segundos. Obrigatório. } } } ``` **Sistema (system)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "system", "permission": "1000" } ] ``` **Atributos (Estado):** ``` { "restart": true // Comando para reiniciar o dispositivo. **Tipo:** Boolean. Obrigatório. O valor deve ser `true`. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "system": { // Configuração relacionada à capacidade. Opcional. "restart": true } } ``` **Umidade (moisture)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "moisture", "permission": "0100" } ] ``` **Atributos (Estado):** ``` { "moisture": 55.5 // O campo `moisture` representa a porcentagem de saturação de umidade. **Tipo:** Number. Obrigatório. Faixa: 0 a 100. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "moisture": { "moisture": 55.5 } } ``` **Pressão Barométrica (barometric-pressure)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "barometric-pressure", "permission": "0100", "settings": { "barometricPressureRange": { "type": "numeric", "permission": "01", "min": 540, // Valor mínimo. **Tipo:** Integer. Obrigatório. Deve ser menor que `max`. "max": 1100 // Valor máximo. **Tipo:** Integer. Obrigatório. Deve ser maior que `min`. } } } ] ``` **Atributos (Estado):** ``` { "barometricPressure": 50 // Valor da pressão barométrica. **Tipo:** Integer. Obrigatório. **Unidade:** hPa. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "barometric-pressure": { "barometricPressure": 50 } } ``` **Velocidade do Vento (wind-speed)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "wind-speed", "permission": "0100", "settings": { "windSpeedRange": { "type": "numeric", "permission": "01", "min": 0, // Valor mínimo. **Tipo:** Number. Obrigatório. Deve ser menor que `max`. "max": 50 // Valor máximo. **Tipo:** Number. Obrigatório. Deve ser maior que `min`. } } } ] ``` **Atributos (Estado):** ``` { "windSpeed": 50 // Valor da velocidade do vento. **Tipo:** Number. Obrigatório. **Unidade:** m/s (metros por segundo). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "wind-speed": { "windSpeed": 50 } } ``` **Direção do Vento (wind-direction)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "wind-direction", "permission": "0100" } ] ``` **Atributos (Estado):** ``` { "windDirection": 10 // Direção do vento. **Tipo:** Integer. Obrigatório. **Unidade:** Graus. Faixa: 0 a 360 graus (direção horário). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "wind-direction": { "windDirection": 10 } } ``` **Precipitação (rainfall)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "rainfall", "permission": "0100", "settings": { "rainfallRange": { "type": "numeric", "permission": "01", "min": 0, // Valor mínimo. **Tipo:** Number. Obrigatório. Deve ser menor que `max`. "max": 450 // Valor máximo. **Tipo:** Number. Obrigatório. Deve ser maior que `min`. } } } ] ``` **Atributos (Estado):** ``` { "rainfall": 11.11 // Valor de precipitação. **Tipo:** Number. Obrigatório. **Unidade:** mm/h (milímetros por hora). } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "rainfall": { "rainfall": 11.11 } } ``` **Índice Ultravioleta (ultraviolet-index)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "ultraviolet-index", "permission": "0100", "settings": { "ultravioletIndexRange": { "type": "numeric", "permission": "01", "min": 0, // Valor mínimo. **Tipo:** Number. Obrigatório. Deve ser menor que `max`. "max": 16 // Valor máximo. **Tipo:** Number. Obrigatório. Deve ser maior que `min`. } } } ] ``` **Atributos (Estado):** ``` { "ultravioletIndex": 11.1 // Índice ultravioleta. **Tipo:** Number. Obrigatório. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "ultraviolet-index": { "ultravioletIndex": 11.1 } } ``` **Condutividade Elétrica (electrical-conductivity)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "electrical-conductivity", "permission": "0100", "settings": { "electricalConductivityRange": { "type": "numeric", "permission": "01", "min": 0, // Valor mínimo. **Tipo:** Number. Obrigatório. Deve ser menor que `max`. "max": 23 // Valor máximo. **Tipo:** Number. Obrigatório. Deve ser maior que `min`. } } } ] ``` **Atributos (Estado):** ``` { "electricalConductivity": 11.11 // Valor da condutividade elétrica. **Tipo:** Number. Obrigatório. **Unidade:** dS/m. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "electrical-conductivity": { "electricalConductivity": 11.11 } } ``` **Potência de Transmissão (transmit-power)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "transmit-power", "permission": "1100" } ] ``` **Atributos (Estado):** ``` { "transmitPower": 9 // Valor de potência de transmissão do dispositivo. **Tipo:** Integer. Obrigatório. **Unidade:** dBm. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "transmit-power": { "transmitPower": 9 } } ``` **Detecção de PM2.5 (pm25)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "pm25", "permission": "0100" } ] ``` **Atributos (Estado):** ``` { "pm25": 10 // Concentração de PM2.5 no ar. **Tipo:** Number. Obrigatório. **Unidade:** µg/m³. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "pm25": { "pm25": 10 } } ``` **Índice de VOC (voc-index)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "voc-index", "permission": "0100" } ``` **Atributos (Estado):** ``` { "vocIndex": 10 // Índice VOC que reflete o nível de poluição por gases nocivos. **Tipo:** Number. Obrigatório. **Unidade:** µg/m³. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "voc-index": { "vocIndex": 10 } } ``` **Detecção de Gás Natural (gas)** **Exemplo de Declaração de Capacidade:** ``` { "capability": "gas", "permission": "0100" } ``` **Atributos (Estado):** ``` { "gas": true // Indica se foi detectado vazamento de gás natural. **Tipo:** Boolean. Obrigatório. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "gas": { "gas": true } } ``` **Status de Trabalho de Irrigação (irrigation/work-status)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "irrigation", "permission": "0101", "name": "work-status", "settings": { "volumeUnit": { "type": "enum", "permission": "01", "values": ["L"], "value": "L" } } } ] ``` **Atributos (Estado):** ``` { "realTimeVolume": 20, // Volume de irrigação em tempo real. **Tipo:** Number. Opcional. **Unidade:** L. "start": "2020-07-05T08:00:00Z", // Hora de início da irrigação. **Tipo:** Date. Opcional. "end": "2020-07-05T09:00:00Z", // Hora de término da irrigação. **Tipo:** Date. Opcional. "dailyVolume": 20 // Volume diário de irrigação. **Tipo:** Number. Opcional. **Unidade:** L. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Relato de Status de Trabalho: ``` { "irrigation": { "work-status": { "realTimeVolume": 20, "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z", "dailyVolume": 20 } } } ``` Consulta de Status de Trabalho: ``` { "irrigation": { "type": "oneDay", // Tipo de agregação. **Tipo:** String. Obrigatório. Opções: "oneDay", "30Days", "180Days". "timeRange": { // Intervalo de tempo para agregação. **Tipo:** Object. Obrigatório. "start": "2020-07-05T08:00:00Z", // Hora de início para agregação dos dados de irrigação. **Tipo:** String. Obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término para agregação dos dados de irrigação. **Tipo:** String. Opcional. Se omitido, o horário atual é usado. } } } ``` Resultado da Consulta de Status de Trabalho: ``` { "irrigation": { "type": "oneDay", // Tipo de agregação. **Tipo:** String. Obrigatório. "irrigationIntervals": [ { "volume": 6500, // Volume de irrigação. **Tipo:** Number. Obrigatório. **Unidade:** L. "duration": 30, // Duração da irrigação. **Tipo:** Number. Obrigatório. **Unidade:** minutos. "start": "2020-07-05T08:00:00Z", // Hora de início. **Tipo:** String. Obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término. **Tipo:** String. Obrigatório. }, { "volume": 6500, // Volume de irrigação. **Tipo:** Number. Obrigatório. **Unidade:** L. "duration": 30, // Duração da irrigação. **Tipo:** Number. Obrigatório. **Unidade:** minutos. "start": "2020-07-05T08:00:00Z", // Hora de início. **Tipo:** String. Obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término. **Tipo:** String. Obrigatório. } ] } } ``` **Modo de Trabalho de Irrigação (irrigation/work-mode)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "irrigation", "permission": "0100", "name": "work-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", // Modo manual "TIMER", // Agendamento único "CYCLE-TIMER", // Agendamento repetido "VOLUME", // Volume único "CYCLE-VOLUME" // Volume repetido ] } } } ] ``` **Atributos (Estado):** ``` { "workMode": "MANUAL" // Modo de trabalho de irrigação. **Tipo:** String. Opcional. Os valores devem ser provenientes de `settings.supportedModes`. } ``` **Protocolo (Consulta de Status e Instruções de Controle):** ``` { "irrigation": { "work-mode": "MANUAL" } } ``` **Controlador de Irrigação Automático (irrigation/auto-controller)** **Exemplo de Declaração de Capacidade:** ``` [ { "capability": "irrigation", "permission": "1100", "name": "auto-controller", "settings": { "volumeRange": { // Faixa de volume "type": "enum", "permission": "01", "min": 0, "max": 6500, "unit": "L" }, "timeRange": { // Faixa de tempo "type": "enum", "permission": "01", "min": 1, "max": 86400, "unit": "second" }, "cycleCountRange": { // Faixa de contagem de ciclos "type": "enum", "permission": "01", "min": 1, "max": 100, "step": 1 } } } ] ``` **Atributos (Estado):** Agendamento Único ou Repetido: ``` { "type": "time", // Modo de irrigação. **Tipo:** String. Obrigatório. Opções: "volume", "time". "action": { "perDuration": 60, // Duração por ciclo de irrigação. **Tipo:** Number. Obrigatório. "intervalDuration": 20, // Intervalo entre ciclos de irrigação. **Tipo:** Number. Obrigatório. "count": 3 // Número de ciclos de irrigação. **Tipo:** Number. Obrigatório. } } ``` Volume Único ou Repetido: ``` { "type": "volume", // Modo de irrigação. **Tipo:** String. Obrigatório. Opções: "volume", "time". "action": { "perConsumedVolume": 60, // Volume consumido por ciclo de irrigação. **Tipo:** Number. Obrigatório. "intervalDuration": 20, // Intervalo entre ciclos de irrigação. **Tipo:** Number. Obrigatório. "count": 3 // Número de ciclos de irrigação. **Tipo:** Number. Obrigatório. } } ``` **Protocolo (Consulta de Status e Instruções de Controle):** Agendamento Único ou Repetido: ``` { "irrigation": { "auto-controller": { "type": "time", // Modo de irrigação. **Tipo:** String. Obrigatório. "action": { "perDuration": 60, // Duração por ciclo de irrigação. **Tipo:** Number. Obrigatório. "intervalDuration": 20, // Intervalo entre ciclos. **Tipo:** Number. Obrigatório. "count": 3 // Número de ciclos. **Tipo:** Number. Obrigatório. } } } } ``` Volume Único ou Repetido: ``` { "irrigation": { "auto-controller": { "type": "volume", // Modo de irrigação. **Tipo:** String. Obrigatório. "action": { "perConsumedVolume": 60, // Volume consumido por ciclo. **Tipo:** Number. Obrigatório. "intervalDuration": 20, // Intervalo entre ciclos. **Tipo:** Number. Obrigatório. "count": 3 // Número de ciclos. **Tipo:** Number. Obrigatório. } } } } ``` **Modos Predefinidos Suportados** | \*\*Nomes dos Modos \*\* | \*\*Valores Opcionais \*\* | | ------------------------------------------------------ | -------------------------- | | fanLevel (nível do ventilador) | "low" | | "medium" | | | "high" | | | thermostatMode (Modo do Termostato) | "auto" | | "manual" | | | airConditionerMode >= 1.11.0 (Modo do Ar-Condicionado) | "cool" | | "heat" | | | "auto" | | | "fan" | | | "dry" | | | fanMode >= 1.11.0 (Modo do 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. Descrição das Tags * A chave especial toggle é usada para definir o nome do subcomponente toggle. ``` { "toggle": { '1': 'Chanel1', '2': 'Chanel2', '3': 'Chanel3', '4': 'Chanel4', }, } ``` * A chave especial temperature\_unit é usada para definir a unidade de temperatura. ``` { "temperature_unit":'c' // c-Celsius; f-Fahrenheit } ``` #### d. Código de Erro Especial e Descrição | **Código de Erro** | **Descrição** | Versão do iHost | | ------------------ | -------------------------------------------------------------------------------- | --------------- | | 110000 | O subdispositivo/grupo correspondente ao id não existe | ≥2.1.0 | | 110001 | O gateway está no estado de descoberta de dispositivos zigbee | ≥2.1.0 | | 110002 | Dispositivos em um grupo não têm uma capacidade comum | ≥2.1.0 | | 110003 | Número incorreto de dispositivos | ≥2.1.0 | | 110004 | Número incorreto de grupos | ≥2.1.0 | | 110005 | Dispositivo Offline | ≥2.1.0 | | 110006 | Falha ao atualizar o status do dispositivo | ≥2.1.0 | | 110007 | Falha ao atualizar o status do grupo | ≥2.1.0 | | 110008 | O número máximo de grupos foi atingido. Crie até 50 grupos | ≥2.1.0 | | 110009 | O endereço IP do dispositivo da câmera está incorreto | ≥2.1.0 | | 110010 | Erro de Autorização de Acesso ao Dispositivo de Câmera | ≥2.1.0 | | 110011 | Endereço de stream do dispositivo de câmera incorreto | ≥2.1.0 | | 110012 | Codificação de vídeo do dispositivo de câmera não é suportada | ≥2.1.0 | | 110013 | Dispositivo já existe | ≥2.1.0 | | 110014 | A câmera não suporta operação offline | ≥2.1.0 | | 110015 | A senha da conta é inconsistente com a senha da conta no endereço de stream RTSP | ≥2.1.0 | | 110016 | O gateway está no estado de descoberta de câmeras onvif | ≥2.1.0 | | 110017 | Excedido o número máximo de câmeras adicionadas | ≥2.1.0 | | 110018 | O caminho da câmera ESP está errado | ≥2.1.0 | | 110019 | Falha ao acessar o endereço de serviço do dispositivo de terceiros | ≥2.1.0 | #### e. Buscar Subdispositivo Permitir que usuários autorizados habilitem ou desabilitem a busca de subdispositivos pelo gateway através desta interface * 💡Observação: Atualmente suporta apenas busca por subdispositivos Zigbee. * 💡Observação: Subdispositivos Zigbee serão adicionados automaticamente após a busca. Não é necessário usar a interface "Adicionar Subdispositivos Manualmente" :::tips * **URL**：/open-api/V2/rest/devices/discovery * **Método**: PUT * **Cabeçalho**： * Content-Type: application/json * Autorization: Bearer ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ---------------------------------------------------- | | habilitar | boolean | N | true (Iniciar pareamento); false (Pausar pareamento) | | type | string | N | Tipo de Busca: Zigbee | Resposta de dados bem-sucedida: Objeto vazio {} :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\* `200 OK` ::: **Exemplo de resposta**: ``` { "error": 0, "data": {}, "message": "success" } ``` #### f. Adicionar Subdispositivo Manualmente Permitir que usuários autorizados adicionem um **único** subdispositivo através desta interface. * Observação: Atualmente apenas Câmera RTSP e Câmera ESP32 são suportadas :::tips * **URL**：/open-api/V2/rest/devices * **Método**：POST * **Cabeçalho**： * Content-Type: application/json * Autorization: Bearer ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ----------------- | ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nome do subdispositivo | | display\_category | string | N | Tipo de Dispositivo. Suporta apenas câmera. | | capabilities | CapabilityObject\[] | N | Lista de capacidades. Quando display\_category = camera, as capacidades incluem apenas capacidades de camera-stream. | | protocal | string | N | Protocolo do dispositivo. RTSP; ESP32-CAM | | manufacturer | string | N | Fabricante. | | model | string | N | Modelo do dispositivo | | firmware\_version | string | N | Versão do firmware do dispositivo | CapabilityObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------- | ------------------------------- | ------------ | -------------------------------------------------- | | capability | string | N | Nome da capacidade. Suporta apenas "camera-stream" | | permission | string | N | Permissão do dispositivo. Suporta apenas leitura. | | configuration | CameraStreamConfigurationObject | Y | Configuração de stream da câmera. | SettingsObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------- | ------------------- | ------------ | --------------------------------- | | streamSetting | StreamSettingObject | N | Configuração do serviço de stream | StreamSettingObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------------------ | ------------ | ----------------------------------------------------------- | | type | string | N | Configuração do serviço de stream | | permission | string | N | Permissão da capacidade. Suporta apenas "11" (modificável). | | campo value | StreamSettingValueObject | N | Valores de configuração específicos | StreamSettingValueObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------------ | | stream\_url | string | N | Formato da URL de Stream | | Formato:`://:/:@` | | | | | Exemplo:`rtsp://admin:123456@192.168.10.115:554/streaming/channel01` | | | | | Opções de Schema: | | | | | `rtsp` (Protocolo de Streaming em Tempo Real) | | | | | `http` (Protocolo de Transferência de Hipertexto) — Para dispositivos ESP32-CAM | | | | | \*Observação: Algumas câmeras podem não exigir nome de usuário ou senha. Nesses casos, você pode omitir o `` e `` campos da URL. | | | | Resposta de dados bem-sucedida: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------- | -------- | ------------ | ------------------------------------ | | serial\_number | string | N | Número de série único do dispositivo | :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ``` { "error": 0, "data": { "serial_number": "serial_number" }, "message": "success" } ``` Resposta de falha na adição: Objeto vazio :::tips **Condição**： 1. Erro de acesso ao endereço de stream da câmera (erro de formato, falha de autorização, exceção de rede, etc.) 2. Dispositivo já existe 3. Se um único dispositivo falhar ao adicionar, retorna que todos os dispositivos falharam ao adicionar. **Código de Status**: 200 OK **Código de erro**： ● 110009 Erro no endereço IP da câmera ● 110010 Erro de autorização de acesso à câmera ● 110011 Erro no endereço de stream da câmera ● 110012 A codificação de vídeo da câmera não é suportada ● 110013 Dispositivo já existe ::: **Exemplo de resposta**: ``` { "error": 110009, "data": {}, "message": "falha no acesso ao ip da câmera" } ``` #### g. Obter Lista de Subdispositivos Permitir que usuários autorizados obtenham a lista de subdispositivos do gateway por esta interface. :::tips * **URL**：/open-api/V2/rest/devices * **Método**: GET * **Cabeçalho**： * Content-Type: application/json * Autorization: Bearer ::: Parâmetros da requisição: nenhum Resposta de dados bem-sucedida: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ----------------------- | ------------ | --------------------- | | device\_list | ResponseDeviceObject\[] | N | Lista de dispositivos | ResponseDeviceObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | --------------------- | ------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de série único do dispositivo | | third\_serial\_number | string | "N" quando um dispositivo de terceiros está conectado, caso contrário "Y" | Número de série único do dispositivo de terceiros | | service\_address | string | "N" quando um dispositivo de terceiros está conectado, caso contrário "Y" | Endereço de serviço de terceiros | | name | string | N | Nome do dispositivo; se não for renomeado, será exibido pelo front-end conforme as regras de exibição padrão. | | manufacturer | string | N | Fabricante | | model | string | N | Modelo do dispositivo | | firmware\_version | string | N | Versão do firmware. Pode ser uma string vazia. | | hostname | string | Y | Nome do host do dispositivo | | mac\_address | string | Y | Endereço mac do dispositivo | | app\_name | string | Y | O nome do aplicativo ao qual pertence. Se o app\_name for preenchido ao obter o certificado de interface aberta, então todos os dispositivos subsequentes conectados através do certificado serão escritos neste campo. | | display\_category | string | N | Categoria do dispositivo | | capabilities | CapabilityObject\[] | N | Capacidades do dispositivo | | protocol | string | "N" quando um dispositivo de terceiros está conectado, caso contrário "Y" | Protocolo do dispositivo: zigbee, onvif, rtsp, esp32-cam | | state | object | Y | Objeto de estado do dispositivo. Para exemplos de estado de diferentes capacidades, consulte 【Suporte a Capacidades do Dispositivo】 | | tags | object | Y | Formato JSON chave-valor, informações personalizadas do dispositivo. A função é a seguinte:- Usado para armazenar canais do dispositivo- Usado para armazenar unidades de temperatura- Informações personalizadas para outros dispositivos de terceiros | | online | boolean | N | Status online: True para onlineFalse é offline | | subnet | boolean | Y | Se está na mesma sub-rede que o gateway | CapabilityObject 💡Observação: Verifique os Exemplos de Capacidades de Dispositivo Suportadas em \[Supported Device Capabilities]. | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | capability | string | N | Nome da capacidade. Para detalhes, verifique \[Supported Device Capabilities] | | permission | string | N | Permissão da capacidade. Valores possíveis: "read" (somente leitura), "write" (gravável), "readWrite" (leitura e gravação). | | configuration | object | Y | Informações de configuração da capacidade. Atualmente usa-se camera-stream, verifique \[Supported Device Capabilities] | | name | string | Y | O campo name em toggle. O número do subcanal usado para identificar dispositivos multicanais. Por exemplo, se name for 1, significa canal 1. | :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ``` { "error": 0, "data":{ "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "My Device", "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. Atualizar Informações ou Estado Específico do Dispositivo Permite que usuários autorizados modifiquem as informações básicas do subdispositivo e emitam comandos de controle por meio desta interface. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Método**：PUT * **Cabeçalho**： * Content-Type: application/json * Autorization: Bearer ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- | | name | string | Y | Nome do dispositivo | | tags | object | Y | Formato JSON chave-valor, informações personalizadas do dispositivo. | | state | object | Y | Objeto de estado do dispositivo. Para exemplos de estado de diferentes capacidades, consulte \[Support Device Capabilities] | | configuration | object | Y | Informações de configuração da capacidade, atualmente apenas a capacidade camera\_stream suporta modificação. | Resposta de dados bem-sucedida: :::tips **Condições**: Os parâmetros da solicitação são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de Status: \*\*200 OK **Código de Erro**: * 110000 O subdispositivo/grupo correspondente ao id não existe ::: **Exemplo de resposta**: ``` { "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. Excluir Subdispositivo Permite que usuários autorizados excluam subdispositivos por meio desta interface. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Método**：DELETE * **Cabeçalho**： * Content-Type: application/json * Autorization: Bearer ::: Parâmetros da Solicitação: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Y | Nome do dispositivo. | | tags | object | Y | Pares chave-valor em formato JSON usados para armazenar nomes de canais do dispositivo e outras informações sobre subdispositivos. | | state | object | Y | Alterar status do dispositivo; para detalhes do protocolo, consulte "Supported Device Capabilities." | | capabilities | CapabilityObject \[] | Y | Informações de configuração da capacidade; todas as capacidades que suportam configuração podem ser modificadas. Observe que permissões não podem ser alteradas. | Resposta de dados bem-sucedida: :::tips **Condições**: Os parâmetros da solicitação são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de Status: \*\*200 OK **Códigos de Erro:** * 110000: O subdispositivo/grupo correspondente ao ID não existe. * 110006: Falha ao atualizar o status do dispositivo. * 110019: Falha ao acessar o endereço do serviço do dispositivo de terceiros. * 110024: Falha ao atualizar a configuração do dispositivo. ::: **Exemplo de resposta**: ``` { "error": 0, "data": {}, "message": "success" } ``` ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // ligar 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. Excluir Subdispositivo Permite que usuários autorizados excluam subdispositivos por meio desta interface.\ :::tips * **URL**：`/open-api/v2/rest/devices/{serial_number}` * **Método**：`DELETE` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da solicitação: Nenhum Resposta de dados bem-sucedida: :::tips **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### k. Consultar Status do Dispositivo Permite que usuários autorizados consultem o status do dispositivo por meio desta interface.\ :::tips * **URL**：`/open-api/v2/rest/devices/:serial_number/query-state/{capability}` * **Método**：POST * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------ | | query\_state | object | N | Consultar status do dispositivo; para detalhes do protocolo, consulte "Supported Device Capabilities." | ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // ligar 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 estatística, obrigatório "timeRange": { // Intervalo de tempo para sumarização, obrigatório quando type="summarize" "start": "2020-07-05T08:00:00Z", // Hora de início para estatísticas de consumo de energia "end": "2020-07-05T09:00:00Z" // Hora de término para estatísticas de consumo de energia; se omitido, usa-se por padrão o horário atual } } } }); })() ``` Resposta de dados bem-sucedida: :::tips **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.4 Gerenciamento de Segurança #### a. Obter Lista de Segurança Permite que usuários autorizados modifiquem configurações do gateway por meio desta interface. :::tips * **URL**：`/open-api/v2/rest/security` * **Método**：`GET` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da solicitação: Nenhum Resposta de dados bem-sucedida: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------- | ------------------------- | ------------ | --------------------------------- | | security\_list | ResponseSecurityObject\[] | N | Lista de dispositivos de resposta | ResponseDeviceObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------------ | | sid | int | N | id de segurança | | name | string | N | nome da segurança | | habilitar | bool | N | se está habilitado | * true Habilitado * false Desabilitado | :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": { "security_list":[ { "sid": 1, "name": "Home Mode", "enable": true } ] }, "message": "success" } ``` #### b. Habilitar Modo de Segurança Específico Permite que usuários autorizados habilitem um modo de segurança específico por meio desta interface.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/enable` * **Método**：`PUT` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da solicitação: Nenhum Resposta de dados bem-sucedida: Objeto vazio {} :::tips **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### c. Desabilitar Modo de Segurança Específico Permite que usuários autorizados desabilitem um modo de segurança específico por meio desta interface.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/disable` * **Método**：`PUT` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da solicitação: Nenhum Resposta de dados bem-sucedida: Objeto vazio {} :::tips **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Habilitar Configuração de Segurança com Um Clique Permite que usuários autorizados habilitem o modo de configuração de segurança com um clique por meio desta interface.\ :::tips * **URL**：`/open-api/v2/rest/security/enable` * **Método**：`PUT` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da solicitação: Nenhum Resposta de dados bem-sucedida: Objeto vazio {} :::tips **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### e. Desabilitar Segurança Permite que usuários autorizados desabilitem a segurança por meio desta interface.\ :::tips * **URL**：`/open-api/v2/rest/security/disable` * **Método**：`PUT` * **Cabeçalho**： * Content-Type: application/json * Authorization: Bearer ::: Parâmetros da solicitação: Nenhum Resposta de dados bem-sucedida: Objeto vazio {} :::tips **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\*200 OK ::: **Exemplo de resposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 4. Acesso de Dispositivo de Terceiros ### 4.1 Instrução de Acesso #### Acesso de Dispositivo
#### Acesso de gateway de terceiros
#### Etapas de acesso 1. Determine a classificação do dispositivo no gateway. Para mais detalhes, consulte \[Supported Device Type]. 2. Determine as capacidades que o dispositivo pode acessar. Para mais detalhes, consulte \[Supported Device Capabilities]. 3. Solicite a interface \[Discovery Request] para adicionar o dispositivo ao gateway. 1. *Atenção: Você precisa fornecer o endereço de serviço para receber as instruções emitidas pelo gateway, que é usado para receber as instruções de controle do dispositivo emitidas pelo gateway*. 4. Se o estado do dispositivo de terceiros mudar, você precisa chamar a interface \[Device States Change Report] para enviar o estado mais recente de volta ao gateway. 5. Após adicionar, o dispositivo de terceiros aparecerá na Lista de Dispositivos, com a maioria das funções do gateway (outros dispositivos não terceirizados). As interfaces abertas comuns relacionadas ao dispositivo podem ser usadas normalmente. * Selecione a categoria de dispositivo apropriada. A classificação afetará o resultado final exibido na UI após o dispositivo ser conectado ao gateway. * Escolha a capacidade de dispositivo correta. A lista de capacidades determinará o status do protocolo de estado do dispositivo. #### Processo do Programa **a. Acesso de Dispositivo**
**b. Acesso de Gateway de Terceiros**
### 4.2 Exemplo de Acesso #### Interruptor, Tomada **Sincronizar dispositivos de terceiros** ``` // Requisição URL：/open-api/v2/rest/thirdparty/event Método：POST Cabeçalho： Content-Type: application/json Autorization: Bearer Corpo: { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "2" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "my plug", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "1100" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "nome do fabricante", "model": "nome do modelo", "firmware_version": "versão do firmware", "service_address": "http://192.168.31.14/webhook" } ] } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number", "serial_number": "serial number" } ] } } ``` **Relatar status do dispositivo** ``` URL：/open-api/V2/rest/thirdparty/event Método：POST Cabeçalho： Content-Type: application/json Autorization: Bearer Corpo: { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": {} } ``` **Relatar offline/online** ``` {  "event": {    "header": {      "name": "DeviceStatesChangeReport",      "message_id": "Identificador único, preferencialmente um UUID versão 4",      "version": "1"   },    "endpoint": {      "serial_number": "serial_number"   },    "payload": {       "online": true   } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": {} } ``` **Receber as instruções sobre o controle do dispositivo pelo gateway** ``` URL： Método：POST Cabeçalho：  Content-Type: application/json B {  "directive": {    "header": {      "name": "UpdateDeviceStates",      "message_id": "Identificador único, preferencialmente um UUID versão 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, preferencialmente um UUID versão 4", "version": "1" }, "payload": {} } ``` **Consultar dispositivo** ``` URL：/open-api/V2/rest/devices Método：GET Cabeçalho：  Content-Type: application/json  Autorization: Bearer   Corpo: Nenhum ``` ``` { "error": 0, "data": { "device_list": [ { "serial_number": "serial number", "third_serial_number": "third_serial_number", "name": "my plug", "manufacturer": "nome do fabricante", "model": "nome do modelo", "firmware_version": "versão do firmware", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ] }, "message": "success" } ``` ### 4.3 API Web #### Interface de Solicitação de Gateway de Terceiros **Formato da Solicitação** Permite que usuários autorizados enviem solicitações de evento ao gateway por meio desta interface. :::tips * **URL**：/open-api/V2/rest/thirdparty/event * **Método**：POST * **Cabeçalho**： * Content-Type: application/json * Autorization: Bearer ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ----------- | ------------ | ----------------------------------------------------------- | | event | EventObject | N | Informações da estrutura do objeto de evento da solicitação | EventObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho da solicitação | | endpoint | EndpointObject | Y | Informações da estrutura do endpoint da solicitaçãoObservação: Este campo está vazio ao sincronizar uma nova lista de dispositivos. | | payload | PayloadObject | N | Informações da estrutura do payload da solicitação | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nome da solicitação. parâmetro opcional: DiscoveryRequest: Sincronizar novos dispositivos DeviceStatesChangeReport: Relatório de atualização de status do dispositivo DeviceOnlineChangeReport: Relatório de status online do dispositivo | | message\_id | string | N | ID da mensagem da solicitação, UUID\_V4 | | version | string | N | Número da versão do protocolo da solicitação. Atualmente fixo em 1 | EndpointObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | --------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de série único do dispositivo | | third\_serial\_number | string | N | Número de série único do dispositivo de terceiros | | tags | object | Y | Formato JSON chave-valor, informações personalizadas do dispositivo. \[Função de Gerenciamento de Dispositivos] - \[Descrição das Tags] | PayloadObject Conforme o header.name diferente, há diferentes estruturas de solicitação. **Formato da Resposta** :::tips \*\*Código de Status: \*\*200 OK **Parâmetros da resposta:** ::: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------- | ------------ | ------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho de resposta | | payload | PayloadObject | N | Informações da estrutura do payload de resposta | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nome do cabeçalho de resposta. parâmetros opcionais:Response: Resposta bem-sucedida ErrorResponse: Resposta de erro | | message\_id | string | N | ID da mensagem do cabeçalho de resposta, UUID\_V4. Passe aqui o header.message\_id da requisição \*Se o parâmetro de entrada da solicitação não contiver message\_id, este campo será uma string vazia na resposta. | | version | string | N | - Número da versão do protocolo da solicitação. Atualmente fixo em 1. | > Resposta bem-sucedida--PayloadObject ： Dependendo do tipo de solicitação, a estrutura da resposta é diferente. Para detalhes, consulte o documento de instrução da solicitação específica. > Resposta de falha--PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------- | | type | string | N | Tipos de Erro: | * INVALID\_PARAMETERS: Erro de parâmetro * AUTH\_FAILURE: Erro de autorização * INTERNAL\_ERROR: Erro interno do serviço | | descrição | string | N | Descrição do erro | **DiscoveryRequest Sincronizar uma nova lista de dispositivos** * Observação: Após o dispositivo ser sincronizado com o gateway, ele fica online por padrão, ou seja, online=true. Mudanças subsequentes de online dependem totalmente da sincronização com o terceiro através da interface DeviceOnlineChangeReport. **Parâmetros da solicitação:** EndpointObject\*\*：\*\*Nenhum PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ----------------- | ------------ | --------------------- | | endpoints | EndpointObject\[] | N | Lista de Dispositivos | EndpointObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | --------------------- | ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | third\_serial\_number | string | N | Número de série único do dispositivo de terceiros | | name | string | N | Nome do dispositivo | | display\_category | string | N | Categoria do Dispositivo. Veja \[Supported Device Type] para detalhes. \*Dispositivos de terceiros não suportam adicionar câmeras no momento. | | capabilities | CapabilityObject\[] | N | Lista de capacidades | | state | object | N | Informações de estado inicial | | manufacturer | string | N | Fabricante | | model | string | N | Modelo do dispositivo | | tags | object | Y | Formato JSON chave-valor, informações personalizadas do dispositivo:Usado para armazenar canais do dispositivoUsado para armazenar unidades de temperaturaOutros dados personalizados de terceiros | | firmware\_version | string | N | Versão do firmware | | service\_address | string | N | Endereço de serviço. Por exemplo | Exemplo de Solicitação : ``` { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "my plug", "display_category": "plug", "capabilities": [ { "capability": "power", "permission" "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "nome do fabricante", "model": "nome do modelo", "firmware_version": "versão do firmware", "service_address": "http://192.168.31.14/service_address" } ] } } } ``` **Parâmetros da resposta:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ----------------- | ------------ | --------------------- | | endpoints | EndpointObject\[] | N | Lista de dispositivos | EndpointObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | --------------------- | -------- | ------------ | ------------------------------------------------- | | serial\_number | string | N | Número de série único do dispositivo | | third\_serial\_number | string | N | Número de série único do dispositivo de terceiros | Exemplo de uma resposta correta: ``` { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "endpoints": [ { "serial_number": "serial number", "third_serial_number": "third_serial_number" } ] } } ``` Exemplo de uma resposta de erro: ``` { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "webhook cannot be empty" } } ``` **DeviceStatesChangeReport Relatório de alteração de status do dispositivo** * Observação: Relatórios de status repetidos podem acionar falsamente cenas associadas. **Parâmetros da solicitação:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ---------------------------------------------------------------------------- | | state | object | N | Estado do dispositivo, Consulte \[Supported device cabilities] para detalhes | Exemplo de Solicitação : ``` { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Parâmetros da resposta:** PayloadObject: Objeto Vazio Exemplo de resposta bem-sucedida: ``` { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": {} } ``` **DeviceOnlineChangeReport Relatório de status online do dispositivo** * Observação: Relatórios de status repetidos podem acionar falsamente cenas associadas. **Parâmetros da solicitação:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------- | -------- | ------------ | ----------------------------------------- | | online | boolean | N | Status online do dispositivo true: Online | | false: Offline | | | | Exemplo de Solicitação : ``` { "event": { "header": { "name": "DeviceOnlineChangeReport", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": true } } } ``` **Parâmetros da resposta:** PayloadObject: Objeto Vazio Exemplo de resposta bem-sucedida: ``` { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": {} } ``` **DeviceInformationUpdatedReport Relatório de Atualização de Informações do Dispositivo** * Observação: Atualizar pode afetar cenas existentes ou funções de segurança. **Parâmetros da solicitação:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------- | | capabilities | | | | \| CapabilityObject\[] \| N \| Lista de Capacidades. Detalhes podem ser encontrados na seção de capacidades de dispositivo suportadas. \*\*Observação: \*\*Este parâmetro irá apenas atualizar o `campo value` do `ajuste` chave dentro do `CapabilityObject`, e atualizações são permitidas apenas se o `permission` para a `ajuste` chave for `11` ou `01`. Para a definição de estrutura específica do `ajuste` em `CapabilityObject`, consulte a descrição detalhada na seção 2.3 Categorias de Exibição de Dispositivo & Capacidades do Dispositivo. | | tags \| object \| Y \| Formato JSON chave-valor, informações personalizadas do dispositivo. * Pode ser usado para armazenar canais do dispositivo * Pode ser usado para armazenar unidades de temperatura * Outros dados personalizados de terceiros | Exemplo de Solicitação : ```json { "event": { "header": { "name": "DeviceInformationUpdatedReport", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "capabilities": [ { "capability": "detect", "permission": "0110", "settings":{ "detectInterval":{ "permission": "11", "type": "numeric", "value": 300, }, "detectSensitivity":{ "permission": "11", "type": "numeric", "value": 1000, } } } ] } } } ``` **parâmetros de resposta:** PayloadObject: Objeto Vazio Exemplo de resposta bem-sucedida: ```json { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "2" }, "payload": {} } ``` #### O gateway envia a interface de instrução através do endereço de serviço do dispositivo * Observação: 1. As três partes precisam responder à solicitação do gateway dentro de 3s. Caso contrário, o gateway julgará o tempo de processamento do comando expirado. 2. Se o serviço de terceiros estiver offline, o gateway definirá o dispositivo como offline, e o serviço de terceiros precisa relatar o estado do dispositivo (DeviceStatesChangeReport) ou o estado online (DeviceOnlineChangeReport) antes de retornar ao estado online. **Formato da solicitação** O gateway envia instruções ao terceiro por meio da interface de endereço de serviço do dispositivo. :::tips * **URL**： * **Método**：POST * **Cabeçalho**： * Content-Type: application/json ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | --------------- | ------------ | ------------------------------------------- | | directive | DirectiveObject | N | Informações da estrutura do objeto diretiva | DirectiveObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------------- | ------------ | ---------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho da solicitação | | endpoint | EndpointObject | N | Informações da estrutura do endpoint da solicitação | | payload | PayloadObject | N | Informações da estrutura do payload da solicitação | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------- | | name | string | N | Nome da solicitação. Parâmetros opcionais:UpdateDeviceStates: Atualizar estados do dispositivo | | message\_id | string | N | ID da mensagem da solicitação, UUID\_V4 | | version | string | N | Número da versão do protocolo da solicitação. Atualmente fixo em 1. | EndpointObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | --------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de série único do dispositivo | | third\_serial\_number | string | N | Número de série único do dispositivo de terceiros | | tags | object | N | Formato JSON chave-valor, informações personalizadas do dispositivo. \[Função de Gerenciamento de Dispositivos] - \[Descrição das Tags] | PayloadObject: Conforme diferentes `header.name`, há uma estrutura de solicitação específica para cada um. Exemplo de Solicitação : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", "tags": {} }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Formato da resposta** :::tips \*\*Código de Status HTTP: \*\*200 OK **Atributo de Resposta HTTP：** ::: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ----------- | ------------ | ---------------------------------------------- | | event | EventObject | N | Informações da estrutura do evento de resposta | EventObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------- | ------------ | ---------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho da solicitação | | payload | PayloadObject | N | Informações da estrutura do payload da solicitação | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nome do cabeçalho de resposta. Parâmetro opcional: UpdateDeviceStatesResponse: Resposta de atualização de estados do dispositivo ErrorResponse: Resposta de erro | | message\_id | string | N | ID da mensagem do cabeçalho de resposta, UUID\_V4. Passe aqui o header.message\_id da solicitação | | version | string | N | Número da versão do protocolo da solicitação. Atualmente fixo em 1. | > Resposta bem-sucedida--PayloadObject： Dependendo do tipo de solicitação, a estrutura da resposta é diferente. Para detalhes, consulte o documento de instrução da solicitação específica. > Resposta de falha--PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------------ | | type | string | N | **Tipos de Erro**: | * **ENDPOINT\_UNREACHABLE**: Dispositivo inalcançável ou offline * **ENDPOINT\_LOW\_POWER**: Dispositivo em modo de baixa energia e não pode ser controlado * **INVALID\_DIRECTIVE**: Diretiva anormal do gateway * **NO\_SUCH\_ENDPOINT**: Dispositivo não existe * **NOT\_SUPPORTED\_IN\_CURRENT\_MODE**: O modo atual não suporta a operação * **INTERNAL\_ERROR**: Erro interno do serviço * **REMOTE\_KEY\_CODE\_NOT\_LEARNED**: Código de tecla do controle remoto não aprendido | :::dicas **Condições**: Os parâmetros da solicitação são legais. \*\*Código de Status: \*\*200 OK **Parâmetros da resposta:** ::: ``` { "event": { "header": { "name": "UpdateDeviceStatesResponse", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": {} } } ``` ``` { "event": { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "type": "ENDPOINT_UNREACHABLE" } } } ``` **UpdateDeviceStates** **Parâmetros da solicitação:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ----------------------------------------------------------------------------- | | state | object | N | Estado do dispositivo, Consulte \[Supported device cabilities] para detalhes. | Exemplo de Solicitação : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": : { "power": { "powerState": "on" } } } } } ``` **Parâmetros da resposta:** PayloadObject：Objeto vazio Exemplo de Resposta Bem-sucedida ``` { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": {} } ``` **QueryDeviceStates** **Parâmetros da solicitação:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ----------------------------------------------------------------------------- | | state | object | N | Estado do dispositivo, Consulte \[Supported device cabilities] para detalhes. | Exemplo de Solicitação : ```json { "directive": { "header": { "name": "QueryDeviceStates", "message_id": "Identificador único, preferencialmente um UUID versão 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 início para estatísticas de consumo de energia, obrigatório. "end": "2020-07-05T09:00:00Z" // Hora de término para estatísticas de consumo de energia, obrigatório. } } } } } } ``` **Parâmetros da resposta:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ----------------------------------------------------------------------------- | | state | object | N | Estado do dispositivo, Consulte \[Supported device cabilities] para detalhes. | **Exemplo de resposta:** ```json { "event": { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "2" }, "payload": { "state": { "power-consumption": { "electricityIntervals": [ // Dividido em vários registros com base em configuration.resolution { "usage": 26.5, // Valor de consumo de energia, obrigatório. Tipo: number. "start": "2020-07-05T08:00:00Z", // Hora de início, obrigatório. Tipo: date. "end": "2020-07-05T09:00:00Z" // Hora de término, obrigatório. Tipo: date. Se o intervalo entre end e start for menor que resolution, todos os registros relatados são considerados inválidos. }, { "usage": 26.5, // Valor de consumo de energia, obrigatório. Tipo: number. "start": "2020-07-05T09:00:00Z", // Hora de início, obrigatório. Tipo: date. "end": "2020-07-05T10:00:00Z" // Hora de término, obrigatório. Tipo: date. Se o intervalo entre end e start for menor que resolution, todos os registros relatados são considerados inválidos. } ] } } } } } ``` **ConfigureDeviceCapabilities** **Parâmetros da solicitação:** PayloadObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | capabilities | CapabilityObject\[] | N | Lista de capacidades. Detalhes podem ser vistos na seção de capacidades de dispositivo suportadas. Observe que o campo permission não pode ser alterado, passe o mesmo valor ao sincronizar. | Exemplo de Solicitação : ```json { "directive": { "header": { "name": "ConfigureDeviceCapabilities", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "2" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Tipo de detecção de controle de temperatura, obrigatório. Valores opcionais: humidity (detecção de umidade), temperature (detecção de temperatura) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Configurações de detecção suportadas, obrigatório. { "name": "lowerSetpoint", // Valor mínimo que a detecção deve manter. Deve ser fornecido lowerSetpoint ou upperSetpoint. "value": { // Faixa de detecção, opcional. Preencha se houver condições pré-definidas. "value": 68.0, // Valor de temperatura ou umidade, obrigatório. "scale": "f" // Unidade de temperatura, obrigatório se name=temperature. Opções: c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Valor máximo que a detecção deve manter. Deve ser fornecido lowerSetpoint ou upperSetpoint. "value": { // Faixa de detecção, opcional. Preencha se houver condições pré-definidas. "value": 68.0, // Valor de temperatura ou umidade, obrigatório. "scale": "f" // Unidade de temperatura, obrigatório se name=temperature. Opções: c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } } ``` **Parâmetros da resposta:** PayloadObject：Objeto vazio Exemplo de Resposta Bem-sucedida ```json { "event": { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "2" }, "payload": {} } } ``` ## 5. Eventos enviados pelo servidor > Descrição da interface MDN EventSource： ### 5.1 Instrução O gateway suporta empurrar mensagens para o cliente usando SSE (Server-sent events). O cliente pode monitorar mensagens SSE após obter as credenciais de acesso e pode analisar o conteúdo das mensagens push de acordo com o protocolo de notificação de eventos da interface de desenvolvimento após receber as mensagens enviadas pelo gateway. Deve-se notar que o gateway atualmente usa o protocolo HTTP1.1, portanto o SSE no lado do navegador terá um limite máximo de no máximo 6 conexões (instruções específicas podem ser encontradas na descrição da interface MDN EventSource.) ### 5.2 Formato Comum :::dicas * **URL**：/open-api/V2/sse/bridge * **Método**：`GET` ::: Parâmetros da solicitação: | Nome | Tipo | Opcional | Descrição | | ------------- | ------ | -------- | --------------- | | access\_token | string | N | Token de Acesso | Observação: Ao solicitar uma conexão SSE, o gateway verificará o access\_token, e retornará um erro de falha de autenticação se for inválido. { "error": 401, "data": {}, "message": "invalid access\_token"} > \## Por exemplo: Nome do Módulo: device Versão: 1,v2,v3 Tipo de Mensagem: addDevice Exemplo: ```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 Adicionar Dispositivo :::tips Nome do Módulo：device Versão：v2 Tipo de Mensagem：addDevice event.data parâmetros： ::: | Nome | Tipo | Opcional | Descrição | | ------- | -------------------------------------------------------------------------- | -------- | -------------------------- | | payload | ResponseDeviceObjectObject - Interface igual à Obter Lista de Dispositivos | N | informações do dispositivo | Exemplo: ```json // event.data { "payload": { "serial_number": "ABCDEFGHIJK", "third_serial_number": "third_serial_number", "name": "Mydevice", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "1100" }, { "capability": "rssi", "permission": "0100" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } } ``` #### b. Evento Atualizar Estado do Dispositivo :::tips Nome do Módulo：device Versão：v2 Tipo de Mensagem：updateDeviceState event.data parâmetros： ::: | Nome | Tipo | Opcional | Descrição | | -------- | ------------------------------------------------ | -------- | ------------------------------ | | endpoint | EndpointObject | N | Informações do Dispositivo | | payload | object。 Estrutura igual ao estado do dispositivo | N | Dados de Status do Dispositivo | EndpointObject: | Parâmetro | Tipo | Opcional | Descrição | | --------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de Série único do Dispositivo | | third\_serial\_number | string | Y | O número de série único do dispositivo de terceiros. Para dispositivos conectados por interfaces abertas, este campo é obrigatório. | Exemplo: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "power": { "powerState": "on" }, "brightness": { "brightness": 100 } } } ``` #### c. Evento Atualizar Informações do Dispositivo :::tips Nome do Módulo：device Versão：v2 Tipo de Mensagem：updateDeviceInfo event.data parâmetros： ::: | Nome | Tipo | Opcional | Descrição | | -------- | ------------------ | -------- | --------------------------------- | | endpoint | EndpointObject | N | Informações do Dispositivo | | payload | DeviceChangeObject | N | Dados de Alteração do Dispositivo | EndpointObject: | Atributo | Tipo | Opcional | Descrição | | --------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de Série único do Dispositivo | | third\_serial\_number | string | Y | O número de série único do dispositivo de terceiros. Para dispositivos conectados por interfaces abertas, este campo é obrigatório. | DeviceChangeObject | Nome | Tipo | Opcional | Descrição | | ------------ | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | name | string | N | Nome do Dispositivo | | capabilities | CapabilityObject \[] | Y | Lista de capacidades do dispositivo. | | tags | object | Y | **tags**`object` \| Nullable \| Pares chave-valor em formato JSON para informações personalizadas do dispositivo. | * Pode ser usado para armazenar canais do dispositivo. * Pode ser usado para armazenar unidades de temperatura. * Para outros dados personalizados de terceiros. | Exemplo: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "name": "nome do dispositivo", "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Tipo de detecção de controle de temperatura, obrigatório. Valores opcionais: humidity (detecção de umidade), temperature (detecção de temperatura) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Configurações de detecção suportadas, obrigatório. { "name": "lowerSetpoint", // Valor mínimo que a detecção deve manter. Deve ser fornecido lowerSetpoint ou upperSetpoint. "value": { // Faixa de detecção, opcional. Preencha se houver condições pré-definidas. "value": 68.0, // Valor de temperatura ou umidade, obrigatório. "scale": "f" // Unidade de temperatura, obrigatório se name=temperature. Opções: c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Valor máximo que a detecção deve manter. Deve ser fornecido lowerSetpoint ou upperSetpoint. "value": { // Faixa de detecção, opcional. Preencha se houver condições pré-definidas. "value": 68.0, // Valor de temperatura ou umidade, obrigatório. "scale": "f" // Unidade de temperatura, obrigatório se name=temperature. Opções: c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } ``` #### d. Evento Excluir Dispositivo :::tips Nome do Módulo：device Versão：v2 Tipo de Mensagem：deleteDevice event.data parâmetros： ::: | \*\* Nome \*\* | \*\* Tipo \*\* | \*\* Opcional\*\* | \*\* Descrição \*\* | | -------------- | -------------- | ----------------- | -------------------------- | | endpoint | EndpointObject | N | Informações do Dispositivo | EndpointObject: | Atributo | Tipo | Opcional | Descrição | | --------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de Série único do Dispositivo | | third\_serial\_number | string | Y | O número de série único do dispositivo de terceiros. Para dispositivos conectados por interfaces abertas, este campo é obrigatório. | Exemplo: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" } } ``` #### e. Evento Atualizar Online do Dispositivo :::tips Nome do Módulo：device Versão：v2 Tipo de Mensagem：updateDeviceOnline event.data parâmetros： ::: | Nome | Tipo | Opcional | Descrição | | -------- | ------------------ | -------- | --------------------------------- | | endpoint | EndpointObject | N | Informações do Dispositivo | | payload | DeviceChangeObject | N | Dados de Alteração do Dispositivo | EndpointObject: | Atributo | Tipo | Opcional | Descrição | | --------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Número de Série único do Dispositivo | | third\_serial\_number | string | Y | O número de série único do dispositivo de terceiros. Para dispositivos conectados por interfaces abertas, este campo é obrigatório. | DeviceChangeObject | Nome | Tipo | Opcional | Descrição | | ------ | ------- | -------- | ---------------------------- | | online | boolean | N | Status Online do Dispositivo | Exemplo: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": false } } ``` ### 5.4 Módulo Gateway #### a. Evento de Atualização do Estado de Segurança :::tips Nome do Módulo：device Versão：v2 Tipo de Mensagem：updateDeviceOnline event.data parâmetros： ::: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------------- | ------------ | -------------------------- | | payload | SecurityStateObject | N | Informações do Dispositivo | SecurityStateObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------- | | alarm\_state | string | N | | * `arming` | Armado * `disarming` | Desarmado | Exemplo: ```json // event.data { "payload": { "alarm_state": "alarming" } } ``` ### 5.5 Módulo de Segurança #### a. Evento de Atualização do Estado de Armamento :::tips Nome do Módulo：device Versão：v2 Tipo de Mensagem：updateDeviceOnline event.data parâmetros： ::: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------------- | ------------ | --------------------------------------- | | payload | ArmStateObject | N | informações de armamento e desarmamento | ArmStateObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------- | | arm\_state | string | N | | * `arming` | Armado * `disarming` | Desarmado | | detail | DetailObject | N | Detalhes de armamento/desarmamento | DetailObject： | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ----------------------- | | sid | int | N | id do modo de segurança | | name | string | N | nome da segurança | Exemplo ```json // event.data { "payload": { "arm_state": "arming", "detail": { "sid": 1, "name": "Home Mode" } } } ``` ## 6. TTS (**Função do mecanismo de Texto-para-Fala** ### 6.1 Instrução #### Papel-chave * Provedor de Serviço TTS: O provedor do serviço de mecanismo TTS é responsável por registrar o mecanismo TTS no gateway e fornecer serviços TTS * Servidor Gateway：iHost * Cliente da API Aberta do Gateway #### 6.1.1 Registro do Serviço do Mecanismo TTS 1. 【Provedor de Serviço TTS】Chame a interface para registrar o mecanismo TTS no gateway. 2. 【Servidor Gateway】Após o registro bem-sucedido, o gateway armazenará as informações básicas do mecanismo TTS (incluindo o endereço de serviço server\_address, e a comunicação subsequente entre o gateway e o Provedor de Serviço TTS será realizada através do endereço server\_address), e alocará o ID do serviço do mecanismo TTS dentro do gateway.
#### 6.1.2 Obter a Lista de Áudios Sintetizados 1. 【Cliente da API Aberta do Gateway】Chame a interface para obter a lista de serviços de mecanismo TTS registrados. Você pode obter a lista atual de mecanismos TTS registrados (incluindo o ID do mecanismo TTS alocado pelo gateway). 2. 【Cliente da API Aberta do Gateway】Chame a interface para obter a lista de áudio de um mecanismo TTS especificado. O gateway emitirá uma instrução síncrona de lista de áudio para o Provedor de Serviço TTS especificado e retornará o resultado.
#### 6.1.3 Síntese de Fala especificando um Mecanismo de Fala 1. 【Cliente da API Aberta do Gateway】Chame a interface para obter a lista de serviços de mecanismo TTS registrados. Você pode obter a lista atual de mecanismos TTS registrados (incluindo o ID do mecanismo TTS alocado pelo gateway). 2. 【Cliente da API Aberta do Gateway】Chame a interface para obter a lista de áudio de um mecanismo TTS especificado. O gateway emitirá uma instrução síncrona de lista de áudio para o Provedor de Serviço TTS especificado e retornará o resultado.
#### 6.1.4 Sintetizar Áudio e Reproduzir Fala TTS. 1. 【Cliente da API Aberta do Gateway】Chame a interface para obter a lista de serviços de mecanismo TTS registrados. Você pode obter a lista atual de mecanismos TTS registrados (incluindo o ID do mecanismo TTS alocado pelo gateway). 2. 【Cliente da API Aberta do Gateway】Chame a interface para obter a lista de áudio de um mecanismo TTS especificado. O gateway emitirá uma instrução síncrona de lista de áudio para o Provedor de Serviço TTS especificado e retornará o resultado. (incluindo o endereço do arquivo de áudio TTS) 3. 【Cliente da API Aberta do Gateway】Registre o endereço do arquivo de áudio TTS a partir do resultado retornado na etapa anterior, chame a interface de reproduzir arquivo de áudio e reproduza-o através do gateway. ### 6.2 Módulo do Mecanismo TTS #### 6.2.1 Capacidades Abertas do Gateway **a. Obter a lista de serviços de mecanismo TTS registrados** :::dicas * **URL**：`/open-api/V2/rest/tts/engines` * **Método**：`GET` * **Cabeçalho**： * Content-Type: application/json * Autorização: Bearer ::: Parâmetros da Solicitação: nenhum Resposta de dados correta: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ---------------- | ------------ | ----------------------------------- | | engines | EngineObject \[] | N | Lista de mecanismos TTS registrados | Estrutura do EngineObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------------------------------- | | id | string | N | ID do mecanismo atribuído pelo gateway | | name | string | N | Nome do serviço do mecanismo TS | :::dicas Condições: Os parâmetros da solicitação são legais e a verificação da identidade do usuário foi aprovada. \*\*Código de Status: \*\*`200 OK` **Exemplo de Resposta:**： ::: ```json { "error": 0, "data": { "engines": [ { "id": "engine id", "name": "engine name" } ] }, "message": "success" } ``` **b. Obter lista de áudio de um mecanismo TTS especificado** :::dicas * **URL**：`/open-api/V2/rest/tts/engine/{id}/audio-list` * **Método**：`GET` * **Cabeçalho**： * Content-Type: application/json * Autorização: Bearer ::: Parâmetros da Solicitação: nenhum Resposta de dados correta: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | --------------- | ------------ | -------------- | | audio\_list | AudioObject \[] | N | Lista de áudio | Estrutura do AudioObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------------------------------------------------- | -------- | ------------ | ------------------------------------- | | url | string | N | URL do arquivo de áudio, por exemplo: | | | | | | | label | string | Y | Rótulo do arquivo de áudio | :::dicas Condições: Os parâmetros da solicitação são legais e a verificação da identidade do usuário foi aprovada. \*\*Código de Status: \*\*`200 OK` \*\*Código de Erro: \*\* * 190000 O mecanismo está com funcionamento anormal **Exemplo de Resposta:**： ::: ```json { "error": 0, "data": { "audio_list": [ { "url": "endereço do áudio tts", // por exemplo: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "rótulo do áudio tts" } ] }, "message": "success" } ``` **c .Realizar síntese de fala usando o mecanismo TTS especificado** :::dicas * **URL**：`/open-api/V2/rest/tts/engine/{id}/synthesize` * **Método**：`POST` * **Cabeçalho**： * Content-Type: application/json * Autorização: Bearer ::: Parâmetros da Solicitação: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Texto usado para sintetizar o áudio | | label | string | Y | Rótulo do arquivo de áudio | | language | string | Y | Campo transparente. Código de idioma opcional para a solicitação de síntese de fala. A lista específica de códigos de idioma suportados é fornecida pelo provedor do serviço de mecanismo TTS. Observe que o serviço do mecanismo TTS precisa suportar um idioma padrão para síntese de fala, o que significa que, se o idioma não for informado, o idioma padrão do mecanismo será usado para a síntese. | | options | object | Y | Campo transparente. Ele é usado para passar os parâmetros de configuração necessários para a síntese ao serviço do mecanismo de fala TTS. | Resposta de dados correta: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ----------- | ------------ | -------------- | | audio | AudioObject | N | Lista de áudio | Estrutura do AudioObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------------------------------------------------- | -------- | ------------ | ------------------------------------- | | url | string | N | URL do arquivo de áudio, por exemplo: | | | | | | | label | string | Y | Rótulo do arquivo de áudio | :::dicas Condições: Os parâmetros da solicitação são legais e a verificação da identidade do usuário foi aprovada. \*\*Código de Status: \*\*`200 OK` \*\*Código de Erro: \*\* * 190000 O mecanismo está com funcionamento anormal **Exemplo de Resposta:**： ::: ```json { "error": 0, "data": { "audio": { "url": "endereço do áudio tts" // por exemplo, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "rótulo do áudio tts" } }, "message": "success" } ``` #### 6.2.2 Comunicação Entre Gateway e Serviço TTS **a. Registro do serviço do mecanismo TTS** > Enviar solicitação ao gateway pelo Provedor de Serviço TTS :::dicas * **URL**：`/open-api/V2/rest/thirdparty/event` * **Método**：`POST` * **Cabeçalho**： * Content-Type: application/json * Autorização: Bearer ::: Parâmetros da Solicitação: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ----------- | ------------ | ----------------------------------------------------------- | | event | EventObject | N | Informações da estrutura do Objeto de Evento de Solicitação | EventObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------- | ------------ | ---------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho da solicitação | | payload | PayloadObject | N | Informações da estrutura do payload da solicitação | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ---------------------------------------- | | name | string | N | Nome da solicitação. Parâmetro opcional. | * RegisterTTSEngine | | message\_id | string | N | ID da mensagem da solicitação, UUID\_V4 | | version | string | N | Número da versão do protocolo de solicitação. Atualmente fixo em 1 | PayloadObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ---------------- | -------- | ------------ | ------------------------------------------- | | service\_address | string | N | Endereço do Serviço. Por exemplo, http\:/// | | name | string | N | Nome do serviço | Exemplo de Solicitação: ```json { "event": { "header": { "name": "RegisterTTSEngine", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "service_address": "service_address", "name": "nome do serviço tts" } } } ``` \*\*Parâmetros de resposta corretos: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------- | ------------ | ---------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho da solicitação | | payload | PayloadObject | N | Informações da estrutura do payload da solicitação | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------------------------------------------- | | name | string | N | Nome do cabeçalho de resposta. Parâmetro opcional: | * Resposta (Resposta bem-sucedida) * ErrorResponse (Resposta de erro) | | message\_id | string | N | ID da mensagem do cabeçalho de resposta, UUID\_V4. Mensagem de solicitação recebida aqui: header.message\_id | | version | string | N | Número da versão do protocolo de solicitação. Atualmente fixo em 1 | PayloadObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------------------------------- | | engine\_id | string | N | ID do mecanismo atribuído pelo gateway | :::dicas Condições: Os parâmetros da solicitação são legais e a verificação da identidade do usuário foi aprovada. \*\*Código de Status: \*\*`200 OK` **Exemplo de Resposta:**： ::: Exemplo de Resposta Correta： ```json { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "engine_id": "engine id" } } ``` \*\*Parâmetros de resposta anormais: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------- | | type | string | N | Tipo de Erro | * INVALID\_PARAMETERS (Parâmetros inválidos) * AUTH\_FAILURE (Falha de autenticação) * INTERNAL\_ERROR (Erro interno do serviço) | | description | string | N | Descrição do erro | Exemplo de Resposta de Erro： ```json { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address cannot be empty" } } ``` **b. Comando de sincronização da lista de áudio** > Enviar comando ao Provedor de Serviço TTS pelo gateway. :::dicas * **URL**：`` * **Método**：`POST` * **Cabeçalho**： * Content-Type: application/json ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | --------------- | ------------ | ----------------------------------------------- | | directive | DirectiveObject | N | Informações da estrutura do objeto de instrução | DirectiveObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------- | ------------ | ---------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho da solicitação | | payload | PayloadObject | N | Informações da estrutura do payload da solicitação | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ---------------------------------------- | | name | string | N | Nome da solicitação. Parâmetro opcional: | * SyncTTSAudioList | | message\_id | string | N | ID da mensagem da solicitação, UUID\_V4 | | version | string | N | Número da versão do protocolo de solicitação. Atualmente fixo em 1 | Exemplo de Solicitação: ```json { "directive": { "header": { "name": "SyncTTSAudioList", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": {} } } ``` \*\*Parâmetros de resposta corretos: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------- | ------------ | ---------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho da solicitação | | payload | PayloadObject | N | Informações da estrutura do payload da solicitação | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------------------------------------------- | | name | string | N | Nome do cabeçalho de resposta. Parâmetro opcional: | * Resposta (Resposta bem-sucedida) * ErrorResponse (Resposta de erro) | | message\_id | string | N | ID da mensagem do cabeçalho de resposta, UUID\_V4. Mensagem de solicitação recebida aqui: header.message\_id | | version | string | N | Número da versão do protocolo de solicitação. Atualmente fixo em 1 | PayloadObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | --------------- | ------------ | ------------------ | | audio\_list | AudioObject \[] | N | Lista de Áudio TTS | Estrutura do AudioObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------------------------------------------------- | -------- | ------------ | ------------------------------------- | | url | string | N | URL do arquivo de áudio, por exemplo: | | | | | | | label | string | Y | Rótulo do arquivo de áudio | :::dicas Condições: Os parâmetros da solicitação são legais e a verificação da identidade do usuário foi aprovada. \*\*Código de Status: \*\*`200 OK` **Exemplo de Resposta:**： ::: Exemplo de Resposta Correta： ```json { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "audio_list": [ { "url": "url do áudio tts", "label": "rótulo do áudio tts" } ] } } ``` \*\*Parâmetros de resposta anormais: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------- | | type | string | N | Tipo de Erro | * INVALID\_PARAMETERS (Parâmetros inválidos) * AUTH\_FAILURE (Falha de autenticação) * INTERNAL\_ERROR (Erro interno do serviço) | | description | string | N | Descrição do erro | Exemplo de Resposta de Erro： ```json { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address cannot be empty" } } ``` **c. Comando de síntese de fala** > Enviar comando ao Provedor de Serviço TTS pelo gateway. :::dicas * **URL**：`` * **Método**：`POST` * **Cabeçalho**： * Content-Type: application/json ::: Parâmetros da requisição: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | --------------- | ------------ | ----------------------------------------------- | | directive | DirectiveObject | N | Informações da estrutura do objeto de instrução | DirectiveObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------- | ------------ | ---------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho da solicitação | | payload | PayloadObject | N | Informações da estrutura do payload da solicitação | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ---------------------------------------- | | name | string | N | Nome da solicitação. Parâmetro opcional: | * SynthesizeSpeech | | message\_id | string | N | ID da mensagem da solicitação: UUID\_V4 | | version | string | N | Número da versão do protocolo de solicitação. Atualmente fixo em 1 | PayloadObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Texto usado para sintetizar o áudio | | label | string | Y | Rótulo do arquivo de áudio | | language | string | Y | Campo transparente. Código de idioma opcional para a solicitação de síntese de fala. A lista específica de códigos de idioma suportados é fornecida pelo provedor do serviço de mecanismo TTS. Observe que o serviço do mecanismo TTS precisa suportar um idioma padrão para síntese de fala, o que significa que, se o idioma não for informado, o idioma padrão do mecanismo será usado para a síntese. | | options | object | Y | Campo transparente. Ele é usado para passar os parâmetros de configuração necessários para a síntese ao serviço do mecanismo de fala TTS. | Exemplo de Solicitação: ```json { "directive": { "header": { "name": "SynthesizeSpeech", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "text": "Texto de entrada para sintetizar.", "label": "rótulo do áudio tts" } } } ``` \*\*Parâmetros de resposta corretos: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------- | ------------ | ---------------------------------------------------- | | header | HeaderObject | N | Informações da estrutura do cabeçalho da solicitação | | payload | PayloadObject | N | Informações da estrutura do payload da solicitação | HeaderObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------------------------------------------- | | name | string | N | Nome do cabeçalho de resposta. Parâmetro opcional: | * Resposta (Resposta bem-sucedida) * ErrorResponse (Resposta de erro) | | message\_id | string | N | ID da mensagem do cabeçalho de resposta, UUID\_V4. Mensagem de solicitação recebida aqui: header.message\_id | | version | string | N | Número da versão do protocolo de solicitação. Atualmente fixo em 1 | PayloadObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ----------- | ------------ | ------------- | | audio | AudioObject | N | Áudio TTS | Estrutura do AudioObject | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------------------------------------------------- | -------- | ------------ | ------------------------------------- | | url | string | N | URL do arquivo de áudio, por exemplo: | | | | | | | label | string | Y | Rótulo do arquivo de áudio | :::dicas Condições: Os parâmetros da solicitação são legais e a verificação da identidade do usuário foi aprovada. \*\*Código de Status: \*\*`200 OK` **Exemplo de Resposta:**： ::: Exemplo de Resposta Correta： ```json { "header": { "name": "Response", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "audio": { "url": "url do áudio tts", "label": "rótulo do áudio tts" } } } ``` \*\*Parâmetros de resposta anormais: \*\* | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------- | | type | string | N | Tipo de Erro | * INVALID\_PARAMETERS (Parâmetros inválidos) * AUTH\_FAILURE (Falha de autenticação) * INTERNAL\_ERROR (Erro interno do serviço) | | description | string | N | Descrição do erro | Exemplo de Resposta de Erro： ```json { "header": { "name": "ErrorResponse", "message_id": "Identificador único, preferencialmente um UUID versão 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address cannot be empty" } } ``` ## 7. Módulo Multimídia ### 7.1 Reproduzir Arquivo de Áudio :::dicas * **URL**：`/open-api/V2/rest/media/audio-player` * **Método**：`POST` * **Cabeçalho**： * Content-Type: application/json * Autorização: Bearer ::: Parâmetros da Solicitação: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | --------------------- | | audio\_url | string | N | Endereço URL do áudio | Resposta de dados correta: :::dicas Condições: Os parâmetros da solicitação são legais e a verificação da identidade do usuário foi aprovada. \*\*Código de Status: \*\*`200 OK` **Exemplo de Resposta:**： ::: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 8. Cartão de IU Personalizado Cartões de IU personalizados permitem exibir qualquer conteúdo desejado dentro do cartão. Esse conteúdo pode ser uma página da web, uma imagem ou qualquer serviço com interface do usuário. Você só precisa fornecer a URL do conteúdo que deseja exibir. O cartão de IU ajustará automaticamente sua largura e altura, e o conteúdo será renderizado usando um iFrame. ### 8.1 Instrução #### Papel-chave * **Provedor de Serviço de IU**: O provedor responsável por criar cartões de IU personalizados no gateway. * **Servidor Gateway**: O servidor gateway (iHost). * **Cliente da API Aberta do Gateway**: O cliente Open API para o gateway. #### 8.1.1 Criando um Cartão de IU Personalizado * **\[Provedor de Serviço de IU]**: Chama a API para criar um cartão de IU personalizado no gateway. * **\[Servidor Gateway]**: Após o registro bem-sucedido, o gateway armazena as informações básicas do cartão de IU (incluindo configuração de tamanho e URL do recurso do cartão) e atribui um ID interno do cartão de IU dentro do gateway.
#### 8.1.2 Recuperando a Lista de Cartões de IU * **\[Provedor de Serviço de IU]**: Chama a API para recuperar a lista de cartões de IU. * **\[Servidor Gateway]**: Retorna a lista de cartões de IU armazenados no gateway, incluindo cartões de IU personalizados não criados pelo chamador.
#### 8.1.3 Modificando a Configuração de um Cartão de IU Especificado * **\[Provedor de Serviço de IU]**: Chama a API para modificar a configuração de um cartão de IU especificado, como a configuração de tamanho e URL do recurso. * **\[Servidor Gateway]**: Após a modificação bem-sucedida, o gateway armazena as informações atualizadas do cartão de IU, incluindo a nova configuração de tamanho e URL do recurso.
#### 8.1.4 Excluindo um Cartão de IU Personalizado 1. **\[Provedor de Serviço de IU]**: Chama a API para excluir um cartão de IU personalizado especificado. 2. **\[Servidor Gateway]**: O gateway removerá todas as informações relacionadas ao cartão de IU especificado.
### 8.2 Módulo de Cartão de IU Personalizado #### 8.2.1 Criando um Cartão de IU Personalizado > O Provedor de Serviço de IU envia uma solicitação ao gateway para criar um cartão de IU personalizado. :::dicas * **URL**：`/open-api/v2/rest/ui/cards` * **Método**：`POST` * **Cabeçalho**： * Content-Type: application/json * Autorização: Bearer ::: Parâmetros da Solicitação: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------- | ------------------ | ------------ | ------------------------------------------------------------------------------ | | label | string | Y | Rótulo do Cartão: Usado para descrever o cartão. É o apelido do cartão. | | cast\_settings | CastSettingsObject | Y | Configurações do Cartão Cast: Configurações de configuração para cartões cast. | | web\_settings | WebSettingsObject | N | Configurações do Cartão Web: Configurações de configuração para cartões web. | CastSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------------- | ------------ | ---------------------------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configuração de Tamanho: Deve incluir pelo menos uma configuração. | | default | string | N | Especificação Padrão: A especificação de tamanho padrão é usada, com parâmetros opcionais: 2x2 | WebSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ----------------- | ------------------- | ------------ | ------------------------------------------------------------------ | | dimensions | DimensionObject \[] | N | Configuração de Tamanho: Deve incluir pelo menos uma configuração. | | drawer\_component | DrawerObject | Y | Configurações de Exibição do Componente Drawer. | | default | string | N | Especificação Padrão: | * 1x1 * 2x1 | DimensionObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------------------------------------- | -------- | ------------ | -------------------------------------------------- | | src | string | N | URL do Recurso: Por exemplo: | | size | string | N | Especificações de Tamanho: | | Parâmetros Opcionais do CastSettingsObject: | | | | * 2×2 Parâmetros Opcionais do WebSettingsObject: * 1x1 * 2x1 | DrawerObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------------------------------------------- | | src | string | N | URL do Recurso: Por exemplo: | Resposta de dados bem-sucedida: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | ------------------------ | | id | string | N | ID único do Cartão de IU | :::dicas **Condições**: Os parâmetros da requisição são legais e a verificação de identidade do usuário foi aprovada. \*\*Código de status: \*\* `200 OK` ::: Exemplo de solicitação： ```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" } } ``` Exemplo de Resposta: ```json { "error": 0, "data": { "id": "72cc5a4a-f486-4287-857f-b482d7818b16" }, "message": "success" } ``` #### 8.2.2 Recuperar Lista de Cartões de IU :::dicas * **URL**：`/open-api/v2/rest/ui/cards` * **Método**：`GET` * **Cabeçalho**： * Content-Type: application/json * Autorização: Bearer ::: Parâmetros da Solicitação: Nenhum Parâmetros de Resposta: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | ------------- | ------------ | ---------------------- | | data | CardObject\[] | N | Lista de Cartões de IU | CardObjec Object: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------- | ------------------ | ------------ | --------------------------------------------------------------------------------------------- | | id | string | N | ID do Cartão: Um identificador único para o cartão. | | label | string | Y | Rótulo do Cartão: Usado para descrever o cartão. Serve como um apelido ou nome para o cartão. | | cast\_settings | CastSettingsObject | Y | Rótulo do Cartão: Usado para descrever o cartão. É o apelido do cartão. | | web\_settings | WebSettingsObject | N | Configurações do Cartão Cast: Configurações de configuração para cartões cast. | | app\_name | string | Y | Configurações do Cartão Web: Configurações de configuração para cartões web. | CastSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ----------------------- | ------------------- | ------------ | ------------------------------------------------------------------ | | dimensions | DimensionObject \[] | N | Configuração de Tamanho: Deve incluir pelo menos uma configuração. | | default | string | N | Especificação Padrão: | | Parâmetro Opcional: 2x2 | | | | | used | string | N | Especificação Atual: | | Parâmetro Opcional: 2x2 | | | | WebSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------------- | ------------------- | ------------ | ------------------------------------------------------------------ | | dimensions | DimensionObject \[] | N | Configuração de Tamanho: Deve incluir pelo menos uma configuração. | | drawer\_component | DrawerObject | Y | Configurações de Exibição do Componente Drawer. | | default | string | N | Especificação Padrão: | | Parâmetro Opcional: | | | | * 1x1 * 2x1 | | used | string | N | Especificação Atual: Parâmetro Opcional: * 1x1 * 2x1 | DimensionObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------------- | -------- | ------------ | -------------------------------------------------- | | src | string | N | URL do Recurso: Por exemplo: | | size | string | N | Especificações de Tamanho: | | Parâmetro Opcional: | | | | * 1x1 * 2x1 **Observação**: Atualmente, cartões cast suportam apenas a especificação 2x2. A especificação 2x2 não será eficaz. | DrawerObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------ | -------- | ------------ | -------------------------------------------------- | | src | string | N | URL do Recurso: Por exemplo: | Exemplo de Resposta: ```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 Configuração de um Cartão de IU Especificado > Usuários autorizados podem modificar a configuração de um cartão de IU existente através desta interface. Provedores de serviço de cartão personalizado só podem modificar cartões de IU que eles próprios criaram. :::dicas * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Método**：`PUT` * **Cabeçalho**： * Content-Type: application/json * Autorização: Bearer ::: Parâmetros da Solicitação: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | -------------- | ------------------ | ------------ | ----------------------------------------------------- | | label | string | Y | Usado para descrever o cartão. É o apelido do cartão. | | cast\_settings | CastSettingsObject | Y | Configurações do Cartão Cast | | web\_settings | WebSettingsObject | Y | Configurações do Cartão Web | CastSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------------- | -------- | ----------------------------------------------------------------------------------------------------- | -------------------- | | used | string | Y, Um dos dois `used` ou `src` deve ser fornecido, mas pelo menos um desses parâmetros é obrigatório. | Especificação Atual: | | Parâmetro Opcional: | | | | * 2x2 \| | src | string | Y, Um dos dois `used` ou `src` deve ser fornecido, mas pelo menos um desses parâmetros é obrigatório. | URL do Recurso: | WebSettingsObject: | **Atributo** | **Tipo** | **Opcional** | **Descrição** | | ------------------- | -------- | ----------------------------------------------------------------------------------------------------- | -------------------- | | used | string | Y, Um dos dois `used` ou `src` deve ser fornecido, mas pelo menos um desses parâmetros é obrigatório. | Especificação Atual: | | Parâmetro Opcional: | | | | * 1x1 * 2x1 | | src | string | Y, Um dos dois `used` ou `src` deve ser fornecido, mas pelo menos um desses parâmetros é obrigatório. | URL do Recurso: | Resposta de dados bem-sucedida: :::tips **Condições**: Os parâmetros da solicitação são legais e a verificação da identidade do usuário foi aprovada. O cartão de IU sendo modificado deve ter sido criado pelo provedor de cartão de IU personalizado que chama a interface. \*\*Código de Status: \*\* `200 OK` **Código de Erro:** * **406**: Sem permissão para acessar este recurso ::: \*\*Exemplo de Resposta: \*\* ```json { "error": 0, "data": {}, "message": "success" } ``` \*\*Exemplo de Solicitação: \*\* ```json { "cast_settings": { "used": "2×2" }, "web_settings": { "used": "1×1" } } ``` #### 8.2.4 Excluir Cartão de IU Personalizado > Usuários autorizados estão autorizados a excluir um cartão de IU existente usando esta interface. Provedores de cartão personalizado só podem excluir cartões de IU que eles próprios criaram. :::dicas * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Método**：`DELETE` * **Cabeçalho**： * Content-Type: application/json * Autorização: Bearer ::: Parâmetros da Solicitação: Nenhum Resposta de dados bem-sucedida: :::dicas **Condições**: Os parâmetros da solicitação são legais e a verificação da identidade do usuário foi aprovada. O cartão de IU sendo modificado deve ter sido criado pelo provedor de cartão de IU personalizado que chama a interface. \*\*Código de Status: \*\* `200 OK` **Código de Erro:** * **406**: Sem permissão para acessar este recurso. ::: \*\*Exemplo de Resposta: \*\* ```json { "error": 0, "data": {}, "message": "success" } ```