Guida per sviluppatori e API

1. Inizio utilizzo

1.1 Preparazione

Passo 1. Assicurarsi che il gateway sia alimentato e funzioni correttamente.

Passo 2. Assicurarsi che il gateway e il PC siano connessi alla stessa LAN. Quindi inserire l'URL di CUBE nel browser.

Nota: Se disponi di più gateway, puoi ottenere l'indirizzo IP corrispondente per accedere al gateway specificato nei due modi seguenti.

1. Accedi al tuo router wireless e controlla l'indirizzo IP del gateway nel DHCP.

2. CUBE supporta la scoperta locale tramite mDNS.

1.2 Inizia

• Chiama l'interfaccia [Access Token] e ricevi una risposta di errore che indica di fare clic su <Fine>. 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" 
}

• Fai clic su <Fine> e chiama nuovamente l'interfaccia [Access Token]. La risposta ha esito positivo 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"
}

• Verifica token. Chiama l'interfaccia [Get Device List]. La risposta ha esito positivo 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": "device name",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  }
  "message": "success"
}

• Metodo per ottenere il token di accesso CUBE: dopo aver chiamato l'interfaccia [Access Token], la pagina della console web CUBE mostra un pop-up globale che richiede all'utente di confermare l'acquisizione delle credenziali per la chiamata dell'interfaccia.

• Nota: Se apri più di una pagina della console web CUBE, il pop-up di conferma apparirà su più pagine contemporaneamente, e il pop-up delle altre pagine verrà chiuso dopo aver cliccato la conferma su una delle pagine.

2. Concetto principale

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

• **Capacità del dispositivo. **La capacità del dispositivo viene utilizzata per descrivere le specifiche sotto-funzioni del dispositivo. Come controllo dell'alimentazione, controllo della luminosità, controllo della temperatura di colore, ecc. Un singolo dispositivo può supportare 1 o più capacità.

  • capability: Descrive il nome della capacità, che deve essere univoco a livello globale e di tipo stringa. Più parole in inglese devono essere separate da trattini ("-"). Ad esempio: "thermostat-target-setpoint".

  • name: Descrive la categoria sotto la capacità, anch'essa di tipo stringa. Più parole in inglese devono essere separate da trattini ("-"). Ad esempio: "auto-mode", "manual-mode".

  • permission: Descrive i permessi associati alla capacità. Il tipo è stringa, formattato in un codice binario 8421. Esempi includono:

    • Il dispositivo è controllabile: "1000"

    • Il dispositivo è configurabile: "0010"

    • Il dispositivo è controllabile e configurabile: "1010"

    • Il dispositivo è controllabile e in grado di segnalare: "1100"

Il significato di ogni bit, da destra a sinistra, è il seguente: ⅰ. Bit 0: Consente l'interrogazione del dispositivo ⅱ. Bit 1: Consente la configurazione del dispositivo ⅲ. Bit 2: Consente al dispositivo di segnalare 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 gli elementi di configurazione per la capacità, che sono di tipo oggetto e includono una descrizione di ogni voce di configurazione. ⅰ. key: Descrive il nome della voce di configurazione, di tipo stringa. Più parole in inglese dovrebbero essere espresse in camelCase. Ad esempio: "temperatureUnit". ⅱ. value: Descrive il contenuto della voce di configurazione. Le specifiche dettagliate sono indicate 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 | | tipo | 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**:

   • La value il campo (che descrive il valore della voce di configurazione) è obbligatorio se permission consente la modifica ("10" o "11").

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

   • La 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 step 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**:

   • La value il campo è obbligatorio se permission consente la modifica ("10" o "11").

   • La default il campo è opzionale.

4. Quando **type = boolean**:

   • La value il campo è obbligatorio se permission consente la modifica ("10" o "11").

   • La default il campo è opzionale.

5. Quando **type = string**:

   • La value il campo è obbligatorio se permission consente la modifica ("10" o "11").

   • La 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 IEEE 754 a virgola mobile a doppia precisione a 64 bit
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 di risposta generici

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 non è uguale a 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 allarme 1)

• alert2 (Suono allarme 2)

• alert3 (Suono allarme 3)

• alert4 (Suono allarme 4)

• alert5 (Suono allarme 5)

• doorbell1 (Suono campanello 1)

• doorbell2 (Suono campanello 2)

• doorbell3 (Suono campanello 3)

• doorbell4 (Suono campanello 4)

• doorbell5 (Suono campanello 5)

• alarm1 (Suono allarme 1)

• alarm2 (Suono allarme 2)

• alarm3 (Suono allarme 3)

• alarm4 (Suono allarme 4)

• alarm5 (Suono allarme 5) | | Deep supportati | - bootComplete (Avvio del sistema completato)

• networkConnected (Rete connessa)

• networkDisconnected (Rete disconnessa)

• systemShutdown (Spegnimento del sistema) -deviceDiscovered (Dispositivo scoperto)

• system Armed (Sistema armato abilitato)

• system Disarmed (Sistema armato disabilitato)

• factoryReset (Ripristina dispositivo) |

3.1 Funzione del Gateway

a. Token di accesso

Consente agli utenti di ottenere il token di accesso.

• Nota: Il token verrà cancellato dopo il ripristino del dispositivo.

• Nota: 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 all'interfaccia. È valido a lungo termine, si prega di salvarlo
app_name	string	Y	Descrizione del nome dell'applicazione.

:::tips Condizione: L'utente attiva il < tasto di comando > e accede a questa interfaccia entro il tempo valido. **Codice di stato: **200 OK ::: Esempio di risposta:

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

Risposta dati in caso di errore：Oggetto vuoto :::tips Condizioni：L'utente non ha attivato il < tasto di comando >, oppure il tempo valido è scaduto. **Codice di stato: ** 200 OK ::: Esempio di risposta:

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

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

  • Autorization: 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à 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 è superata. **Codice di stato: **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. Configura 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

  • Autorization: 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 è superata. **Codice di stato: **200 OK ::: Esempio di risposta:

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

d. Ottieni 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 firmware
name	string	N	Nome del dispositivo

Risposta dati di successo: Oggetto vuoto {} :::tips Condizioni: Nessuno **Codice di stato: **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. Disattiva audio Gateway

Consente agli utenti autorizzati di disattivare l'audio del 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 è superata. **Codice di stato: **200 OK ::: Esempio di risposta:

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

f. Riattiva audio Gateway

Consente agli utenti autorizzati di riattivare l'audio 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 è superata. **Codice di stato: **200 OK ::: Esempio di risposta:

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

g. Annulla 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 è superata. **Codice di stato: **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

  • Autorization: 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 è superata. **Codice di stato: **200 OK :::

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

b. Controllo 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 (riproduci il suono) 2.play_beep (riproduci il beep)
sound	SoundObject	Y (N se type è play_sound.)	Il suono.
beep	BeepObject	Y (N se type è play_beep.)	Il beep

SoundObject

Attributo	Tipo	Opzionale	Descrizione
name	string	N	Il nome del suono. I valori supportati possono essere verificati in [Resource List - Supported sound]
volume	int	N	Il volume del suono. [0-100]
countdown	int	N	La durata per cui l'altoparlante riproduce il suono; si fermerà automaticamente allo scadere del tempo. Unità: secondi. [0,1799]

BeepObject

Attributo	Tipo	Opzionale	Descrizione
name	string	N	Il nome dell'evento (deep). I valori supportati possono essere verificati in [Resource List - Supported deep]
volume	int	N	Il volume dell'evento (deep). [0-100]

Risposta dati di successo: Oggetto vuoto {} :::tips Condizioni: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è superata. **Codice di stato: ** 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
Plug	plug	≥ 2.1.0
Switch	switch	≥ 2.1.0
Light	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à dei dispositivi supportate

Interruttore di alimentazione (power):

Esempio di Dichiarazione delle Capacità:

[
  {
    "capability": "power", // Nome della capacità
    "permission": "1100",  // ihost non supporta la configurazione di avvio/arresto morbido, quindi manca il 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 inversione.
}

Protocollo (Query Stato & Istruzioni di Controllo):

Accendi:

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

Spegni:

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

Commutazione Canale (toggle):

Esempio di Dichiarazione delle 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 toggle dell'attributo {name} del dispositivo {device_id}. Obbligatorio. **Tipo:** Stringa. "on" indica attivato, "off" indica disattivato, "toggle" indica inversione.
}

Protocollo (Query Stato & Istruzioni di Controllo):

Formato Toggle:

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

Inching Canale (toggle-inching):

Esempio di Dichiarazione delle 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 spenta), "on" (alimentazione accesa)
              "delay": 1000, // Tempo di ritardo dell'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 spenta), "on" (alimentazione accesa)
              "delay": 1000, // Tempo di ritardo dell'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 spenta), "on" (alimentazione accesa)
              "delay": 1000, // Tempo di ritardo dell'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 spenta), "on" (alimentazione accesa)
              "delay": 1000, // Tempo di ritardo dell'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 (Query Stato & Istruzioni di Controllo)

Nessuno

Regolazione Luminosità (brightness):

Esempio di Dichiarazione delle Capacità:

{
  "capability": "brightness", // Nome della capacità
  "permission": "1100"  // Permesso
}

Attributo di Stato:

{
  "brightness": 100, // Il campo brightness indica la percentuale di luminosità. Scegli tra brightness o brightnessDelta. **Tipo:** Numero. Intervallo: 0-100.
}

Protocollo (Query Stato & Istruzioni di Controllo):

Imposta Luminosità al 80%. (0 è il più scuro e 100 il più chiaro.)

json
Copia codice
{
  "brightness": {
    "brightness": 80
  }
}

Regolazione Temperatura Colore (color-temperature):

Esempio di Dichiarazione delle Capacità:

{
  "capability": "color-temperature", // Nome della capacità
  "permission": "1100"  // Permesso
}

Attributo di Stato:

{
  "colorTemperature": 100, // Il campo colorTemperature indica la percentuale della temperatura colore. Scegli tra colorTemperature o colorTemperatureDelta. **Tipo:** Numero. Intervallo: 0-100. 0 indica luce calda, 50 luce neutra, 100 luce fredda.
}

Protocollo (Query Stato & Istruzioni di Controllo):

Regola Temperatura Colore al 50%:

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

Regolazione Colore (color-rgb):

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

Imposta Colore su Viola:

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

Regolazione Percentuale (percentage):

Esempio di Dichiarazione delle Capacità:

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

Attributo di Stato:

{
  "percentage": 100, // Il campo percentage indica un valore percentuale. Scegli tra percentage o percentageDelta. **Tipo:** Numero. Intervallo: 0-100.
}

Protocollo (Query Stato & Istruzioni di Controllo):

Regola al 40%:

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

Controllo Motore (motor-control):

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

Apri Motore:

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

Invertimento Motore (motor-reverse):

Esempio di Dichiarazione delle 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 inverso.
}

Protocollo (Query Stato & Istruzioni di Controllo):

Imposta Motore in Avanti:

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

Calibrazione Motore (motor-clb)

Esempio di Dichiarazione delle 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 di Accensione all'Avvio (startup)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "startup": "on" // Stato di alimentazione all'avvio. **Tipo:** Stringa. Obbligatorio. Valori opzionali: "on" (accensione), "stay" (mantieni alimentazione), "off" (spegnimento), "toggle" (inverti stato di alimentazione).
}

Protocollo (Query Stato & Istruzioni di Controllo):

Imposta Stato di Alimentazione Sempre On:

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

---

Attivazione Risveglio (identify)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "identify": true // Indica se il dispositivo segnala attivamente i risultati di riconoscimento o viene attivato.
}

Protocollo (Segnalazione Stato & Istruzioni di Controllo):

Imposta Tempo di Attivazione Risveglio:

{
  "identify": {
    "countdown": 180 // Il campo countdown indica il tempo del conto alla rovescia. Obbligatorio. **Tipo:** Numero. Unità: secondi.
  }
}

Segnala Stato di Attivazione:

{
  "identify": {
    "identify": true // Indica se il dispositivo segnala attivamente i risultati di riconoscimento o viene attivato.
  }
}

Interruttore Statistiche Consumo Energetico in Tempo Reale (power-consumption)

Esempio di Dichiarazione delle 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 il tipo è "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. Opzionale. Se omesso, indica l'ora corrente.
  }
}

Rispondi con il Risultato delle Statistiche nell'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. Opzionale.
  "electricityIntervals": [ // Più record statistici divisi secondo configuration.resolution. Opzionale. Non presente quando il tipo è "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 è inferiore alla 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 è inferiore alla risoluzione, tutti i record segnalati sono considerati non validi.
    }
  ]
}

Protocollo (Segnalazione Stato & 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 delle 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 rilevato dovrebbe 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. Obbligatorio quando name=temperature. Valori opzionali: "c" (Celsius), "f" (Fahrenheit).
            }
          },
          {
            "name": "upperSetpoint", // Il valore rilevato dovrebbe 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. Obbligatorio 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 rilevato dovrebbe 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 rilevato dovrebbe 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à. Opzionale. Valori supportati: "COMFORT" (Modalità Comfort), "COLD" (Modalità Fredda), "HOT" (Modalità Calda), "DRY" (Modalità Asciutto), "WET" (Modalità Umido).
}

Protocollo (Query Stato & Istruzioni di Controllo):

Formato:

{
    [capability] :{
        [nome modalità] :{
            "mode": [value]
        }
    }
}

Esempio:

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

Modalità Termostato (thermostat-mode)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "thermostatMode": "MANUAL" // Modalità di funzionamento del termostato. **Tipo:** Stringa. Valori opzionali: "MANUAL", "AUTO", "ECO".
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Stato Recupero Adattivo del Termostato (thermostat/adaptive-recovery-status)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Impostazione Temperatura Target Modalità Termostato (thermostat-target-setpoint)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Sensore (detect)

Esempio di Dichiarazione delle Capacità:

{
  "capability": "detect",
  "permission": "0110",
  "settings": { // Facoltativo
    "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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Temperatura (temperature)

Esempio di Dichiarazione delle Capacità:

{
  "capability": "temperature",
  "permission": "0110",
  "settings": { // Facoltativo
    "temperatureCalibration": { // Calibrazione 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 gradi Celsius.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Umidità (humidity)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Batteria (battery)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "battery": 95 // Percentuale residua della batteria. **Tipo:** Numero, intervallo -1 a 100. Nota: -1 indica livello batteria sconosciuto.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Pulsante Singolo (press)

Esempio di Dichiarazione delle Capacità:

{
  "capability": "press",
  "permission": "1100",
  "settings": { // Facoltativo
    "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 lunga).
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Multi-Pulsante (multi-press)

Esempio di Dichiarazione delle Capacità:

{
  "capability": "multi-press",
  "permission": "0100",
  "name": "1", // Nome dell'attributo multi-press. **Tipo:** Stringa. Consentiti solo caratteri alfanumerici.
  "settings": { // Facoltativo
    "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 lunga).
}

Protocollo (Query Stato & 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 delle 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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Manomissione (tamper-alert)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "tamper": "clear" // Stato di manomissione. **Tipo:** Stringa. Valori possibili: "clear" (non manomesso), "detected" (manomesso).
}

Protocollo (Query Stato & 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 delle Capacità:

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

Attributi (Stato):

{
  "level": "brighter" // Livello di luminosità. **Tipo:** Stringa. Valori possibili: "brighter" (più luminoso), "darker" (più scuro).
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Tensione (voltage)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "voltage": 50 // Valore di tensione corrente, in unità di 0,01V. **Tipo:** Numero, valori non negativi.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Corrente Elettrica (electric-current)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Potenza Elettrica (electric-power)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Guasto (fault)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "fault": "none" // Stato di guasto. **Tipo:** Stringa. Valori possibili: "none" (nessun guasto), "detected" (guasto rilevato).
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Interruttore di Soglia (threshold-breaker)

Esempio di Dichiarazione delle 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 per il rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0.
              "min_range": 10, // Valore minimo di potenza per il rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0.
              "max_range": 3500 // Valore massimo di potenza per il rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0.
            }
          },
          {
            "name": "upperPower", // Interruttore soglia alta potenza
            "value": {
              "value": 50, // Valore di potenza per il rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0.
              "min_range": 10, // Valore minimo di potenza per il rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0.
              "max_range": 3500 // Valore massimo di potenza per il rilevamento, in unità di 0,01W. **Tipo:** Intero. Intervallo: >=0.
            }
          },
          {
            "name": "lowerElectricCurrent", // Interruttore soglia bassa corrente
            "value": {
              "value": 50, // Valore di corrente per il rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0.
              "min_range": 10, // Valore minimo di corrente per il rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0.
              "max_range": 1500 // Valore massimo di corrente per il rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0.
            }
          },
          {
            "name": "upperElectricCurrent", // Interruttore soglia alta corrente
            "value": {
              "value": 50, // Valore di corrente per il rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0.
              "min_range": 10, // Valore minimo di corrente per il rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0.
              "max_range": 1500 // Valore massimo di corrente per il rilevamento, in unità di 0,01A. **Tipo:** Intero. Intervallo: >=0.
            }
          },
          {
            "name": "lowerVoltage", // Interruttore soglia bassa tensione
            "value": {
              "value": 50, // Valore di tensione per il rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0.
              "min_range": 10, // Valore minimo di tensione per il rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0.
              "max_range": 24000 // Valore massimo di tensione per il rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0.
            }
          },
          {
            "name": "upperVoltage", // Interruttore soglia alta tensione
            "value": {
              "value": 50, // Valore di tensione per il rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0.
              "min_range": 10, // Valore minimo di tensione per il rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0.
              "max_range": 24000 // Valore massimo di tensione per il rilevamento, in unità di 0,01V. **Tipo:** Intero. Intervallo: >=0.
            }
          }
        ]
      }
    }
  }
}

Attributi (Stato)

• Nessuno

Protocollo (Query Stato & Istruzioni di Controllo)

• Nessuno

Funzione Inch (inching)

Esempio di Dichiarazione delle Capacità:

{
  "capability": "inching",
  "permission": "0010",
  "settings": {
    "inchingEnable": { // Impostazione abilitazione 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 (Query Stato & Istruzioni di Controllo):

• Nessuno

Stream Fotocamera (camera-stream)

Esempio di Dichiarazione delle 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. Obbligatorio.
          "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 (Query Stato & Istruzioni di Controllo):

• Nessuno

Controllo Modalità (mode)

Esempio di Dichiarazione delle 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 predefiniti.
      }
    }
  },
  {
    "capability": "mode",
    "name": "thermostatMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["auto", "manual"] // Valori modalità personalizzati. I valori configurati sovrascrivono i 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 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 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 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 predefiniti.
      }
    }
  }
]

Attributi (Stato):

{
  "modeValue": "low" // Valore modalità. **Tipo:** Stringa. Obbligatorio. Fare riferimento alle modalità preimpostate supportate.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Anidride Carbonica (co2)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "co2": 111 // Concentrazione di anidride carbonica. **Tipo:** Intero. Unità: ppm.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Illuminazione (illumination)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Fumo (smoke)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "smoke": true // Risultato del rilevamento. **Tipo:** Booleano. `true` indica rilevamento, `false` indica nessun rilevamento.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Apertura/Chiusura Calamita Porta (contact)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "contact": true // Risultato del rilevamento. **Tipo:** Booleano. `true` indica rilevamento, `false` indica nessun rilevamento.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Movimento (motion)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Perdita d'Acqua (water-leak)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Interruttore Rilevamento Finestra (window-detection)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione attivata, `off` indica alimentazione disattivata.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Blocco Bambino (child-lock)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione attivata, `off` indica alimentazione disattivata.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Interruttore Anti-Soffiamento Diretto (anti-direct-blow)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione attivata, `off` indica alimentazione disattivata.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Interruttore Oscillazione Orizzontale (horizontal-swing)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione attivata, `off` indica alimentazione disattivata.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Interruttore Oscillazione Verticale (vertical-swing)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione attivata, `off` indica alimentazione disattivata.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Modalità ECO (eco)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "powerState": "on" // Il campo `powerState` indica lo stato di alimentazione. **Tipo:** Stringa. `on` indica alimentazione attivata, `off` indica alimentazione disattivata.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Avvio Alternabile (toggle-startup)

Esempio di Dichiarazione delle 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` (mantenimento accensione), `off` (spegnimento).
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Hold (detect-hold)

Esempio di Dichiarazione delle 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 di mantenimento del rilevamento. **Tipo:** Stringa. `on` significa mantenimento attivo, `off` significa mantenimento inattivo.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Identificazione/Attivazione Alternabile (toggle-identify)

Esempio di Dichiarazione delle Capacità:

{
  "capability": "toggle-identify",
  "permission": "1100", // Nota: Questa capacità 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 identificazione o attivazione.
  "countdown": 180 // Il campo `countdown` indica la durata dell'attivazione. **Tipo:** Numero. Unità: secondi.
}

Protocollo (Query Stato & 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 Alternabile (toggle-voltage)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "voltage": 230 // Il campo `voltage` indica la tensione rilevata. **Tipo:** Numero. Unità: Volt.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento Corrente Elettrica del Sottocomponente (toggle-electric-current)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Potenza del Sottocomponente (toggle-electric-power)

Esempio di Dichiarazione delle 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 attuale. **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 attuale. **Unità:** 0.01 W. **Tipo:** Intero. Opzionale.
  "activePower": 50, // Il campo `activePower` rappresenta il valore di potenza attiva attuale. **Unità:** 0.01 W. **Tipo:** Intero. Opzionale.
  "apparentPower": 50 // Il campo `apparentPower` rappresenta il valore di potenza apparente attuale. **Unità:** 0.01 W. **Tipo:** Intero. Opzionale.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Statistiche di Consumo Energetico del Sottocomponente (toggle-power-consumption)

Esempio di Dichiarazione delle 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. Opzionale. Se non fornito, predefinito al tempo corrente.
  }
}

Risposta per il 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. Opzionale.
  "electricityIntervals": [ // Suddiviso da `configuration.resolution` in più record. Opzionale. 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 (Query Stato & 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à Link (lqi)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "lqi": 60 // Il campo `lqi` rappresenta l'indicatore di qualità del link. **Tipo:** Numero. Intervallo di valori: 0 a 255.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Configurazione Funzionale (configuration)

Esempio di Dichiarazione delle 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 (Query Stato & 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 delle Capacità:

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

Attributi (Stato):

{
  "restart": true // Comando di riavvio del dispositivo. **Tipo:** Booleano. Obbligatorio. Il valore deve essere `true`.
}

Protocollo (Query Stato & Istruzioni di Controllo):

{
  "system": { // Configurazione correlata alla capability. Opzionale.
    "restart": true
  }
}

Umidità (moisture)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Pressione Barometrica (barometric-pressure)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Velocità del Vento (wind-speed)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Direzione del Vento (wind-direction)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Precipitazioni (rainfall)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Indice Ultravioletti (ultraviolet-index)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Conduttività Elettrica (electrical-conductivity)

Esempio di Dichiarazione delle 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 della conduttività elettrica. **Tipo:** Numero. Obbligatorio. **Unità:** dS/m.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Potenza di Trasmissione (transmit-power)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "transmitPower": 9 // Valore di potenza di trasmissione del dispositivo. **Tipo:** Intero. Obbligatorio. **Unità:** dBm.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Rilevamento PM2.5 (pm25)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "pm25": 10 // Concentrazione di PM2.5 nell'aria. **Tipo:** Numero. Obbligatorio. **Unità:** µg/m³.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Indice VOC (voc-index)

Esempio di Dichiarazione delle 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 (Query Stato & Istruzioni di Controllo):

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

Rilevamento Gas Naturale (gas)

Esempio di Dichiarazione delle Capacità:

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

Attributi (Stato):

{
  "gas": true // Indica se è rilevata una perdita di gas naturale. **Tipo:** Booleano. Obbligatorio.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Stato Lavoro Irrigazione (irrigation/work-status)

Esempio di Dichiarazione delle 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. Opzionale. **Unità:** L.
  "start": "2020-07-05T08:00:00Z", // Ora di inizio irrigazione. **Tipo:** Data. Opzionale.
  "end": "2020-07-05T09:00:00Z", // Ora di fine irrigazione. **Tipo:** Data. Opzionale.
  "dailyVolume": 20 // Volume giornaliero di irrigazione. **Tipo:** Numero. Opzionale. **Unità:** L.
}

Protocollo (Query Stato & 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 dello Stato di 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. Opzionale. Se omesso, viene utilizzato il tempo 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 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 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à di Lavoro Irrigazione (irrigation/work-mode)

Esempio di Dichiarazione delle Capacità:

[
  {
    "capability": "irrigation",
    "permission": "0100",
    "name": "work-mode",
    "settings": {
      "supportedModes": {
        "type": "enum",
        "permission": "01",
        "values": [
          "MANUAL", // Modalità manuale
          "TIMER", // Programmazione singola
          "CYCLE-TIMER", // Programmazione ripetuta
          "VOLUME", // Volume singolo
          "CYCLE-VOLUME" // Volume ripetuto
        ]
      }
    }
  }
]

Attributi (Stato):

{
  "workMode": "MANUAL" // Modalità di lavoro irrigazione. **Tipo:** Stringa. Opzionale. I valori devono provenire da `settings.supportedModes`.
}

Protocollo (Query Stato & Istruzioni di Controllo):

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

Controller Irrigazione Automatico (irrigation/auto-controller)

Esempio di Dichiarazione delle 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 conteggio cicli
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 100,
        "step": 1
      }
    }
  }
]

Attributi (Stato):

Programmazione 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 i 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 i cicli di irrigazione. **Tipo:** Numero. Obbligatorio.
    "count": 3 // Numero di cicli di irrigazione. **Tipo:** Numero. Obbligatorio.
  }
}

Protocollo (Query Stato & Istruzioni di Controllo):

Programmazione 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 Opzionali **
fanLevel (livello Ventilatore)	"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 del sottocomponente toggle.

{
    "toggle": {
        '1': 'Chanel1',
        '2': 'Chanel2',
        '3': 'Chanel3',
        '4': 'Chanel4',
    },
}

• 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 di Errore	Descrizione	Versione iHost
110000	Il sotto-dispositivo/gruppo corrispondente all'id non esiste	≥2.1.0
110001	Il gateway è nello stato di scoperta dei 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 la modalità offline	≥2.1.0
110015	La password dell'account non è coerente con la password dell'account nell'indirizzo stream RTSP	≥2.1.0
110016	Il gateway è nello stato di scoperta delle 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 del Sotto-dispositivo

Consentire agli utenti autorizzati di abilitare o disabilitare la ricerca di sotto-dispositivi del gateway tramite questa interfaccia

• 💡Nota: Ora supporta solo la ricerca di sotto-dispositivi Zigbee.

• 💡Nota: I sotto-dispositivi Zigbee verranno aggiunti automaticamente dopo la ricerca. Non è necessario utilizzare l'interfaccia "Aggiungi manualmente sotto-dispositivi" :::tips

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

• Metodo: PUT

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametri della richiesta:

Attributo	Tipo	Opzionale	Descrizione
enable	boolean	N	true (Avvia associazione); false (Pausa associazione)
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 è superata. **Codice di stato: ** 200 OK ::: Esempio di risposta:

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

f. Aggiunta Manuale del Sotto-dispositivo

Consentire agli utenti autorizzati di aggiungere un singolo sotto-dispositivo 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

  • Autorization: Bearer ::: Parametri della richiesta:

Attributo	Tipo	Opzionale	Descrizione
name	string	N	Nome del sotto-dispositivo
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 lettura.
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).
value	StreamSettingValueObject	N	Valori di configurazione specifici

StreamSettingValueObject

Attributo	Tipo	Opzionale	Descrizione
stream_url	string	N	Formato URL 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 tali casi, è possibile omettere <username> e <password> i 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 è superata. **Codice di stato: **200 OK ::: Esempio di risposta:

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

Risposta dati in caso di fallimento: Oggetto vuoto :::tips Condizione：

1. Errore accesso indirizzo stream camera (errore formato, autorizzazione fallita, eccezione di rete, ecc.)

2. Dispositivo già esistente

3. Se l'aggiunta di un singolo dispositivo fallisce, vengono restituiti tutti i dispositivi non aggiunti.

Codice di Stato: 200 OK Codice 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 Sotto-dispositivi

Consentire agli utenti autorizzati di ottenere l'elenco dei sotto-dispositivi del gateway tramite questa interfaccia. :::tips

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

• Metodo: GET

• Header：

  • Content-Type: application/json

  • Autorization: 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 un dispositivo di terze parti è connesso, altrimenti "Y"	Numero di serie univoco del dispositivo di terze parti
service_address	string	"N" quando un dispositivo di terze parti è connesso, altrimenti "Y"	Indirizzo del servizio di terze parti
name	string	N	Nome del dispositivo, se non rinominato, verrà 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 è compilato quando si ottiene il certificato dell'interfaccia open, allora tutti i dispositivi successivi collegati tramite il certificato verranno inseriti in questo campo.
display_category	string	N	Categoria dispositivo
capabilities	CapabilityObject[]	N	Capability del dispositivo
protocol	string	"N" quando un dispositivo di terze parti è connesso, altrimenti "Y"	Protocollo del dispositivo: zigbee, onvif, rtsp, esp32-cam
state	object	Y	Oggetto stato del dispositivo. Per esempi di stato di diverse capability, si prega di consultare 【Support Device Capabilities】
tags	object	Y	Formato JSON chiave-valore, 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 si trova nella stessa sottorete del gateway

CapabilityObject 💡Nota: Si prega di controllare gli Esempi di Capacità dei Dispositivi Supportati per [Capacità dei Dispositivi Supportate].

Attributo	Tipo	Opzionale	Descrizione
capability	string	N	Nome della capacità. Per dettagli, controllare [Capacità dei Dispositivi Supportate]
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 usato camera-stream, controllare [Capacità dei Dispositivi Supportate]
name	string	Y	Il campo name in toggle. Il numero del sotto-canale usato per identificare i dispositivi multi-canale. Per esempio, se name è 1, significa canale 1.

:::tips Condizioni: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è superata. **Codice di stato: **200 OK ::: Esempio di risposta:

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

h. Aggiorna informazioni o stato specificato del dispositivo

Consente agli utenti autorizzati di modificare le informazioni di base del sotto-dispositivo e inviare comandi di controllo tramite questa interfaccia. :::tips

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

• Metodo：PUT

• Header：

  • Content-Type: application/json

  • Autorization: Bearer ::: Parametri della richiesta:

Attributo	Tipo	Opzionale	Descrizione
name	string	Y	Nome del dispositivo
tags	object	Y	Formato JSON chiave-valore, informazioni personalizzate del dispositivo.
state	object	Y	Oggetto stato del dispositivo. Per esempi di stato delle diverse capacità, controllare [Capacità dei Dispositivi Supportate]
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 legali e la verifica dell'identità utente è superata. **Codice di stato: **200 OK Codice di Errore:

• 110000 Il sotto-dispositivo/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 Sotto-dispositivo

Consente agli utenti autorizzati di eliminare sotto-dispositivi tramite questa interfaccia. :::tips

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

• Metodo：DELETE

• Header：

  • Content-Type: application/json

  • Autorizzazione: Bearer ::: Parametri della richiesta:

Attributo	Tipo	Opzionale	Descrizione
name	string	Y	Nome del dispositivo.
tags	object	Y	Coppie chiave-valore in formato JSON utilizzate per memorizzare i nomi dei canali del dispositivo e altre informazioni sui sotto-dispositivi.
state	object	Y	Modifica lo stato del dispositivo; per i dettagli del protocollo specifico, fare riferimento a "Capacità dei Dispositivi Supportate."
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 modificati.

Risposta dati riuscita: :::tips Condizioni: I parametri della richiesta sono legali e la verifica dell'identità utente è superata. **Codice di stato: **200 OK Codici di errore:

• 110000: Il sotto-dispositivo/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://<domain name or ip address>/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 Sotto-Dispositivo

Consente agli utenti autorizzati di eliminare sotto-dispositivi 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 è superata. **Codice di stato: **200 OK ::: Esempio di risposta:

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

k. Interroga Stato del 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 i dettagli del protocollo specifico, fare riferimento a "Capacità dei Dispositivi Supportate."

import axios from 'axios';

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

(async function main() {
  // accendi dispositivo
  await axios({
    url: `http://<domain name or ip address>/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 sommaria, 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 a ora corrente
          }
        }
      }
    });
})()

Risposta dati riuscita: :::tips Condizioni: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è superata. **Codice di stato: **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 della 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 è superata. **Codice di stato: **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 è superata. **Codice di stato: **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 è superata. **Codice di stato: **200 OK ::: Esempio di risposta:

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

d. Abilitazione Rapida della Sicurezza

Consente agli utenti autorizzati di abilitare la modalità di impostazione rapida della sicurezza 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 è superata. **Codice di stato: **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 è superata. **Codice di stato: **200 OK ::: Esempio di risposta:

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

4. Accesso Dispositivi di Terze Parti

4.1 Istruzioni di Accesso

Accesso Dispositivo

1.0.jpg

Accesso gateway di terze parti

2.0.jpg

Passi di accesso

1. Determinare la classificazione del dispositivo nel gateway. Per i dettagli, consultare [Tipo di Dispositivo Supportato].

2. Determinare le capacità a cui il dispositivo può accedere. Per i dettagli, consultare [Capacità dei Dispositivi Supportate].

3. Richiedere l'interfaccia [Discovery Request] per aggiungere il dispositivo al gateway.

   1. Attenzione: È necessario fornire l'indirizzo di servizio per ricevere le istruzioni emesse dal gateway, che è usato 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 l'ultimo stato 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 open comuni correlate al dispositivo possono essere utilizzate normalmente.

• Selezionare la categoria di dispositivo appropriata. La classificazione influenzerà il risultato finale della visualizzazione dell'UI dopo che il dispositivo è connesso al gateway.

• Scegliere la capacità del dispositivo corretta. L'elenco delle capacità determinerà lo stato del protocollo di stato del dispositivo.

Processo del Programma

a. Accesso Dispositivo

3.0.jpg

b. Accesso Gateway di Terze Parti

4.0.jpg

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
  Autorizzazione: 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": "my plug",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission": "1100"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "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": "serial number"
      }
    ]
  }
}

Segnala stato del dispositivo

URL：/open-api/V2/rest/thirdparty/event
Metodo：POST
Header：
  Content-Type: application/json
  Autorizzazione: 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 dal 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
Metodo：GET
Header：
  Content-Type: application/json
  Autorizzazione: Bearer  <token>
Body: 无

{
  "error": 0,
  "data": {
    "device_list": [
      {
        "serial_number": "serial number",
        "third_serial_number": "third_serial_number",
        "name": "my plug",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "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 Gateway per Richieste di Terze Parti

Formato della Richiesta

Consente agli utenti autorizzati di inviare richieste di eventi al gateway tramite questa interfaccia. :::tips

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

• Metodo：POST

• Header：

  • Content-Type: application/json

  • Autorization: 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 una nuova lista 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: Rapporto di aggiornamento stato dispositivo DeviceOnlineChangeReport: Rapporto stato online dispositivo
message_id	string	N	ID del messaggio della richiesta, UUID_V4
version	string	N	Numero di versione del protocollo della richiesta. Attualmente fisso 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
tags	object	Y	Formato JSON chiave-valore, informazioni personalizzate del dispositivo. [Funzione di Gestione Dispositivi] - [Descrizione dei Tag]

PayloadObject In base al diverso header.name ha differenti strutture di richiesta.

Formato della Risposta

:::tips **Codice di stato: **200 OK Parametri di risposta: :::

Attributo	Tipo	Opzionale	Descrizione
header	HeaderObject	N	Informazioni sulla struttura dell'intestazione della risposta
payload	PayloadObject	N	Informazioni sulla struttura del payload della risposta

HeaderObject

Attributo	Tipo	Opzionale	Descrizione
name	string	N	Nome dell'intestazione della risposta. parametri opzionali:Response: Risposta riuscita ErrorResponse: Risposta di errore
message_id	string	N	ID del messaggio dell'intestazione della risposta, UUID_V4. Passare qui l'header.message_id del messaggio di richiesta*Se il parametro message_id manca nella richiesta, questo campo sarà una stringa vuota nella risposta.
version	string	N	- Numero di versione del protocollo della richiesta. Attualmente fisso a 1.

Risposta riuscita--PayloadObject ：

A seconda del tipo di richiesta, la struttura della risposta è differente. 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 | | description | string | N | Descrizione dell'errore |

DiscoveryRequest Sincronizza una nuova lista dispositivi

• Nota: Dopo che il dispositivo è sincronizzato al gateway, è online per impostazione predefinita, cioè online=true. I successivi cambiamenti 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. Vedere [Tipo di Dispositivo Supportato] per i dettagli. *I dispositivi di terze parti non supportano ora l'aggiunta di telecamere.
capabilities	CapabilityObject[]	N	Elenco delle capacità
state	object	N	Informazioni di stato iniziali
manufacturer	string	N	Produttore
model	string	N	Modello del dispositivo
tags	object	Y	Formato JSON chiave-valore, 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 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": "my plug",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission" "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "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": "serial number",
        "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 Rapporto 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 [Capacità dei dispositivi supportate] per dettaglio

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 Rapporto 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 Rapporto 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à dei dispositivi supportate. **Nota: **Questo parametro aggiornerà solo il value del impostazione chiave all'interno del CapabilityObject, e gli aggiornamenti sono consentiti solo se il permission per il impostazione key è 11 o 01. Per la definizione della struttura specifica del impostazione in CapabilityObject, fare riferimento alla descrizione dettagliata nella sezione 2.3 Categorie di Visualizzazione del Dispositivo & Capacità del Dispositivo. | | tags

| object

| Y

| Formato JSON chiave-valore, 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 in stato 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 del messaggio della richiesta, UUID_V4
version	string	N	Numero di versione del protocollo della richiesta. Attualmente fisso 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
tags	object	N	Formato JSON chiave-valore, informazioni personalizzate del dispositivo. [Funzione di Gestione Dispositivi] - [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 della 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 della risposta. Parametro opzionale: UpdateDeviceStatesResponse: Risposta aggiornamento stati dispositivo ErrorResponse: Risposta di errore
message_id	string	N	ID del messaggio dell'intestazione della risposta, UUID_V4. Passare qui l'header.message_id del messaggio di richiesta
version	string	N	Numero di versione del protocollo della richiesta. Attualmente fisso a 1.

Risposta riuscita--PayloadObject：

A seconda del tipo di richiesta, la struttura della risposta è differente. 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: Il 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 legali. **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 [Capacità dei dispositivi supportate] per dettaglio.

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 [Capacità dei dispositivi supportate] per dettaglio.

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 [Capacità dei dispositivi supportate] per dettaglio.

Esempio di risposta:

{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Identificatore univoco, preferibilmente un UUID versione 4",
      "version": "2"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "electricityIntervals": [ // Diviso in più record in base a configuration.resolution
            {
              "usage": 26.5, // Valore del 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 è minore di resolution, tutti i record riportati sono considerati non validi.
            },
            {
              "usage": 26.5, // Valore del 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 è minore di resolution, tutti i record riportati sono considerati non validi.
            }
          ]
        }
      }
    }
  }
}

ConfigureDeviceCapabilities

Parametri della richiesta: PayloadObject：

Attributo	Tipo	Opzionale	Descrizione
capabilities	CapabilityObject[]	N	Elenco delle capacità. I dettagli possono essere consultati nella parte delle capacità dei dispositivi supportate. Nota, il campo permission non può essere modificato, inviare 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 del controllo della 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 dovrebbe 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 dovrebbe 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 l'invio di messaggi al client utilizzando 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 in base al protocollo di notifica eventi dell'interfaccia di sviluppo dopo aver ricevuto i messaggi inviati dal gateway. Si noti che il gateway attualmente utilizza il protocollo HTTP1.1, quindi SSE dal lato browser avrà un limite massimo di non più di 6 connessioni (Istruzioni specifiche si trovano 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	Access Token

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://<domain name or ip address>/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": "Mydevice",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "1100"
      },
      {
        "capability": "rssi",
        "permission": "0100"
      }
    ],
    "protocal": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  }
}

b. Evento Aggiorna Stato Dispositivo

:::tips Nome Modulo：device Versione：v2 Tipo Messaggio：updateDeviceState event.data parametri： :::

Nome	Tipo	Opzionale	Descrizione
endpoint	EndpointObject	N	Informazioni del Dispositivo
payload	oggetto。 Struttura uguale allo stato del dispositivo	N	Dati di 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 open, 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 del 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 open, questo campo è obbligatorio.

DeviceChangeObject

Nome	Tipo	Opzionale	Descrizione
name	string	N	Nome del Dispositivo
capabilities	CapabilityObject []	Y	Elenco delle capacità del dispositivo.
tags	object	Y	tagsobject | Nullable | Coppie chiave-valore in formato JSON per informazioni personalizzate del dispositivo.

• 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": "device name",
    "capabilities": [
      {
        "capability": "thermostat-mode-detect",
        "permission": "0110",
        "name": "temperature", // Tipo di rilevamento del controllo della 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 dovrebbe 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 dovrebbe 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 **	** Facoltativo**	** Descrizione **
endpoint	EndpointObject	N	Informazioni 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 open, questo campo è obbligatorio.

Esempio:

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

e. Evento Aggiorna Stato Online Dispositivo

:::tips Nome Modulo：device Versione：v2 Tipo Messaggio：updateDeviceOnline event.data parametri： :::

Nome	Tipo	Opzionale	Descrizione
endpoint	EndpointObject	N	Informazioni del 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 open, 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 del 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 disarmamento

ArmStateObject：

Attributo	Tipo	Opzionale	Descrizione
arm_state	string	N

• arming | Armato

• disarming | Disarmato | | detail | DetailObject | N | Dettagli armamento/disarmamento |

DetailObject：

Attributo	Tipo	Opzionale	Descrizione
sid	int	N	id della modalità di sicurezza
name	string	N	Nome della 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 motore TTS è responsabile della registrazione del motore TTS sul gateway e della fornitura dei servizi TTS

• Server Gateway：iHost

• Client Open API 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 server service_address, e le successive comunicazioni tra il gateway e il fornitore del servizio TTS avverranno attraverso l'indirizzo server_address), e assegnerà l'ID del servizio motore TTS all'interno del gateway.

image.png

6.1.2 Ottenere l'elenco degli audio sintetizzati

1. 【Client Open API 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 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.

image.png

6.1.3 Sintesi vocale specificando un motore vocale

1. 【Client Open API 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 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.

image.png

6.1.4 Sintetizzare l'audio e riprodurre la voce TTS.

1. 【Client Open API 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 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 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

  • Authorization: Bearer ::: Parametri della richiesta: nessuno Risposta dati corretta:

Attributo	Tipo	Opzionale	Descrizione
engines	EngineObject []	N	Elenco dei motori TTS registrati

Struttura di EngineObject

Attributo	Tipo	Opzionale	Descrizione
id	string	N	ID del motore assegnato dal gateway
name	string	N	Nome del servizio motore TS

:::tips Condizioni: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. **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

  • Authorization: Bearer ::: Parametri della richiesta: nessuno Risposta dati corretta:

Attributo	Tipo	Opzionale	Descrizione
audio_list	AudioObject []	N	Elenco audio

Struttura di 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 legali e la verifica dell'identità dell'utente è passata. **Codice di stato: **200 OK **Codice di errore: **

• 190000 Il motore funziona 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 utilizzando il motore TTS specificato

:::tips

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

• Metodo：POST

• Header：

  • Content-Type: application/json

  • Authorization: Bearer ::: Parametri della richiesta:

Attributo	Tipo	Opzionale	Descrizione
text	string	N	Testo utilizzato 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 motore TTS deve supportare una lingua predefinita per la sintesi vocale, il che significa che se la lingua non viene passata, verrà utilizzata la lingua predefinita del motore per la sintesi.
options	object	Y	Campo trasparente. Viene utilizzato per passare i parametri di configurazione necessari per la sintesi al servizio motore TTS.

Risposta dati corretta:

Attributo	Tipo	Opzionale	Descrizione
audio	AudioObject	N	Elenco audio

Struttura di 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 legali e la verifica dell'identità dell'utente è passata. **Codice di stato: **200 OK **Codice di errore: **

• 190000 Il motore funziona 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 la 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

  • Authorization: Bearer ::: Parametri della richiesta:

Attributo	Tipo	Opzionale	Descrizione
evento	EventObject	N	Struttura dell'oggetto evento di richiesta Informazioni

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 fisso 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 fisso a 1 |

PayloadObject

Attributo	Tipo	Opzionale	Descrizione
engine_id	string	N	ID del motore assegnato dal gateway

:::tips Condizioni: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. **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 anomali: **

Attributo	Tipo	Opzionale	Descrizione
type	string	N	Tipo di errore

• INVALID_PARAMETERS (Parametri errati)

• AUTH_FAILURE (Autenticazione fallita)

• 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 dell'elenco audio

Inviare il comando al fornitore del servizio TTS da parte del 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 fisso 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 fisso a 1 |

PayloadObject:

Attributo	Tipo	Opzionale	Descrizione
audio_list	AudioObject []	N	Elenco audio TTS

Struttura di 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 legali e la verifica dell'identità dell'utente è passata. **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 anomali: **

Attributo	Tipo	Opzionale	Descrizione
type	string	N	Tipo di errore

• INVALID_PARAMETERS (Parametri errati)

• AUTH_FAILURE (Autenticazione fallita)

• 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 da parte del 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 fisso a 1 |

PayloadObject

Attributo	Tipo	Opzionale	Descrizione
text	string	N	Testo utilizzato 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 motore TTS deve supportare una lingua predefinita per la sintesi vocale, il che significa che se la lingua non viene passata, verrà utilizzata la lingua predefinita del motore per la sintesi.
options	object	Y	Campo trasparente. Viene utilizzato per passare i parametri di configurazione necessari per la sintesi al servizio motore 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 fisso a 1 |

PayloadObject

Attributo	Tipo	Opzionale	Descrizione
audio	AudioObject	N	Audio TTS

Struttura di 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 legali e la verifica dell'identità dell'utente è passata. **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 anomali: **

Attributo	Tipo	Opzionale	Descrizione
type	string	N	Tipo di errore

• INVALID_PARAMETERS (Parametri errati)

• AUTH_FAILURE (Autenticazione fallita)

• 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

  • Authorization: Bearer ::: Parametri della richiesta:

Attributo	Tipo	Opzionale	Descrizione
audio_url	string	N	Indirizzo URL audio

Risposta dati corretta: :::tips Condizioni: I parametri della richiesta sono legali e la verifica dell'identità dell'utente è passata. **Codice di stato: **200 OK Esempio di risposta:： :::

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

8. Scheda UI personalizzata

Le schede UI personalizzate consentono di visualizzare qualsiasi contenuto si desideri all'interno della scheda. Questo contenuto può essere una pagina web, un'immagine o qualsiasi servizio con un'interfaccia utente. È sufficiente fornire l'URL del contenuto che si desidera visualizzare. La scheda UI adatterà automaticamente la larghezza e l'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 gateway (iHost).

• Client Open API 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]: Al momento della 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.

image.png

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.

image.png

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]: In caso di modifica avvenuta con successo, il gateway memorizza le informazioni aggiornate della scheda UI, inclusa la nuova configurazione delle dimensioni e l'URL della risorsa.

image.png

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 relative alla scheda UI specificata.

image.png

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

  • Authorization: Bearer ::: Parametri della richiesta:

Attributo	Tipo	Opzionale	Descrizione
label	string	Y	Etichetta della scheda: utilizzata 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 delle dimensioni: Deve includere almeno una configurazione.
default	string	N	Specifiche predefinite: La specifica delle dimensioni predefinita viene utilizzata, con parametri opzionali: 2x2

WebSettingsObject:

Attributo	Tipo	Opzionale	Descrizione
dimensions	DimensionObject []	N	Configurazione delle dimensioni: Deve includere almeno una configurazione.
drawer_component	DrawerObject	Y	Impostazioni di visualizzazione del componente Drawer.
default	string	N	Specifiche predefinite:

• 1x1

• 2x1 |

DimensionObject:

Attributo	Tipo	Opzionale	Descrizione
src	string	N	URL della risorsa: Per esempio: http://example.html
size	string	N	Specifiche delle dimensioni:
Parametri opzionali di CastSettingsObject:

• 2×2

Parametri opzionali di 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 è superata. **Codice di stato: ** 200 OK ::: Esempio di richiesta：

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

  • Authorization: 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: utilizzata per descrivere la scheda. Serve come alias o nome per la scheda.
cast_settings	CastSettingsObject	Y	Etichetta della scheda: utilizzata 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 delle dimensioni: Deve includere almeno una configurazione.
default	string	N	Specifiche predefinite:
Parametro opzionale: 2x2
used	string	N	Specificazione corrente:
Parametro opzionale: 2x2

WebSettingsObject:

Attributo	Tipo	Opzionale	Descrizione
dimensions	DimensionObject []	N	Configurazione delle dimensioni: Deve includere almeno una configurazione.
drawer_component	DrawerObject	Y	Impostazioni di visualizzazione del componente Drawer.
default	string	N	Specifiche predefinite:
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 delle dimensioni:
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

  • Authorization: Bearer ::: Parametri della richiesta:

Attributo	Tipo	Opzionale	Descrizione
label	string	Y	Utilizzato 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
used	string	Y, Uno dei due used o src deve essere fornito, ma è richiesto almeno uno di questi parametri.	Specificazione corrente:
Parametro opzionale:

• 2x2

| | src | string | Y, Uno dei due used o src deve essere fornito, ma è richiesto almeno uno di questi parametri. | URL della risorsa: http://example.html |

WebSettingsObject:

Attributo	Tipo	Opzionale	Descrizione
used	string	Y, Uno dei due used o src deve essere fornito, ma è richiesto almeno uno di questi parametri.	Specificazione corrente:
Parametro opzionale:

• 1x1

• 2x1 | | src | string | Y, Uno dei due used 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 legali e la verifica dell'identità dell'utente è passata. La scheda UI che viene modificata deve essere stata creata dal fornitore del servizio di schede UI personalizzate che chiama l'interfaccia. **Codice di stato: ** 200 OK Codice di errore:

• 406: Nessun permesso 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

  • 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. La scheda UI che viene modificata deve essere stata creata dal fornitore del servizio di schede UI personalizzate che chiama l'interfaccia. **Codice di stato: ** 200 OK Codice di errore:

• 406: Nessun permesso per accedere a questa risorsa. ::: **Esempio di risposta: **

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