# Guida per sviluppatori e API ## 1. Iniziare ad usare ### 1.1 Preparazione Passo 1. Assicurarsi che il gateway sia alimentato e funzioni correttamente. Passo 2. Assicurarsi che il gateway e il PC siano collegati alla stessa LAN. Quindi inserire l'URL di CUBE nel browser. Avviso: Se avete più gateway, potete ottenere l'indirizzo IP corrispondente per accedere al gateway specificato nei seguenti due modi. 1. Accedere al vostro router wireless e controllare l'indirizzo IP del gateway nel DHCP. 2. CUBE supporta la scoperta locale tramite mDNS. ### 1.2 Per iniziare * Chiamare l'interfaccia \[Access Token], e ottenere una risposta di errore che invita a cliccare <**Fatto**>. Nota che dopo la pressione, l'accesso all'interfaccia è valido per non più di 5 minuti. ```json // Richiesta curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Risposta { "error": 401, "data": {}, "message": "link button not pressed" } ``` * Cliccare <**Fatto**> e chiamare nuovamente l'interfaccia \[Access Token]. La risposta è positiva e il token viene ottenuto. ```json // Richiesta curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Risposta { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` * Verificare il token. Chiamare l'interfaccia \[Get Device List]. La risposta è positiva e viene ottenuta la lista dei dispositivi. ```json // Richiesta curl --location --request GET 'http:///open-api/V2/rest/devices' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d' // Risposta { "error": 0, "data": { "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "nome dispositivo", "manufacturer": "nome produttore", "model": "nome modello", "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" } ``` * Metodo per ottenere il token di accesso CUBE: dopo aver chiamato l'interfaccia \[Access Token], la finestra pop-up globale della pagina della console Web CUBE invita l'utente a confermare l'acquisizione delle credenziali per la chiamata dell'interfaccia. * Nota: Se si aprono più pagine della console web CUBE, la finestra di conferma apparirà su più pagine della console web contemporaneamente, e la finestra pop-up delle altre pagine della console web verrà chiusa dopo aver cliccato la conferma su una delle pagine. ## 2. Concetto chiave ### 2.1 Indirizzo dell'interfaccia di sviluppo L'interfaccia Web API del gateway ha due metodi di accesso (basati su IP o nome di dominio), solitamente il percorso root è /open-api/V2/rest/< specifico modulo funzionale > // Accesso IP http\:///open-api/V2/rest/bridge // Accesso tramite nome di dominio http\:///open-api/V2/rest/bridge ### 2.2 Categoria di visualizzazione del dispositivo e capacità * \*\*Categoria di visualizzazione del dispositivo (DisplayCategory). \*\*La categoria di visualizzazione del dispositivo viene utilizzata per identificare categorie specifiche di (dispositivi), come switch, plug, light, ecc. **Questa informazione determinerà l'effetto di visualizzazione UI del dispositivo nel gateway**. * \*\*Capability del dispositivo. \*\*La capability del dispositivo viene utilizzata per descrivere le specifiche sotto-funzioni del dispositivo. Ad esempio controllo di alimentazione, controllo della luminosità, controllo della temperatura del colore, ecc. **Un singolo dispositivo può supportare 1 o più capability**. * **capability:** Descrive il nome della capability, che deve essere globalmente unico e di tipo stringa. Più parole inglesi devono essere separate da trattini ("-"). Per esempio: `"thermostat-target-setpoint"`. * **name:** Descrive la categoria sotto la capability, anch'essa di tipo stringa. Più parole inglesi devono essere separate da trattini ("-"). Per esempio: `"auto-mode"`, `"manual-mode"`. * **permission:** Descrive i permessi associati alla capability. Il tipo è stringa, formattata in codice binario 8421. Esempi includono: * Dispositivo controllabile: `"1000"` * Dispositivo configurabile: `"0010"` * Dispositivo controllabile e configurabile: `"1010"` * Dispositivo controllabile e in grado di segnalare: `"1100"` Il significato di ogni bit, da destra a sinistra, è il seguente: ⅰ. Bit 0: Consente la consultazione del dispositivo ⅱ. Bit 1: Consente la configurazione del dispositivo ⅲ. Bit 2: Consente al dispositivo di riportare dati ⅳ. Bit 3: Consente il controllo del 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:** Descrive le voci di configurazione per la capability, che sono di tipo oggetto e includono una descrizione per ciascuna voce di configurazione. ⅰ. **key:** Descrive il nome della voce di configurazione, che è di tipo stringa. Più parole inglesi dovrebbero essere espresse in camelCase. Per esempio: `"temperatureUnit"`. ⅱ. **value:** Descrive il contenuto della voce di configurazione. Le specifiche dettagliate sono descritte nella tabella sottostante. | Attributo | Tipo | Opzionale | Descrizione | | --------------------- | ------ | --------- | -------------------------------------------------- | | permission | string | N | Descrive i permessi per la voce di configurazione. | | **Valori opzionali:** | | | | * Consente la modifica di questa voce di configurazione: `"10"` * Consente la visualizzazione di questa voce di configurazione: `"01"` * Consente sia la modifica che la visualizzazione di questa voce di configurazione: `"11"` **Spiegazione dei bit:** 1. **Bit 0:** Consente la visualizzazione di questa voce di configurazione 2. **Bit 1:** Consente la modifica di questa voce di configurazione | | type | string | N | Descrive il tipo di dato del valore della voce di configurazione. **Valori opzionali:** * `"enum"` * `"numeric"` * `"object"` * `"boolean"` * `"string"` **Linee guida specifiche per tipo:** 1. **Quando `**type = enum**`:** * Il `campo value` (che descrive il valore della voce di configurazione) è obbligatorio se `permission` consente la modifica (`"10"` o `"11"`). * Il `default` (che descrive il valore predefinito della voce di configurazione) e `values` (che descrive i valori selezionabili per la voce di configurazione) i campi sono opzionali. 2. **Quando `**type = numeric**`:** * Il `campo value` il campo è obbligatorio se `permission` consente la modifica (`"10"` o `"11"`). * I seguenti campi sono opzionali: * `min` (che descrive il valore minimo della voce di configurazione) * `max` (che descrive il valore massimo della voce di configurazione) * `step` (che descrive il valore di passo per la voce di configurazione) * `precision` (che descrive la precisione) * `unit` (che descrive l'unità della voce di configurazione) * `default` (che descrive il valore predefinito) 3. **Quando `**type = object**`:** * Il `campo value` il campo è obbligatorio se `permission` consente la modifica (`"10"` o `"11"`). * Il `default` il campo è opzionale. 4. **Quando `**type = boolean**`:** * Il `campo value` il campo è obbligatorio se `permission` consente la modifica (`"10"` o `"11"`). * Il `default` il campo è opzionale. 5. **Quando `**type = string**`:** * Il `campo value` il campo è obbligatorio se `permission` consente la modifica (`"10"` o `"11"`). * Il `default` il campo è opzionale. | ```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 di dato | Tipo | Descrizione | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | string | Tipo di dato stringa. Codifica UTF8. | | number | Tipo di dato numerico. [Formato binario a virgola mobile a doppia precisione a 64 bit IEEE 754](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) | | int | Tipo di dato intero. | | object | Tipo di dato oggetto. Oggetto conforme a JSON | | string\[] | Array di stringhe | | int\[] | Array di interi | | object\[] | Array di oggetti | | bool | Booleano | | date | Stringa di tempo. Stringa in formato ISO (Formato esteso ISO 8601): YYYY-MM-DDTHH:mm:ss.sssZ. Il fuso orario è sempre UTC (Tempo Coordinato Universale), identificato dal suffisso "Z". | ### Risultati generici della risposta | Attributo | Tipo | Opzionale | Descrizione | | --------------------------------------------------------------------------------------------------- | ------ | --------- | ----------------------------- | | error | int | N | Codice di errore: | | 0: Successo | | | | | 400: Errore di parametro | | | | | 401: Autenticazione fallita | | | | | 500: Eccezione del server | | | | | data | object | N | Corpo dei dati della risposta | | message | string | N | Descrizione della risposta: | | Quando error è uguale a 0, il contenuto è success | | | | | Quando error è diverso da 0, è una stringa non vuota, e il contenuto è una descrizione dell'errore. | | | | **Esempio di risposta**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` ```json { "error": 400, "data": {}, "message": "invalid parameters" } ``` ### Elenco delle risorse | Tipo | Descrizione | | ---------------- | ----------------------------- | | Suoni supportati | - alert1 (Suono di allarme 1) | * alert2 (Suono di allarme 2) * alert3 (Suono di allarme 3) * alert4 (Suono di allarme 4) * alert5 (Suono di allarme 5) * doorbell1 (Suono campanello 1) * doorbell2 (Suono campanello 2) * doorbell3 (Suono campanello 3) * doorbell4 (Suono campanello 4) * doorbell5 (Suono campanello 5) * alarm1 (Suono di allarme 1) * alarm2 (Suono di allarme 2) * alarm3 (Suono di allarme 3) * alarm4 (Suono di allarme 4) * alarm5 (Suono di allarme 5) | | Deep supportati | - bootComplete (Avvio del sistema completato) * networkConnected (Rete connessa) * networkDisconnected (Rete disconnessa) * systemShutdown (Spegnimento del sistema) -deviceDiscovered (Scoperta dispositivo) * system Armed (Sistema armato abilitato) * system Disarmed (Sistema armato disabilitato) * factoryReset (Ripristina dispositivo) | ### 3.1 La funzione del Gateway #### a. Access Token Consente agli utenti di ottenere il token di accesso. * Avviso: Il token verrà cancellato dopo il reset del dispositivo. * Avviso: Dopo aver ottenuto il token, è necessario premere nuovamente il pulsante per ottenere con successo un nuovo token. :::tips * **URL**：`/open-api/V2/rest/bridge/access_token` * **Metodo**：`GET` * **Header**： * Content-Type: application/json ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------------------------------- | | app\_name | string | Y | Descrizione del nome dell'applicazione. | Risposta dati di successo: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------------------------------------------------------------------- | | token | string | N | Il token di accesso dell'interfaccia. È valido a lungo termine, conservarlo | | app\_name | string | Y | Descrizione del nome dell'applicazione. | :::tips **Condizione**: L'utente attiva il < comando > e accede a questa interfaccia entro il tempo valido. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` Risposta dati di errore：Oggetto vuoto :::tips **Condizioni**：L'utente non ha attivato il < comando >, o il tempo valido è scaduto. \*\*Status Code: \*\* `200 OK` ::: **Esempio di risposta**: ```json { "error": 401, "data": {}, "message": "link button not pressed" } ``` #### b. Ottenere lo stato del Gateway Consente agli utenti autorizzati di ottenere lo stato del gateway tramite questa interfaccia :::tips * **URL**：`/open-api/V2/rest/bridge/runtime` * **Metodo**：`GET` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: nessuno Risposta dati di successo: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ----------------------------------------------------------------------------- | -------- | ------------- | ------------------------------------------- | | ram\_used | int | N | Percentuale di utilizzo della RAM. \[0-100] | | cpu\_used | int | N | Percentuale di utilizzo della CPU. \[0-100] | | power\_up\_time | date | N | L'ultima ora di accensione | | cpu\_temp | int | N | Temperatura CPU: | | Unità: Celsius | | | | | cpu\_temp\_unit | string | N | Unità di temperatura CPU: | | Opzionale | | | | | valori:`'c'`, `'f'` | | | | | sd\_card\_used | int | Y | Utilizzo della scheda SD (percentuale): | | Intervallo:`[0-100]` con una cifra decimale di precisione | | | | | \*Nota: Se la scheda SD non è inserita o non è formattata, il valore è vuoto. | | | | :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```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. Configurare il Gateway Consente agli utenti autorizzati di configurare il gateway tramite questa interfaccia :::tips * **URL**：`/open-api/V2/rest/bridge/config` * **Metodo**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------------------- | | volume | int | Y | Volume di sistema. \[0-100] | Risposta dati di successo: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Ottenere le informazioni del Gateway Consente agli utenti autorizzati di ottenere le informazioni del gateway tramite questa interfaccia :::tips * **URL**：`/open-api/V2/rest/bridge` * **Metodo**：`GET` * **Header**： * Content-Type: application/json ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | -------------------------------- | | ip | string | N | indirizzo ip | | mac | string | N | indirizzo mac | | domain | string | Y | Dominio del servizio del gateway | | fw\_version | string | N | Versione del firmware | | name | string | N | Nome del dispositivo | Risposta dati di successo: Oggetto vuoto {} :::tips **Condizioni**: Nessuno \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```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. Silenziare il Gateway Consente agli utenti autorizzati di silenziare il gateway tramite questa interfaccia. :::tips * **URL**：`/open-api/v2/rest/bridge/mute` * **Metodo**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: nessuno Risposta dati di successo: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### f. Riattivare il suono del Gateway Consente agli utenti autorizzati di riattivare il suono del gateway tramite questa interfaccia.\ :::tips * **URL**：`/open-api/v2/rest/bridge/unmute` * **Metodo**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: nessuno Risposta dati di successo: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### g. Disattivare l'allarme del Gateway Consente agli utenti autorizzati di disabilitare lo stato del suono di allarme sul gateway tramite questa interfaccia. :::tips * **URL**：`/open-api/v2/rest/bridge/cancel_alarm` * **Metodo**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: nessuno Risposta dati di successo: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.2 Funzione hardware #### a. Riavviare il Gateway Consente all'utente autorizzato di riavviare il gateway tramite questa interfaccia :::tips * **URL**：`/open-api/V2/rest/hardware/reboot` * **Metodo**：`POST` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: nessuno Risposta dati di successo: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: ```json { "error": 0, "data": {}, "message": "success" } ``` #### b. Controllo dell'altoparlante Consente agli utenti autorizzati di controllare l'altoparlante tramite questa interfaccia :::tips * **URL**：`/open-api/V2/rest/hardware/speaker` * **Metodo**：`POST` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ----------- | ------------------------------- | ------------------------------------------------------------------------------------------ | | type | string | N | Parametri opzionali: 1.play\_sound (riprodurre il suono) 2.play\_beep (riprodurre il beep) | | sound | SoundObject | Y (N se il tipo è play\_sound.) | Il suono. | | beep | BeepObject | Y (N se il tipo è play\_beep.) | Il beep | SoundObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Il nome del suono. I valori supportati possono essere verificati in \[Elenco risorse - Suoni supportati] | | volume | int | N | Il volume del suono. \[0-100] | | countdown | int | N | La durata della riproduzione del suono dall'altoparlante; si interromperà automaticamente al termine del tempo. Unità: secondi. \[0,1799] | BeepObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------ | | name | string | N | Il nome del deep. I valori supportati possono essere verificati in \[Elenco risorse - Deep supportati] | | volume | int | N | Il volume del deep. \[0-100] | Risposta dati di successo: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\* `200 OK` ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.3 Funzione di gestione dei dispositivi #### a. Tipi di dispositivi supportati | **Tipo di dispositivo** | **Valore** | Versione iHost | | -------------------------------- | ---------------------------- | -------------- | | Presina | plug | ≥ 2.1.0 | | Interruttore | switch | ≥ 2.1.0 | | Luce | light | ≥ 2.1.0 | | Tenda | curtain | ≥ 2.1.0 | | Sensore porta/finestra | contactSensor | ≥ 2.1.0 | | Sensore di movimento | motionSensor | ≥ 2.1.0 | | Sensore di temperatura | temperatureSensor | ≥ 2.1.0 | | Sensore di umidità | humiditySensor | ≥ 2.1.0 | | Sensore di temperatura e umidità | temperatureAndHumiditySensor | ≥ 2.1.0 | | Rilevatore di perdite d'acqua | waterLeakDetector | ≥ 2.1.0 | | Rilevatore di fumo | smokeDetector | ≥ 2.1.0 | | Pulsante wireless | button | ≥ 2.1.0 | | Telecamera | camera | ≥ 2.1.0 | | Sensore generico | sensor | ≥ 2.1.0 | | Sensore generico | sensor | ≥ 2.1.0 | | Ventilatore con luce | fanLight | ≥ 2.1.0 | | Condizionatore | airConditioner | ≥ 2.1.0 | | Ventilatore | fan | ≥ 2.1.0 | | Termostato | thermostat | ≥ 2.1.0 | #### b. Capacità del dispositivo supportate **Interruttore di alimentazione (power):** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "power", // Nome della capacità "permission": "1100", // ihost non supporta la configurazione di avvio/arresto morbido, quindi nessun campo configure } ] ``` **Attributo di stato:** ``` { "powerState": "on", // Il campo powerState indica lo stato di accensione/spegnimento. Obbligatorio. **Tipo:** stringa. "on" indica acceso, "off" indica spento, "toggle" indica commutazione. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** **Accendi:** ``` { "power": { "powerState": "on" } } ``` **Spegni:** ``` { "power": { "powerState": "off" } } ``` **Interruttore canale (toggle):** **Esempio di dichiarazione della capacità:** Esempio componente singolo: ``` [ { "capability": "toggle", // Nome della capacità "permission": "1100", // Permesso "name": "1", // Nome del componente, **Tipo:** Stringa. Valori opzionali: "1" (Canale 1), "2" (Canale 2), "3" (Canale 3), "4" (Canale 4), o altri valori contenenti lettere maiuscole, minuscole e numeri } ] ``` Esempio componenti multipli: ``` [ { "capability": "toggle", "permission": "1100", "name": "1" }, { "capability": "toggle", "permission": "1100", "name": "2" } ] ``` **Attributo di stato:** ``` { "toggleState": "on", // Il campo toggleState indica lo stato di commutazione dell'attributo {name} del dispositivo {device_id}. Obbligatorio. **Tipo:** Stringa. "on" indica abilitato, "off" indica disabilitato, "toggle" indica commutazione. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Formato toggle: ``` { [capability]: { [toggle-name]: { [toggleState]: [value] } } } Componente 1 acceso, componente 2 spento: { "toggle": { "1": { "toggleState": "on" }, "2": { "toggleState": "off" } } } ``` **Inching canale (toggle-inching):** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "toggle-inching", // Nome della capacità "permission": "0010", // Permesso "settings": { "toggleInchingSetting": { "permission": "11", "type": "object", "value": { "supported": { "1": { // Nome del componente "enable": true, // Se la funzione inching è abilitata. **Tipo:** Booleano. Obbligatorio. "inchingSwitch": "off", // Impostazione dell'interruttore inching. **Tipo:** Stringa. Obbligatorio. "off" (alimentazione disattivata), "on" (alimentazione attivata) "delay": 1000, // Tempo di ritardo inching in millisecondi. **Tipo:** Intero. Obbligatorio. "min_delay": 500, // Tempo di ritardo minimo "max_delay": 100000 // Tempo di ritardo massimo }, "2": { // Nome del componente "enable": true, // Se la funzione inching è abilitata. **Tipo:** Booleano. Obbligatorio. "inchingSwitch": "off", // Impostazione dell'interruttore inching. **Tipo:** Stringa. Obbligatorio. "off" (alimentazione disattivata), "on" (alimentazione attivata) "delay": 1000, // Tempo di ritardo inching in millisecondi. **Tipo:** Intero. Obbligatorio. "min_delay": 500, // Tempo di ritardo minimo "max_delay": 100000 // Tempo di ritardo massimo }, "3": { // Nome del componente "enable": true, // Se la funzione inching è abilitata. **Tipo:** Booleano. Obbligatorio. "inchingSwitch": "off", // Impostazione dell'interruttore inching. **Tipo:** Stringa. Obbligatorio. "off" (alimentazione disattivata), "on" (alimentazione attivata) "delay": 1000, // Tempo di ritardo inching in millisecondi. **Tipo:** Intero. Obbligatorio. "min_delay": 500, // Tempo di ritardo minimo "max_delay": 100000 // Tempo di ritardo massimo }, "4": { // Nome del componente "enable": true, // Se la funzione inching è abilitata. **Tipo:** Booleano. Obbligatorio. "inchingSwitch": "off", // Impostazione dell'interruttore inching. **Tipo:** Stringa. Obbligatorio. "off" (alimentazione disattivata), "on" (alimentazione attivata) "delay": 1000, // Tempo di ritardo inching in millisecondi. **Tipo:** Intero. Obbligatorio. "min_delay": 500, // Tempo di ritardo minimo "max_delay": 100000 // Tempo di ritardo massimo } } } } } } ] ``` **Attributo di stato** Nessuno **Protocollo (interrogazione dello stato e istruzioni di controllo)** Nessuno **Regolazione della luminosità (brightness):** **Esempio di dichiarazione della capacità:** ``` { "capability": "brightness", // Nome della capacità "permission": "1100" // Permesso } ``` **Attributo di stato:** ``` { "brightness": 100, // Il campo brightness indica la percentuale di luminosità. Scegliere tra brightness o brightnessDelta. **Tipo:** Numero. Intervallo: 0-100. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Imposta la luminosità all'80%. (0 è il più scuro e 100 è il più luminoso.) ``` json Copia codice { "brightness": { "brightness": 80 } } ``` **Regolazione della temperatura del colore (color-temperature):** **Esempio di dichiarazione della capacità:** ``` { "capability": "color-temperature", // Nome della capacità "permission": "1100" // Permesso } ``` **Attributo di stato:** ``` { "colorTemperature": 100, // Il campo colorTemperature indica la percentuale di temperatura colore. Scegliere tra colorTemperature o colorTemperatureDelta. **Tipo:** Numero. Intervallo: 0-100. 0 indica luce calda, 50 indica luce neutra, 100 indica luce fredda. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Regola la temperatura del colore al 50%: ``` json { "color-temperature": { "colorTemperature": 50 } } ``` **Regolazione del colore (color-rgb):** **Esempio di dichiarazione della capacità:** ``` { "capability": "color-rgb", // Nome della capacità "permission": "1100" // Permesso } ``` **Attributo di stato:** ``` { "red": 255, // Il campo red rappresenta il rosso nello spazio colore RGB. Obbligatorio. **Tipo:** Numero. Intervallo: 0-255. "green": 0, // Il campo green rappresenta il verde nello spazio colore RGB. Obbligatorio. **Tipo:** Numero. Intervallo: 0-255. "blue": 255 // Il campo blue rappresenta il blu nello spazio colore RGB. Obbligatorio. **Tipo:** Numero. Intervallo: 0-255. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Imposta il colore su viola: ``` { "color-rgb": { "red": 255, "green": 0, "blue": 255 } } ``` **Regolazione percentuale (percentage):** **Esempio di dichiarazione della capacità:** ``` { "capability": "percentage", "permission": "1100", "settings": { // Opzionale "percentageRange": { "permission": "01", "type": "numeric", "min": 0, "max": 100, "step": 5 } } } ``` **Attributo di stato:** ``` { "percentage": 100, // Il campo percentage indica un valore percentuale. Scegliere tra percentage o percentageDelta. **Tipo:** Numero. Intervallo: 0-100. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Regola al 40%: ``` { "percentage": { "percentage": 40 } } ``` **Controllo motore (motor-control):** **Esempio di dichiarazione della capacità:** ``` { "capability": "motor-control", "permission": "1100" } ``` **Attributo di stato:** ``` json { "motorControl": "stop", // Il campo motorControl indica lo stato del motore. Obbligatorio. **Tipo:** Stringa. Valori possibili: "open" (apri), "close" (chiudi), "stop" (ferma), "lock" (blocca). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Apri motore: ``` { "motor-control": { "motorControl": "open" } } ``` **Inversione motore (motor-reverse):** **Esempio di dichiarazione della capacità:** ``` { "capability": "motor-reverse", "permission": "1100" } ``` **Attributo di stato:** ``` { "motorReverse": true, // Il campo motorReverse indica l'impostazione della direzione del motore. Obbligatorio. **Tipo:** Booleano. true indica avanti, false indica indietro. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Imposta motore in avanti: ``` { "motor-reverse": { "motorReverse": true } } ``` **Calibrazione motore (motor-clb)** **Esempio di dichiarazione della capacità:** ``` { "capability": "motor-clb", "permission": "0100" } ``` **Attributi (Stato):** ``` { "motorClb": "calibration" // Il campo motorClb indica lo stato di calibrazione del motore. Obbligatorio. **Tipo:** Stringa. "normal" indica modalità normale (calibrato), "calibration" indica calibrazione in corso. } ``` **Protocollo (segnalazione stato):** Segnala che lo stato del motore è in calibrazione: ``` { "motor-clb": { "motorClb": "calibration" } } ``` **Stato all'accensione (startup)** **Esempio di dichiarazione della capacità:** ``` { "capability": "startup", "permission": "1100" } ``` **Attributi (Stato):** ``` { "startup": "on" // Stato di alimentazione all'avvio. **Tipo:** Stringa. Obbligatorio. Valori opzionali: "on" (accendi), "stay" (mantieni alimentazione), "off" (spegni), "toggle" (inverti stato di alimentazione). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Imposta lo stato di alimentazione su Sempre On: ``` { "startup": { "startup": "on" } } ``` *** **Attivazione di risveglio (identify)** **Esempio di dichiarazione della capacità:** ``` { "capability": "identify", "permission": "0100" } ``` **Attributi (Stato):** ``` { "identify": true // Indica se il dispositivo segnala attivamente i risultati di riconoscimento o è stato attivato. } ``` **Protocollo (segnalazione stato e istruzioni di controllo):** Imposta il tempo di attivazione di risveglio: ``` { "identify": { "countdown": 180 // Il campo countdown indica il tempo di conto alla rovescia. Obbligatorio. **Tipo:** Numero. Unità: secondi. } } ``` Segnala lo stato di attivazione: ``` { "identify": { "identify": true // Indica se il dispositivo segnala attivamente i risultati di riconoscimento o è stato attivato. } } ``` **Interruttore statistiche consumo energetico in tempo reale (power-consumption)** **Esempio di dichiarazione della capacità:** ``` { "capability": "power-consumption", "permission": "1101", "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ``` **Attributi (Stato):** Avvia/Arresta statistiche in tempo reale: ``` { "rlSummarize": true, // Avvia/arresta le statistiche in tempo reale. **Tipo:** Booleano. Obbligatorio. "timeRange": { // Intervallo di tempo riepilogato. Obbligatorio. "start": "2020-07-05T08:00:00Z", // Ora di inizio delle statistiche di consumo energetico. **Tipo:** Stringa. Obbligatorio. "end": "2020-07-05T09:00:00Z" // Ora di fine delle statistiche di consumo energetico. **Tipo:** Stringa. Obbligatorio. } } ``` Interroga il consumo energetico per intervallo di tempo: ``` { "type": "summarize", // Tipo di statistiche. **Tipo:** Stringa. Obbligatorio. Valori opzionali: "rlSummarize" (riepilogo in tempo reale), "summarize" (riepilogo corrente). "timeRange": { // Intervallo di tempo riepilogato. Obbligatorio se type è "summarize". "start": "2020-07-05T08:00:00Z", // Ora di inizio delle statistiche di consumo energetico. **Tipo:** Stringa. Obbligatorio. "end": "2020-07-05T09:00:00Z" // Ora di fine delle statistiche di consumo energetico. **Tipo:** Stringa. Facoltativo. Se omesso, indica l'ora corrente. } } ``` Rispondere con il risultato delle statistiche entro l'intervallo di tempo: ``` json { "type": "summarize", // Tipo di statistiche. **Tipo:** Stringa. Obbligatorio. Valori opzionali: "rlSummarize" (riepilogo in tempo reale), "summarize" (riepilogo corrente). "rlSummarize": 50.0, // Consumo energetico totale. **Tipo:** Numero. Unità: 0,01 kWh. Facoltativo. "electricityIntervals": [ // Più record statistici divisi secondo configuration.resolution. Facoltativo. Non presente quando type è "rlSummarize". { "usage": 26.5, // Consumo energetico. **Tipo:** Numero. Unità: 0,01 kWh. Obbligatorio. "start": "2020-07-05T08:00:00Z", // Ora di inizio. **Tipo:** Data. Obbligatorio. "end": "2020-07-05T09:00:00Z" // Ora di fine. **Tipo:** Data. Obbligatorio. Se l'intervallo tra end e start è minore della risoluzione, tutti i record segnalati sono considerati non validi. }, { "usage": 26.5, // Consumo energetico. **Tipo:** Numero. Unità: 0,01 kWh. Obbligatorio. "start": "2020-07-05T09:00:00Z", // Ora di inizio. **Tipo:** Data. Obbligatorio. "end": "2020-07-05T10:00:00Z" // Ora di fine. **Tipo:** Data. Obbligatorio. Se l'intervallo tra end e start è minore della risoluzione, tutti i record segnalati sono considerati non validi. } ] } ``` **Protocollo (segnalazione stato e istruzioni di controllo):** Avvia statistiche in tempo reale: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Arresta statistiche in tempo reale: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Ottieni consumo energetico storico: ``` json { "power-consumption": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } ``` Ottieni consumo energetico in tempo reale: ``` json { "power-consumption": { "powerConsumption": { "type": "rlSummarize" } } } ``` **Rilevamento modalità temperatura e umidità (thermostat-mode-detect)** **Esempio di dichiarazione della capacità:** ``` { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Tipo di rilevamento controllo temperatura. **Tipo:** Stringa. Obbligatorio. Valori opzionali: "humidity" (rilevamento umidità), "temperature" (rilevamento temperatura). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Impostazioni di rilevamento supportate. Obbligatorio. { "name": "lowerSetpoint", // Il valore di rilevamento deve essere superiore a questo setpoint. Almeno uno tra lowerSetpoint o upperSetpoint è richiesto. "value": { // Intervallo di rilevamento. Opzionale. Specificare se esistono condizioni preimpostate. "value": 68.0, // Valore di temperatura. **Tipo:** Numero. Obbligatorio. "scale": "f" // Unità di temperatura. Obbligatoria quando name=temperature. Valori opzionali: "c" (Celsius), "f" (Fahrenheit). } }, { "name": "upperSetpoint", // Il valore di rilevamento deve essere inferiore a questo setpoint. Almeno uno tra lowerSetpoint o upperSetpoint è richiesto. "value": { // Intervallo di rilevamento. Opzionale. Specificare se esistono condizioni preimpostate. "value": 68.0, // Valore di temperatura. **Tipo:** Numero. Obbligatorio. "scale": "f" // Unità di temperatura. Obbligatoria quando name=temperature. Valori opzionali: "c" (Celsius), "f" (Fahrenheit). } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } { "capability": "thermostat-mode-detect", "permission": "0110", "name": "humidity", // Tipo di rilevamento controllo temperatura. **Tipo:** Stringa. Obbligatorio. Valori opzionali: "humidity" (rilevamento umidità), "temperature" (rilevamento temperatura). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Impostazioni di rilevamento supportate. Obbligatorio. { "name": "lowerSetpoint", // Il valore di rilevamento deve essere superiore a questo setpoint. Almeno uno tra lowerSetpoint o upperSetpoint è richiesto. "value": { // Intervallo di rilevamento. Opzionale. Specificare se esistono condizioni preimpostate. "value": 68.0, // Valore di umidità. **Tipo:** Numero. Obbligatorio } }, { "name": "upperSetpoint", // Il valore di rilevamento deve essere inferiore a questo setpoint. Almeno uno tra lowerSetpoint o upperSetpoint è richiesto. "value": { // Intervallo di rilevamento. Opzionale. Specificare se esistono condizioni preimpostate. "value": 68.0, // Valore di umidità. **Tipo:** Numero. Obbligatorio } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ``` **Attributi (Stato):** ``` { "mode": "COMFORT" // ID modalità. Facoltativo. Valori supportati: "COMFORT" (Modalità Comfort), "COLD" (Modalità Fredda), "HOT" (Modalità Calda), "DRY" (Modalità Asciutta), "WET" (Modalità Umida). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Formato: ``` { [capability] :{ [mode name] :{ "mode": [value] } } } ``` Esempio: ``` { "thermostat-mode-detect": { "humidity": { "mode": "COMFORT" } } } ``` **Modalità termostato (thermostat-mode)** **Esempio di dichiarazione della capacità:** ``` { "capability": "thermostat", "permission": "1100", "name": "thermostat-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", "AUTO", "ECO" ] } } } ``` **Attributi (Stato):** ``` { "thermostatMode": "MANUAL" // Modalità operativa del termostato. **Tipo:** Stringa. Valori opzionali: "MANUAL", "AUTO", "ECO". } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "thermostat": { "thermostat-mode": { "thermostatMode": "MANUAL" } } } ``` **Stato di recupero adattivo del termostato (thermostat/adaptive-recovery-status)** **Esempio di dichiarazione della capacità:** ``` { "capability": "thermostat", "permission": "0100", "name": "adaptive-recovery-status" // Stato di recupero adattivo del termostato } ``` **Attributi (Stato):** ``` { "adaptiveRecoveryStatus": "HEATING" // Stato di recupero adattivo del termostato. **Tipo:** Stringa. Valori opzionali: "HEATING", "INACTIVE". } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "thermostat": { "adaptive-recovery-status": { "adaptiveRecoveryStatus": "HEATING" } } } ``` **Impostazione della temperatura target della modalità termostato (thermostat-target-setpoint)** **Esempio di dichiarazione della capacità:** ``` [[ { "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, // Ora di inizio in minuti. **Tipo:** int. Es.: 7:20 = 440 minuti. "upperSetpoint": 36.5, // Temperatura target massima. **Tipo:** numero. "lowerSetpoint": 20 // Temperatura target minima. **Tipo:** numero. }, { "startTimeInMinutes": 900, // Ora di inizio in minuti. Es.: 15:00 = 900 minuti. "upperSetpoint": 26.5, // Temperatura target massima. **Tipo:** numero. "lowerSetpoint": 21 // Temperatura target minima. **Tipo:** numero. } ], "Tuesday": [... ], "Wednesday": [... ], "Thursday": [... ], "Friday": [... ], "Saturday": [... ], "Sunday": [... ], } } } } ] ``` **Attributi (Stato):** ``` { "targetSetpoint": 30 // Temperatura target per la modalità specificata. **Tipo:** numero, nell'unità specificata da temperatureUnit. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "thermostat-target-setpoint": { "manual-mode": { "targetSetpoint": 30 }, "auto-mode": { "targetSetpoint": 30 } } } ``` **Rilevamento sensori (detect)** **Esempio di dichiarazione della capacità:** ``` { "capability": "detect", "permission": "0110", "settings": { // Opzionale "detectInterval": { "permission": "11", "type": "numeric", "value": 300 }, "detectSensitivity": { "permission": "11", "type": "numeric", "value": 1000 } } } ``` **Attributi (Stato):** ``` { "detected": true // Risultato del rilevamento. **Tipo:** Booleano. `true` indica rilevamento, `false` indica nessun rilevamento. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "detect": { "detected": true } } ``` **Rilevamento temperatura (temperature)** **Esempio di dichiarazione della capacità:** ``` { "capability": "temperature", "permission": "0110", "settings": { // Opzionale "temperatureCalibration": { // Calibrazione della temperatura opzionale "type": "numeric", "permission": "11", "min": -7, // Valore minimo "max": 7, // Valore massimo "step": 0.2, // Passo di regolazione della temperatura, unità uguale a temperatureUnit "value": 5.2 // Valore corrente di calibrazione della temperatura. **Tipo:** numero. }, "temperatureUnit": { // Unità di temperatura opzionale "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange": { // Intervallo di rilevamento temperatura opzionale "type": "numeric", "permission": "01", "min": -40, "max": 80 } } } ``` **Attributi (Stato):** ``` json Copia codice { "temperature": 26.5 // Temperatura corrente. **Tipo:** Numero, in Celsius. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "temperature": { "temperature": 20 } } ``` **Rilevamento umidità (humidity)** **Esempio di dichiarazione della capacità:** ``` { "capability": "humidity", "permission": "0100", "settings": { // Intervallo di rilevamento umidità opzionale. "humidityRange": { "type": "numeric", "permission": "01", "min": 0, "max": 100 } } } ``` **Attributi (Stato):** ``` { "humidity": 50 // Umidità relativa corrente (percentuale). **Tipo:** Numero, intervallo 0-100. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "humidity": { "humidity": 20 } } ``` **Rilevamento batteria (battery)** **Esempio di dichiarazione della capacità:** ``` { "capability": "battery", "permission": "0100" } ``` **Attributi (Stato):** ``` { "battery": 95 // Percentuale di batteria rimanente. **Tipo:** Numero, intervallo -1 a 100. Nota: -1 indica livello batteria sconosciuto. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "battery": { "battery": 40 } } ``` **Rilevamento singolo pulsante (press)** **Esempio di dichiarazione della capacità:** ``` { "capability": "press", "permission": "1100", "settings": { // Opzionale "actions": { // Azioni del pulsante, opzionali. "type": "enum", "permission": "01", "values": [ // Azioni del pulsante opzionali. I valori predefiniti sono "singlePress", "doublePress", "longPress". Le azioni configurate sostituiscono i valori predefiniti. ] } } } ``` **Attributi (Stato):** ``` { "press": "singlePress" // Tipo di pressione del pulsante. **Tipo:** Stringa. Valori standard: "singlePress" (pressione singola o breve), "doublePress" (doppia pressione), "longPress" (pressione prolungata). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "press": { "press": "singlePress" } } ``` **Rilevamento multi-pulsante (multi-press)** **Esempio di dichiarazione della capacità:** ``` { "capability": "multi-press", "permission": "0100", "name": "1", // Nome dell'attributo multi-press. **Tipo:** Stringa. Consentiti solo caratteri alfanumerici. "settings": { // Opzionale "actions": { // Azioni del pulsante, opzionali. "type": "enum", "permission": "01", "values": [ // Azioni del pulsante opzionali. I valori predefiniti sono "singlePress", "doublePress", "longPress". Le azioni configurate sostituiscono i valori predefiniti. ] } } } ``` **Attributi (Stato):** ``` { "press": "singlePress" // Tipo di pressione del pulsante. **Tipo:** Stringa. Valori standard: "singlePress" (pressione singola o breve), "doublePress" (doppia pressione), "longPress" (pressione prolungata). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { [capability] :{ [multi-press-name]：{ press:[value] } } } esempio: { "multi-press": { "1": { "press": "singlePress" }, "2": { "press": "doublePress" } } } ``` **Rilevamento intensità segnale (rssi)** **Esempio di dichiarazione della capacità:** ``` { "capability": "rssi", "permission": "0100" } ``` **Attributi (Stato):** ``` { "rssi": -65 // Intensità del segnale wireless (Received Signal Strength Indicator). **Tipo:** Numero, unità dBm, valori interi negativi. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "rssi": { "rssi": -65 } } ``` **Rilevamento manomissione (tamper-alert)** **Esempio di dichiarazione della capacità:** ``` { "capability": "tamper-alert", "permission": "0100" } ``` **Attributi (Stato):** ``` { "tamper": "clear" // Stato di manomissione. **Tipo:** Stringa. Valori possibili: "clear" (non manomesso), "detected" (manomesso). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "tamper-alert": { "tamper": "clear" // Stato di manomissione. **Tipo:** Stringa. Valori possibili: "clear" (non manomesso), "detected" (manomesso). } } ``` **Rilevamento livello di illuminazione (illumination-level)** **Esempio di dichiarazione della capacità:** ``` { "capability": "illumination-level", "permission": "0100" } ``` **Attributi (Stato):** ``` { "level": "brighter" // Livello di luminosità. **Tipo:** Stringa. Valori possibili: "brighter" (più luminoso), "darker" (più scuro). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "illumination-level": { "level": "brighter" } } ``` **Rilevamento tensione (voltage)** **Esempio di dichiarazione della capacità:** ``` { "capability": "voltage", "permission": "0100" } ``` **Attributi (Stato):** ``` { "voltage": 50 // Valore di tensione corrente, in unità di 0,01V. **Tipo:** Numero, valori non negativi. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "voltage": { "voltage": 50 } } ``` **Rilevamento corrente elettrica (electric-current)** **Esempio di dichiarazione della capacità:** ``` { "capability": "electric-current", "permission": "0100" } ``` **Attributi (Stato):** ``` { "electric-current": 50 // Valore di corrente corrente, in unità di 0,01A. **Tipo:** Numero, valori interi non negativi. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "electric-current": { "electric-current": 50 } } ``` **Rilevamento potenza elettrica (electric-power)** **Esempio di dichiarazione della capacità:** ``` { "capability": "electric-power", "permission": "0100" } ``` **Attributi (Stato):** ``` { "electric-power": 50 // Valore di potenza corrente, in unità di 0,01W. **Tipo:** Numero, valori interi non negativi. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "electric-power": { "electric-power": 50 } } ``` **Rilevamento guasti (fault)** **Esempio di dichiarazione della capacità:** ``` { "capability": "fault", "permission": "0100" } ``` **Attributi (Stato):** ``` { "fault": "none" // Stato di guasto. **Tipo:** Stringa. Valori possibili: "none" (nessun guasto), "detected" (guasto rilevato). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "fault": { "fault": "none" } } ``` **Interruttore soglia (threshold-breaker)** **Esempio di dichiarazione della capacità:** ``` { "capability": "threshold-breaker", "permission": "0010", "settings": { "supportedSetting": { "type": "object", "permission": "11", "value": { "supported": [ { "name": "lowerPower", // Interruttore soglia bassa potenza "value": { "value": 50, // Valore di potenza di rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0. "min_range": 10, // Valore minimo di potenza di rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0. "max_range": 3500 // Valore massimo di potenza di rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0. } }, { "name": "upperPower", // Interruttore soglia alta potenza "value": { "value": 50, // Valore di potenza di rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0. "min_range": 10, // Valore minimo di potenza di rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0. "max_range": 3500 // Valore massimo di potenza di rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0. } }, { "name": "lowerElectricCurrent", // Interruttore soglia bassa corrente "value": { "value": 50, // Valore di corrente di rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0. "min_range": 10, // Valore minimo di corrente di rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0. "max_range": 1500 // Valore massimo di corrente di rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0. } }, { "name": "upperElectricCurrent", // Interruttore soglia alta corrente "value": { "value": 50, // Valore di corrente di rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0. "min_range": 10, // Valore minimo di corrente di rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0. "max_range": 1500 // Valore massimo di corrente di rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0. } }, { "name": "lowerVoltage", // Interruttore soglia bassa tensione "value": { "value": 50, // Valore di tensione di rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0. "min_range": 10, // Valore minimo di tensione di rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0. "max_range": 24000 // Valore massimo di tensione di rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0. } }, { "name": "upperVoltage", // Interruttore soglia alta tensione "value": { "value": 50, // Valore di tensione di rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0. "min_range": 10, // Valore minimo di tensione di rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0. "max_range": 24000 // Valore massimo di tensione di rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0. } } ] } } } } ``` **Attributi (Stato)** * Nessuno **Protocollo (interrogazione dello stato e istruzioni di controllo)** * Nessuno **Funzione inch (inching)** **Esempio di dichiarazione della capacità:** ``` { "capability": "inching", "permission": "0010", "settings": { "inchingEnable": { // Impostazione di abilitazione della funzione inch "permission": "11", "type": "boolean", "value": false }, "inchingSwitch": { // Impostazione azione inch "type": "enum", "permission": "11", "value": "on", "values": ["on", "off"] }, "inchingDelay": { // Impostazione tempo inch "type": "numeric", "permission": "11", "min": 500, "max": 100000, "value": 1000, "unit": "ms" } } } ``` **Attributi (Stato):** * Nessuno **Protocollo (interrogazione dello stato e istruzioni di controllo):** * Nessuno **Stream della telecamera (camera-stream)** **Esempio di dichiarazione della capacità:** ``` { "capability": "camera-stream", "permission": "0010", "settings": { "streamSetting": { "type": "object", "permission": "11", "value": { "username": "String", // Account di accesso. **Tipo:** Stringa. Obbligatorio. "password": "String", // Password di accesso. **Tipo:** Stringa. Obbligatorio. "streamUrl": "rtsp://:@:/streaming/channel01", // URL dello stream. **Tipo:** Stringa. Obbligatorio. "videoCodec": "", // Codec video. **Tipo:** Stringa. Obbligatorio. Parametri opzionali da definire. "resolution": { // Risoluzione video. Obbligatoria. "width": 1080, // Larghezza. **Tipo:** Numero. Obbligatorio. "height": 720 // Altezza. **Tipo:** Numero. Obbligatorio. }, "keyFrameInterval": 5, // Intervallo key frame. **Tipo:** Stringa. Obbligatorio. "audioCodec": "G711", // Codec audio. **Tipo:** Stringa. Obbligatorio. Parametri opzionali da definire. "samplingRate": 50, // Frequenza di campionamento audio, in Hz. **Tipo:** Numero. Obbligatorio. Parametri opzionali da definire. "dataRate": 50 // Bitrate. **Tipo:** Numero. Obbligatorio. Unità: kb/s. } } } } ``` **Attributi (Stato):** * Nessuno **Protocollo (interrogazione dello stato e istruzioni di controllo):** * Nessuno **Controllo modalità (mode)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "mode", "name": "fanLevel", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["low", "medium", "high"] // Valori modalità personalizzati. I valori configurati sovrascrivono i valori predefiniti. } } }, { "capability": "mode", "name": "thermostatMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["auto", "manual"] // Valori modalità personalizzati. I valori configurati sovrascrivono i valori predefiniti. } } }, { "capability": "mode", "name": "airConditionerMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["cool", "heat", "auto", "fan", "dry"] // Valori modalità personalizzati. I valori configurati sovrascrivono i valori predefiniti. } } }, { "capability": "mode", "name": "fanMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["normal", "sleep", "child"] // Valori modalità personalizzati. I valori configurati sovrascrivono i valori predefiniti. } } }, { "capability": "mode", "name": "horizontalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Valori modalità personalizzati. I valori configurati sovrascrivono i valori predefiniti. } } }, { "capability": "mode", "name": "verticalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Valori modalità personalizzati. I valori configurati sovrascrivono i valori predefiniti. } } } ] ``` **Attributi (Stato):** ``` { "modeValue": "low" // Valore modalità. **Tipo:** Stringa. Obbligatorio. Fare riferimento alle modalità preset supportate. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "mode": { "fanLevel": { "modeValue": "low" } } } ``` **Rilevamento diossido di carbonio (co2)** **Esempio di dichiarazione della capacità:** ``` { "capability": "co2", "permission": "0100", "settings": { "co2Range": { "type": "numeric", "permission": "01", "min": 400, "max": 10000 } } } ``` **Attributi (Stato):** ``` { "co2": 111 // Concentrazione dianidride carbonica. **Tipo:** Intero. Unità: ppm. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "co2": { "co2": 500 } } ``` **Rilevamento illuminazione (illumination)** **Esempio di dichiarazione della capacità:** ``` { "capability": "illumination", "permission": "0100", "settings": { "illuminationRange": { "type": "numeric", "permission": "01", "min": 0, "max": 160000 } } } ``` **Attributi (Stato):** ``` { "illumination": 11 // Livello di illuminazione. **Tipo:** Intero. Unità: lux. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "illumination": { "illumination": 50 } } ``` **Rilevamento fumo (smoke)** **Esempio di dichiarazione della capacità:** ``` { "capability": "smoke", "permission": "0100" } ``` **Attributi (Stato):** ``` { "smoke": true // Risultato del rilevamento. **Tipo:** Booleano. `true` indica rilevamento, `false` indica nessun rilevamento. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "smoke": { "smoke": true } } ``` **Rilevamento Apertura/Chiusura Magnetico Porta (contatto)** **Esempio di dichiarazione della capacità:** ``` { "capability": "contact", "permission": "0100" } ``` **Attributi (Stato):** ``` { "contact": true // Risultato del rilevamento. **Tipo:** Booleano. `true` indica rilevamento, `false` indica nessun rilevamento. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "contact": { "contact": true } } ``` **Rilevamento Movimento (motion)** **Esempio di dichiarazione della capacità:** ``` { "capability": "motion", "permission": "0110", "settings": { "motionInterval": { "type": "numeric", "permission": "11", "value": 300 }, "motionSensitivity": { "type": "numeric", "permission": "11", "value": 1000 } } } ``` **Attributi (Stato):** ``` { "motion": true // Risultato del rilevamento. **Tipo:** Booleano. `true` indica rilevamento, `false` indica nessun rilevamento. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "motion": { "motion": true } } ``` **Rilevamento Perdita d'Acqua (water-leak)** **Esempio di dichiarazione della capacità:** ``` { "capability": "water-leak", "permission": "0100" } ``` **Attributi (Stato):** ``` { "waterLeak": true // Il campo `waterLeak` indica l'attuale risultato del rilevamento. **Tipo:** Booleano. `true` indica rilevamento, `false` indica nessun rilevamento. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "water-leak": { "waterLeak": true } } ``` **Interruttore Rilevamento Finestra (window-detection)** **Esempio di dichiarazione della capacità:** ``` { "capability": "window-detection", "permission": "1100" } ``` **Attributi (Stato):** ``` { "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione accesa, `off` indica alimentazione spenta. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "window-detection": { "powerState": "on" } } ``` **Interruttore Blocco Bambini (child-lock)** **Esempio di dichiarazione della capacità:** ``` { "capability": "child-lock", "permission": "1100" } ``` **Attributi (Stato):** ``` { "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione accesa, `off` indica alimentazione spenta. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "child-lock": { "powerState": "on" } } ``` **Interruttore Anti-Soffiaggio Diretto (anti-direct-blow)** **Esempio di dichiarazione della capacità:** ``` { "capability": "anti-direct-blow", "permission": "1100" } ``` **Attributi (Stato):** ``` { "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione accesa, `off` indica alimentazione spenta. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "anti-direct-blow": { "powerState": "on" } } ``` **Interruttore Oscillazione Orizzontale (horizontal-swing)** **Esempio di dichiarazione della capacità:** ``` { "capability": "horizontal-swing", "permission": "1100" } ``` **Attributi (Stato):** ``` { "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione accesa, `off` indica alimentazione spenta. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "horizontal-swing": { "powerState": "on" } } ``` **Interruttore Oscillazione Verticale (vertical-swing)** **Esempio di dichiarazione della capacità:** ``` { "capability": "vertical-swing", "permission": "1100" } ``` **Attributi (Stato):** ``` { "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione accesa, `off` indica alimentazione spenta. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "vertical-swing": { "powerState": "on" } } ``` **Modalità ECO (eco)** **Esempio di dichiarazione della capacità:** ``` { "capability": "eco", "permission": "1100" } ``` **Attributi (Stato):** ``` { "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione accesa, `off` indica alimentazione spenta. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "eco": { "powerState": "on" } } ``` **Avvio Alternato (toggle-startup)** **Esempio di dichiarazione della capacità:** ``` { "capability": "toggle-startup", "permission": "1100", "name": "1" // Il campo `name` specifica il nome dell'attributo per `toggle-startup`. **Tipo:** Stringa. Sono consentite solo lettere e numeri. } ``` **Attributi (Stato):** ``` { "startup": "on" // **Tipo:** Stringa. Opzioni: `on` (accensione), `stay` (mantenere accceso), `off` (spegnimento). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "toggle-startup": { "1": { "startup": "on" }, "2": { "startup": "off" } } } ``` **Rilevamento Mantenimento (detect-hold)** **Esempio di dichiarazione della capacità:** ``` { "capability": "detect-hold", "permission": "0100", "settings": { "detectHoldEnable": { // Impostazione abilitazione detect hold "permission": "01", "type": "boolean", "value": false }, "detectHoldSwitch": { // Impostazione azione detect hold "type": "enum", "permission": "01", "value": "on", "values": ["on", "off"] }, "detectHoldTime": { // Impostazione tempo detect hold "type": "numeric", "permission": "01", "min": 1, "max": 359, "value": 5, "unit": "minute" } } } ``` **Attributi (Stato):** ``` { "detectHold": "on" // Il campo `detectHold` indica lo stato del mantenimento del rilevamento. **Tipo:** Stringa. `on` significa che il mantenimento è attivo, `off` significa che il mantenimento è inattivo. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "detect-hold": { "detectHold": "on" } } ``` **Identificazione/Attivazione Alternata (toggle-identify)** **Esempio di dichiarazione della capacità:** ``` { "capability": "toggle-identify", "permission": "1100", // Nota: Questa capability non è utilizzata per il reporting nella versione corrente (V1.13.7) su ihost. "name": "1" // Nome del componente. **Tipo:** Stringa. Valori opzionali: "1" (Canale 1), "2" (Canale 2), "3" (Canale 3), "4" (Canale 4). } ``` **Attributi (Stato):** ``` { "identify": true, // Indica che il dispositivo ha segnalato attivamente l'identificazione o l'attivazione. "countdown": 180 // Il campo `countdown` indica la durata dell'attivazione. **Tipo:** Numero. Unità: secondi. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "toggle-identify": { "1": { "countdown": 180 // Attiva il dispositivo per 180 secondi. } } } // Il dispositivo segnala auto-attivazione { "toggle-identify": { "1": { "identify": true } } } ``` **Rilevamento Tensione Alternata (toggle-voltage)** **Esempio di dichiarazione della capacità:** ``` { "capability": "toggle-voltage", "permission": "1100" } ``` **Attributi (Stato):** ``` { "voltage": 230 // Il campo `voltage` indica la tensione rilevata. **Tipo:** Numero. Unità: Volt. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "toggle-voltage": { "voltage": 230 } } ``` **Rilevamento Corrente Elettrica Sottocomponente (toggle-electric-current)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "toggle-electric-current", "permission": "0100", "name": "1" // Nome del componente. **Tipo:** Stringa. Valori opzionali: "1" (Canale 1), "2" (Canale 2), "3" (Canale 3), "4" (Canale 4). } ] ``` **Attributi (Stato):** ``` { "electricCurrent": 50 // Il campo `electricCurrent` rappresenta il valore di corrente. **Unità:** 0.01 A. **Tipo:** Intero. Il valore deve essere maggiore o uguale a 0. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "toggle-electric-current": { "1": { "electricCurrent": 50 } } } ``` **Rilevamento Potenza Sottocomponente (toggle-electric-power)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "toggle-electric-power", "permission": "0100", "name": "1" // Nome del componente. **Tipo:** Stringa. Valori opzionali: "1" (Canale 1), "2" (Canale 2), "3" (Canale 3), "4" (Canale 4). } ] ``` **Attributi (Stato):** ``` { "electricPower": 50, // Il campo `electricPower` rappresenta il valore di potenza corrente. **Unità:** 0.01 W. **Tipo:** Intero. Il valore deve essere maggiore o uguale a 0. "reactivePower": 50, // Il campo `reactivePower` rappresenta il valore di potenza reattiva corrente. **Unità:** 0.01 W. **Tipo:** Intero. Facoltativo. "activePower": 50, // Il campo `activePower` rappresenta il valore di potenza attiva corrente. **Unità:** 0.01 W. **Tipo:** Intero. Facoltativo. "apparentPower": 50 // Il campo `apparentPower` rappresenta il valore di potenza apparente corrente. **Unità:** 0.01 W. **Tipo:** Intero. Facoltativo. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "toggle-electric-power": { "1": { "electricPower": 50, "reactivePower": 50, "activePower": 50, "apparentPower": 50 } } } ``` **Statistiche Consumo Energetico Sottocomponente (toggle-power-consumption)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "toggle-power-consumption", "permission": "1101", "name": "1", // Nome del componente. **Tipo:** Stringa. Valori opzionali: "1" (Canale 1), "2" (Canale 2), "3" (Canale 3), "4" (Canale 4). "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ] ``` **Attributi (Stato):** Avvia/Arresta statistiche in tempo reale: ``` { "rlSummarize": true, // Avvia o interrompe le statistiche in tempo reale. **Tipo:** Booleano. Obbligatorio. "timeRange": { // Intervallo di riepilogo. Obbligatorio. "start": "2020-07-05T08:00:00Z", // Ora di inizio del consumo energetico. **Tipo:** Stringa. Obbligatorio. "end": "2020-07-05T09:00:00Z" // Ora di fine del consumo energetico. **Tipo:** Stringa. Obbligatorio. } } ``` Interroga il consumo energetico per intervallo di tempo: ``` { "type": "summarize", // Tipo di riepilogo. **Tipo:** Stringa. Obbligatorio. Opzioni: "rlSummarize" (Riepilogo in tempo reale), "summarize" (Riepilogo corrente). "timeRange": { // Intervallo di riepilogo, obbligatorio quando il tipo è "summarize". "start": "2020-07-05T08:00:00Z", // Ora di inizio del consumo energetico. **Tipo:** Stringa. Obbligatorio. "end": "2020-07-05T09:00:00Z" // Ora di fine del consumo energetico. **Tipo:** Stringa. Facoltativo. Se non fornito, viene impostato l'orario corrente. } } ``` Risposta per Consumo Energetico nell'Intervallo di Tempo: ``` { "type": "summarize", // Tipo di riepilogo. **Tipo:** Stringa. Obbligatorio. "rlSummarize": 50.0, // Consumo energetico totale. **Unità:** 0.01 kWh. **Tipo:** Numero. Facoltativo. "electricityIntervals": [ // Suddiviso da `configuration.resolution` in più record. Facoltativo. Non presente quando il tipo è "rlSummarize". { "usage": 26.5, // Consumo energetico. **Unità:** 0.01 kWh. **Tipo:** Numero. Obbligatorio. "start": "2020-07-05T08:00:00Z", // Ora di inizio. **Tipo:** Stringa. Obbligatorio. "end": "2020-07-05T09:00:00Z" // Ora di fine. **Tipo:** Stringa. Obbligatorio. I record con intervalli più brevi della risoluzione sono considerati non validi. }, { "usage": 26.5, // Consumo energetico. **Unità:** 0.01 kWh. **Tipo:** Numero. Obbligatorio. "start": "2020-07-05T09:00:00Z", // Ora di inizio. **Tipo:** Stringa. Obbligatorio. "end": "2020-07-05T10:00:00Z" // Ora di fine. **Tipo:** Stringa. Obbligatorio. I record con intervalli più brevi della risoluzione sono considerati non validi. } ] } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Avvia statistiche in tempo reale: ``` { "toggle-power-consumption": { "1": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Arresta statistiche in tempo reale: ``` { "toggle-power-consumption": { "1": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Ottieni consumo energetico storico: ``` { "toggle-power-consumption": { "1": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Ottieni consumo energetico in tempo reale: ``` { "toggle-power-consumption": { "1": { "type": "rlSummarize" } } } ``` **Indicatore Qualità Collegamento (lqi)** **Esempio di dichiarazione della capacità:** ``` { "capability": "lqi", "permission": "0100" } ``` **Attributi (Stato):** ``` { "lqi": 60 // Il campo `lqi` rappresenta l'indicatore di qualità del collegamento. **Tipo:** Numero. Intervallo valori: 0 a 255. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "lqi": { "lqi": 60 } } ``` **Configurazione Funzionale (configuration)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "configuration", "permission": "1100" } ] ``` **Attributi (Stato):** ``` { "deviceConfiguration": { // Configurazione funzionale relativa al dispositivo "defaultResolution": 300, // Risoluzione predefinita per la lettura dei dati di saturazione dell'umidità. **Tipo:** Intero. **Unità:** Secondi. Obbligatorio. "maxResolution": 86400, // Risoluzione massima per la lettura dei dati di saturazione dell'umidità. **Tipo:** Intero. **Unità:** Secondi. Obbligatorio. "minResolution": 60 // Risoluzione minima per la lettura dei dati di saturazione dell'umidità. **Tipo:** Intero. **Unità:** Secondi. Obbligatorio. } } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "configuration": { "deviceConfiguration": { // Configurazione funzionale relativa al dispositivo "defaultResolution": 300, // Risoluzione predefinita per la lettura dei dati di saturazione dell'umidità. **Tipo:** Intero. **Unità:** Secondi. Obbligatorio. "maxResolution": 86400, // Risoluzione massima per la lettura dei dati di saturazione dell'umidità. **Tipo:** Intero. **Unità:** Secondi. Obbligatorio. "minResolution": 60 // Risoluzione minima per la lettura dei dati di saturazione dell'umidità. **Tipo:** Intero. **Unità:** Secondi. Obbligatorio. } } } ``` **Sistema (system)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "system", "permission": "1000" } ] ``` **Attributi (Stato):** ``` { "restart": true // Comando di riavvio del dispositivo. **Tipo:** Booleano. Obbligatorio. Il valore deve essere `true`. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "system": { // Configurazione relativa alla capability. Facoltativo. "restart": true } } ``` **Umidità (moisture)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "moisture", "permission": "0100" } ] ``` **Attributi (Stato):** ``` { "moisture": 55.5 // Il campo `moisture` rappresenta la percentuale di saturazione dell'umidità. **Tipo:** Numero. Obbligatorio. Intervallo: 0 a 100. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "moisture": { "moisture": 55.5 } } ``` **Pressione Barometrica (barometric-pressure)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "barometric-pressure", "permission": "0100", "settings": { "barometricPressureRange": { "type": "numeric", "permission": "01", "min": 540, // Valore minimo. **Tipo:** Intero. Obbligatorio. Deve essere inferiore a `max`. "max": 1100 // Valore massimo. **Tipo:** Intero. Obbligatorio. Deve essere maggiore di `min`. } } } ] ``` **Attributi (Stato):** ``` { "barometricPressure": 50 // Valore della pressione barometrica. **Tipo:** Intero. Obbligatorio. **Unità:** hPa. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "barometric-pressure": { "barometricPressure": 50 } } ``` **Velocità del Vento (wind-speed)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "wind-speed", "permission": "0100", "settings": { "windSpeedRange": { "type": "numeric", "permission": "01", "min": 0, // Valore minimo. **Tipo:** Numero. Obbligatorio. Deve essere inferiore a `max`. "max": 50 // Valore massimo. **Tipo:** Numero. Obbligatorio. Deve essere maggiore di `min`. } } } ] ``` **Attributi (Stato):** ``` { "windSpeed": 50 // Valore della velocità del vento. **Tipo:** Numero. Obbligatorio. **Unità:** m/s (metri al secondo). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "wind-speed": { "windSpeed": 50 } } ``` **Direzione del Vento (wind-direction)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "wind-direction", "permission": "0100" } ] ``` **Attributi (Stato):** ``` { "windDirection": 10 // Direzione del vento. **Tipo:** Intero. Obbligatorio. **Unità:** Gradi. Intervallo: 0 a 360 gradi (direzione oraria). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "wind-direction": { "windDirection": 10 } } ``` **Precipitazioni (rainfall)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "rainfall", "permission": "0100", "settings": { "rainfallRange": { "type": "numeric", "permission": "01", "min": 0, // Valore minimo. **Tipo:** Numero. Obbligatorio. Deve essere inferiore a `max`. "max": 450 // Valore massimo. **Tipo:** Numero. Obbligatorio. Deve essere maggiore di `min`. } } } ] ``` **Attributi (Stato):** ``` { "rainfall": 11.11 // Valore delle precipitazioni. **Tipo:** Numero. Obbligatorio. **Unità:** mm/h (millimetri all'ora). } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "rainfall": { "rainfall": 11.11 } } ``` **Indice Ultravioletti (ultraviolet-index)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "ultraviolet-index", "permission": "0100", "settings": { "ultravioletIndexRange": { "type": "numeric", "permission": "01", "min": 0, // Valore minimo. **Tipo:** Numero. Obbligatorio. Deve essere inferiore a `max`. "max": 16 // Valore massimo. **Tipo:** Numero. Obbligatorio. Deve essere maggiore di `min`. } } } ] ``` **Attributi (Stato):** ``` { "ultravioletIndex": 11.1 // Indice ultravioletti. **Tipo:** Numero. Obbligatorio. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "ultraviolet-index": { "ultravioletIndex": 11.1 } } ``` **Conducibilità Elettrica (electrical-conductivity)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "electrical-conductivity", "permission": "0100", "settings": { "electricalConductivityRange": { "type": "numeric", "permission": "01", "min": 0, // Valore minimo. **Tipo:** Numero. Obbligatorio. Deve essere inferiore a `max`. "max": 23 // Valore massimo. **Tipo:** Numero. Obbligatorio. Deve essere maggiore di `min`. } } } ] ``` **Attributi (Stato):** ``` { "electricalConductivity": 11.11 // Valore di conducibilità elettrica. **Tipo:** Numero. Obbligatorio. **Unità:** dS/m. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "electrical-conductivity": { "electricalConductivity": 11.11 } } ``` **Potenza di Trasmissione (transmit-power)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "transmit-power", "permission": "1100" } ] ``` **Attributi (Stato):** ``` { "transmitPower": 9 // Valore della potenza di trasmissione del dispositivo. **Tipo:** Intero. Obbligatorio. **Unità:** dBm. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "transmit-power": { "transmitPower": 9 } } ``` **Rilevamento PM2.5 (pm25)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "pm25", "permission": "0100" } ] ``` **Attributi (Stato):** ``` { "pm25": 10 // Concentrazione di PM2.5 nell'aria. **Tipo:** Numero. Obbligatorio. **Unità:** µg/m³. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "pm25": { "pm25": 10 } } ``` **Indice VOC (voc-index)** **Esempio di dichiarazione della capacità:** ``` { "capability": "voc-index", "permission": "0100" } ``` **Attributi (Stato):** ``` { "vocIndex": 10 // Indice VOC che riflette il livello di inquinamento da gas nocivi. **Tipo:** Numero. Obbligatorio. **Unità:** µg/m³. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "voc-index": { "vocIndex": 10 } } ``` **Rilevamento Gas Naturale (gas)** **Esempio di dichiarazione della capacità:** ``` { "capability": "gas", "permission": "0100" } ``` **Attributi (Stato):** ``` { "gas": true // Indica se è rilevata una perdita di gas naturale. **Tipo:** Booleano. Obbligatorio. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "gas": { "gas": true } } ``` **Stato Lavoro Irrigazione (irrigation/work-status)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "irrigation", "permission": "0101", "name": "work-status", "settings": { "volumeUnit": { "type": "enum", "permission": "01", "values": ["L"], "value": "L" } } } ] ``` **Attributi (Stato):** ``` { "realTimeVolume": 20, // Volume di irrigazione in tempo reale. **Tipo:** Numero. Facoltativo. **Unità:** L. "start": "2020-07-05T08:00:00Z", // Ora di inizio irrigazione. **Tipo:** Data. Facoltativo. "end": "2020-07-05T09:00:00Z", // Ora di fine irrigazione. **Tipo:** Data. Facoltativo. "dailyVolume": 20 // Volume di irrigazione giornaliero. **Tipo:** Numero. Facoltativo. **Unità:** L. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Segnalazione Stato Lavoro: ``` { "irrigation": { "work-status": { "realTimeVolume": 20, "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z", "dailyVolume": 20 } } } ``` Query Stato Lavoro: ``` { "irrigation": { "type": "oneDay", // Tipo di aggregazione. **Tipo:** Stringa. Obbligatorio. Opzioni: "oneDay", "30Days", "180Days". "timeRange": { // Intervallo di tempo per l'aggregazione. **Tipo:** Oggetto. Obbligatorio. "start": "2020-07-05T08:00:00Z", // Ora di inizio per l'aggregazione dei dati di irrigazione. **Tipo:** Stringa. Obbligatorio. "end": "2020-07-05T09:00:00Z" // Ora di fine per l'aggregazione dei dati di irrigazione. **Tipo:** Stringa. Facoltativo. Se omesso, viene usato l'orario corrente. } } } ``` Risultato Query Stato Lavoro: ``` { "irrigation": { "type": "oneDay", // Tipo di aggregazione. **Tipo:** Stringa. Obbligatorio. "irrigationIntervals": [ { "volume": 6500, // Volume di irrigazione. **Tipo:** Numero. Obbligatorio. **Unità:** L. "duration": 30, // Durata dell'irrigazione. **Tipo:** Numero. Obbligatorio. **Unità:** minuti. "start": "2020-07-05T08:00:00Z", // Ora di inizio. **Tipo:** Stringa. Obbligatorio. "end": "2020-07-05T09:00:00Z" // Ora di fine. **Tipo:** Stringa. Obbligatorio. }, { "volume": 6500, // Volume di irrigazione. **Tipo:** Numero. Obbligatorio. **Unità:** L. "duration": 30, // Durata dell'irrigazione. **Tipo:** Numero. Obbligatorio. **Unità:** minuti. "start": "2020-07-05T08:00:00Z", // Ora di inizio. **Tipo:** Stringa. Obbligatorio. "end": "2020-07-05T09:00:00Z" // Ora di fine. **Tipo:** Stringa. Obbligatorio. } ] } } ``` **Modalità Lavoro Irrigazione (irrigation/work-mode)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "irrigation", "permission": "0100", "name": "work-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", // Modalità manuale "TIMER", // Pianificazione a singola esecuzione "CYCLE-TIMER", // Pianificazione ripetuta "VOLUME", // Volume a singola esecuzione "CYCLE-VOLUME" // Volume ripetuto ] } } } ] ``` **Attributi (Stato):** ``` { "workMode": "MANUAL" // Modalità di lavoro irrigazione. **Tipo:** Stringa. Facoltativo. I valori devono essere presi da `settings.supportedModes`. } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** ``` { "irrigation": { "work-mode": "MANUAL" } } ``` **Controller Irrigazione Automatico (irrigation/auto-controller)** **Esempio di dichiarazione della capacità:** ``` [ { "capability": "irrigation", "permission": "1100", "name": "auto-controller", "settings": { "volumeRange": { // Intervallo di volume "type": "enum", "permission": "01", "min": 0, "max": 6500, "unit": "L" }, "timeRange": { // Intervallo di tempo "type": "enum", "permission": "01", "min": 1, "max": 86400, "unit": "second" }, "cycleCountRange": { // Intervallo numero di cicli "type": "enum", "permission": "01", "min": 1, "max": 100, "step": 1 } } } ] ``` **Attributi (Stato):** Pianificazione Singola o Ripetuta: ``` { "type": "time", // Modalità di irrigazione. **Tipo:** Stringa. Obbligatorio. Opzioni: "volume", "time". "action": { "perDuration": 60, // Durata per ciclo di irrigazione. **Tipo:** Numero. Obbligatorio. "intervalDuration": 20, // Intervallo tra cicli di irrigazione. **Tipo:** Numero. Obbligatorio. "count": 3 // Numero di cicli di irrigazione. **Tipo:** Numero. Obbligatorio. } } ``` Volume Singolo o Ripetuto: ``` { "type": "volume", // Modalità di irrigazione. **Tipo:** Stringa. Obbligatorio. Opzioni: "volume", "time". "action": { "perConsumedVolume": 60, // Volume consumato per ciclo di irrigazione. **Tipo:** Numero. Obbligatorio. "intervalDuration": 20, // Intervallo tra cicli di irrigazione. **Tipo:** Numero. Obbligatorio. "count": 3 // Numero di cicli di irrigazione. **Tipo:** Numero. Obbligatorio. } } ``` **Protocollo (interrogazione dello stato e istruzioni di controllo):** Pianificazione Singola o Ripetuta: ``` { "irrigation": { "auto-controller": { "type": "time", // Modalità di irrigazione. **Tipo:** Stringa. Obbligatorio. "action": { "perDuration": 60, // Durata per ciclo di irrigazione. **Tipo:** Numero. Obbligatorio. "intervalDuration": 20, // Intervallo tra i cicli. **Tipo:** Numero. Obbligatorio. "count": 3 // Numero di cicli. **Tipo:** Numero. Obbligatorio. } } } } ``` Volume Singolo o Ripetuto: ``` { "irrigation": { "auto-controller": { "type": "volume", // Modalità di irrigazione. **Tipo:** Stringa. Obbligatorio. "action": { "perConsumedVolume": 60, // Volume consumato per ciclo. **Tipo:** Numero. Obbligatorio. "intervalDuration": 20, // Intervallo tra i cicli. **Tipo:** Numero. Obbligatorio. "count": 3 // Numero di cicli. **Tipo:** Numero. Obbligatorio. } } } } ``` **Modalità Preimpostate Supportate** | \*\*Nomi Modalità \*\* | \*\*Valori Facoltativi \*\* | | ----------------------------------------------------- | --------------------------- | | fanLevel (livello ventola) | "low" | | "medium" | | | "high" | | | thermostatMode(Modalità Termostato) | "auto" | | "manual" | | | airConditionerMode >= 1.11.0(Modalità Condizionatore) | "cool" | | "heat" | | | "auto" | | | "fan" | | | "dry" | | | fanMode >= 1.11.0(Modalità Ventilatore) | "normal" | | "sleep" | | | "child" | | | horizontalAngle >= 1.11.0(Angolo Orizzontale) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | | verticalAngle >= 1.11.0(Angolo Verticale) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | #### c. Descrizione dei Tag * La chiave speciale toggle è usata per impostare il nome della sottocomponente toggle. ``` { "toggle": { '1': 'Canale1', '2': 'Canale2', '3': 'Canale3', '4': 'Canale4', }, } ``` * La chiave speciale temperature\_unit è usata per impostare l'unità di temperatura. ``` { "temperature_unit":'c' // c-Celsius; f-Fahrenheit } ``` #### d. Codice di Errore Speciale e Descrizione | **Codice Errore** | **Descrizione** | Versione iHost | | ----------------- | ---------------------------------------------------------------------------------- | -------------- | | 110000 | Il sottodispositivo/gruppo corrispondente all'id non esiste | ≥2.1.0 | | 110001 | Il gateway è nello stato di scoperta dispositivi zigbee | ≥2.1.0 | | 110002 | I dispositivi in un gruppo non hanno una capability comune | ≥2.1.0 | | 110003 | Numero di dispositivi errato | ≥2.1.0 | | 110004 | Numero di gruppi errato | ≥2.1.0 | | 110005 | Dispositivo Offline | ≥2.1.0 | | 110006 | Aggiornamento stato dispositivo non riuscito | ≥2.1.0 | | 110007 | Aggiornamento stato gruppo non riuscito | ≥2.1.0 | | 110008 | Raggiunto il numero massimo di gruppi. Crea fino a 50 gruppi | ≥2.1.0 | | 110009 | L'indirizzo IP del dispositivo camera è errato | ≥2.1.0 | | 110010 | Errore di autorizzazione accesso dispositivo camera | ≥2.1.0 | | 110011 | Errore indirizzo stream dispositivo camera | ≥2.1.0 | | 110012 | La codifica video del dispositivo camera non è supportata | ≥2.1.0 | | 110013 | Dispositivo già esistente | ≥2.1.0 | | 110014 | La camera non supporta il funzionamento offline | ≥2.1.0 | | 110015 | La password dell'account non è coerente con la password nell'indirizzo stream RTSP | ≥2.1.0 | | 110016 | Il gateway è nello stato di scoperta camere onvif | ≥2.1.0 | | 110017 | Superato il numero massimo di camere aggiunte | ≥2.1.0 | | 110018 | Il percorso della camera ESP è errato | ≥2.1.0 | | 110019 | Accesso all'indirizzo di servizio del dispositivo di terze parti non riuscito | ≥2.1.0 | #### e. Ricerca di Sottodispositivo Consente agli utenti autorizzati di abilitare o disabilitare la ricerca gateway per sottodispositivi tramite questa interfaccia * 💡Nota: Al momento supporta solo la ricerca di sottodispositivi Zigbee. * 💡Nota: I sottodispositivi Zigbee saranno aggiunti automaticamente dopo la ricerca. Non è necessario utilizzare l'interfaccia "Aggiungi manualmente sottodispositivi" :::tips * **URL**：/open-api/V2/rest/devices/discovery * **Metodo**: PUT * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------------------------------------------- | | enable | boolean | N | true (Avvia abbinamento); false (Pausa abbinamento) | | type | string | N | Tipo di Ricerca: Zigbee | Risposta dati di successo: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\* `200 OK` ::: **Esempio di risposta**: ``` { "error": 0, "data": {}, "message": "success" } ``` #### f. Aggiunta Manuale del Sottodispositivo Consente agli utenti autorizzati di aggiungere un **singolo** sottodispositivo tramite questa interfaccia. * Nota: Al momento sono supportate solo RTSP Camera e ESP32 Camera :::tips * **URL**：/open-api/V2/rest/devices * **Metodo**：POST * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ----------------- | ------------------- | ------------- | ------------------------------------------------------------------------------------------------------- | | name | string | N | Nome sottodispositivo | | display\_category | string | N | Tipo di dispositivo. Supporta solo camera. | | capabilities | CapabilityObject\[] | N | Elenco delle capability. Quando display\_category = camera, le capability includono solo camera-stream. | | protocal | string | N | Protocollo del dispositivo. RTSP; ESP32-CAM | | manufacturer | string | N | Produttore. | | model | string | N | Modello del dispositivo | | firmware\_version | string | N | Versione firmware del dispositivo | CapabilityObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------------------------- | ------------- | ---------------------------------------------------- | | capability | string | N | Nome della capability. Supporta solo "camera-stream" | | permission | string | N | Permesso del dispositivo. Supporta solo read. | | configuration | CameraStreamConfigurationObject | Y | Configurazione dello stream della camera. | SettingsObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------------- | ------------- | ---------------------------------------- | | streamSetting | StreamSettingObject | N | Configurazione del servizio di streaming | StreamSettingObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------------------ | ------------- | ------------------------------------------------------------- | | type | string | N | Configurazione del servizio di streaming | | permission | string | N | Permesso della capability. Supporta solo "11" (modificabile). | | campo value | StreamSettingValueObject | N | Valori di configurazione specifici | StreamSettingValueObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | ------------------------ | | stream\_url | string | N | Formato URL dello stream | | Formato:`://:/:@` | | | | | Esempio:`rtsp://admin:123456@192.168.10.115:554/streaming/channel01` | | | | | Opzioni Schema: | | | | | `rtsp` (Real-Time Streaming Protocol) | | | | | `http` (Hypertext Transfer Protocol) — Per dispositivi ESP32-CAM | | | | | \*Nota: Alcune camere potrebbero non richiedere nome utente o password. In tal caso, è possibile omettere `` e `` campi dall'URL. | | | | Risposta dati di successo: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------- | -------- | ------------- | --------------------------------------- | | serial\_number | string | N | Numero di serie univoco del dispositivo | :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ``` { "error": 0, "data": { "serial_number": "serial_number" }, "message": "success" } ``` Risposta dati di errore: Oggetto vuoto :::tips **Condizione**： 1. Errore accesso indirizzo stream camera (errore formato, autorizzazione fallita, eccezione di rete, ecc.) 2. Dispositivo già esistente 3. Se un singolo dispositivo non viene aggiunto correttamente, vengono restituiti tutti i dispositivi non aggiunti. **Codice Stato**: 200 OK **Codice di errore**： ● 110009 Errore indirizzo IP camera ● 110010 Errore autorizzazione accesso camera ● 110011 Errore indirizzo stream camera ● 110012 La codifica video della camera non è supportata ● 110013 Dispositivo già esistente ::: **Esempio di risposta**: ``` { "error": 110009, "data": {}, "message": "accesso IP camera non riuscito" } ``` #### g. Ottieni Elenco dei Sottodispositivi Consente agli utenti autorizzati di ottenere l'elenco dei sottodispositivi del gateway tramite questa interfaccia. :::tips * **URL**：/open-api/V2/rest/devices * **Metodo**: GET * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: nessuno Risposta dati di successo: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ----------------------- | ------------- | ------------------ | | device\_list | ResponseDeviceObject\[] | N | Elenco dispositivi | ResponseDeviceObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | --------------------- | ------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numero di serie univoco del dispositivo | | third\_serial\_number | string | "N" quando è connesso un dispositivo di terze parti, altrimenti "Y" | Numero di serie univoco del dispositivo di terze parti | | service\_address | string | "N" quando è connesso un dispositivo di terze parti, altrimenti "Y" | Indirizzo del servizio di terze parti | | name | string | N | Nome del dispositivo; se non viene rinominato, sarà visualizzato dal front-end secondo le regole di visualizzazione predefinite. | | manufacturer | string | N | Produttore | | model | string | N | Modello del dispositivo | | firmware\_version | string | N | Versione firmware. Può essere una stringa vuota. | | hostname | string | Y | Hostname del dispositivo | | mac\_address | string | Y | Indirizzo MAC del dispositivo | | app\_name | string | Y | Il nome dell'applicazione a cui appartiene. Se app\_name è stato compilato durante l'ottenimento del certificato open interface, tutti i dispositivi successivamente connessi tramite il certificato saranno scritti in questo campo. | | display\_category | string | N | Categoria dispositivo | | capabilities | CapabilityObject\[] | N | Capability del dispositivo | | protocol | string | "N" quando è connesso un dispositivo di terze parti, altrimenti "Y" | Protocollo del dispositivo: zigbee, onvif, rtsp, esp32-cam | | state | object | Y | Oggetto stato del dispositivo. Per esempi di stato di diverse capacità, consultare 【Support Device Capabilities】 | | tag | object | Y | Chiave-valore in formato JSON, informazioni personalizzate del dispositivo. La funzione è la seguente:- Utilizzato per memorizzare i canali del dispositivo- Utilizzato per memorizzare le unità di temperatura- Informazioni personalizzate per altri dispositivi di terze parti | | online | boolean | N | Stato online: True per onlineFalse è offline | | sottorete | boolean | Y | Se è nella stessa sottorete del gateway | CapabilityObject 💡Nota: Si prega di controllare gli esempi di capacità dispositivo supportate per \[Supported Device Capabilities]. | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | capability | string | N | Nome della capacità. Per dettagli, consultare \[Supported Device Capabilities] | | permission | string | N | Permesso della capacità. I valori possibili sono "read" (leggibile), "write" (scrivibile), "readWrite" (leggibile e scrivibile). | | configuration | object | Y | Informazioni di configurazione della capacità. Attualmente viene utilizzato camera-stream, controllare \[Supported Device Capabilities] | | name | string | Y | Il campo name in toggle. Il numero del sotto-canale usato per identificare dispositivi multi-canale. Ad esempio, se name è 1, significa canale 1. | :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ``` { "error": 0, "data":{ "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "Il Mio Dispositivo", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "readWrite" }, { "capability": "rssi", "permission": "read" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ], } "message": "success" } ``` #### h. Aggiorna informazioni o stato dispositivo specificato Consente agli utenti autorizzati di modificare le informazioni di base del sottodispositivo e inviare comandi di controllo tramite questa interfaccia. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Metodo**：PUT * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------ | | name | string | Y | Nome del dispositivo | | tag | object | Y | Chiave-valore in formato JSON, informazioni personalizzate del dispositivo. | | state | object | Y | Oggetto stato del dispositivo. Per esempi di stato di diverse capacità, controllare \[Support Device Capabilities] | | configuration | object | Y | Informazioni di configurazione della capacità, attualmente solo la capacità camera\_stream supporta la modifica. | Risposta dati riuscita: :::tips **Condizioni**: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. \*\*Codice di Stato: \*\*200 OK **Codice Errore**: * 110000 Il sottodispositivo/gruppo corrispondente all'id non esiste ::: **Esempio di risposta**: ``` { "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. Elimina Sottodispositivo Consente agli utenti autorizzati di eliminare i sottodispositivi tramite questa interfaccia. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Metodo**：DELETE * **Header**： * Content-Type: application/json * Autorization: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Y | Nome del dispositivo. | | tag | object | Y | Coppie chiave-valore in formato JSON utilizzate per memorizzare i nomi dei canali del dispositivo e altre informazioni sui sottodispositivi. | | state | object | Y | Modifica lo stato del dispositivo; per dettagli specifici del protocollo fare riferimento a "Supported Device Capabilities." | | capabilities | CapabilityObject \[] | Y | Informazioni di configurazione della capacità; tutte le capacità che supportano l'impostazione delle configurazioni possono essere modificate. Nota che i permessi non possono essere cambiati. | Risposta dati riuscita: :::tips **Condizioni**: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. \*\*Codice di Stato: \*\*200 OK **Codici di errore:** * 110000: Il sottodispositivo/gruppo corrispondente all'ID non esiste. * 110006: Impossibile aggiornare lo stato del dispositivo. * 110019: Impossibile accedere all'indirizzo del servizio del dispositivo di terze parti. * 110024: Impossibile aggiornare la configurazione del dispositivo. ::: **Esempio di risposta**: ``` { "error": 0, "data": {}, "message": "success" } ``` ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // accendi 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. Elimina Sott-Dispositivo Consente agli utenti autorizzati di eliminare i sottodispositivi tramite questa interfaccia.\ :::tips * **URL**：`/open-api/v2/rest/devices/{serial_number}` * **Metodo**：`DELETE` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: Nessuno Risposta dati riuscita: :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### k. Query Stato Dispositivo Consente agli utenti autorizzati di interrogare lo stato del dispositivo tramite questa interfaccia.\ :::tips * **URL**：`/open-api/v2/rest/devices/:serial_number/query-state/{capability}` * **Metodo**：POST * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------- | | query\_state | object | N | Interroga lo stato del dispositivo; per dettagli specifici del protocollo fare riferimento a "Supported Device Capabilities." | ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // accendi 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 di statistiche, obbligatorio "timeRange": { // Intervallo di tempo per la sintesi, obbligatorio quando type="summarize" "start": "2020-07-05T08:00:00Z", // Ora di inizio per le statistiche di consumo energetico "end": "2020-07-05T09:00:00Z" // Ora di fine per le statistiche di consumo energetico; se omesso, predefinito all'ora corrente } } } }); })() ``` Risposta dati riuscita: :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.4 Gestione della Sicurezza #### a. Ottieni Elenco Sicurezza Consente agli utenti autorizzati di modificare le impostazioni del gateway tramite questa interfaccia. :::tips * **URL**：`/open-api/v2/rest/security` * **Metodo**：`GET` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: Nessuno Risposta dati riuscita: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------- | ------------------------- | ------------- | ------------------------------ | | security\_list | ResponseSecurityObject\[] | N | Elenco dispositivi di risposta | ResponseDeviceObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------- | | sid | int | N | id sicurezza | | name | string | N | Nome sicurezza | | enable | bool | N | Se abilitato | * true Abilitato * false Disabilitato | :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": { "security_list":[ { "sid": 1, "name": "Home Mode", "enable": true } ] }, "message": "success" } ``` #### b. Abilita Modalità di Sicurezza Specificata Consente agli utenti autorizzati di abilitare una modalità di sicurezza specificata tramite questa interfaccia.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/enable` * **Metodo**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: Nessuno Risposta dati riuscita: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### c. Disabilita Modalità di Sicurezza Specificata Consente agli utenti autorizzati di disabilitare una modalità di sicurezza specificata tramite questa interfaccia.\ :::tips * **URL**：`/open-api/v2/rest/security/{security_id}/disable` * **Metodo**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: Nessuno Risposta dati riuscita: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Abilitazione Rapida della Sicurezza Consente agli utenti autorizzati di abilitare la modalità di configurazione di sicurezza con un clic tramite questa interfaccia.\ :::tips * **URL**：`/open-api/v2/rest/security/enable` * **Metodo**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: Nessuno Risposta dati riuscita: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### e. Disabilita Sicurezza Consente agli utenti autorizzati di disabilitare la sicurezza tramite questa interfaccia.\ :::tips * **URL**：`/open-api/v2/rest/security/disable` * **Metodo**：`PUT` * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: Nessuno Risposta dati riuscita: Oggetto vuoto {} :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\*200 OK ::: **Esempio di risposta**: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 4. Accesso Dispositivi di Terze Parti ### 4.1 Istruzioni di Accesso #### Accesso Dispositivo
#### Accesso Gateway di Terze Parti
#### Passi di accesso 1. Determinare la classificazione del dispositivo nel gateway. Per i dettagli consultare \[Supported Device Type]. 2. Determinare le capacità a cui il dispositivo può accedere. Per i dettagli consultare \[Supported Device Capabilities]. 3. Richiedere l'interfaccia \[Discovery Request] per aggiungere il dispositivo al gateway. 1. *Attenzione: È necessario fornire l'indirizzo del servizio per ricevere le istruzioni emesse dal gateway, che viene utilizzato per ricevere i comandi di controllo del dispositivo emessi dal gateway*. 4. Se lo stato del dispositivo di terze parti cambia, è necessario chiamare l'interfaccia \[Device States Change Report] per inviare lo stato più aggiornato al gateway. 5. Dopo l'aggiunta, il dispositivo di terze parti apparirà nell'Elenco Dispositivi, con la maggior parte delle funzioni del gateway (altri dispositivi non di terze parti). Le interfacce aperte comuni correlate al dispositivo possono essere utilizzate normalmente. * Selezionare la categoria di dispositivo appropriata. La classificazione influenzerà il risultato finale della visualizzazione dell'interfaccia utente dopo che il dispositivo è connesso al gateway. * Scegliere la capacità di dispositivo corretta. L'elenco delle capacità determinerà lo stato del protocollo di stato del dispositivo. #### Processo del Programma **a. Accesso Dispositivo**
**b. Accesso Gateway di Terze Parti**
### 4.2 Esempio di Accesso #### Interruttore, Presa **Sincronizza dispositivi di terze parti** ``` // Richiesta URL：/open-api/v2/rest/thirdparty/event Metodo：POST Header： Content-Type: application/json Autorization: Bearer Body: { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "2" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "la mia presa", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "1100" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "nome produttore", "model": "nome modello", "firmware_version": "versione firmware", "service_address": "http://192.168.31.14/webhook" } ] } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number", "serial_number": "numero seriale" } ] } } ``` **Segnala lo stato del dispositivo** ``` URL：/open-api/V2/rest/thirdparty/event Metodo：POST Header： Content-Type: application/json Autorization: Bearer Body: { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": {} } ``` **Segnala offline/online** ``` {  "event": {    "header": {      "name": "DeviceStatesChangeReport",      "message_id": "Identificatore univoco, preferibilmente un UUID versione 4",      "version": "1"   },    "endpoint": {      "serial_number": "serial_number"   },    "payload": {       "online": true   } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": {} } ``` **Ricevi le istruzioni relative al controllo del dispositivo da parte del gateway** ``` URL： Metodo：POST Header：  Content-Type: application/json B {  "directive": {    "header": {      "name": "UpdateDeviceStates",      "message_id": "Identificatore univoco, preferibilmente un UUID versione 4",      "version": "1"   },    "endpoint": {      "third_serial_number": "third_serial_number",      "serial_number": "serial_number"   },    "payload": {       "state": : {         "power": {           "powerState": "on"         }       }   } } } ``` ``` { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": {} } ``` **Interroga dispositivo** ``` URL：/open-api/V2/rest/devices Method：GET Header：  Content-Type: application/json  Autorization: Bearer   Body: Nessuno ``` ``` { "error": 0, "data": { "device_list": [ { "serial_number": "numero seriale", "third_serial_number": "third_serial_number", "name": "la mia presa", "manufacturer": "nome produttore", "model": "nome modello", "firmware_version": "versione firmware", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ] }, "message": "success" } ``` ### 4.3 Web API #### Interfaccia di richiesta per terze parti verso il gateway **Formato di richiesta** Consente agli utenti autorizzati di inviare richieste di evento al gateway tramite questa interfaccia. :::tips * **URL**：/open-api/V2/rest/thirdparty/event * **Metodo**：POST * **Header**： * Content-Type: application/json * Authorization: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ----------- | ------------- | ---------------------------------------------------------------- | | evento | EventObject | N | Informazioni sulla struttura dell'oggetto evento della richiesta | EventObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione della richiesta | | endpoint | EndpointObject | Y | Informazioni sulla struttura dell'endpoint della richiesta Nota: Questo campo è vuoto quando si sincronizza un nuovo elenco di dispositivi. | | payload | PayloadObject | N | Informazioni sulla struttura del payload della richiesta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nome della richiesta. parametro opzionale: DiscoveryRequest: Sincronizza nuovi dispositivi DeviceStatesChangeReport: Report di aggiornamento stato dispositivo DeviceOnlineChangeReport: Report stato online del dispositivo | | message\_id | string | N | ID messaggio della richiesta, UUID\_V4 | | version | string | N | Numero di versione del protocollo della richiesta. Attualmente fissato a 1 | EndpointObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | --------------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numero di serie univoco del dispositivo | | third\_serial\_number | string | N | Numero di serie univoco del dispositivo di terze parti | | tag | object | Y | Chiave-valore in formato JSON, informazioni personalizzate del dispositivo. \[Funzione di gestione dispositivo] - \[Descrizione dei tag] | PayloadObject In base al diverso header.name ha diverse strutture di richiesta. **Formato di risposta** :::tips \*\*Codice di Stato: \*\*200 OK **Parametri di risposta:** ::: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------- | ------------- | ---------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione di risposta | | payload | PayloadObject | N | Informazioni sulla struttura del payload di risposta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nome dell'intestazione di risposta. parametri opzionali:Response: Risposta riuscita ErrorResponse: Risposta di errore | | message\_id | string | N | ID messaggio dell'intestazione di risposta, UUID\_V4. Passare qui l'header.message\_id del messaggio di richiesta \*Se la richiesta in ingresso non contiene message\_id, questo campo sarà una stringa vuota nella risposta. | | version | string | N | - Numero di versione del protocollo della richiesta. Attualmente fissato a 1. | > Risposta riuscita--PayloadObject ： A seconda del tipo di richiesta, la struttura della risposta è diversa. Per i dettagli, fare riferimento al documento di istruzioni della richiesta specifica. > Risposta di errore--PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------- | | type | string | N | Tipi di errore: | * INVALID\_PARAMETERS: Errore nei parametri * AUTH\_FAILURE: Errore di autorizzazione * INTERNAL\_ERROR: Errore interno del servizio | | descrizione | stringa | N | Descrizione dell'errore | **DiscoveryRequest Sincronizza un nuovo elenco di dispositivi** * Nota: Dopo che il dispositivo è sincronizzato nel gateway, è online di default, cioè online=true. I successivi cambiamenti di online dipendono completamente dalla sincronizzazione con la terza parte tramite l'interfaccia DeviceOnlineChangeReport. **Parametri della richiesta:** EndpointObject\*\*：\*\*Nessuno PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ----------------- | ------------- | ------------------ | | endpoints | EndpointObject\[] | N | Elenco dispositivi | EndpointObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | --------------------- | ------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | third\_serial\_number | string | N | Numero di serie univoco del dispositivo di terze parti | | name | string | N | Nome del dispositivo | | display\_category | string | N | Categoria del dispositivo. Consultare \[Supported Device Type] per dettagli. \*I dispositivi di terze parti non supportano l'aggiunta di telecamere al momento. | | capabilities | CapabilityObject\[] | N | Elenco delle capacità | | state | object | N | Informazioni di stato iniziali | | manufacturer | string | N | Produttore | | model | string | N | Modello del dispositivo | | tag | object | Y | Chiave-valore in formato JSON, informazioni personalizzate del dispositivo:Usato per memorizzare i canali del dispositivoUsato per memorizzare le unità di temperaturaAltri dati personalizzati di terze parti | | firmware\_version | string | N | Versione del firmware | | service\_address | string | N | Indirizzo del servizio. Per esempio | Esempio di richiesta : ``` { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "la mia presa", "display_category": "plug", "capabilities": [ { "capability": "power", "permission" "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "nome produttore", "model": "nome modello", "firmware_version": "versione firmware", "service_address": "http://192.168.31.14/service_address" } ] } } } ``` **Parametri di risposta:** PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ----------------- | ------------- | ------------------ | | endpoints | EndpointObject\[] | N | Elenco dispositivi | EndpointObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | --------------------- | -------- | ------------- | ------------------------------------------------------ | | serial\_number | string | N | Numero di serie univoco del dispositivo | | third\_serial\_number | string | N | Numero di serie univoco del dispositivo di terze parti | Esempio di risposta corretta: ``` { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "endpoints": [ { "serial_number": "numero seriale", "third_serial_number": "third_serial_number" } ] } } ``` Esempio di risposta di errore: ``` { "header": { "name": "ErrorResponse", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "webhook cannot be empty" } } ``` **DeviceStatesChangeReport Report di cambiamento dello stato del dispositivo** * Nota: Rapporti di stato ripetuti possono attivare falsamente scene associate. **Parametri della richiesta:** PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------------------------------------------------------------- | | state | object | N | Stato del dispositivo, Vedere \[Supported device cabilities] per dettagli | Esempio di richiesta : ``` { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Parametri di risposta:** PayloadObject: Oggetto Vuoto Esempio di risposta riuscita: ``` { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": {} } ``` **DeviceOnlineChangeReport Report sullo stato online del dispositivo** * Nota: Rapporti di stato ripetuti possono attivare falsamente scene associate. **Parametri della richiesta:** PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------- | -------- | ------------- | ----------------------------------------- | | online | boolean | N | Stato online del dispositivo true: Online | | false: Offline | | | | Esempio di richiesta : ``` { "event": { "header": { "name": "DeviceOnlineChangeReport", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": true } } } ``` **Parametri di risposta:** PayloadObject: Oggetto Vuoto Esempio di risposta riuscita: ``` { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": {} } ``` **DeviceInformationUpdatedReport Report di Aggiornamento Informazioni Dispositivo** * Nota: L'aggiornamento può influire su scene esistenti o funzioni di sicurezza. **Parametri della richiesta:** PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------- | | capabilities | | | | \| CapabilityObject\[] \| N \| Elenco delle capacità. I dettagli possono essere trovati nella sezione capacità dispositivo supportate. \*\*Nota: \*\*Questo parametro aggiornerà solo il `campo value` del `impostazione` chiave all'interno del `CapabilityObject`, e gli aggiornamenti sono consentiti solo se il `permission` per la `impostazione` chiave è `11` o `01`. Per la definizione strutturale specifica del `impostazione` in `CapabilityObject`, fare riferimento alla descrizione dettagliata nella sezione 2.3 Categorie di visualizzazione dispositivo & Capacità dispositivo. | | tags \| oggetto \| Y \| Chiave-valore in formato JSON, informazioni personalizzate del dispositivo. * Può essere usato per memorizzare i canali del dispositivo * Può essere usato per memorizzare le unità di temperatura * Altri dati personalizzati di terze parti | Esempio di richiesta : ```json { "event": { "header": { "name": "DeviceInformationUpdatedReport", "message_id": "Identificatore univoco, preferibilmente un UUID versione 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, } } } ] } } } ``` **parametri di risposta:** PayloadObject: Oggetto Vuoto Esempio di risposta riuscita: ```json { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "2" }, "payload": {} } ``` #### Il gateway invia l'interfaccia di istruzione tramite l'indirizzo del servizio del dispositivo * Nota: 1. Le terze parti devono rispondere alla richiesta del gateway entro 3s. Altrimenti, il gateway giudicherà il timeout di elaborazione del comando. 2. Se il servizio di terze parti è offline, il gateway imposterà il dispositivo in stato offline, e il servizio di terze parti deve segnalare lo stato del dispositivo (DeviceStatesChangeReport) o lo stato online (DeviceOnlineChangeReport) prima di ritornare online. **Formato della richiesta** Il gateway invia istruzioni alla terza parte tramite l'interfaccia dell'indirizzo del servizio del dispositivo. :::tips * **URL**： * **Metodo**：POST * **Header**： * Content-Type: application/json ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | --------------- | ------------- | --------------------------------------------------- | | directive | DirectiveObject | N | Informazioni sulla struttura dell'oggetto direttiva | DirectiveObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------------- | ------------- | -------------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione della richiesta | | endpoint | EndpointObject | N | Informazioni sulla struttura dell'endpoint della richiesta | | payload | PayloadObject | N | Informazioni sulla struttura del payload della richiesta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | -------------------------------------------------------------------------------------------- | | name | string | N | Nome della richiesta. Parametri opzionali:UpdateDeviceStates: Aggiorna stati del dispositivo | | message\_id | string | N | ID messaggio della richiesta, UUID\_V4 | | version | string | N | Numero di versione del protocollo della richiesta. Attualmente fissato a 1. | EndpointObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | --------------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numero di serie univoco del dispositivo | | third\_serial\_number | string | N | Numero di serie univoco del dispositivo di terze parti | | tag | object | N | Chiave-valore in formato JSON, informazioni personalizzate del dispositivo. \[Funzione di gestione dispositivo] - \[Descrizione dei tag] | PayloadObject: In base a diversi `header.name`, esiste una struttura di richiesta specifica per ciascuno. Esempio di richiesta : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", "tags": {} }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Formato di risposta** :::tips \*\*Codice di Stato HTTP: \*\*200 OK **Attributo di risposta HTTP：** ::: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ----------- | ------------- | ---------------------------------------------------- | | evento | EventObject | N | Informazioni sulla struttura dell'evento di risposta | EventObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------- | ------------- | -------------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione della richiesta | | payload | PayloadObject | N | Informazioni sulla struttura del payload della richiesta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Nome dell'intestazione di risposta. Parametro opzionale: UpdateDeviceStatesResponse: Risposta aggiornamento stati dispositivo ErrorResponse: Risposta di errore | | message\_id | string | N | ID messaggio dell'intestazione di risposta, UUID\_V4. Passare qui l'header.message\_id del messaggio di richiesta | | version | string | N | Numero di versione del protocollo della richiesta. Attualmente fissato a 1. | > Risposta riuscita--PayloadObject： A seconda del tipo di richiesta, la struttura della risposta è diversa. Per i dettagli, fare riferimento al documento di istruzioni della richiesta specifica. > Risposta di errore--PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------- | | type | string | N | **Tipi di errore**: | * **ENDPOINT\_UNREACHABLE**: Dispositivo irraggiungibile o offline * **ENDPOINT\_LOW\_POWER**: Il dispositivo è in modalità a basso consumo e non può essere controllato * **INVALID\_DIRECTIVE**: Direttiva anomala dal gateway * **NO\_SUCH\_ENDPOINT**: Il dispositivo non esiste * **NOT\_SUPPORTED\_IN\_CURRENT\_MODE**: La modalità corrente non supporta l'operazione * **INTERNAL\_ERROR**: Errore interno del servizio * **REMOTE\_KEY\_CODE\_NOT\_LEARNED**: Codice tasto del telecomando non appreso | :::tips **Condizioni**: I parametri della richiesta sono validi. \*\*Codice di Stato: \*\*200 OK **Parametri di risposta:** ::: ``` { "event": { "header": { "name": "UpdateDeviceStatesResponse", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": {} } } ``` ``` { "event": { "header": { "name": "ErrorResponse", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "type": "ENDPOINT_UNREACHABLE" } } } ``` **UpdateDeviceStates** **Parametri della richiesta:** PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | -------------------------------------------------------------------------- | | state | object | N | Stato del dispositivo, Vedere \[Supported device cabilities] per dettagli. | Esempio di richiesta : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": : { "power": { "powerState": "on" } } } } } ``` **Parametri di risposta:** PayloadObject：Oggetto Vuoto Esempio di Risposta Riuscita ``` { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": {} } ``` **QueryDeviceStates** **Parametri della richiesta:** PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | -------------------------------------------------------------------------- | | state | object | N | Stato del dispositivo, Vedere \[Supported device cabilities] per dettagli. | Esempio di richiesta : ```json { "directive": { "header": { "name": "QueryDeviceStates", "message_id": "Identificatore univoco, preferibilmente un UUID versione 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", // Ora di inizio per le statistiche di consumo energetico, obbligatoria. "end": "2020-07-05T09:00:00Z" // Ora di fine per le statistiche di consumo energetico, obbligatoria. } } } } } } ``` **Parametri di risposta:** PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | -------------------------------------------------------------------------- | | state | object | N | Stato del dispositivo, Vedere \[Supported device cabilities] per dettagli. | **Esempio di risposta:** ```json { "event": { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "2" }, "payload": { "state": { "power-consumption": { "electricityIntervals": [ // Suddiviso in più record in base alla configurazione.resolution { "usage": 26.5, // Valore di consumo energetico, obbligatorio. Tipo: number. "start": "2020-07-05T08:00:00Z", // Ora di inizio, obbligatoria. Tipo: date. "end": "2020-07-05T09:00:00Z" // Ora di fine, obbligatoria. Tipo: date. Se l'intervallo tra end e start è inferiore a resolution, tutti i record segnalati sono considerati non validi. }, { "usage": 26.5, // Valore di consumo energetico, obbligatorio. Tipo: number. "start": "2020-07-05T09:00:00Z", // Ora di inizio, obbligatoria. Tipo: date. "end": "2020-07-05T10:00:00Z" // Ora di fine, obbligatoria. Tipo: date. Se l'intervallo tra end e start è inferiore a resolution, tutti i record segnalati sono considerati non validi. } ] } } } } } ``` **ConfigureDeviceCapabilities** **Parametri della richiesta:** PayloadObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | capabilities | CapabilityObject\[] | N | Elenco delle capacità. I dettagli possono essere visti nella parte delle capacità dispositivo supportate. Nota, il campo permission non può essere modificato, passare lo stesso valore durante la sincronizzazione. | Esempio di richiesta : ```json { "directive": { "header": { "name": "ConfigureDeviceCapabilities", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "2" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Tipo di rilevamento controllo temperatura, obbligatorio. Valori opzionali: humidity (rilevamento umidità), temperature (rilevamento temperatura) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Impostazioni di rilevamento supportate, obbligatorie. { "name": "lowerSetpoint", // Valore minimo che il rilevamento deve mantenere. Deve essere fornito lowerSetpoint o upperSetpoint. "value": { // Intervallo di rilevamento, opzionale. Compilare se ci sono condizioni preimpostate. "value": 68.0, // Valore di temperatura o umidità, obbligatorio. "scale": "f" // Unità di temperatura, obbligatoria se name=temperature. Opzioni: c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Valore massimo che il rilevamento deve mantenere. Deve essere fornito lowerSetpoint o upperSetpoint. "value": { // Intervallo di rilevamento, opzionale. Compilare se ci sono condizioni preimpostate. "value": 68.0, // Valore di temperatura o umidità, obbligatorio. "scale": "f" // Unità di temperatura, obbligatoria se name=temperature. Opzioni: c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } } ``` **Parametri di risposta:** PayloadObject：Oggetto Vuoto Esempio di Risposta Riuscita ```json { "event": { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "2" }, "payload": {} } } ``` ## 5. Eventi inviati dal server > Descrizione dell'interfaccia MDN EventSource： ### 5.1 Istruzione Il gateway supporta la spinta di messaggi al client usando SSE (Server-sent events). Il client può monitorare i messaggi SSE dopo aver ottenuto le credenziali di accesso e può analizzare il contenuto dei messaggi push secondo il protocollo di notifica eventi dell'interfaccia di sviluppo dopo aver ricevuto i messaggi inviati dal gateway. Si noti che il gateway utilizza attualmente il protocollo HTTP1.1, quindi SSE lato browser avrà un limite massimo di non più di 6 connessioni (Istruzioni specifiche possono essere trovate nella descrizione dell'interfaccia MDN EventSource.) ### 5.2 Formato Comune :::tips * **URL**：/open-api/V2/sse/bridge * **Metodo**：`GET` ::: Parametri della richiesta: | Nome | Tipo | Opzionale | Descrizione | | ------------- | ------ | --------- | ---------------- | | access\_token | string | N | Token di Accesso | Nota: Quando si richiede una connessione SSE, il gateway verificherà l'access\_token, e restituirà un errore di autenticazione se non è valido. { "error": 401, "data": {}, "message": "invalid access\_token"} > \## Per esempio: Nome Modulo: device Versione: 1,v2,v3 Tipo Messaggio: addDevice Esempio: ```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 Modulo Dispositivo #### a. Evento Aggiungi Dispositivo :::tips Nome Modulo：device Versione：v2 Tipo Messaggio：addDevice event.data parametri： ::: | Nome | Tipo | Opzionale | Descrizione | | ------- | ----------------------------------------------------------------- | --------- | ---------------------------- | | payload | ResponseDeviceObjectObject - Interfaccia uguale a Get Device List | N | informazioni sul dispositivo | Esempio: ```json // event.data { "payload": { "serial_number": "ABCDEFGHIJK", "third_serial_number": "third_serial_number", "name": "Miodispositivo", "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 Aggiorna Stato Dispositivo :::tips Nome Modulo：device Versione：v2 Tipo Messaggio：updateDeviceState event.data parametri： ::: | Nome | Tipo | Opzionale | Descrizione | | -------- | ---------------------------------------------------- | --------- | -------------------------------- | | endpoint | EndpointObject | N | Informazioni sul Dispositivo | | payload | oggetto。 Struttura uguale allo stato del dispositivo | N | Dati dello Stato del Dispositivo | EndpointObject: | Parametro | Tipo | Opzionale | Descrizione | | --------------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numero di Serie Unico del Dispositivo | | third\_serial\_number | string | Y | Il numero di serie univoco del dispositivo di terze parti. Per i dispositivi connessi tramite interfacce aperte, questo campo è obbligatorio. | Esempio: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "power": { "powerState": "on" }, "brightness": { "brightness": 100 } } } ``` #### c. Evento Aggiorna Info Dispositivo :::tips Nome Modulo：device Versione：v2 Tipo Messaggio：updateDeviceInfo event.data parametri： ::: | Nome | Tipo | Opzionale | Descrizione | | -------- | ------------------ | --------- | -------------------------------- | | endpoint | EndpointObject | N | Informazioni sul Dispositivo | | payload | DeviceChangeObject | N | Dati di modifica del dispositivo | EndpointObject: | Attributo | Tipo | Opzionale | Descrizione | | --------------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numero di Serie Unico del Dispositivo | | third\_serial\_number | string | Y | Il numero di serie univoco del dispositivo di terze parti. Per i dispositivi connessi tramite interfacce aperte, questo campo è obbligatorio. | DeviceChangeObject | Nome | Tipo | Opzionale | Descrizione | | ------------ | -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | | name | string | N | Nome del Dispositivo | | capabilities | CapabilityObject \[] | Y | Elenco delle capacità del dispositivo. | | tag | object | Y | **tag**`object` \| Nullable \| Coppie chiave-valore in formato JSON per informazioni dispositivo personalizzate. | * Può essere usato per memorizzare i canali del dispositivo. * Può essere usato per memorizzare le unità di temperatura. * Per altri dati personalizzati di terze parti. | Esempio: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "name": "nome dispositivo", "capabilities": [ { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Tipo di rilevamento controllo temperatura, obbligatorio. Valori opzionali: humidity (rilevamento umidità), temperature (rilevamento temperatura) "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Impostazioni di rilevamento supportate, obbligatorie. { "name": "lowerSetpoint", // Valore minimo che il rilevamento deve mantenere. Deve essere fornito lowerSetpoint o upperSetpoint. "value": { // Intervallo di rilevamento, opzionale. Compilare se ci sono condizioni preimpostate. "value": 68.0, // Valore di temperatura o umidità, obbligatorio. "scale": "f" // Unità di temperatura, obbligatoria se name=temperature. Opzioni: c (Celsius), f (Fahrenheit) } }, { "name": "upperSetpoint", // Valore massimo che il rilevamento deve mantenere. Deve essere fornito lowerSetpoint o upperSetpoint. "value": { // Intervallo di rilevamento, opzionale. Compilare se ci sono condizioni preimpostate. "value": 68.0, // Valore di temperatura o umidità, obbligatorio. "scale": "f" // Unità di temperatura, obbligatoria se name=temperature. Opzioni: c (Celsius), f (Fahrenheit) } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ] } } ``` #### d. Evento Elimina Dispositivo :::tips Nome Modulo：device Versione：v2 Tipo Messaggio：deleteDevice event.data parametri： ::: | \*\* Nome \*\* | \*\* Tipo \*\* | \*\* Opzionale\*\* | \*\* Descrizione \*\* | | -------------- | -------------- | ------------------ | ---------------------------- | | endpoint | EndpointObject | N | Informazioni sul Dispositivo | EndpointObject: | Attributo | Tipo | Opzionale | Descrizione | | --------------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numero di Serie Unico del Dispositivo | | third\_serial\_number | string | Y | Il numero di serie univoco del dispositivo di terze parti. Per i dispositivi connessi tramite interfacce aperte, questo campo è obbligatorio. | Esempio: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" } } ``` #### e. Evento Aggiorna Online Dispositivo :::tips Nome Modulo：device Versione：v2 Tipo Messaggio：updateDeviceOnline event.data parametri： ::: | Nome | Tipo | Opzionale | Descrizione | | -------- | ------------------ | --------- | -------------------------------- | | endpoint | EndpointObject | N | Informazioni sul Dispositivo | | payload | DeviceChangeObject | N | Dati di modifica del dispositivo | EndpointObject: | Attributo | Tipo | Opzionale | Descrizione | | --------------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Numero di Serie Unico del Dispositivo | | third\_serial\_number | string | Y | Il numero di serie univoco del dispositivo di terze parti. Per i dispositivi connessi tramite interfacce aperte, questo campo è obbligatorio. | DeviceChangeObject | Nome | Tipo | Opzionale | Descrizione | | ------ | ------- | --------- | ---------------------------- | | online | boolean | N | Stato Online del Dispositivo | Esempio: ```json // event.data { "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": false } } ``` ### 5.4 Modulo Gateway #### a. Evento Aggiornamento Stato Sicurezza :::tips Nome Modulo：device Versione：v2 Tipo Messaggio：updateDeviceOnline event.data parametri： ::: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------------- | ------------- | ---------------------------- | | payload | SecurityStateObject | N | Informazioni sul Dispositivo | SecurityStateObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------- | | alarm\_state | string | N | | * `arming` | Armato * `disarming` | Disarmato | Esempio: ```json // event.data { "payload": { "alarm_state": "alarming" } } ``` ### 5.5 Modulo Sicurezza #### a. Evento Aggiornamento Stato Armamento :::tips Nome Modulo：device Versione：v2 Tipo Messaggio：updateDeviceOnline event.data parametri： ::: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------------- | ------------- | ------------------------------------------ | | payload | ArmStateObject | N | informazioni di armamento e disattivazione | ArmStateObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------- | | arm\_state | string | N | | * `arming` | Armato * `disarming` | Disarmato | | dettaglio | DetailObject | N | Dettagli di armamento/disarmamento | DetailObject： | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------------ | | sid | int | N | id modalità di sicurezza | | name | string | N | Nome sicurezza | Esempio ```json // event.data { "payload": { "arm_state": "arming", "detail": { "sid": 1, "name": "Home Mode" } } } ``` ## 6. TTS (**Funzione del motore Text-to-Speech)** ### 6.1 Istruzione #### Ruolo chiave * Fornitore del servizio TTS: Il fornitore del servizio del motore TTS è responsabile della registrazione del motore TTS sul gateway e della fornitura dei servizi TTS * Server Gateway：iHost * Client Open API del Gateway #### 6.1.1 Registrazione del servizio motore TTS 1. 【Fornitore del servizio TTS】Chiama l'interfaccia per registrare il motore TTS sul gateway. 2. 【Server Gateway】Dopo la registrazione avvenuta con successo, il gateway memorizzerà le informazioni di base del motore TTS (incluso l'indirizzo del servizio server\_address, e la comunicazione successiva tra il gateway e il fornitore del servizio TTS avverrà tramite l'indirizzo server\_address), e assegnerà l'ID del servizio del motore TTS all'interno del gateway.
#### 6.1.2 Ottenere l'elenco degli audio sintetizzati 1. 【Client Open API del Gateway】Chiama l'interfaccia per ottenere l'elenco dei servizi motore TTS registrati. È possibile ottenere l'elenco corrente dei motori TTS registrati (incluso l'ID del motore TTS assegnato dal gateway). 2. 【Client Open API del Gateway】Chiama l'interfaccia per ottenere l'elenco degli audio di un motore TTS specificato. Il gateway invierà un'istruzione sincrona di elenco audio al Fornitore del servizio TTS specificato e restituirà il risultato.
#### 6.1.3 Sintesi vocale specificando un motore di sintesi 1. 【Client Open API del Gateway】Chiama l'interfaccia per ottenere l'elenco dei servizi motore TTS registrati. È possibile ottenere l'elenco corrente dei motori TTS registrati (incluso l'ID del motore TTS assegnato dal gateway). 2. 【Client Open API del Gateway】Chiama l'interfaccia per ottenere l'elenco degli audio di un motore TTS specificato. Il gateway invierà un'istruzione sincrona di elenco audio al Fornitore del servizio TTS specificato e restituirà il risultato.
#### 6.1.4 Sintetizzare audio e riprodurre il parlato TTS. 1. 【Client Open API del Gateway】Chiama l'interfaccia per ottenere l'elenco dei servizi motore TTS registrati. È possibile ottenere l'elenco corrente dei motori TTS registrati (incluso l'ID del motore TTS assegnato dal gateway). 2. 【Client Open API del Gateway】Chiama l'interfaccia per ottenere l'elenco degli audio di un motore TTS specificato. Il gateway invierà un'istruzione sincrona di elenco audio al Fornitore del servizio TTS specificato e restituirà il risultato. (incluso l'indirizzo del file audio TTS) 3. 【Client Open API del Gateway】Registra l'indirizzo del file audio TTS dal risultato restituito nel passaggio precedente, chiama l'interfaccia di riproduzione del file audio e lo riproduce tramite il gateway. ### 6.2 Modulo motore TTS #### 6.2.1 Capacità aperte del Gateway **a. Ottenere l'elenco dei servizi motore TTS registrati** :::tips * **URL**：`/open-api/V2/rest/tts/engines` * **Metodo**：`GET` * **Header**： * Content-Type: application/json * Autorizzazione: Bearer ::: Parametri della richiesta: nessuno Risposta dati corretta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ---------------- | ------------- | -------------------------------- | | engines | EngineObject \[] | N | Elenco dei motori TTS registrati | Struttura EngineObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ----------------------------------- | | id | string | N | ID del motore assegnato dal gateway | | name | string | N | Nome del servizio del motore TS | :::tips Condizioni: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. \*\*Codice di stato: \*\*`200 OK` **Esempio di risposta:**： ::: ```json { "error": 0, "data": { "engines": [ { "id": "engine id", "name": "engine name" } ] }, "message": "success" } ``` **b. Ottenere l'elenco degli audio di un motore TTS specificato** :::tips * **URL**：`/open-api/V2/rest/tts/engine/{id}/audio-list` * **Metodo**：`GET` * **Header**： * Content-Type: application/json * Autorizzazione: Bearer ::: Parametri della richiesta: nessuno Risposta dati corretta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | --------------- | ------------- | --------------- | | audio\_list | AudioObject \[] | N | Elenco audio | Struttura AudioObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------------------------------------------------- | -------- | ------------- | -------------------------------- | | url | string | N | URL del file audio, per esempio: | | | | | | | label | string | Y | Etichetta del file audio | :::tips Condizioni: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. \*\*Codice di stato: \*\*`200 OK` \*\*Codice di errore: \*\* * 190000 Il motore sta funzionando in modo anomalo **Esempio di risposta:**： ::: ```json { "error": 0, "data": { "audio_list": [ { "url": "indirizzo audio tts", // per esempio: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "etichetta audio tts" } ] }, "message": "success" } ``` **c. Eseguire la sintesi vocale usando il motore TTS specificato** :::tips * **URL**：`/open-api/V2/rest/tts/engine/{id}/synthesize` * **Metodo**：`POST` * **Header**： * Content-Type: application/json * Autorizzazione: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Testo usato per sintetizzare l'audio | | label | string | Y | Etichetta del file audio | | language | string | Y | Campo trasparente. Codice lingua opzionale per la richiesta di sintesi vocale. L'elenco specifico dei codici lingua supportati è fornito dal fornitore del servizio motore TTS. Si noti che il servizio del motore TTS deve supportare una lingua predefinita per la sintesi vocale, il che significa che se la lingua non viene fornita, verrà utilizzata la lingua predefinita del motore per la sintesi. | | options | object | Y | Campo trasparente. Viene utilizzato per trasmettere i parametri di configurazione necessari per la sintesi al servizio del motore di sintesi vocale TTS. | Risposta dati corretta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ----------- | ------------- | --------------- | | audio | AudioObject | N | Elenco audio | Struttura AudioObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------------------------------------------------- | -------- | ------------- | -------------------------------- | | url | string | N | URL del file audio, per esempio: | | | | | | | label | string | Y | Etichetta del file audio | :::tips Condizioni: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. \*\*Codice di stato: \*\*`200 OK` \*\*Codice di errore: \*\* * 190000 Il motore sta funzionando in modo anomalo **Esempio di risposta:**： ::: ```json { "error": 0, "data": { "audio": { "url": "indirizzo audio tts" // per esempio, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "etichetta audio tts" } }, "message": "success" } ``` #### 6.2.2 Comunicazione tra Gateway e Servizio TTS **a. Registrazione del servizio motore TTS** > Inviare richiesta al gateway da parte del Fornitore del servizio TTS :::tips * **URL**：`/open-api/V2/rest/thirdparty/event` * **Metodo**：`POST` * **Header**： * Content-Type: application/json * Autorizzazione: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ----------- | ------------- | ---------------------------------------------------------------- | | evento | EventObject | N | Struttura delle informazioni dell'oggetto evento della richiesta | EventObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------- | ------------- | -------------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione della richiesta | | payload | PayloadObject | N | Informazioni sulla struttura del payload della richiesta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------------------------------ | | name | string | N | Nome della richiesta. Parametro opzionale. | * RegisterTTSEngine | | message\_id | string | N | ID del messaggio della richiesta, UUID\_V4 | | version | string | N | Numero di versione del protocollo della richiesta. Attualmente fissato a 1 | PayloadObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ---------------- | -------- | ------------- | ---------------------------------------------- | | service\_address | string | N | Indirizzo del servizio. Per esempio, http\:/// | | name | string | N | Nome del servizio | Esempio di richiesta: ```json { "event": { "header": { "name": "RegisterTTSEngine", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "service_address": "service_address", "name": "tts service name" } } } ``` \*\*Parametri di risposta corretti: \*\* | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------- | ------------- | -------------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione della richiesta | | payload | PayloadObject | N | Informazioni sulla struttura del payload della richiesta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | -------------------------------------------------------- | | name | string | N | Nome dell'intestazione di risposta. Parametro opzionale: | * Risposta (Risposta riuscita) * ErrorResponse (Risposta di errore) | | message\_id | string | N | ID del messaggio dell'intestazione di risposta, UUID\_V4. Messaggio di richiesta in ingresso qui: header.message\_id | | version | string | N | Numero di versione del protocollo della richiesta. Attualmente fissato a 1 | PayloadObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ----------------------------------- | | engine\_id | string | N | ID del motore assegnato dal gateway | :::tips Condizioni: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. \*\*Codice di stato: \*\*`200 OK` **Esempio di risposta:**： ::: Esempio di risposta corretta:： ```json { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "engine_id": "engine id" } } ``` \*\*Parametri di risposta anomala: \*\* | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------- | | type | string | N | Tipo di errore | * INVALID\_PARAMETERS (Errore nei parametri) * AUTH\_FAILURE (Errore di autenticazione) * INTERNAL\_ERROR (Errore interno del servizio) | | description | string | N | Descrizione dell'errore | Esempio di risposta di errore:： ```json { "header": { "name": "ErrorResponse", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address non può essere vuoto" } } ``` **b. Comando di sincronizzazione della lista audio** > Inviare il comando al Fornitore del servizio TTS dal gateway. :::tips * **URL**：`` * **Metodo**：`POST` * **Header**： * Content-Type: application/json ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | --------------- | ------------- | ---------------------------------------------------- | | directive | DirectiveObject | N | Informazioni sulla struttura dell'oggetto istruzione | DirectiveObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------- | ------------- | -------------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione della richiesta | | payload | PayloadObject | N | Informazioni sulla struttura del payload della richiesta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------------------------------ | | name | string | N | Nome della richiesta. Parametro opzionale: | * SyncTTSAudioList | | message\_id | string | N | ID del messaggio della richiesta, UUID\_V4 | | version | string | N | Numero di versione del protocollo della richiesta. Attualmente fissato a 1 | Esempio di richiesta: ```json { "directive": { "header": { "name": "SyncTTSAudioList", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": {} } } ``` \*\*Parametri di risposta corretti: \*\* | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------- | ------------- | -------------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione della richiesta | | payload | PayloadObject | N | Informazioni sulla struttura del payload della richiesta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | -------------------------------------------------------- | | name | string | N | Nome dell'intestazione di risposta. Parametro opzionale: | * Risposta (Risposta riuscita) * ErrorResponse (Risposta di errore) | | message\_id | string | N | ID del messaggio dell'intestazione di risposta, UUID\_V4. Messaggio di richiesta in ingresso qui: header.message\_id | | version | string | N | Numero di versione del protocollo della richiesta. Attualmente fissato a 1 | PayloadObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | --------------- | ------------- | ---------------- | | audio\_list | AudioObject \[] | N | Elenco audio TTS | Struttura AudioObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------------------------------------------------- | -------- | ------------- | -------------------------------- | | url | string | N | URL del file audio, per esempio: | | | | | | | label | string | Y | Etichetta del file audio | :::tips Condizioni: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. \*\*Codice di stato: \*\*`200 OK` **Esempio di risposta:**： ::: Esempio di risposta corretta:： ```json { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "audio_list": [ { "url": "url audio tts", "label": "etichetta audio tts" } ] } } ``` \*\*Parametri di risposta anomala: \*\* | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------- | | type | string | N | Tipo di errore | * INVALID\_PARAMETERS (Errore nei parametri) * AUTH\_FAILURE (Errore di autenticazione) * INTERNAL\_ERROR (Errore interno del servizio) | | description | string | N | Descrizione dell'errore | Esempio di risposta di errore:： ```json { "header": { "name": "ErrorResponse", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address non può essere vuoto" } } ``` **c. Comando di sintesi vocale** > Inviare il comando al Fornitore del servizio TTS dal gateway. :::tips * **URL**：`` * **Metodo**：`POST` * **Header**： * Content-Type: application/json ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | --------------- | ------------- | ---------------------------------------------------- | | directive | DirectiveObject | N | Informazioni sulla struttura dell'oggetto istruzione | DirectiveObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------- | ------------- | -------------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione della richiesta | | payload | PayloadObject | N | Informazioni sulla struttura del payload della richiesta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------------------------------ | | name | string | N | Nome della richiesta. Parametro opzionale: | * SynthesizeSpeech | | message\_id | string | N | ID del messaggio della richiesta: UUID\_V4 | | version | string | N | Numero di versione del protocollo della richiesta. Attualmente fissato a 1 | PayloadObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Testo usato per sintetizzare l'audio | | label | string | Y | Etichetta del file audio | | language | string | Y | Campo trasparente. Codice lingua opzionale per la richiesta di sintesi vocale. L'elenco specifico dei codici lingua supportati è fornito dal fornitore del servizio motore TTS. Si noti che il servizio del motore TTS deve supportare una lingua predefinita per la sintesi vocale, il che significa che se la lingua non viene fornita, verrà utilizzata la lingua predefinita del motore per la sintesi. | | options | object | Y | Campo trasparente. Viene utilizzato per trasmettere i parametri di configurazione necessari per la sintesi al servizio del motore di sintesi vocale TTS. | Esempio di richiesta: ```json { "directive": { "header": { "name": "SynthesizeSpeech", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "text": "Testo di input da sintetizzare.", "label": "etichetta audio tts" } } } ``` \*\*Parametri di risposta corretti: \*\* | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------- | ------------- | -------------------------------------------------------------- | | header | HeaderObject | N | Informazioni sulla struttura dell'intestazione della richiesta | | payload | PayloadObject | N | Informazioni sulla struttura del payload della richiesta | HeaderObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | -------------------------------------------------------- | | name | string | N | Nome dell'intestazione di risposta. Parametro opzionale: | * Risposta (Risposta riuscita) * ErrorResponse (Risposta di errore) | | message\_id | string | N | ID del messaggio dell'intestazione di risposta, UUID\_V4. Messaggio di richiesta in ingresso qui: header.message\_id | | version | string | N | Numero di versione del protocollo della richiesta. Attualmente fissato a 1 | PayloadObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ----------- | ------------- | --------------- | | audio | AudioObject | N | Audio TTS | Struttura AudioObject | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------------------------------------------------- | -------- | ------------- | -------------------------------- | | url | string | N | URL del file audio, per esempio: | | | | | | | label | string | Y | Etichetta del file audio | :::tips Condizioni: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. \*\*Codice di stato: \*\*`200 OK` **Esempio di risposta:**： ::: Esempio di risposta corretta:： ```json { "header": { "name": "Response", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "audio": { "url": "url audio tts", "label": "etichetta audio tts" } } } ``` \*\*Parametri di risposta anomala: \*\* | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | --------------- | | type | string | N | Tipo di errore | * INVALID\_PARAMETERS (Errore nei parametri) * AUTH\_FAILURE (Errore di autenticazione) * INTERNAL\_ERROR (Errore interno del servizio) | | description | string | N | Descrizione dell'errore | Esempio di risposta di errore:： ```json { "header": { "name": "ErrorResponse", "message_id": "Identificatore univoco, preferibilmente un UUID versione 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address non può essere vuoto" } } ``` ## 7. Modulo multimediale ### 7.1 Riprodurre file audio :::tips * **URL**：`/open-api/V2/rest/media/audio-player` * **Metodo**：`POST` * **Header**： * Content-Type: application/json * Autorizzazione: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ------------------------ | | audio\_url | string | N | Indirizzo URL dell'audio | Risposta dati corretta: :::tips Condizioni: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. \*\*Codice di stato: \*\*`200 OK` **Esempio di risposta:**： ::: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 8. Scheda UI personalizzata Le schede UI personalizzate ti consentono di visualizzare qualsiasi contenuto desideri all'interno della scheda. Questo contenuto può essere una pagina web, un'immagine o qualsiasi servizio con un'interfaccia utente. Devi semplicemente fornire l'URL del contenuto che desideri visualizzare. La scheda UI si adatterà automaticamente alla larghezza e all'altezza e il contenuto verrà renderizzato utilizzando un iFrame. ### 8.1 Istruzione #### Ruolo chiave * **Fornitore del servizio UI**: Il fornitore responsabile della creazione di schede UI personalizzate sul gateway. * **Server Gateway**: Il server del gateway (iHost). * **Client Open API del Gateway**: Il client Open API per il gateway. #### 8.1.1 Creazione di una scheda UI personalizzata * **\[Fornitore del servizio UI]**: Chiama l'API per creare una scheda UI personalizzata sul gateway. * **\[Server Gateway]**: Dopo la registrazione avvenuta con successo, il gateway memorizza le informazioni di base della scheda UI (inclusa la configurazione delle dimensioni e l'URL della risorsa della scheda) e assegna un ID interno della scheda UI all'interno del gateway.
#### 8.1.2 Recupero dell'elenco delle schede UI * **\[Fornitore del servizio UI]**: Chiama l'API per recuperare l'elenco delle schede UI. * **\[Server Gateway]**: Restituisce l'elenco delle schede UI memorizzate sul gateway, incluse le schede UI personalizzate non create dal chiamante.
#### 8.1.3 Modifica della configurazione di una scheda UI specificata * **\[Fornitore del servizio UI]**: Chiama l'API per modificare la configurazione di una scheda UI specificata, come la configurazione delle dimensioni e l'URL della risorsa. * **\[Server Gateway]**: Dopo la modifica avvenuta con successo, il gateway memorizza le informazioni aggiornate della scheda UI, inclusa la nuova configurazione delle dimensioni e l'URL della risorsa.
#### 8.1.4 Eliminazione di una scheda UI personalizzata 1. **\[Fornitore del servizio UI]**: Chiama l'API per eliminare una scheda UI personalizzata specificata. 2. **\[Server Gateway]**: Il gateway rimuoverà tutte le informazioni correlate alla scheda UI specificata.
### 8.2 Modulo scheda UI personalizzata #### 8.2.1 Creazione di una scheda UI personalizzata > Il Fornitore del servizio UI invia una richiesta al gateway per creare una scheda UI personalizzata. :::tips * **URL**：`/open-api/v2/rest/ui/cards` * **Metodo**：`POST` * **Header**： * Content-Type: application/json * Autorizzazione: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------- | ------------------ | ------------- | ---------------------------------------------------------------------------------- | | label | string | Y | Etichetta della scheda: Usata per descrivere la scheda. È l'alias della scheda. | | cast\_settings | CastSettingsObject | Y | Impostazioni della scheda Cast: Impostazioni di configurazione per le schede cast. | | web\_settings | WebSettingsObject | N | Impostazioni della scheda Web: Impostazioni di configurazione per le schede web. | CastSettingsObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configurazione della dimensione: Deve includere almeno una configurazione. | | default | string | N | Specificazione predefinita: La specifica della dimensione predefinita viene utilizzata, con parametri opzionali: 2x2 | WebSettingsObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ----------------- | ------------------- | ------------- | -------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configurazione della dimensione: Deve includere almeno una configurazione. | | drawer\_component | DrawerObject | Y | Impostazioni di visualizzazione del componente Drawer. | | default | string | N | Specificazione predefinita: | * 1x1 * 2x1 | DimensionObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | --------------------------------------- | -------- | ------------- | ----------------------------------------------------- | | src | string | N | URL della risorsa: Per esempio: | | size | string | N | Specifiche della dimensione: | | Parametri opzionali CastSettingsObject: | | | | * 2×2 Parametri opzionali WebSettingsObject: * 1x1 * 2x1 | DrawerObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ----------------------------------------------------- | | src | string | N | URL della risorsa: Per esempio: | Risposta dati di successo: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | -------------------------- | | id | string | N | ID univoco della scheda UI | :::tips **Condizioni**: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. \*\*Status Code: \*\* `200 OK` ::: 请求示例： ```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" } } ``` Esempio di risposta: ```json { "error": 0, "data": { "id": "72cc5a4a-f486-4287-857f-b482d7818b16" }, "message": "success" } ``` #### 8.2.2 Recuperare l'elenco delle schede UI :::tips * **URL**：`/open-api/v2/rest/ui/cards` * **Metodo**：`GET` * **Header**： * Content-Type: application/json * Autorizzazione: Bearer ::: Parametri della richiesta: Nessuno Parametri di risposta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | ------------- | ------------- | ---------------------- | | data | CardObject\[] | N | Elenco delle schede UI | Oggetto CardObjec: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------- | ------------------ | ------------- | ------------------------------------------------------------------------------------------------ | | id | string | N | ID della scheda: Un identificatore univoco per la scheda. | | label | string | Y | Etichetta della scheda: Usata per descrivere la scheda. Funziona come alias o nome della scheda. | | cast\_settings | CastSettingsObject | Y | Etichetta della scheda: Usata per descrivere la scheda. È l'alias della scheda. | | web\_settings | WebSettingsObject | N | Impostazioni della scheda Cast: Impostazioni di configurazione per le schede cast. | | app\_name | string | Y | Impostazioni della scheda Web: Impostazioni di configurazione per le schede web. | CastSettingsObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------------------ | ------------------- | ------------- | -------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configurazione della dimensione: Deve includere almeno una configurazione. | | default | string | N | Specificazione predefinita: | | Parametro opzionale: 2x2 | | | | | usato | string | N | Specificazione corrente: | | Parametro opzionale: 2x2 | | | | WebSettingsObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------------- | ------------------- | ------------- | -------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Configurazione della dimensione: Deve includere almeno una configurazione. | | drawer\_component | DrawerObject | Y | Impostazioni di visualizzazione del componente Drawer. | | default | string | N | Specificazione predefinita: | | Parametro opzionale: | | | | * 1x1 * 2x1 | | used | string | N | Specificazione corrente: Parametro opzionale: * 1x1 * 2x1 | DimensionObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------------- | -------- | ------------- | ----------------------------------------------------- | | src | string | N | URL della risorsa: Per esempio: | | size | string | N | Specifiche della dimensione: | | Parametro opzionale: | | | | * 1x1 * 2x1 **Nota**: Attualmente, le schede cast supportano solo la specifica 2x2. La specifica 2x2 non sarà efficace. | DrawerObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | ------------- | -------- | ------------- | ----------------------------------------------------- | | src | string | N | URL della risorsa: Per esempio: | Esempio di risposta: ```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 Modificare la configurazione di una scheda UI specificata > Agli utenti autorizzati è consentito modificare la configurazione di una scheda UI esistente tramite questa interfaccia. I fornitori di servizi di schede personalizzate possono modificare solo le schede UI che hanno creato. :::tips * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Metodo**：`PUT` * **Header**： * Content-Type: application/json * Autorizzazione: Bearer ::: Parametri della richiesta: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------- | ------------------ | ------------- | ------------------------------------------------------- | | label | string | Y | Usato per descrivere la scheda. È l'alias della scheda. | | cast\_settings | CastSettingsObject | Y | Impostazioni della scheda Cast | | web\_settings | WebSettingsObject | Y | Impostazioni della scheda Web | CastSettingsObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------------- | -------- | -------------------------------------------------------------------------------------------------- | ------------------------ | | usato | string | Y, Uno dei due `usato` o `src` deve essere fornito, ma è richiesto almeno uno di questi parametri. | Specificazione corrente: | | Parametro opzionale: | | | | * 2x2 \| | src | string | Y, Uno dei due `usato` o `src` deve essere fornito, ma è richiesto almeno uno di questi parametri. | URL della risorsa: | WebSettingsObject: | **Attributo** | **Tipo** | **Opzionale** | **Descrizione** | | -------------------- | -------- | -------------------------------------------------------------------------------------------------- | ------------------------ | | usato | string | Y, Uno dei due `usato` o `src` deve essere fornito, ma è richiesto almeno uno di questi parametri. | Specificazione corrente: | | Parametro opzionale: | | | | * 1x1 * 2x1 | | src | string | Y, Uno dei due `usato` o `src` deve essere fornito, ma è richiesto almeno uno di questi parametri. | URL della risorsa: | Risposta dati riuscita: :::tips **Condizioni**: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. La scheda UI da modificare deve essere stata creata dal fornitore del servizio di schede personalizzate che chiama l'interfaccia. \*\*Codice di stato: \*\* `200 OK` **Codice di errore:** * **406**: Nessuna autorizzazione per accedere a questa risorsa ::: \*\*Esempio di risposta: \*\* ```json { "error": 0, "data": {}, "message": "success" } ``` \*\*Esempio di richiesta: \*\* ```json { "cast_settings": { "used": "2×2" }, "web_settings": { "used": "1×1" } } ``` #### 8.2.4 Eliminare la scheda UI personalizzata > Agli utenti autorizzati è consentito eliminare una scheda UI esistente utilizzando questa interfaccia. I fornitori di schede personalizzate possono eliminare solo le schede UI che hanno creato. :::tips * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Metodo**：`DELETE` * **Header**： * Content-Type: application/json * Autorizzazione: Bearer ::: Parametri della richiesta: Nessuno Risposta dati riuscita: :::tips **Condizioni**: I parametri della richiesta sono validi e la verifica dell'identità dell'utente è superata. La scheda UI da modificare deve essere stata creata dal fornitore del servizio di schede personalizzate che chiama l'interfaccia. \*\*Codice di stato: \*\* `200 OK` **Codice di errore:** * **406**: Nessuna autorizzazione per accedere a questa risorsa. ::: \*\*Esempio di risposta: \*\* ```json { "error": 0, "data": {}, "message": "success" } ```