Konventioner för IoT Plug and Play

Artikel
02/06/2024

IoT Plug and Play-enheter bör följa en uppsättning konventioner när de utbyter meddelanden med en IoT-hubb. IoT Plug and Play-enheter använder MQTT-protokollet för att kommunicera med IoT Hub. IoT Hub har också stöd för AMQP-protokollet som är tillgängligt i vissa IoT-enhets-SDK:er.

En enhet kan innehålla moduler eller implementeras i en IoT Edge-modul som hanteras av IoT Edge-körningen.

Du beskriver telemetri, egenskaper och kommandon som en IoT Plug and Play-enhet implementerar med en DTDL-modell (Digital Twins Definition Language). Det finns två typer av modeller som nämns i den här artikeln:

Ingen komponent – en modell utan komponenter. Modellen deklarerar telemetri, egenskaper och kommandon som element på den översta nivån i innehållsavsnittet i huvudgränssnittet. I Azure IoT Explorer-verktyget visas den här modellen som en enda standardkomponent.
Flera komponenter – en modell som består av två eller flera gränssnitt. Ett huvudgränssnitt, som visas som standardkomponent, med telemetri, egenskaper och kommandon. Ett eller flera gränssnitt som deklareras som komponenter med mer telemetri, egenskaper och kommandon.

Mer information finns i modelleringsguiden för IoT Plug and Play.

Identifiera modellen

För att meddela vilken modell den implementerar innehåller en IoT Plug and Play-enhet eller -modul modell-ID:t i MQTT-anslutningspaketet genom att lägga model-id till i USERNAME fältet.

För att identifiera den modell som en enhet eller modul implementerar kan en tjänst hämta modell-ID:t från:

Fältet enhetstvilling modelId .
Fältet digital tvilling $metadata.$model .
Ett meddelande om ändring av digital tvilling.

Telemetri

Telemetri som skickas från en enhet utan komponent kräver inga extra metadata. Systemet lägger till egenskapen dt-dataschema .
Telemetri som skickas från en enhet med hjälp av komponenter måste lägga till komponentnamnet i telemetrimeddelandet.
När du använder MQTT lägger du till $.sub egenskapen med komponentnamnet i telemetriavsnittet, systemet lägger till dt-subject egenskapen.
När du använder AMQP lägger du till dt-subject egenskapen med komponentnamnet som en meddelandeanteckning.

Kommentar

Telemetri från komponenter kräver ett meddelande per komponent.

Fler telemetriexempel finns i Telemetri för nyttolaster >

Skrivskyddade egenskaper

En enhet anger en skrivskyddad egenskap som den sedan rapporterar till serverdelsprogrammet.

Exempel på ingen skrivskyddad komponentegenskap

En enhet eller modul kan skicka en giltig JSON som följer DTDL-reglerna.

DTDL som definierar en egenskap i ett gränssnitt:

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

Exempel på rapporterad egenskapsnyttolast:

"reported" :
{
  "temperature" : 21.3
}

Exempel på skrivskyddad egenskap för flera komponenter

Enheten eller modulen måste lägga till {"__t": "c"} markören för att indikera att elementet refererar till en komponent.

DTDL som refererar till en komponent:

{
  "@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 som definierar komponenten:

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

Exempel på rapporterad egenskapsnyttolast:

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

Mer skrivskyddade egenskapsexempel finns i Egenskaper för nyttolaster>.

Skrivbara egenskaper

Ett serverdelsprogram anger en skrivbar egenskap som IoT Hub sedan skickar till enheten.

Enheten eller modulen bör bekräfta att den tog emot egenskapen genom att skicka en rapporterad egenskap. Den rapporterade egenskapen bör innehålla:

value – det faktiska värdet för egenskapen (vanligtvis det mottagna värdet, men enheten kan besluta att rapportera ett annat värde).
ac – en bekräftelsekod som använder en HTTP-statuskod.
av – en bekräftelseversion som refererar till den $version önskade egenskapen. Du hittar det här värdet i den önskade egenskapenS JSON-nyttolast.
ad – en valfri bekräftelsebeskrivning.

Bekräftelsesvar

När du rapporterar skrivbara egenskaper ska enheten skapa bekräftelsemeddelandet genom att använda de fyra fälten i föregående lista för att ange det faktiska enhetstillståndet enligt beskrivningen i följande tabell:

Status(ac)	Version(av)	Value(value)	Description(av)
200	Önskad version	Önskat värde	Önskat egenskapsvärde accepteras
202	Önskad version	Värde som godkänts av enheten	Önskat egenskapsvärde accepteras, uppdatering pågår (bör slutföras med 200)
203	0	Värdet som angetts av enheten	Egenskapsuppsättning från enheten, vilket inte återspeglar önskade
400	Önskad version	Verkligt värde som används av enheten	Önskat egenskapsvärde accepteras inte
500	Önskad version	Verkligt värde som används av enheten	Undantag vid tillämpning av egenskapen

När en enhet startas bör den begära enhetstvillingen och söka efter eventuella skrivbara egenskapsuppdateringar. Om versionen av en skrivbar egenskap ökade när enheten var offline bör enheten skicka ett rapporterat egenskapssvar för att bekräfta att den tog emot uppdateringen.

När en enhet startas för första gången kan den skicka ett initialt värde för en rapporterad egenskap om den inte tar emot en ursprunglig önskad egenskap från IoT-hubben. I det här fallet kan enheten skicka standardvärdet med av till 0 och ac till 203. Till exempel:

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

En enhet kan använda den rapporterade egenskapen för att tillhandahålla annan information till hubben. Enheten kan till exempel svara med en serie pågående meddelanden, till exempel:

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

När enheten når måltemperaturen skickar den följande meddelande:

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

En enhet kan rapportera ett fel som:

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

Object type

Om en skrivbar egenskap definieras som ett objekt måste tjänsten skicka ett fullständigt objekt till enheten. Enheten bör bekräfta uppdateringen genom att skicka tillbaka tillräckligt med information till tjänsten för att förstå hur enheten har agerat vid uppdateringen. Det här svaret kan innehålla:

Hela objektet.
Bara de fält som enheten uppdaterade.
En delmängd av fälten.

För stora objekt bör du överväga att minimera storleken på det objekt som du inkluderar i bekräftelsen.

I följande exempel visas en skrivbar egenskap som definierats som en Object med fyra fält:

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
}

Om du vill uppdatera den här skrivbara egenskapen skickar du ett fullständigt objekt från tjänsten som ser ut som i följande exempel:

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

Enheten svarar med en bekräftelse som ser ut som i följande exempel:

{
  "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
    }
  }
}

Exempel på skrivbar egenskap för ingen komponent

När en enhet tar emot flera önskade egenskaper i en enda nyttolast kan den skicka rapporterade egenskapssvar över flera nyttolaster eller kombinera svaren till en enda nyttolast.

En enhet eller modul kan skicka en giltig JSON som följer DTDL-reglerna.

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
    }
  ]
}

Exempel på önskad egenskapsnyttolast:

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

Exempel på rapporterad egenskaps första nyttolast:

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

Exempel på rapporterad egenskaps andra nyttolast:

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

Kommentar

Du kan välja att kombinera dessa två rapporterade egenskapsnyttolaster till en enda nyttolast.

Exempel på skrivbar egenskap för flera komponenter

Enheten eller modulen måste lägga till {"__t": "c"} markören för att indikera att elementet refererar till en komponent.

Markören skickas endast för uppdateringar av egenskaper som definierats i en komponent. Uppdateringar till egenskaper som definierats i standardkomponenten inkluderar inte markören, se Exempel på ingen skrivbar egenskap för komponenten.

När en enhet tar emot flera rapporterade egenskaper i en enda nyttolast kan den skicka rapporterade egenskapssvar över flera nyttolaster eller kombinera svaren till en enda nyttolast.

Enheten eller modulen bör bekräfta att den tog emot egenskaperna genom att skicka rapporterade egenskaper:

DTDL som refererar till en komponent:

{
  "@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 som definierar komponenten:

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

Exempel på önskad egenskapsnyttolast:

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

Exempel på rapporterad egenskaps första nyttolast:

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

Exempel på rapporterad egenskaps andra nyttolast:

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

Kommentar

Du kan välja att kombinera dessa två rapporterade egenskapsnyttolaster till en enda nyttolast.

Fler skrivbara egenskapsexempel finns i Egenskaper för nyttolaster>.

Kommandon

Inga komponentgränssnitt använder kommandonamnet utan prefix.

På en enhet eller modul använder flera komponentgränssnitt kommandonamn med följande format: componentName*commandName.

Fler kommandoexempel finns i Payloads-kommandon>.

Dricks

IoT Central har egna konventioner för att implementera långvariga kommandon och offlinekommandon.

Nästa steg

Nu när du har lärt dig mer om IoT Plug and Play-konventioner finns här några andra resurser:

Konventioner för IoT Plug and Play

Identifiera modellen

Telemetri

Skrivskyddade egenskaper

Exempel på ingen skrivskyddad komponentegenskap

Exempel på skrivskyddad egenskap för flera komponenter

Skrivbara egenskaper

Bekräftelsesvar

Object type

Exempel på skrivbar egenskap för ingen komponent

Exempel på skrivbar egenskap för flera komponenter

Kommandon

Nästa steg

Ytterligare resurser