Implementazione dei dispositivi e procedure consigliate per IoT Central

  • Articolo

Questo articolo fornisce informazioni su come implementare i dispositivi che si connettono all'applicazione IoT Central. Include anche alcune procedure consigliate. Per altre informazioni sul processo di connessione generale, vedere Connessione un dispositivo.

Per il codice di implementazione di un dispositivo di esempio, vedere Esercitazione: Creare e connettere un'applicazione client all'applicazione Azure IoT Central.

Implementare il dispositivo

I dispositivi che si connettono a IoT Central devono seguire le convenzioni di Plug and Play IoT. Una di queste convenzioni è che un dispositivo deve inviare l'ID modello del modello di dispositivo che implementa quando si connette. L'ID modello consente all'applicazione IoT Central di assegnare il dispositivo al modello di dispositivo corretto.

Un modello di dispositivo di IoT Central include un modello che specifica i comportamenti che dovranno essere implementati da un dispositivo di questo tipo. I comportamenti includono dati di telemetria, proprietà e comandi.

Ogni modello ha un identificatore univoco del modello di gemelli digitali (DTMI), ad esempio dtmi:com:example:Thermostat;1. Quando un dispositivo si connette a IoT Central, invia l'identificatore DTMI del modello che implementa. IoT Central può quindi assegnare il modello di dispositivo corretto al dispositivo.

Plug and Play IoT definisce un set di convenzioni che un dispositivo deve seguire quando implementa un modello DTDL (Digital Twin Definition Language).

Gli Azure IoT SDK per dispositivi includono il supporto per le convenzioni di Plug and Play IoT.

Device model (Modello del dispositivo)

Un modello di dispositivo viene definito usando il linguaggio di modellazione DTDL V2 . Questo linguaggio consente di definire:

  • I dati di telemetria inviati dal dispositivo. La definizione include il nome e il tipo di dati di telemetria. Ad esempio, un dispositivo invia dati di telemetria sulla temperatura come valore double.
  • Le proprietà che il dispositivo segnala a IoT Central. Una definizione di proprietà ne include il nome e il tipo di dati. Ad esempio, un dispositivo segnala lo stato di una valvola come valore booleano.
  • Le proprietà che il dispositivo può ricevere da IoT Central. Facoltativamente, è possibile contrassegnare una proprietà come scrivibile. Ad esempio, IoT Central invia una temperatura obiettivo come valore double a un dispositivo.
  • I comandi a cui il dispositivo risponde. La definizione include il nome del comando, oltre ai nomi e ai tipi di dati di eventuali parametri. Ad esempio, un dispositivo risponde a un comando di riavvio che specifica quanti secondi aspettare prima del riavvio.

Nota

IoT Central definisce alcune estensioni per il linguaggio DTDL v2. Per altre informazioni, vedere Estensione IoT Central.

Un modello DTDL può essere senza componenti o a più componenti:

  • Modello senza componenti: un modello semplice non usa componenti incorporati o a catena. Tutti i dati di telemetria, le proprietà e i comandi sono definiti un singolo componente radice. Per un esempio, vedere il modello di Termostato.
  • Modello a più componenti: un modello più complesso che include due o più componenti. Questi componenti includono un singolo componente radice e uno o più componenti annidati. Per un esempio, vedere il modello di Temperature Controller.

Suggerimento

È possibile importare ed esportare un modello di dispositivo completo o una singola interfaccia da un modello di dispositivo IoT Central come file DTDL v2.

Per altre informazioni sui modelli di dispositivo, vedere la guida alla modellazione Plug and Play IoT

Convenzioni

Un dispositivo deve seguire le convenzioni di Plug and Play IoT quando scambia dati con IoT Central. Le convenzioni includono:

  • Inviare l'identificatore DTMI quando il dispositivo si connette a IoT Central.
  • Inviare payload e metadati JSON correttamente formattati a IoT Central.
  • Rispondere correttamente alle proprietà e ai comandi scrivibili inviati da IoT Central.
  • Seguire le convenzioni di denominazione per i comandi dei componenti.

Nota

Attualmente, IoT Central non supporta completamente i dati DTDL di tipo matrice e geospaziali.

Per altre informazioni sulle convenzioni di Plug and Play IoT, vedere Convenzioni di Plug and Play IoT.

Per altre informazioni sul formato dei messaggi JSON che un dispositivo scambia con IoT Central, vedere Payload di telemetria, proprietà e comandi.

SDK del dispositivo

Usare uno degli Azure IoT SDK per dispositivi per implementare il comportamento del dispositivo. Il codice deve:

  • Registrare il dispositivo con DPM e usare le informazioni di DPM per connettersi all'hub IoT interno nell'applicazione IoT Central.
  • Annunciare l'identificatore DTMI del modello implementato dal dispositivo.
  • Inviare dati di telemetria nel formato specificato dal modello di dispositivo. IoT Central usa il modello nel modello di dispositivo per determinare come usare i dati di telemetria per le visualizzazioni e l'analisi.
  • Sincronizzare i valori delle proprietà tra il dispositivo e IoT Central. Il modello specifica i nomi delle proprietà e i tipi di dati in modo che IoT Central possa visualizzare le informazioni.
  • Implementare i gestori per i comandi specificati nel modello. Il modello specifica i nomi e i parametri dei comandi che il dispositivo deve usare.

Per altre informazioni sul ruolo dei modelli di dispositivo, vedere Che cosa sono i modelli di dispositivo?.

La tabella seguente riepiloga le corrispondenze tra le funzionalità di dispositivo di Azure IoT Central e le funzionalità dell'hub IoT:

Azure IoT Central Hub IoT di Azure
Telemetria Messaggistica da dispositivo a cloud
Comandi offline Messaggistica da cloud a dispositivo
Proprietà Proprietà segnalate del dispositivo gemello
Proprietà (scrivibile) Proprietà desiderate e segnalate del dispositivo gemello
Comando Metodi diretti

Protocolli di comunicazione

I protocolli di comunicazione che un dispositivo può usare per connettersi a IoT Central includono MQTT, AMQP e HTTPS. Internamente, IoT Central usa un hub IoT per abilitare la connettività dei dispositivi. Per altre informazioni sui protocolli di comunicazione supportati dall'hub IoT per la connettività dei dispositivi, vedere Scegliere un protocollo di comunicazione.

Se il dispositivo non può usare alcun protocollo supportato, usare Azure IoT Edge per eseguire la conversione del protocollo. IoT Edge supporta altri scenari intelligence-on-the-edge per eseguire l'offload dell'elaborazione dall'applicazione Azure IoT Central.

Timestamp di telemetria

Per impostazione predefinita, IoT Central usa il tempo accodato del messaggio quando visualizza i dati di telemetria nei dashboard e nei grafici. L'ora di accodamento dei messaggi viene impostata internamente quando IoT Central riceve il messaggio dal dispositivo.

Un dispositivo può impostare la iothub-creation-time-utc proprietà quando crea un messaggio da inviare a IoT Central. Se questa proprietà è presente, IoT Central lo usa quando visualizza i dati di telemetria nei dashboard e nei grafici.

È possibile esportare sia il tempo accodato che la iothub-creation-time-utc proprietà quando si esportano i dati di telemetria dall'applicazione IoT Central.

Per altre informazioni sulle proprietà dei messaggi, vedere Proprietà di sistema dei messaggi da dispositivo a cloud hub IoT.

Procedure consigliate

Queste raccomandazioni illustrano come implementare i dispositivi per sfruttare la disponibilità elevata predefinita, il ripristino di emergenza e il ridimensionamento automatico in IoT Central.

Gestire gli errori di connessione

Ai fini del ridimensionamento o del ripristino di emergenza, IoT Central può aggiornare gli hub IoT sottostanti. Per mantenere la connettività, il codice del dispositivo deve gestire errori di connessione specifici stabilendo una connessione a un nuovo endpoint hub IoT.

Se il dispositivo riceve uno degli errori seguenti quando si connette, deve eseguire nuovamente il provisioning del dispositivo con DPS per ottenere una nuova stringa di connessione. Questi errori indicano che il stringa di connessione non è più valido:

  • Endpoint hub IoT non raggiungibile.
  • Token di sicurezza scaduto.
  • Dispositivo disabilitato in hub IoT.

Se il dispositivo riceve uno degli errori seguenti quando si connette, deve usare una strategia di back-off per ritentare la connessione. Questi errori indicano che il stringa di connessione è ancora valido, ma le condizioni temporanee arrestano la connessione del dispositivo:

  • Dispositivo bloccato dall'operatore.
  • Errore interno 500 dal servizio.

Per altre informazioni sui codici di errore del dispositivo, vedere Risoluzione dei problemi relativi alle connessioni dei dispositivi.

Per altre informazioni sull'implementazione delle riconnessioni automatiche, vedere Gestire le riconnessioni dei dispositivi per creare applicazioni resilienti.

Funzionalità di failover di test

L'interfaccia della riga di comando di Azure consente di testare le funzionalità di failover del codice del dispositivo. Il comando dell'interfaccia della riga di comando funziona spostando temporaneamente una registrazione del dispositivo a un hub IoT interno diverso. Per verificare il funzionamento del failover del dispositivo, verificare che il dispositivo invii ancora i dati di telemetria e risponda ai comandi.

Per eseguire il test di failover per il dispositivo, eseguire il comando seguente:

az iot central device manual-failover \
    --app-id {Application ID of your IoT Central application} \
    --device-id {Device ID of the device you're testing} \
    --ttl-minutes {How to wait before moving the device back to it's original IoT hub}

Suggerimento

Per trovare l'ID applicazione, passare a Gestione applicazioni > nell'applicazione IoT Central.

Se il comando ha esito positivo, viene visualizzato un output simile all'esempio seguente:

Command group 'iot central device' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
{
  "hubIdentifier": "6bd4...bafa",
  "message": "Success! This device is now being failed over. You can check your device'’'s status using 'iot central device registration-info' command. The device will revert to its original hub at Tue, 18 May 2021 11:03:45 GMT. You can choose to failback earlier using device-manual-failback command. Learn more: https://aka.ms/iotc-device-test"
}

Per altre informazioni sul comando dell'interfaccia della riga di comando, vedere az iot central device manual-failover.

È ora possibile verificare che i dati di telemetria dal dispositivo raggiungano ancora l'applicazione IoT Central.

Suggerimento

Per visualizzare il codice del dispositivo di esempio che gestisce i failover in vari linguaggi di programmazione, vedere Client a disponibilità elevata di IoT Central.

Passaggi successivi

Alcuni passaggi successivi suggeriti sono: