Konvence IoT Plug and Play

Článek
02/06/2024

Zařízení IoT technologie Plug and Play by měla při výměně zpráv se službou IoT Hub dodržovat sadu konvencí. Zařízení technologie Plug and Play IoT používají ke komunikaci se službou IoT Hub protokol MQTT. IoT Hub také podporuje protokol AMQP, který je k dispozici v některých sadách SDK zařízení IoT.

Zařízení může obsahovat moduly nebo je implementovat v modulu IoT Edge hostovaném modulem runtime IoT Edge.

Popisujete telemetrii, vlastnosti a příkazy, které zařízení IoT technologie Plug and Play implementuje pomocí modelu DTDL (Digital Twins Definition Language). Existují dva typy modelu uvedené v tomto článku:

Žádná komponenta – model bez komponent. Model deklaruje telemetrii, vlastnosti a příkazy jako elementy nejvyšší úrovně v části obsahu hlavního rozhraní. V nástroji Azure IoT Explorer se tento model zobrazí jako jedna výchozí komponenta.
Více komponent – model složený ze dvou nebo více rozhraní. Hlavní rozhraní, které se zobrazuje jako výchozí komponenta s telemetrií, vlastnostmi a příkazy. Jedno nebo více rozhraní deklarovaných jako komponenty s více telemetrií, vlastnostmi a příkazy.

Další informace najdete v průvodci modelováním technologie Plug and Play IoT.

Identifikace modelu

K oznámení modelu, který implementuje, zahrnuje ioT technologie Plug and Play zařízení nebo modul ID modelu v paketu připojení MQTT přidáním model-id do USERNAME pole.

K identifikaci modelu, který zařízení nebo modul implementuje, může služba získat ID modelu z:

Pole dvojčete modelId zařízení.
Pole digitálního dvojčete $metadata.$model .
Oznámení o změně digitálního dvojčete

Telemetrie

Telemetrie odeslaná ze zařízení žádné komponenty nevyžaduje žádná další metadata. Systém přidá dt-dataschema vlastnost.
Telemetrie odeslaná ze zařízení pomocí komponent musí přidat název komponenty do zprávy telemetrie.
Při použití MQTT přidejte $.sub vlastnost s názvem komponenty do tématu telemetrie, systém vlastnost přidá dt-subject .
Při použití AMQP přidejte dt-subject vlastnost s názvem komponenty jako poznámku ke zprávě.

Poznámka:

Telemetrie ze součástí vyžaduje jednu zprávu pro každou komponentu.

Další příklady telemetrie najdete v tématu Telemetrie datových > částí.

Vlastnosti jen pro čtení

Zařízení nastaví vlastnost jen pro čtení, kterou pak hlásí back-endové aplikaci.

Ukázka vlastnosti jen pro čtení součásti

Zařízení nebo modul může odeslat libovolný platný kód JSON, který se řídí pravidly DTDL.

DTDL, která definuje vlastnost v rozhraní:

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

Ukázková datová část ohlášené vlastnosti:

"reported" :
{
  "temperature" : 21.3
}

Ukázka vlastnosti jen pro čtení několika komponent

Zařízení nebo modul musí přidat {"__t": "c"} značku, která označuje, že prvek odkazuje na komponentu.

DTDL, která odkazuje na komponentu:

{
  "@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, který definuje komponentu:

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

Ukázková datová část ohlášené vlastnosti:

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

Další příklady vlastností jen pro čtení najdete v tématu Vlastnosti datových > částí.

Zapisovatelné vlastnosti

Back-endová aplikace nastaví zapisovatelnou vlastnost, kterou IoT Hub pak odešle do zařízení.

Zařízení nebo modul by měly potvrdit, že obdržela vlastnost odesláním ohlášené vlastnosti. Ohlášená vlastnost by měla zahrnovat:

value – skutečná hodnota vlastnosti (obvykle přijatá hodnota, ale zařízení se může rozhodnout ohlásit jinou hodnotu).
ac – kód potvrzení, který používá stavový kód HTTP.
av – verze potvrzení, která odkazuje na $version požadovanou vlastnost. Tuto hodnotu najdete v datové části JSON požadované vlastnosti.
ad – volitelný popis potvrzení.

Odpovědi na potvrzení

Při generování sestav zapisovatelných vlastností by zařízení mělo vytvořit zprávu potvrzení pomocí čtyř polí v předchozím seznamu, která označují skutečný stav zařízení, jak je popsáno v následující tabulce:

Status(ac)	Version(av)	Value(value)	Description(av)
200	Požadovaná verze	Požadovaná hodnota	Přijatá hodnota požadované vlastnosti
202	Požadovaná verze	Hodnota přijatá zařízením	Požadovaná hodnota vlastnosti byla přijata, probíhá aktualizace (měla by být dokončena s hodnotou 200)
203	0	Hodnota nastavená zařízením	Vlastnost nastavená ze zařízení, která neodráží žádné požadované
400	Požadovaná verze	Skutečná hodnota používaná zařízením	Desired property value not accepted
500	Požadovaná verze	Skutečná hodnota používaná zařízením	Výjimka při použití vlastnosti

Když se zařízení spustí, mělo by požádat o dvojče zařízení a zkontrolovat všechny aktualizace zapisovatelných vlastností. Pokud se verze zapisovatelné vlastnosti zvýšila, když bylo zařízení offline, mělo by zařízení odeslat ohlášenou odpověď na vlastnost, aby potvrdilo, že obdržela aktualizaci.

Když se zařízení poprvé spustí, může odeslat počáteční hodnotu ohlášené vlastnosti, pokud neobdrží počáteční požadovanou vlastnost ze služby IoT Hub. V tomto případě může zařízení odeslat výchozí hodnotu do av0 a ac do 203. Příklad:

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

Zařízení může ohlášenou vlastnost použít k poskytnutí dalších informací do centra. Zařízení může například reagovat řadou probíhajících zpráv, jako jsou:

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

Když zařízení dosáhne cílové teploty, odešle následující zprávu:

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

Zařízení může nahlásit chybu, například:

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

Object type

Pokud je zapisovatelná vlastnost definována jako objekt, služba musí odeslat kompletní objekt do zařízení. Zařízení by mělo aktualizaci potvrdit odesláním dostatečných informací zpět do služby, aby bylo jasné, jak zařízení na aktualizaci fungovalo. Tato odpověď může zahrnovat:

Celý objekt.
Jenom pole, která zařízení aktualizovalo.
Podmnožina polí

U velkých objektů zvažte minimalizaci velikosti objektu, který zahrnete do potvrzení.

Následující příklad ukazuje zapisovatelnou vlastnost definovanou jako se Object čtyřmi poli:

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
}

Chcete-li aktualizovat tuto zapisovatelnou vlastnost, odešlete úplný objekt ze služby, který vypadá jako v následujícím příkladu:

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

Zařízení odpoví potvrzením, které vypadá jako v následujícím příkladu:

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

Ukázka vlastnosti zapisovatelné součásti

Když zařízení obdrží několik požadovaných vlastností v jedné datové části, může odeslat ohlášené odpovědi na vlastnost napříč několika datovými částmi nebo zkombinovat odpovědi do jedné datové části.

Zařízení nebo modul může odeslat libovolný platný kód JSON, který se řídí pravidly 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
    }
  ]
}

Ukázková datová část požadované vlastnosti:

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

Ukázková hlášená vlastnost– první datová část:

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

Ukázková hlášená vlastnost – druhá datová část:

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

Poznámka:

Tyto dvě hlášené datové části vlastností můžete zkombinovat do jedné datové části.

Ukázka zapisovatelné vlastnosti s více komponentami

Zařízení nebo modul musí přidat {"__t": "c"} značku, která označuje, že prvek odkazuje na komponentu.

Značka se odesílá pouze pro aktualizace vlastností definovaných v komponentě. Aktualizace k vlastnostem definovaným ve výchozí komponentě nezahrnou značku, viz Ukázka žádné zapisovatelné vlastnosti komponenty

Když zařízení obdrží více ohlášených vlastností v jedné datové části, může odeslat ohlášené odpovědi na vlastnost napříč několika datovými částmi nebo zkombinovat odpovědi do jedné datové části.

Zařízení nebo modul by měl potvrdit, že obdržel vlastnosti odesláním ohlášených vlastností:

DTDL, která odkazuje na komponentu:

{
  "@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, který definuje komponentu:

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

Ukázková datová část požadované vlastnosti:

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

Ukázková hlášená vlastnost– první datová část:

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

Ukázková hlášená vlastnost – druhá datová část:

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

Poznámka:

Tyto dvě hlášené datové části vlastností můžete zkombinovat do jedné datové části.

Další příklady zapisovatelných vlastností najdete v tématu Vlastnosti datových > částí.

Příkazy

Žádná rozhraní komponent nepoužívají název příkazu bez předpony.

V zařízení nebo modulu používá více rozhraní komponent názvy příkazů s následujícím formátem: componentName*commandName.

Další příklady příkazů najdete v tématu Příkazy datových > částí.

Tip

IoT Central má vlastní konvence pro implementaci dlouhotrvajících příkazů a příkazů offline.

Další kroky

Teď, když jste se seznámili s konvencemi technologie Plug and Play IoT, tady jsou některé další zdroje informací:

Konvence IoT Plug and Play

Identifikace modelu

Telemetrie

Vlastnosti jen pro čtení

Ukázka vlastnosti jen pro čtení součásti

Ukázka vlastnosti jen pro čtení několika komponent

Zapisovatelné vlastnosti

Odpovědi na potvrzení

Object type

Ukázka vlastnosti zapisovatelné součásti

Ukázka zapisovatelné vlastnosti s více komponentami

Příkazy

Další kroky

Další materiály