Guida al sistema di sicurezza per la smart home

action.devices.types.SECURITYSYSTEM - I sistemi di sicurezza possono essere abilitati e disabilitati. Possono essere abilitati a più livelli di sicurezza (ad esempio, in casa e fuori casa) e possono segnalare informazioni su determinati sensori, ad esempio un sensore che rileva i movimenti o una finestra aperta.

Questo tipo indica che il dispositivo riceve l'icona del sistema di sicurezza e alcuni sinonimi e alias correlati.

Funzionalità del dispositivo

Per i dettagli di implementazione, ad esempio gli attributi e gli stati che il tuo servizio deve supportare e come creare risposte EXECUTE e QUERY, consulta la documentazione del tratto corrispondente.

Tratti obbligatori

Questi tratti e comandi sono obbligatori, se applicabili al tuo dispositivo. Se il tuo dispositivo non supporta questi tratti, inserisci il codice di errore functionNotSupported in una risposta QUERY o EXECUTE. Per ulteriori informazioni, consulta la sezione Errori ed eccezioni.

Questi tratti sono consigliati, se applicabili al tuo dispositivo. Tuttavia, puoi combinare tutti i tratti disponibili per adattarli al meglio alle funzionalità del tuo prodotto esistente.

Esempio di dispositivo: sistema di sicurezza semplice

Questa sezione contiene esempi di payload di intent che rappresentano un "sistema di sicurezza" comune basato sul tipo di dispositivo e sui tratti sopra indicati. Se aggiungi o rimuovi tratti nell'implementazione, modifica le risposte di conseguenza per riflettere queste modifiche.

Esempio di risposta SYNC

Richiesta
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Risposta
{
  "requestId": "6894439706274654512",
  "payload": {
    "agentUserId": "user123",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.SECURITYSYSTEM",
        "traits": [
          "action.devices.traits.StatusReport",
          "action.devices.traits.ArmDisarm"
        ],
        "name": {
          "name": "Simple security system"
        },
        "willReportState": true,
        "attributes": {
          "availableArmLevels": {
            "levels": [
              {
                "level_name": "home_key",
                "level_values": [
                  {
                    "level_synonym": [
                      "Home and Guarding",
                      "level 1",
                      "home",
                      "SL1"
                    ],
                    "lang": "en"
                  }
                ]
              },
              {
                "level_name": "away_key",
                "level_values": [
                  {
                    "level_synonym": [
                      "Away and Guarding",
                      "level 2",
                      "away",
                      "SL2"
                    ],
                    "lang": "en"
                  }
                ]
              }
            ],
            "ordered": true
          }
        },
        "deviceInfo": {
          "manufacturer": "smart-home-inc",
          "model": "hs1234",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        }
      }
    ]
  }
}

Esempio di risposta QUERY

Richiesta
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
Risposta
{
  "requestId": "6894439706274654514",
  "payload": {
    "devices": {
      "123": {
        "status": "SUCCESS",
        "online": true,
        "isArmed": true,
        "currentArmLevel": "home_key",
        "currentStatusReport": [
          {
            "blocking": false,
            "deviceTarget": "123",
            "priority": 0,
            "statusCode": "lowBattery"
          }
        ]
      }
    }
  }
}

Esempio di comandi EXECUTE

ArmDisarm

Per ulteriori dettagli sui parametri dei comandi, consulta il action.devices.traits.ArmDisarm riferimento.

Richiesta
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ArmDisarm",
                "params": {
                  "arm": true,
                  "armLevel": "away_key"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Risposta
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

ERRORI del dispositivo

Consulta l'elenco completo di errori ed eccezioni.

Segnalare le eccezioni di abilitazione

Quando tenti di abilitare o disabilitare il sistema, puoi fornire un contesto aggiuntivo tramite i codici di eccezione che segnali tramite il tratto StatusReport. Le eccezioni possono essere segnalate come bloccanti o non bloccanti.

  • Le eccezioni non bloccanti segnalate con lo stato "SUCCESS" indicano che l'eccezione non ha impedito l'abilitazione o la disabilitazione.
  • Eccezioni bloccanti segnalate con lo stato "EXCEPTIONS" indicano che l'abilitazione o la disabilitazione è stata interrotta a causa di queste eccezioni.

I codici di eccezione comunemente associati ai sistemi di sicurezza includono:

  • doorOpen: una porta è aperta.
  • windowOpen: una finestra è aperta.
  • isOpen: un sensore rileva che qualcosa è aperto (ma non sa se si tratta di una porta o di una finestra).

Esempio: eccezione non bloccante

Questo esempio mostra un'eccezione non bloccante in cui il sistema di sicurezza è abilitato anche se una finestra è segnalata come aperta.

Utente Imposta il sistema di sicurezza su Protezione alta.
Assistente Google Ok, la finestra anteriore è aperta. Abilito il sistema di sicurezza su Protezione alta.
Richiesta
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true,
              "armLevel": "L2"
            }
          }]
        }]
      }
    }]
  }
Risposta
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "online": true,
            "isArmed": true,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": false,
                "priority": 0,
                "statusCode": "windowOpen",
                "deviceTarget": "sensor_id1"
              }
            ]
          }
        }
      ]
    }
  }

Esempio: eccezione bloccante

Utente Imposta il sistema di sicurezza su Protezione alta.
Assistente Google Si è verificato un errore durante il controllo del sistema di sicurezza. La finestra anteriore è aperta.
Richiesta
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true,
              "armLevel": "L2"
            }
          }]
        }]
      }
    }]
  }
Risposta 2
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "EXCEPTIONS",
          "states": {
            "online": true,
            "isArmed": false,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": true,
                "priority": 0,
                "statusCode": "windowOpen",
                "deviceTarget": "sensor_id1"
              }
            ]
          }
        }
      ]
    }
  }

Abilitare con l'autenticazione a due fattori

Se il flusso di abilitazione richiede agli utenti di inserire un PIN tramite una finestra di dialogo di autenticazione a due fattori, devi indicare se vogliono continuare ad abilitare il sistema quando sono presenti eccezioni attive (ad esempio, quando una finestra o una porta è aperta).

Questo scenario potrebbe richiedere sia l'inserimento di un PIN o di una passphrase, seguito da una conferma.

Esempio: richiesta di conferma

Questo esempio mostra un utente che tenta di abilitare il sistema di sicurezza, ma viene rilevata una porta d'ingresso aperta. L'utente conferma che il sistema di sicurezza deve essere abilitato anche se la porta d'ingresso è aperta.

Utente Abilita il sistema di sicurezza.
Assistente Google La porta d'ingresso è aperta. Vuoi abilitare il sistema di sicurezza?
Utente Sì.
Assistente Google Ok, abilito il sistema di sicurezza.

Nel primo turno, devi rispondere con una richiesta ackNeeded.

Richiesta 1
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true
            }
          }]
        }]
      }
    }]
  }
Risposta 2
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "ERROR",
          "errorCode": "challengeNeeded",
          "challengeNeeded": {
            "type": "ackNeeded"
          },
          "states": {
            "isArmed": true,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": false,
                "priority": 0,
                "statusCode": "doorOpen",
                "deviceTarget": "456"
              }
            ]
          }
        }
      ]
    }
  }

La richiesta successiva di Google conterrà il risultato ack.

Richiesta 2
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true
            },
            "challenge": {
              "ack": true
            }
          }]
        }]
      }
    }]
  }
Risposta
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "isArmed": true
          }
        }
      ]
    }
  }

Esempio: richiesta di PIN e conferma

Questo esempio mostra un utente che tenta di abilitare il sistema di sicurezza che richiede l'inserimento del PIN. Il sistema rileva che le finestre anteriore e posteriore sono aperte e chiede all'utente di confermare che l'abilitazione deve continuare.

Utente Abilita Fuori.
Assistente Google Qual è il tuo PIN?
Utente 1234.
Assistente Google Sembra che la finestra anteriore e quella posteriore siano aperte. Vuoi continuare ad abilitare il sistema di sicurezza su Fuori?
Utente Sì.
Assistente Google Ok, abilito il sistema di sicurezza su Fuori.

Nel primo turno, devi rispondere con una richiesta pinNeeded standard.

Richiesta 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.ArmDisarm",
          "params": {
            "arm": true
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Google invia una richiesta contenente il PIN fornito. Per supportare il secondo turno, devi rispondere con una sfida ackNeeded con informazioni aggiuntive, tra cui il livello di sicurezza di destinazione e il report sullo stato attuale con eccezioni bloccanti.

Richiesta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [...],
        "execution": [{
          "command": "action.devices.commands.ArmDisarm",
          "params": {
            "arm": true,
            "armLevel": "away"
          },
          "challenge": {
            "pin": "1234"
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "states": {
        "targetArmLevel": "away",
        "currentStatusReport": [{
            "blocking": true,
            "priority": 1,
            "deviceTarget": "front_window_id",
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "priority": 1,
            "deviceTarget": "back_window_id",
            "statusCode": "deviceOpen"
          }
        ]
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

La richiesta successiva di Google conterrà solo il risultato ack, e non il PIN fornito nel primo turno.

Richiesta 3
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [...],
        "execution": [{
          "command": "action.devices.commands.ArmDisarm",
          "params": {
            "arm": true,
            "armLevel": "away"
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}