Convenzioni di Plug and Play IoT

  • Articolo

Plug and Play IoT dispositivi devono seguire un set di convenzioni quando scambiano messaggi con un hub IoT. Plug and Play IoT dispositivi usano il protocollo MQTT per comunicare con hub IoT. hub IoT supporta anche il protocollo AMQP disponibile in alcuni SDK per dispositivi IoT.

Un dispositivo può includere moduli o essere implementati in un modulo IoT Edge ospitato dal runtime di IoT Edge.

Vengono descritti i dati di telemetria, le proprietà e i comandi implementati da un dispositivo Plug and Play IoT con un modello DTDL (Digital Twins Definition Language). In questo articolo sono disponibili due tipi di modello:

  • Nessun componente : modello senza componenti. Il modello dichiara i dati di telemetria, le proprietà e i comandi come elementi di primo livello nella sezione contenuto dell'interfaccia principale. Nello strumento Azure IoT Explorer questo modello viene visualizzato come singolo componente predefinito.
  • Più componenti : un modello composto da due o più interfacce. Interfaccia principale, visualizzata come componente predefinito, con dati di telemetria, proprietà e comandi. Una o più interfacce dichiarate come componenti con più dati di telemetria, proprietà e comandi.

Per altre informazioni, vedere Plug and Play IoT guida alla modellazione.

Identificare il modello

Per annunciare il modello implementato, un dispositivo o un modulo Plug and Play IoT include l'ID modello nel pacchetto di connessione MQTT aggiungendo model-id al USERNAME campo .

Per identificare il modello implementato da un dispositivo o un modulo, un servizio può ottenere l'ID modello da:

  • Campo dispositivo gemello modelId .
  • Campo gemello $metadata.$model digitale.
  • Notifica di modifica del gemello digitale.

Telemetria

  • I dati di telemetria inviati da un dispositivo senza componenti non richiedono metadati aggiuntivi. Il sistema aggiunge la dt-dataschema proprietà .
  • I dati di telemetria inviati da un dispositivo che usano componenti devono aggiungere il nome del componente al messaggio di telemetria.
  • Quando si usa MQTT, aggiungere la $.sub proprietà con il nome del componente all'argomento di telemetria, il sistema aggiunge la dt-subject proprietà .
  • Quando si usa AMQP, aggiungere la dt-subject proprietà con il nome del componente come annotazione del messaggio.

Nota

La telemetria dai componenti richiede un messaggio per ogni componente.

Per altri esempi di telemetria, vedere Payloads Telemetry (Telemetria dei payload)>

Proprietà di sola lettura

Un dispositivo imposta una proprietà di sola lettura che quindi segnala all'applicazione back-end.

Esempio nessuna proprietà di sola lettura componente

Un dispositivo o un modulo può inviare qualsiasi codice JSON valido che segue le regole DTDL.

DTDL che definisce una proprietà in un'interfaccia:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

Payload della proprietà segnalata di esempio:

"reported" :
{
  "temperature" : 21.3
}

Proprietà di sola lettura di più componenti di esempio

Il dispositivo o il modulo deve aggiungere l'indicatore {"__t": "c"} per indicare che l'elemento fa riferimento a un componente.

DTDL che fa riferimento a un componente:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

DTDL che definisce il componente:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

Payload della proprietà segnalata di esempio:

"reported": {
  "thermostat1": {
    "__t": "c",
    "temperature": 21.3
  }
}

Per altri esempi di proprietà di sola lettura, vedere Proprietà dei payload>.

Proprietà accessibili in scrittura

Un'applicazione back-end imposta una proprietà scrivibile che hub IoT quindi invia al dispositivo.

Il dispositivo o il modulo deve confermare che ha ricevuto la proprietà inviando una proprietà segnalata. La proprietà segnalata deve includere:

  • value - valore effettivo della proprietà (in genere il valore ricevuto, ma il dispositivo può decidere di segnalare un valore diverso).
  • ac : codice di riconoscimento che usa un codice di stato HTTP.
  • av : una versione di riconoscimento che fa riferimento all'oggetto $version della proprietà desiderata. È possibile trovare questo valore nel payload JSON della proprietà desiderata.
  • ad : una descrizione facoltativa del riconoscimento.

Risposte di riconoscimento

Quando si segnalano proprietà scrivibili, il dispositivo deve comporre il messaggio di riconoscimento, usando i quattro campi nell'elenco precedente, per indicare lo stato effettivo del dispositivo, come descritto nella tabella seguente:

Status(ac) Version(av) Value(value) Description(av)
200 Versione desiderata Valore desiderato Valore della proprietà desiderato accettato
202 Versione desiderata Valore accettato dal dispositivo Valore della proprietà desiderato accettato, aggiornamento in corso (dovrebbe terminare con 200)
203 0 Valore impostato dal dispositivo Set di proprietà dal dispositivo, non riflettendo le eventuali esigenze
400 Versione desiderata Valore effettivo usato dal dispositivo Valore della proprietà desiderato non accettato
500 Versione desiderata Valore effettivo usato dal dispositivo Eccezione durante l'applicazione della proprietà

Quando un dispositivo viene avviato, deve richiedere il dispositivo gemello e verificare la presenza di eventuali aggiornamenti delle proprietà scrivibili. Se la versione di una proprietà scrivibile è aumentata mentre il dispositivo era offline, il dispositivo deve inviare una risposta di proprietà segnalata per confermare che ha ricevuto l'aggiornamento.

Quando un dispositivo viene avviato per la prima volta, può inviare un valore iniziale per una proprietà segnalata se non riceve una proprietà desiderata iniziale dall'hub IoT. In questo caso, il dispositivo può inviare il valore predefinito con av e a ac0203. Ad esempio:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 203,
    "av": 0,
    "ad": "initialize"
  }
}

Un dispositivo può usare la proprietà segnalata per fornire altre informazioni all'hub. Ad esempio, il dispositivo potrebbe rispondere con una serie di messaggi in corso, ad esempio:

"reported": {
  "targetTemperature": {
    "value": 35.0,
    "ac": 202,
    "av": 3,
    "ad": "In-progress - reporting current temperature"
  }
}

Quando il dispositivo raggiunge la temperatura di destinazione, invia il messaggio seguente:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 200,
    "av": 4,
    "ad": "Reached target temperature"
  }
}

Un dispositivo potrebbe segnalare un errore, ad esempio:

"reported": {
  "targetTemperature": {
    "value": 120.0,
    "ac": 500,
    "av": 3,
    "ad": "Target temperature out of range. Valid range is 10 to 99."
  }
}

Object type

Se una proprietà scrivibile è definita come oggetto , il servizio deve inviare un oggetto completo al dispositivo. Il dispositivo deve confermare l'aggiornamento inviando informazioni sufficienti al servizio per comprendere come il dispositivo ha agito sull'aggiornamento. Questa risposta può includere:

  • Intero oggetto.
  • Solo i campi aggiornati dal dispositivo.
  • Subset dei campi.

Per oggetti di grandi dimensioni, valutare la possibilità di ridurre al minimo le dimensioni dell'oggetto incluso nel riconoscimento.

L'esempio seguente mostra una proprietà scrivibile definita come con Object quattro campi:

DTDL:

{
  "@type": "Property",
  "name": "samplingRange",
  "schema": {
    "@type": "Object",
    "fields": [
      {
        "name": "startTime",
        "schema": "dateTime"
      },
      {
        "name": "lastTime",
        "schema": "dateTime"
      },
      {
        "name": "count",
        "schema": "integer"
      },
      {
        "name": "errorCount",
        "schema": "integer"
      }
    ]
  },
  "displayName": "Sampling range"
  "writable": true
}

Per aggiornare questa proprietà scrivibile, inviare un oggetto completo dal servizio simile all'esempio seguente:

{
  "samplingRange": {
    "startTime": "2021-08-17T12:53:00.000Z",
    "lastTime": "2021-08-17T14:54:00.000Z",
    "count": 100,
    "errorCount": 5
  }
}

Il dispositivo risponde con un riconoscimento simile all'esempio seguente:

{
  "samplingRange": {
    "ac": 200,
    "av": 5,
    "ad": "Weighing status updated",
    "value": {
      "startTime": "2021-08-17T12:53:00.000Z",
      "lastTime": "2021-08-17T14:54:00.000Z",
      "count": 100,
      "errorCount": 5
    }
  }
}

Esempio di nessuna proprietà scrivibile del componente

Quando un dispositivo riceve più proprietà desiderate in un singolo payload, può inviare le risposte delle proprietà segnalate tra più payload o combinare le risposte in un singolo payload.

Un dispositivo o un modulo può inviare qualsiasi codice JSON valido che segue le regole DTDL.

DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    },
    {
      "@type": "Property",
      "name": "targetHumidity",
      "schema": "double",
      "writable": true
    }
  ]
}

Payload della proprietà desiderata di esempio:

"desired" :
{
  "targetTemperature" : 21.3,
  "targetHumidity" : 80,
  "$version" : 3
}

Esempio di primo payload della proprietà segnalata:

"reported": {
  "targetTemperature": {
    "value": 21.3,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

Esempio di secondo payload della proprietà segnalata:

"reported": {
  "targetHumidity": {
    "value": 80,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

Nota

È possibile scegliere di combinare questi due payload delle proprietà segnalate in un singolo payload.

Proprietà scrivibile di più componenti di esempio

Il dispositivo o il modulo deve aggiungere l'indicatore {"__t": "c"} per indicare che l'elemento fa riferimento a un componente.

L'indicatore viene inviato solo per gli aggiornamenti alle proprietà definite in un componente. Aggiornamenti alle proprietà definite nel componente predefinito non includono il marcatore, vedere Esempio di nessuna proprietà scrivibile del componente.

Quando un dispositivo riceve più proprietà segnalate in un singolo payload, può inviare le risposte delle proprietà segnalate tra più payload o combinare le risposte in un singolo payload.

Il dispositivo o il modulo deve confermare che ha ricevuto le proprietà inviando le proprietà segnalate:

DTDL che fa riferimento a un componente:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

DTDL che definisce il componente:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    }
  ]
}

Payload della proprietà desiderata di esempio:

"desired": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": 21.3,
    "targetHumidity": 80,
    "$version" : 3
  }
}

Esempio di primo payload della proprietà segnalata:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": {
      "value": 23,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

Esempio di secondo payload della proprietà segnalata:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetHumidity": {
      "value": 80,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

Nota

È possibile scegliere di combinare questi due payload delle proprietà segnalate in un singolo payload.

Per altri esempi di proprietà scrivibili, vedere Proprietà dei payload>.

Comandi

Nessuna interfaccia componente usa il nome del comando senza un prefisso.

In un dispositivo o in un modulo più interfacce componente usano nomi di comando con il formato seguente: componentName*commandName.

Per altri esempi di comandi, vedere Payloads Commands .For more command examples, see Payloads Commands>.

Suggerimento

IoT Central ha le proprie convenzioni per l'implementazione di comandi con esecuzione prolungata e comandi offline.

Passaggi successivi

Dopo aver appreso le convenzioni Plug and Play IoT, ecco alcune altre risorse: