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 all'applicazione. Ad esempio, il modello di dispositivo definisce i dati di telemetria inviati da un dispositivo IoT Central creare visualizzazioni che usano le unità e i tipi di dati corretti.

Un generatore di soluzioni aggiunge modelli di dispositivo a un IoT Central appalto. Uno sviluppatore di dispositivi scrive il codice del dispositivo che implementa i comportamenti definiti nel modello di dispositivo.

Un 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. Uno sviluppatore di dispositivi implementa i comportamenti definiti nel modello.
    • Componente predefinito. Ogni modello di dispositivo ha un componente predefinito. L'interfaccia del componente predefinito descrive le funzionalità specifiche del modello di dispositivo.
    • Componenti . Un modello di dispositivo può includere componenti oltre al componente predefinito 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. Ad esempio, diversi modelli di dispositivo telefono potrebbero usare la stessa interfaccia della fotocamera.
    • Interfacce ereditate. Un modello di dispositivo contiene una o più interfacce che estendono le funzionalità del componente predefinito.
  • Proprietà cloud. Questa parte del modello di dispositivo consente allo sviluppatore di soluzioni di specificare i metadati del dispositivo da archiviare. Le proprietà cloud non vengono mai sincronizzate con i dispositivi ed esistono solo nell'applicazione. Le proprietà cloud non influiscono sul codice scritto da uno sviluppatore di dispositivi per implementare il modello di dispositivo.
  • Personalizzazioni. Questa parte del modello di dispositivo consente allo sviluppatore di soluzioni di eseguire l'override di alcune delle definizioni nel modello di dispositivo. Le personalizzazioni sono utili se lo sviluppatore della soluzione vuole perfezionare il modo in cui l'applicazione gestisce un valore, ad esempio modificando il nome visualizzato per una proprietà o il colore usato per visualizzare un valore di telemetria. Le personalizzazioni non influiscono sul codice scritto da uno sviluppatore di dispositivi per implementare il modello di dispositivo.
  • Visualizza. Questa parte del modello di dispositivo consente allo sviluppatore di soluzioni di definire visualizzazioni per visualizzare i dati dal dispositivo e moduli per gestire e controllare un dispositivo. Le visualizzazioni usano il modello di dispositivo, le proprietà cloud e le personalizzazioni. Le visualizzazioni non influiscono sul codice scritto da uno sviluppatore di dispositivi per implementare il modello di dispositivo.

Modelli di dispositivo

Un modello di dispositivo definisce il modo in cui un dispositivo interagisce con l IoT Central appliale. Lo sviluppatore del dispositivo deve assicurarsi che il dispositivo implementi i comportamenti definiti nel modello di dispositivo in modo che IoT Central 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 il modello di dispositivo in un modello di dispositivo oppure 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 che contiene il modello di dispositivo. Uno sviluppatore di dispositivi può usare questo documento JSON per comprendere in che modo il dispositivo deve comunicare con l IoT Central appalto.

Il file JSON che definisce il modello di dispositivo usa il linguaggio 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. Per altre informazioni, vedere IoT Plug and Play di modellazione.

Un tipico dispositivo IoT è costituito da:

  • Parti personalizzate, ovvero gli elementi che rendono univoco il dispositivo.
  • Parti standard, ovvero elementi comuni a tutti i dispositivi.

Queste parti sono denominate interfacce in un modello di dispositivo. Le interfacce definiscono i dettagli di ogni parte implementata dal dispositivo. Le interfacce sono riutilizzabili tra i modelli di dispositivo. In DTDL un componente fa riferimento a un'altra interfaccia, che può essere definita in un file DTDL separato o in una sezione separata del file.

Nell'esempio seguente viene illustrata la struttura del modello di dispositivo per un dispositivo controller di temperatura. Il componente predefinito include le workingSet definizioni per serialNumber , e reboot . Il modello di dispositivo include anche due thermostat componenti e un componente deviceInformation . Il contenuto dei tre componenti è stato rimosso per motivi di brevità:

[
  {
    "@context": [
      "dtmi:iotcentral:context;2",
      "dtmi:dtdl:context;2"
    ],
    "@id": "dtmi:com:example:TemperatureController;2",
    "@type": "Interface",
    "contents": [
      {
        "@type": [
          "Telemetry",
          "DataSize"
        ],
        "description": {
          "en": "Current working set of the device memory in KiB."
        },
        "displayName": {
          "en": "Working Set"
        },
        "name": "workingSet",
        "schema": "double",
        "unit": "kibibit"
      },
      {
        "@type": "Property",
        "displayName": {
          "en": "Serial Number"
        },
        "name": "serialNumber",
        "schema": "string",
        "writable": false
      },
      {
        "@type": "Command",
        "commandType": "synchronous",
        "description": {
          "en": "Reboots the device after waiting the number of seconds specified."
        },
        "displayName": {
          "en": "Reboot"
        },
        "name": "reboot",
        "request": {
          "@type": "CommandPayload",
          "description": {
            "en": "Number of seconds to wait before rebooting the device."
          },
          "displayName": {
            "en": "Delay"
          },
          "name": "delay",
          "schema": "integer"
        }
      },
      {
        "@type": "Component",
        "displayName": {
          "en": "thermostat1"
        },
        "name": "thermostat1",
        "schema": "dtmi:com:example:Thermostat;2"
      },
      {
        "@type": "Component",
        "displayName": {
          "en": "thermostat2"
        },
        "name": "thermostat2",
        "schema": "dtmi:com:example:Thermostat;2"
      },
      {
        "@type": "Component",
        "displayName": {
          "en": "DeviceInfo"
        },
        "name": "deviceInformation",
        "schema": "dtmi:azure:DeviceManagement:DeviceInformation;1"
      }
    ],
    "displayName": {
      "en": "Temperature Controller"
    }
  },
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:Thermostat;2",
    "@type": "Interface",
    "displayName": "Thermostat",
    "description": "Reports current temperature and provides desired temperature control.",
    "contents": [
      ...
    ]
  },
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "@type": "Interface",
    "displayName": "Device Information",
    "contents": [
      ...
    ]
  }
]

Un'interfaccia ha alcuni campi obbligatori:

  • @id: ID univoco sotto forma di nome di risorsa uniforme semplice.
  • @type: dichiara che questo oggetto è un'interfaccia.
  • @context: specifica la versione DTDL usata per l'interfaccia.
  • contents: elenca le proprietà, i dati di telemetria e i comandi che costituiscono il dispositivo. Le funzionalità possono essere definite in più interfacce.

Esistono alcuni campi facoltativi che è possibile usare per aggiungere altri dettagli al modello di funzionalità, ad esempio il nome visualizzato e la descrizione.

Ogni voce nell'elenco di interfacce nella sezione implements include:

  • name: nome di programmazione dell'interfaccia.
  • schema: interfaccia implementata dal modello di funzionalità.

Interfacce

Il linguaggio DTDL consente di descrivere le funzionalità del dispositivo. Le funzionalità correlate sono raggruppate in interfacce. Le interfacce descrivono le proprietà, i dati di telemetria e i comandi implementati da una parte del dispositivo:

  • Properties. Le proprietà sono campi dati che rappresentano lo stato del dispositivo. Usare le proprietà per rappresentare lo stato durevole del dispositivo, ad esempio lo stato di on-off di una pompa refrigeratore. Le proprietà possono anche rappresentare le proprietà di base del dispositivo, ad esempio la versione del firmware del dispositivo. È possibile dichiarare le proprietà in sola lettura o in scrittura. Solo i dispositivi possono aggiornare il valore di una proprietà di sola lettura. Un operatore può impostare il valore di una proprietà scrivibile da inviare a un dispositivo.
  • Telemetry. I campi di telemetria rappresentano le misurazioni dei sensori. Ogni volta che il dispositivo prende una misurazione del sensore, deve inviare un evento di telemetria contenente i dati del sensore.
  • Commands. I comandi rappresentano i metodi che gli utenti del dispositivo possono eseguire nel dispositivo. Ad esempio, un comando reset o un comando per accendere o spegnere una ventola.

L'esempio seguente illustra la definizione dell'interfaccia termostato:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;2",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "displayName": "Temperature",
      "description": "Temperature in degrees Celsius.",
      "schema": "double",
      "unit": "degreeCelsius"
    },
    {
      "@type": [
        "Property",
        "Temperature"
      ],
      "name": "targetTemperature",
      "schema": "double",
      "displayName": "Target Temperature",
      "description": "Allows to remotely specify the desired target temperature.",
      "unit": "degreeCelsius",
      "writable": true
    },
    {
      "@type": [
        "Property",
        "Temperature"
      ],
      "name": "maxTempSinceLastReboot",
      "schema": "double",
      "unit": "degreeCelsius",
      "displayName": "Max temperature since last reboot.",
      "description": "Returns the max temperature since last device reboot."
    },
    {
      "@type": "Command",
      "name": "getMaxMinReport",
      "displayName": "Get Max-Min report.",
      "description": "This command returns the max, min and average temperature from the specified time to the current time.",
      "request": {
        "name": "since",
        "displayName": "Since",
        "description": "Period to return the max-min report.",
        "schema": "dateTime"
      },
      "response": {
        "name": "tempReport",
        "displayName": "Temperature Report",
        "schema": {
          "@type": "Object",
          "fields": [
            {
              "name": "maxTemp",
              "displayName": "Max temperature",
              "schema": "double"
            },
            {
              "name": "minTemp",
              "displayName": "Min temperature",
              "schema": "double"
            },
            {
              "name": "avgTemp",
              "displayName": "Average Temperature",
              "schema": "double"
            },
            {
              "name": "startTime",
              "displayName": "Start Time",
              "schema": "dateTime"
            },
            {
              "name": "endTime",
              "displayName": "End Time",
              "schema": "dateTime"
            }
          ]
        }
      }
    }
  ]
}

Questo esempio mostra due proprietà (una di sola lettura e una scrivibile), un tipo di telemetria e un comando. Una descrizione minima del campo include:

  • @type per specificare il tipo di funzionalità: Telemetry , Property o Command . In alcuni casi, il tipo include un tipo semantico per consentire IoT Central di fare alcuni presupposti su come gestire il valore.
  • name per il valore di telemetria.
  • schema per specificare il tipo di dati per i dati di telemetria o la proprietà . Questo valore può essere un tipo primitivo, ad esempio double, integer, booleano o stringa. Sono supportati anche i tipi di oggetto complessi e le mappe.

I campi facoltativi, ad esempio il nome visualizzato e la descrizione, consentono di aggiungere altri dettagli all'interfaccia e alle funzionalità.

Proprietà

Per impostazione predefinita, le proprietà sono di sola lettura. Le proprietà di sola lettura significano che il dispositivo segnala che il valore della proprietà viene aggiornato all'IoT Central app. L IoT Central appalto 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 nonché segnalare gli aggiornamenti dei valori delle proprietà all'applicazione.

Non è necessario che i dispositivi siano connessi per impostare i valori delle proprietà. I valori aggiornati vengono trasferiti alla successiva connessione del dispositivo all'applicazione. Questo comportamento si applica sia alle proprietà di sola lettura che a proprietà scrivibili.

Non usare le proprietà per inviare dati di telemetria dal dispositivo. Ad esempio, una proprietà di sola lettura, ad esempio, indica che la temperatura del dispositivo è stata impostata su 80 e che il dispositivo sta tentando di raggiungere o rimanere a temperatureSetting=80 questa temperatura.

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

Telemetria

IoT Central consente di visualizzare i dati di telemetria su dashboard e grafici e di usare regole per attivare azioni quando vengono raggiunte le soglie. IoT Central le informazioni nel modello di dispositivo, ad esempio tipi di dati, unità e nomi visualizzati, per determinare come visualizzare i valori di telemetria.

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

Comandi

Un comando deve essere eseguito entro 30 secondi per impostazione predefinita e il dispositivo deve essere connesso all'arrivo del comando. Se il dispositivo risponde in tempo o 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 Accoda se offline per un comando nel modello di dispositivo.

I comandi offline sono notifiche unidiresche al dispositivo dalla soluzione. I comandi offline possono avere parametri di richiesta ma non restituiscono una risposta.

Nota

Questa opzione è disponibile solo nell'interfaccia IoT Central'interfaccia utente Web. Questa impostazione non è inclusa se si esporta un modello o un'interfaccia dal modello di dispositivo.

Proprietà cloud

Le proprietà cloud fanno parte del modello di dispositivo, ma non fanno parte del modello di dispositivo. Le proprietà cloud consentono allo sviluppatore di soluzioni di specificare i metadati del dispositivo da archiviare nell IoT Central appalto. Le proprietà cloud non influiscono sul codice scritto da uno sviluppatore di dispositivi per implementare il modello di dispositivo.

Uno sviluppatore di soluzioni può aggiungere proprietà cloud a dashboard e visualizzazioni 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 un operatore.

Personalizzazioni

Le personalizzazioni fanno parte del modello di dispositivo, ma non fanno parte del modello di dispositivo. Le personalizzazioni consentono allo sviluppatore di soluzioni di migliorare o sostituire alcune delle definizioni nel modello di dispositivo. Ad esempio, uno sviluppatore di soluzioni può modificare il nome visualizzato per un tipo o una proprietà di telemetria. Uno sviluppatore di soluzioni può anche usare le personalizzazioni per aggiungere la convalida, ad esempio una lunghezza minima o massima per una proprietà del dispositivo stringa.

Le personalizzazioni possono influire sul codice scritto da uno sviluppatore di dispositivi per implementare il modello di dispositivo. Ad esempio, una personalizzazione può impostare la lunghezza minima e massima delle stringhe o i valori numerici minimo e massimo per i dati di telemetria.

Viste

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 vista è associata a un tipo di dispositivo specifico. Una vista 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à del cloud.
  • Riquadri per consentire all'operatore di chiamare comandi, inclusi i comandi che prevedono un payload.
  • Riquadri per visualizzare etichette, immagini o testo markdown.

I dati di telemetria, le proprietà e i comandi che è possibile aggiungere a una vista sono determinati dal modello di dispositivo, dalle proprietà cloud e dalle personalizzazioni nel modello di dispositivo.

Passaggi successivi

Dopo aver appreso i modelli di dispositivo, è consigliabile leggere i payload di telemetria, proprietà e comando per altre informazioni sui dati che un dispositivo scambia con IoT Central.