Schema del tratto NetworkControl per la smart home

action.devices.traits.NetworkControl: questo attributo appartiene ai dispositivi che supportano la generazione di report sui dati di rete ed eseguono operazioni specifiche per la rete.

ATTRIBUTI del dispositivo

I dispositivi con questa caratteristica possono segnalare i seguenti attributi nell'ambito dell'operazione SYNC. Per scoprire di più sulla gestione degli intent SYNC, consulta Adempimento degli intent.

Attributi Tipo Descrizione
supportsEnablingGuestNetwork Valore booleano

(valore predefinito: false)

Imposta su true se la rete ospite può essere attivata.
supportsDisablingGuestNetwork Valore booleano

(valore predefinito: false)

Imposta su true se la rete ospite può essere disattivata.
supportsGettingGuestNetworkPassword Valore booleano

(valore predefinito: false)

Imposta su true se la password della rete ospite può essere ottenuta tramite il comando GetGuestNetworkPassword.
networkProfiles Array

Indica i nomi dei profili di rete supportati.
[item, ...] String

Nome di un profilo di rete che rappresenta un gruppo di dispositivi correlati.
supportsEnablingNetworkProfile Valore booleano

(valore predefinito: "false")

Imposta su true se è possibile attivare i profili di rete.
supportsDisablingNetworkProfile Valore booleano

(valore predefinito: "false")

Impostato su true se i profili di rete possono essere disattivati.
supportsNetworkDownloadSpeedTest Valore booleano

(valore predefinito: false)

Impostato su true se è possibile eseguire un test della velocità di download.
supportsNetworkUploadSpeedTest Valore booleano

(valore predefinito: false)

Impostato su true se è possibile eseguire un test della velocità di caricamento.

Esempi

Dispositivo di rete che supporta la rete ospite, i profili e il test di velocità.

{
  "supportsEnablingGuestNetwork": true,
  "supportsDisablingGuestNetwork": true,
  "supportsEnablingNetworkProfile": true,
  "supportsDisablingNetworkProfile": true,
  "supportsNetworkDownloadSpeedTest": true,
  "supportsNetworkUploadSpeedTest": true,
  "supportsGettingGuestNetworkPassword": true,
  "networkProfiles": [
    "Kids"
  ]
}

STATI del dispositivo

Le entità con questo attributo possono segnalare i seguenti stati nell'ambito dell'operazione QUERY. Per scoprire di più sulla gestione degli intent QUERY, consulta Adempimento degli intent.

Stati Tipo Descrizione
networkEnabled Valore booleano

Indica se la rete principale è attiva.
networkSettings Oggetto

Contiene l'SSID della rete principale.
ssid String

Obbligatorio.

SSID della rete.
guestNetworkEnabled Valore booleano

Indica se la rete ospite è attivata.
guestNetworkSettings Oggetto

Contiene l'SSID della rete ospite.
ssid String

Obbligatorio.

SSID della rete.
numConnectedDevices Intero

Il numero di dispositivi connessi alla rete.
networkUsageMB Number

L'utilizzo della rete in MB (megabyte). L'utilizzo della rete rientra nel periodo di fatturazione corrente, il che può essere utile da monitorare rispetto a un limite di utilizzo della rete per periodo di fatturazione.
networkUsageLimitMB Number

Il limite di utilizzo della rete in MB (megabyte). Il limite di utilizzo della rete rientra nel periodo di fatturazione corrente.
networkUsageUnlimited Valore booleano

Se l'utilizzo della rete è illimitato. Lo stato del dispositivo networkUsageLimitMB verrà ignorato se è impostato su true.
lastNetworkDownloadSpeedTest Oggetto

Contiene i risultati del test di velocità di download della rete più recente.
downloadSpeedMbps Number

La velocità di download in Mbps (megabit al secondo) dell'ultimo test della velocità della rete.
unixTimestampSec Intero

Il timestamp Unix (numero di secondi dall'epoca Unix) dell'ora in cui è stato eseguito l'ultimo test della velocità di download della rete.
status String

Indica se l'ultimo test della velocità di download della rete è riuscito o meno.

Valori supportati:

SUCCESS
FAILURE
lastNetworkUploadSpeedTest Oggetto

Contiene i risultati del test di velocità di caricamento della rete più recente.
uploadSpeedMbps Number

La velocità di upload in Mbps (megabit al secondo) dell'ultimo test della velocità della rete.
unixTimestampSec Intero

Il timestamp Unix (numero di secondi dall'epoca Unix) dell'ora in cui è stato eseguito l'ultimo test della velocità di caricamento della rete.
status String

Indica se l'ultimo test della velocità di caricamento della rete è riuscito o meno.

Valori supportati:

SUCCESS
FAILURE
networkSpeedTestInProgress Valore booleano

(valore predefinito: false)

Indica se è in corso un test di velocità.
networkProfilesState Oggetto

Stato dei profili di rete. Questo oggetto di primo livello deve contenere coppie chiave/valore in cui la chiave è il nome di uno dei profili di rete elencati nell'attributo networkProfiles e il valore deve essere lo stato corrispondente del profilo.
<string> Oggetto

Un oggetto che memorizza lo stato di un singolo profilo di rete. Il valore della chiave deve essere il nome di uno dei profili di rete nell'attributo networkProfiles.
enabled Valore booleano

Lo stato attuale di attivazione/disattivazione del profilo di rete.

Esempi

Dispositivo con una rete attiva.

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "guestNetworkSettings": {
    "ssid": "home-network-123-guest"
  },
  "numConnectedDevices": 4,
  "networkUsageMB": 100.8
}

Dispositivo con una rete attiva e risultati del test di velocità.

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "guestNetworkSettings": {
    "ssid": "home-network-123-guest"
  },
  "numConnectedDevices": 4,
  "networkUsageMB": 100.8,
  "lastNetworkDownloadSpeedTest": {
    "downloadSpeedMbps": 159.8,
    "unixTimestampSec": 1563215576,
    "status": "SUCCESS"
  },
  "lastNetworkUploadSpeedTest": {
    "uploadSpeedMbps": 64.1,
    "unixTimestampSec": 1563215576,
    "status": "SUCCESS"
  }
}

Dispositivo con una rete attiva e un test di velocità in corso.

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "guestNetworkSettings": {
    "ssid": "home-network-123-guest"
  },
  "numConnectedDevices": 4,
  "networkUsageMB": 100.8,
  "networkSpeedTestInProgress": true
}

Dispositivo con networkProfile "kids" disattivato.

{
  "networkEnabled": true,
  "networkSettings": {
    "ssid": "home-network-123"
  },
  "networkProfilesState": {
    "parents": {
      "enabled": true
    },
    "kids": {
      "enabled": false
    }
  }
}

COMANDI del dispositivo

I dispositivi con questa caratteristica possono rispondere ai seguenti comandi nell'ambito dell'operazione EXECUTE. Per scoprire di più sulla gestione degli intent EXECUTE, consulta Adempimento degli intent.

action.devices.commands.EnableDisableGuestNetwork

Attiva o disattiva la rete ospite. È necessario utilizzare la verifica utente secondaria con PIN. La sicurezza domestica di un utente può essere considerata interessata se altri dispositivi di sicurezza vengono disattivati tramite questi comandi.

Questo comando richiede i seguenti attributi: 
{
  "supportsEnablingGuestNetwork": true,
  "supportsDisablingGuestNetwork": true
}

Parametri

Parametri Tipo Descrizione
enable Valore booleano

Obbligatorio.

True per attivare la rete ospite, false per disattivarla.

Esempi

Attiva la rete ospite.

{
  "command": "action.devices.commands.EnableDisableGuestNetwork",
  "params": {
    "enable": true
  }
}

action.devices.commands.EnableDisableNetworkProfile

Attiva o disattiva un profilo di rete. È necessario utilizzare la verifica utente secondaria con PIN. La sicurezza domestica di un utente può essere considerata interessata se altri dispositivi di sicurezza vengono disattivati tramite questi comandi.

Questo comando richiede i seguenti attributi: 
{
  "supportsEnablingNetworkProfile": true,
  "supportsDisablingNetworkProfile": true
}

Parametri

Parametri Tipo Descrizione
profile String

Obbligatorio.

Il nome del profilo dall'attributo networkProfiles.
enable Valore booleano

Obbligatorio.

True per attivare il profilo, false per disattivarlo.

Esempi

Disattiva internet per i bambini.

{
  "command": "action.devices.commands.EnableDisableNetworkProfile",
  "params": {
    "profile": "Kids",
    "enable": false
  }
}

Si è verificato un errore durante il tentativo di controllare il profilo della rete specificato.

Valori supportati:

networkProfileNotRecognized

action.devices.commands.GetGuestNetworkPassword

Ottieni la password della rete ospite. È necessario utilizzare la verifica utente secondaria con PIN. La sicurezza domestica di un utente può essere considerata interessata se altri dispositivi di sicurezza vengono disattivati tramite questi comandi.

Questo comando richiede i seguenti attributi: 
{
  "supportsGettingGuestNetworkPassword": true
}

Parametri

Parametri Tipo Descrizione

Nessuna proprietà

Esempi

Fammi vedere la password del Wi-Fi ospite.

{
  "command": "action.devices.commands.GetGuestNetworkPassword",
  "params": {}
}

Risultati

Risultati Tipo Descrizione
guestNetworkPassword String

Obbligatorio.

La password della rete ospite.

Esempi

Fammi vedere la password del Wi-Fi ospite.

{
  "guestNetworkPassword": "123456"
}

action.devices.commands.TestNetworkSpeed

Verifica la velocità in download e in upload della rete.

Questo comando richiede i seguenti attributi: 
{
  "supportsNetworkDownloadSpeedTest": true,
  "supportsNetworkUploadSpeedTest": true
}

Parametri

Parametri Tipo Descrizione
testDownloadSpeed Valore booleano

Obbligatorio.

Indica se è necessario testare la velocità in download.
testUploadSpeed Valore booleano

Obbligatorio.

Indica se è necessario testare la velocità in upload.
followUpToken String

Obbligatorio.

Token fornito da Google per la risposta di follow-up.

Esempi

Qual è la velocità della connessione Wi-Fi?

{
  "command": "action.devices.commands.TestNetworkSpeed",
  "params": {
    "testDownloadSpeed": true,
    "testUploadSpeed": true,
    "followUpToken": "123"
  }
}

Si è verificato un errore durante il tentativo di richiedere un test di velocità.

Valori supportati:

networkSpeedTestInProgress

Risposte di follow-up

I dispositivi con questa caratteristica possono restituire il seguente payload della risposta di follow-up nell'ambito dell'operazione EXECUTE. Per scoprire di più sull'implementazione delle risposte di follow-up, consulta Notifiche per le azioni per la smart home.

Il payload contiene uno dei seguenti elementi:

Successo: networkDownloadSpeedMbps

Campi Tipo Descrizione
followUpToken String

Obbligatorio.

Token fornito nella richiesta EXECUTE originale.
status String

Obbligatorio.

Risultato della richiesta.

Valori supportati:

SUCCESS
networkDownloadSpeedMbps Number

Obbligatorio.

La velocità di download della rete misurata in megabit al secondo.

Successo: networkUploadSpeedMbps

Campi Tipo Descrizione
followUpToken String

Obbligatorio.

Token fornito nella richiesta EXECUTE originale.
status String

Obbligatorio.

Risultato della richiesta.

Valori supportati:

SUCCESS
networkUploadSpeedMbps Number

Obbligatorio.

La velocità di upload della rete misurata in megabit al secondo.

Successo: networkDownloadSpeedMbps e networkUploadSpeedMbps

Campi Tipo Descrizione
followUpToken String

Obbligatorio.

Token fornito nella richiesta EXECUTE originale.
status String

Obbligatorio.

Risultato della richiesta.

Valori supportati:

SUCCESS
networkDownloadSpeedMbps Number

Obbligatorio.

La velocità di download della rete misurata in megabit al secondo.
networkUploadSpeedMbps Number

Obbligatorio.

La velocità di upload della rete misurata in megabit al secondo.

Operazione non riuscita

Campi Tipo Descrizione
followUpToken String

Obbligatorio.

Token fornito nella richiesta EXECUTE originale.
status String

Obbligatorio.

Risultato della richiesta.

Valori supportati:

FAILURE
errorCode String

Obbligatorio.

Il valore può essere qualsiasi codice di errore per questa caratteristica, ad esempio transientError.

Esempi

Qual è la velocità della connessione Wi-Fi? (follow-up response)

{
  "NetworkControl": {
    "priority": 0,
    "followUpResponse": {
      "status": "SUCCESS",
      "networkDownloadSpeedMbps": 23.3,
      "networkUploadSpeedMbps": 10.2,
      "followUpToken": "1234"
    }
  }
}

Qual è la velocità della connessione Wi-Fi? (follow-up response with failure)

{
  "NetworkControl": {
    "priority": 0,
    "followUpResponse": {
      "status": "FAILURE",
      "errorCode": "transientError",
      "followUpToken": "1234"
    }
  }
}

ERRORI del dispositivo

Consulta l'elenco completo di errori ed eccezioni.

Si è verificato un errore durante il tentativo di controllare il profilo della rete specificato.

Valori supportati:

networkProfileNotRecognized

Si è verificato un errore durante il tentativo di richiedere un test di velocità.

Valori supportati:

networkSpeedTestInProgress