Konventioner för IoT Plug and Play
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 tilldt-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 av egenskaper som definierats i standardkomponenten inkluderar inte markören. Se Exempel på en 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: