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.

// Richiesta
curl --location --request GET 'http://<ip address>/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.

// Richiesta
curl --location --request GET 'http://<ip address>/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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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://<username>:<password>@<hostname>:<port>/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:<schema>://<hostname>:<port>/<username>:<password>@<service_path>
Esempio:rtsp://admin:[email protected]: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 <username> e <password> 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"
}

import axios from 'axios';

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

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

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

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

import axios from 'axios';

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

(async function main() {
  // accendi dispositivo
  await axios({
    url: `http://<nome dominio o indirizzo ip>/open-api/v2/rest/devices/${serial_number}/query-state/power-consumption`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      "query_state":{
        "power-consumption":{
          "type": "summarize", // Tipo 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:

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

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

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

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

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

{
  "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  <token>
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  <token>
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：<service address>
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  <token>
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 http://192.168.31.14/service_address

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 :

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

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

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

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

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

{
  "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：https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

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:

const evtSource = new EventSource("http://<nome dominio o indirizzo ip>/open-api/v2/sse/bridge?access_token=xxxxxx");

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

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

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

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

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

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

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

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

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

{
  "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:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
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:： :::

{
  "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:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
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:： :::

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

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

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

{
  "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：<service address>

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

{
  "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:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
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:：

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

{
  "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：<service address>

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

{
    "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:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
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:：

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

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

{
  "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: http://example.html
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: http://example.html

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 ::: 请求示例：

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

{
  "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: http://example.html
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: http://example.html

Esempio di risposta:

{
  "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: http://example.html |

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: http://example.html |

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

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

**Esempio di richiesta: **

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

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