Az IoT Plug and Playhez kapcsolódó konvenciók

Cikk
02/06/2024

Az IoT Plug and Play-eszközöknek számos konvenciót kell követniük, amikor üzeneteket cserélnek egy IoT Hubbal. Az IoT Plug and Play-eszközök az MQTT protokollt használják az IoT Hubbal való kommunikációhoz. Az IoT Hub támogatja az AMQP protokollt is, amely néhány IoT-eszköz SDK-ban elérhető.

Az eszközök tartalmazhatnak modulokat, vagy implementálhatók az IoT Edge-futtatókörnyezet által üzemeltetett IoT Edge-modulban .

Az IoT Plug and Play-eszközök által a Digital Twins Definition Language (DTDL) modellel implementált telemetriai adatokat, tulajdonságokat és parancsokat ismertetjük. Ebben a cikkben kétféle modellre hivatkozunk:

Nincs összetevő – Olyan modell, amely nem tartalmaz összetevőket. A modell a fő felület tartalomszakaszában legfelső szintű elemként deklarálja a telemetriát, a tulajdonságokat és a parancsokat. Az Azure IoT Explorer eszközben ez a modell egyetlen alapértelmezett összetevőként jelenik meg.
Több összetevő – Két vagy több interfészből álló modell. Egy fő felület, amely alapértelmezett összetevőként jelenik meg telemetriával, tulajdonságokkal és parancsokkal. Egy vagy több, több telemetriával, tulajdonságokkal és parancsokkal rendelkező összetevőként deklarált felület.

További információ: IoT Plug and Play modellezési útmutató.

A modell azonosítása

Az implementálandó modell bejelentéséhez egy IoT Plug and Play-eszköz vagy modul tartalmazza az MQTT-kapcsolatcsomag modellazonosítóját a USERNAME mező hozzáadásávalmodel-id.

Az eszköz vagy modul által implementálható modell azonosításához a szolgáltatás lekérheti a modellazonosítót a következő forrásból:

Az ikereszköz modelId mezője.
A digitális ikermező $metadata.$model .
Egy digitális ikerpéldány változásértesítés.

Telemetria

A nem összetevő eszközről küldött telemetriához nincs szükség további metaadatokra. A rendszer hozzáadja a tulajdonságot dt-dataschema .
Az összetevőket használó eszközről küldött telemetriának hozzá kell adnia az összetevő nevét a telemetriai üzenethez.
Az MQTT használatakor adja hozzá a $.sub tulajdonságot az összetevő nevével a telemetriai témakörhöz, a rendszer hozzáadja a dt-subject tulajdonságot.
Az AMQP használatakor adja hozzá a dt-subject tulajdonságot az összetevő nevével üzenetjegyzetként.

Feljegyzés

Az összetevők telemetriájának összetevőnként egy üzenetre van szüksége.

További telemetria-példákért lásd : Payloads > Telemetry

Csak olvasható tulajdonságok

Az eszköz beállít egy írásvédett tulajdonságot, amelyet aztán a háttéralkalmazásnak jelent.

Csak olvasható összetevő nélküli mintatulajdonság

Egy eszköz vagy modul bármilyen érvényes JSON-t küldhet, amely a DTDL-szabályokat követi.

Egy felület tulajdonságát definiáló DTDL:

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

Minta jelentett tulajdonság hasznos adatai:

"reported" :
{
  "temperature" : 21.3
}

Több összetevő írásvédett tulajdonságának mintája

Az eszköznek vagy modulnak hozzá kell adnia a {"__t": "c"} jelölőt, hogy jelezze, hogy az elem egy összetevőre hivatkozik.

Egy összetevőre hivatkozó DTDL:

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

Az összetevőt meghatározó DTDL:

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

Minta jelentett tulajdonság hasznos adatai:

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

További írásvédett tulajdonságokat a Hasznos adatok > tulajdonságai című témakörben talál.

Írható tulajdonságok

A háttéralkalmazás beállít egy írható tulajdonságot, amelyet az IoT Hub ezután elküld az eszköznek.

Az eszköznek vagy modulnak meg kell erősítenie, hogy megkapta a tulajdonságot egy jelentett tulajdonság elküldésével. A jelentett tulajdonságnak tartalmaznia kell a következőket:

value - a tulajdonság tényleges értéke (jellemzően a kapott érték, de az eszköz dönthet úgy, hogy egy másik értéket jelent).
ac - HTTP-állapotkódot használó nyugtázási kód.
av - a kívánt tulajdonságra hivatkozó $version nyugtázási verzió. Ez az érték a kívánt JSON hasznos adat tulajdonságban található.
ad - opcionális nyugtázási leírás.

Nyugtázási válaszok

Írható tulajdonságok jelentésekor az eszköznek meg kell írnia a nyugtázási üzenetet az előző lista négy mezőjének használatával a tényleges eszközállapot jelzéséhez az alábbi táblázatban leírtak szerint:

Status(ac)	Verzió(av)	Érték(érték)	Leírás(av)
200	Kívánt verzió	Kívánt érték	Elfogadott kívánt tulajdonságérték
202	Kívánt verzió	Az eszköz által elfogadott érték	A kívánt tulajdonság értéke elfogadva, a frissítés folyamatban van (200-zal kell befejeződnie)
203	0	Az eszköz által beállított érték	Az eszközről beállított tulajdonság, amely nem tükrözi a kívánt értéket
400	Kívánt verzió	Az eszköz által használt tényleges érték	A kívánt tulajdonságérték nem fogadható el
500	Kívánt verzió	Az eszköz által használt tényleges érték	Kivétel a tulajdonság alkalmazásakor

Amikor egy eszköz elindul, az ikereszközt kell kérnie, és ellenőriznie kell a írható tulajdonság frissítéseit. Ha egy írható tulajdonság verziója megnőtt, miközben az eszköz offline állapotban volt, az eszköznek jelentést kell küldenie a tulajdonságra adott válaszról, hogy meggyőződjön arról, hogy megkapta a frissítést.

Amikor egy eszköz első alkalommal indul el, elküldheti a jelentett tulajdonság kezdeti értékét, ha nem kap egy kezdeti kívánt tulajdonságot az IoT Hubtól. Ebben az esetben az eszköz elküldheti az alapértelmezett értéket av 0 ide és ac ide 203. Példa:

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

Az eszközök a jelentett tulajdonság használatával más információkat is szolgáltathatnak a központnak. Az eszköz például számos folyamatban lévő üzenettel válaszolhat, például:

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

Amikor az eszköz eléri a célhőmérsékletet, a következő üzenetet küldi:

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

Az eszköz a következőhöz hasonló hibát jelenthet:

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

Objektumtípus

Ha egy írható tulajdonság objektumként van definiálva, a szolgáltatásnak teljes objektumot kell küldenie az eszköznek. Az eszköznek tudomásul kell vennie a frissítést, ha elegendő információt küld vissza a szolgáltatásnak, hogy megértse, hogyan járt el az eszköz a frissítésen. Ez a válasz a következőkre terjedhet ki:

A teljes objektum.
Csak az eszköz által frissített mezők.
A mezők egy részhalmaza.

Nagy objektumok esetén fontolja meg a nyugtázásban szereplő objektum méretének minimalizálását.

Az alábbi példa egy írható tulajdonságot mutat be Object , amely négy mezőből áll:

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
}

A írható tulajdonság frissítéséhez küldjön egy teljes objektumot a szolgáltatásból, amely az alábbi példához hasonlóan néz ki:

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

Az eszköz a következő példához hasonló nyugtával válaszol:

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

Nincs összetevő írható tulajdonságának mintája

Ha egy eszköz több kívánt tulajdonságot kap egyetlen hasznos adatban, több hasznos adatra is elküldheti a jelentett tulajdonságválaszokat, vagy egyetlen hasznos adatba egyesítheti a válaszokat.

Egy eszköz vagy modul bármilyen érvényes JSON-t küldhet, amely a DTDL-szabályokat követi.

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

Minta a kívánt tulajdonság hasznos adataira:

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

Minta jelentett tulajdonság első hasznos adata:

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

Minta jelentett tulajdonság második hasznos adata:

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

Feljegyzés

Dönthet úgy, hogy a két jelentett tulajdonság hasznos adatait egyetlen hasznos adatba egyesíti.

Több összetevő írható tulajdonságának mintája

Az eszköznek vagy modulnak hozzá kell adnia a {"__t": "c"} jelölőt, hogy jelezze, hogy az elem egy összetevőre hivatkozik.

A jelölő csak az összetevőben definiált tulajdonságok frissítéséhez lesz elküldve. Az alapértelmezett összetevőben definiált tulajdonságok frissítései nem tartalmazzák a jelölőt, lásd: Minta nincs összetevő írható tulajdonsága.

Ha egy eszköz több jelentett tulajdonságot kap egyetlen hasznos adatban, több hasznos adatra is elküldheti a jelentett tulajdonságválaszokat, vagy egyetlen hasznos adatba egyesítheti a válaszokat.

Az eszköznek vagy modulnak a jelentett tulajdonságok elküldésével kell ellenőriznie, hogy megkapta-e a tulajdonságokat:

Egy összetevőre hivatkozó DTDL:

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

Az összetevőt meghatározó DTDL:

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

Minta a kívánt tulajdonság hasznos adataira:

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

Minta jelentett tulajdonság első hasznos adata:

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

Minta jelentett tulajdonság második hasznos adata:

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

Feljegyzés

Dönthet úgy, hogy a két jelentett tulajdonság hasznos adatait egyetlen hasznos adatba egyesíti.

További írható tulajdonság példákért lásd a Hasznos adatok tulajdonságai című témakört.>

Parancsok

Egyetlen összetevő-illesztő sem használja a parancsnevet előtag nélkül.

Egy eszközön vagy modulon több összetevő-illesztő a következő formátumú parancsneveket használja: componentName*commandName.

További példa a parancsokra: Payloads > Commands.

Tipp.

Az IoT Central saját konvencióval rendelkezik a hosszú ideig futó parancsok és offline parancsok implementálására.

Következő lépések

Most, hogy megismerkedett az IoT Plug and Play konvencióival, íme néhány további forrás:

Megosztás a következőn keresztül:

Az IoT Plug and Playhez kapcsolódó konvenciók

A modell azonosítása

Telemetria

Csak olvasható tulajdonságok

Csak olvasható összetevő nélküli mintatulajdonság

Több összetevő írásvédett tulajdonságának mintája

Írható tulajdonságok

Nyugtázási válaszok

Objektumtípus

Nincs összetevő írható tulajdonságának mintája

Több összetevő írható tulajdonságának mintája

Parancsok

Következő lépések

Visszajelzés

További források