Che cosa sono i modelli di dispositivo?

Un modello di dispositivo in Azure IoT Central è un progetto che definisce le caratteristiche e i comportamenti di un tipo di dispositivo che si connette a un'applicazione. Il modello di dispositivo definisce ad esempio i dati di telemetria inviati da un dispositivo in modo che IoT Central possa creare visualizzazioni che usano le unità e i tipi di dati corretti. I dati di telemetria che corrispondono alla definizione del modello di dispositivo vengono definiti dati modellati. I dati di telemetria che non corrispondono alla definizione del modello di dispositivo vengono definiti dati non modellati.

Un generatore di soluzioni aggiunge modelli di dispositivo a un'applicazione IoT Central. Uno sviluppatore di dispositivi scrive il codice del dispositivo che implementa i comportamenti definiti nel modello di dispositivo. Per altre informazioni su come creare un modello di dispositivo o generarne uno automaticamente, vedere Creare un modello di dispositivo nell'applicazione Azure IoT Central. Per altre informazioni sui dati che il dispositivo scambia con IoT Central, vedere Payload di telemetria, proprietà e comandi.

Il modello di dispositivo include le sezioni seguenti:

• Un modello di dispositivo. Questa parte del modello di dispositivo definisce il modo in cui il dispositivo interagisce con l'applicazione. Ogni modello di dispositivo ha un ID univoco. Uno sviluppatore di dispositivi implementa i comportamenti definiti nel modello.
  • Componente radice. Ogni modello di dispositivo ha un componente radice. L'interfaccia del componente radice descrive le funzionalità specifiche del modello di dispositivo.
  • Componenti. Un modello di dispositivo può includere componenti oltre al componente radice per descrivere le funzionalità del dispositivo. Ogni componente ha un'interfaccia che descrive le funzionalità del componente. Le interfacce dei componenti possono essere riutilizzate in altri modelli di dispositivo. Diversi modelli di dispositivo telefonico potrebbero ad esempio usare la stessa interfaccia della fotocamera.
  • Interfacce ereditate. Un modello di dispositivo contiene una o più interfacce che estendono le funzionalità del componente radice.
• Visualizzazioni. Questa parte del modello di dispositivo consente allo sviluppatore di soluzioni di definire visualizzazioni per visualizzare i dati dal dispositivo e i moduli per gestire e controllare un dispositivo. Le visualizzazioni non influiscono sul codice che uno sviluppatore di dispositivi scrive per implementare il modello di dispositivo.

Assegnare un dispositivo a un modello di dispositivo

Affinché un dispositivo interagisca con IoT Central, deve essere assegnato a un modello di dispositivo. Questa assegnazione viene eseguita in uno dei quattro modi seguenti:

• Quando si registra un dispositivo nella pagina Dispositivi, è possibile identificare il modello che il dispositivo deve usare.
• Quando si importa in blocco un elenco di dispositivi, è possibile scegliere il modello di dispositivo che tutti i dispositivi nell'elenco devono usare.
• È possibile assegnare manualmente un dispositivo non assegnato a un modello di dispositivo dopo la connessione.
• È possibile assegnare automaticamente un dispositivo a un modello di dispositivo inviando un ID modello quando il dispositivo si connette per la prima volta all'applicazione.

Assegnazione automatica

IoT Central può assegnare automaticamente un dispositivo a un modello di dispositivo quando il dispositivo si connette. Un dispositivo deve inviare un ID modello quando si connette. IoT Central usa l'ID modello per identificare il modello di dispositivo per tale modello di dispositivo specifico. Il processo di individuazione funziona nel modo seguente:

1. Se il modello di dispositivo è già pubblicato nell'applicazione IoT Central, il dispositivo viene assegnato al modello di dispositivo.

2. Se il modello di dispositivo non è già pubblicato nell'applicazione IoT Central, IoT Central cerca il modello di dispositivo nel repository del modello di dispositivo pubblico. Se IoT Central trova il modello, lo usa per generare un modello di dispositivo di base.

3. Se IoT Central non trova il modello nel repository di modelli pubblici, il dispositivo viene contrassegnato come Non assegnato. Un operatore può:

   • Creare un modello di dispositivo per il dispositivo e quindi eseguire la migrazione del dispositivo non assegnato al nuovo modello di dispositivo.
   • Generare automaticamente un modello di dispositivo in base ai dati inviati dal dispositivo.

Lo screenshot seguente mostra come visualizzare l'ID modello di un modello di dispositivo in IoT Central. In un modello di dispositivo, selezionare un componente e quindi selezionare Modifica identità:

È possibile visualizzare il modello termostato nel repository del modello pubblico. La definizione dell'ID modello è simile alla seguente:

"@id": "dtmi:com:example:Thermostat;1"

Usare il payload DPS seguente per assegnare il dispositivo a un modello di dispositivo:

{
  "modelId":"dtmi:com:example:TemperatureController;2"
}

Per altre informazioni sul payload DPS, vedere il codice di esempio usato in Esercitazione: Creare e connettere un'applicazione client all'applicazione Azure IoT Central.

Modelli di dispositivo

Un modello di dispositivo definisce il modo in cui un dispositivo interagisce con l'applicazione IoT Central. Lo sviluppatore di dispositivi deve assicurarsi che il dispositivo implementi i comportamenti definiti nel modello di dispositivo in modo che IoT Central possa monitorare e gestire il dispositivo. Un modello di dispositivo è costituito da una o più interfacce e ogni interfaccia può definire una raccolta di tipi di telemetria, proprietà del dispositivo e comandi. Uno sviluppatore di soluzioni può:

• Importare un file JSON che definisce un modello di dispositivo completo o una singola interfaccia in un modello di dispositivo.
• Usare l'interfaccia utente Web in IoT Central per creare o modificare un modello di dispositivo.

Per altre informazioni sulla modifica di un modello di dispositivo, vedere Modificare un modello di dispositivo esistente

Uno sviluppatore di soluzioni può anche esportare un file JSON dal modello di dispositivo che contiene un modello di dispositivo completo o una singola interfaccia. Uno sviluppatore di dispositivi può usare questo documento JSON per comprendere il modo in cui il dispositivo deve comunicare con l'applicazione IoT Central.

Il file JSON che definisce il modello di dispositivo usa DTDL (Digital Twin Definition Language) v2. IoT Central prevede che il file JSON contenga il modello di dispositivo con le interfacce definite inline anziché in file separati. I modelli creati in IoT Central hanno il contesto dtmi:iotcentral:context;2 definito per indicare che il modello è stato creato in IoT Central:

"@context": [
  "dtmi:iotcentral:context;2",
  "dtmi:dtdl:context;2"
]

Per altre informazioni sui modelli DTDL, vedere la guida alla modellazione Plug and Play IoT.

Proprietà

Per impostazione predefinita, le proprietà sono di sola lettura. Le proprietà di sola lettura indicano che il dispositivo segnala gli aggiornamenti del valore della proprietà all'applicazione IoT Central. L'applicazione IoT Central non può impostare il valore di una proprietà di sola lettura.

È anche possibile contrassegnare una proprietà come scrivibile in un'interfaccia. Un dispositivo può ricevere un aggiornamento di una proprietà scrivibile dall'applicazione IoT Central e segnalare gli aggiornamenti dei valori delle proprietà all'applicazione.

I dispositivi non devono essere connessi per impostare i valori delle proprietà. I valori aggiornati vengono trasferiti quando il dispositivo si connette all'applicazione. Questo comportamento si applica sia alle proprietà di sola lettura che alle proprietà scrivibili.

Non usare le proprietà per inviare dati di telemetria dal dispositivo. Ad esempio, una proprietà readonly, come temperatureSetting=80, deve indicare che la temperatura del dispositivo è impostata su 80 e il dispositivo sta tentando di raggiungere o rimanere in corrispondenza di questa temperatura di destinazione.

Per le proprietà scrivibili, l'applicazione del dispositivo restituisce un codice di stato, una versione e una descrizione desiderati per indicare se ha ricevuto e applicato il valore della proprietà.

Proprietà cloud

È anche possibile aggiungere proprietà cloud al componente radice del modello. Le proprietà cloud consentono di specificare i metadati del dispositivo da archiviare nell'applicazione IoT Central. I valori delle proprietà cloud vengono archiviati nell'applicazione IoT Central e non vengono mai sincronizzati con un dispositivo. Le proprietà cloud non influiscono sul codice che uno sviluppatore di dispositivi scrive per implementare il modello di dispositivo.

Uno sviluppatore di soluzioni può aggiungere proprietà cloud alle visualizzazioni dei dispositivi e ai moduli insieme alle proprietà del dispositivo per consentire a un operatore di gestire i dispositivi connessi all'applicazione. Uno sviluppatore di soluzioni può anche usare le proprietà cloud come parte di una definizione di regola per rendere modificabile un valore soglia da parte di un operatore.

Il frammento DTDL seguente mostra una definizione di proprietà cloud di esempio:

{
    "@id": "dtmi:azureiot:Thermostat:CustomerName",
    "@type": [
        "Property",
        "Cloud",
        "StringValue"
    ],
    "displayName": {
        "en": "Customer Name"
    },
    "name": "CustomerName",
    "schema": "string"
}

Telemetria

IoT Central consente di visualizzare i dati di telemetria nelle visualizzazioni e nei grafici dei dispositivi e di usare le regole per attivare azioni quando vengono raggiunte le soglie. IoT Central usa le informazioni nel modello di dispositivo, ad esempio tipi di dati, unità e nomi visualizzati, per determinare come visualizzare i valori di telemetria. È anche possibile visualizzare i valori di telemetria nelle dashboard dell'applicazione e personali.

È possibile usare la funzionalità di esportazione dei dati di IoT Central per trasmettere i dati di telemetria ad altre destinazioni, ad esempio archiviazione o Hub eventi.

Comandi

Per impostazione predefinita, un comando deve essere eseguito entro 30 secondi e il dispositivo deve essere connesso all'arrivo del comando. Se il dispositivo risponde in tempo o il dispositivo non è connesso, il comando non riesce.

I comandi possono avere parametri di richiesta e restituire una risposta.

Comandi offline

È possibile scegliere i comandi della coda se un dispositivo è attualmente offline abilitando l'opzione Metti in coda se offline per un comando nel modello di dispositivo.

I comandi offline sono notifiche unidirezionale per il dispositivo dalla soluzione. I comandi offline possono avere parametri di richiesta, ma non restituire una risposta.

I comandi offline usano messaggi da cloud a dispositivo dell'hub IoT per inviare il comando e il payload al dispositivo.

Il payload del messaggio ricevuto dal dispositivo è il valore non elaborato del parametro. Una proprietà personalizzata denominata method-name archivia il nome del comando IoT Central. La tabella seguente illustra alcuni payload di esempio:

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un comando. Il comando ha un parametro oggetto con un campo datetime e un'enumerazione:

{
  "@type": "Command",
  "displayName": {
    "en": "Generate Diagnostics"
  },
  "name": "GenerateDiagnostics",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "Payload"
    },
    "name": "Payload",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "StartTime"
          },
          "name": "StartTime",
          "schema": "dateTime"
        },
        {
          "displayName": {
            "en": "Bank"
          },
          "name": "Bank",
          "schema": {
            "@type": "Enum",
            "displayName": {
              "en": "Enum"
            },
            "enumValues": [
              {
                "displayName": {
                  "en": "Bank 1"
                },
                "enumValue": 1,
                "name": "Bank1"
              },
              {
                "displayName": {
                  "en": "Bank2"
                },
                "enumValue": 2,
                "name": "Bank2"
              },
              {
                "displayName": {
                  "en": "Bank3"
                },
                "enumValue": 3,
                "name": "Bank3"
              }
            ],
            "valueSchema": "integer"
          }
        }
      ]
    }
  }
}

Se si abilita l'opzione Metti in coda se offline nell'interfaccia utente del modello di dispositivo per il comando nel frammento precedente, il messaggio ricevuto dal dispositivo include le proprietà seguenti:

Visualizzazioni

Uno sviluppatore di soluzioni crea visualizzazioni che consentono agli operatori di monitorare e gestire i dispositivi connessi. Le visualizzazioni fanno parte del modello di dispositivo, quindi una visualizzazione è associata a un tipo di dispositivo specifico. Una visualizzazione può includere:

• Grafici per tracciare i dati di telemetria.
• Riquadri per visualizzare le proprietà del dispositivo di sola lettura.
• Riquadri per consentire all'operatore di modificare le proprietà del dispositivo scrivibili.
• Riquadri per consentire all'operatore di modificare le proprietà cloud.
• Riquadri per consentire all'operatore di chiamare i comandi, inclusi i comandi che prevedono un payload.
• Riquadri per visualizzare etichette, immagini o testo markdown.

Passaggio successivo

Dopo aver appreso i modelli di dispositivo, un passaggio successivo consigliato consiste nel leggere i payload di telemetria, proprietà e comandi per altre informazioni sui dati che un dispositivo scambia con IoT Central.