Konwencje technologii IoT Plug and Play

Artykuł
02/06/2024

Urządzenia IoT Plug and Play powinny postępować zgodnie z zestawem konwencji podczas wymiany komunikatów z centrum IoT Hub. Urządzenia IoT Plug and Play używają protokołu MQTT do komunikowania się z usługą IoT Hub. Usługa IoT Hub obsługuje również protokół AMQP, który jest dostępny w niektórych zestawach SDK urządzeń IoT.

Urządzenie może zawierać moduły lub zaimplementować je w module usługi IoT Edge hostowanym przez środowisko uruchomieniowe usługi IoT Edge.

Opisano dane telemetryczne, właściwości i polecenia implementujące urządzenie IoT Plug and Play z modelem Digital Twins Definition Language (DTDL). Istnieją dwa typy modelu, o których mowa w tym artykule:

Brak składnika — model bez składników. Model deklaruje dane telemetryczne, właściwości i polecenia jako elementy najwyższego poziomu w sekcji zawartości głównego interfejsu. W narzędziu Eksplorator usługi Azure IoT ten model jest wyświetlany jako pojedynczy składnik domyślny.
Wiele składników — model składający się z co najmniej dwóch interfejsów. Główny interfejs, który jest wyświetlany jako składnik domyślny z danymi telemetrycznymi, właściwościami i poleceniami. Co najmniej jeden interfejs zadeklarowany jako składniki z większą liczbie danych telemetrycznych, właściwości i poleceń.

Aby uzyskać więcej informacji, zobacz Przewodnik modelowania technologii IoT Plug and Play.

Identyfikowanie modelu

Aby ogłosić model, który implementuje, urządzenie lub moduł IoT Plug and Play zawiera identyfikator modelu w pakiecie połączenia MQTT przez dodanie model-id go do USERNAME pola.

Aby zidentyfikować model implementujący urządzenie lub moduł, usługa może uzyskać identyfikator modelu:

Pole bliźniaczej reprezentacji modelId urządzenia.
Pole cyfrowej reprezentacji bliźniaczej $metadata.$model .
Powiadomienie o zmianie cyfrowej reprezentacji bliźniaczej.

Telemetria

Dane telemetryczne wysyłane z urządzenia bez składnika nie wymagają żadnych dodatkowych metadanych. System dodaje dt-dataschema właściwość .
Dane telemetryczne wysyłane z urządzenia przy użyciu składników muszą dodać nazwę składnika do komunikatu telemetrii.
W przypadku korzystania z MQTT dodaj $.sub właściwość z nazwą składnika do tematu telemetrii, system dodaje dt-subject właściwość.
W przypadku korzystania z protokołu AMQP dodaj dt-subject właściwość o nazwie składnika jako adnotację komunikatu.

Uwaga

Dane telemetryczne ze składników wymagają jednego komunikatu na składnik.

Aby uzyskać więcej przykładów telemetrii, zobacz Payloads Telemetry (Dane telemetryczne ładunków > )

Właściwości tylko do odczytu

Urządzenie ustawia właściwość tylko do odczytu, która następnie raportuje do aplikacji zaplecza.

Przykładowa właściwość bez składnika tylko do odczytu

Urządzenie lub moduł może wysyłać dowolny prawidłowy kod JSON zgodny z regułami DTDL.

DTDL definiujący właściwość w interfejsie:

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

Przykładowy zgłoszony ładunek właściwości:

"reported" :
{
  "temperature" : 21.3
}

Przykładowa właściwość tylko do odczytu wielu składników

Urządzenie lub moduł musi dodać {"__t": "c"} znacznik, aby wskazać, że element odwołuje się do składnika.

DTDL, który odwołuje się do składnika:

{
  "@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 definiujący składnik:

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

Przykładowy zgłoszony ładunek właściwości:

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

Aby uzyskać więcej przykładów właściwości tylko do odczytu, zobacz Właściwości ładunków>.

Właściwości z możliwością zapisu

Aplikacja zaplecza ustawia właściwość zapisywalną, którą usługa IoT Hub następnie wysyła do urządzenia.

Urządzenie lub moduł powinien potwierdzić, że odebrał właściwość, wysyłając zgłoszoną właściwość. Zgłoszona właściwość powinna zawierać następujące elementy:

value - rzeczywista wartość właściwości (zazwyczaj odebrana wartość, ale urządzenie może zdecydować się zgłosić inną wartość).
ac — kod potwierdzenia, który używa kodu stanu HTTP.
av — wersja potwierdzenia, która odwołuje się do $version żądanej właściwości. Tę wartość można znaleźć w ładunku JSON żądanej właściwości.
ad — opcjonalny opis potwierdzenia.

Odpowiedzi na potwierdzenie

Podczas raportowania właściwości zapisywalnych urządzenie powinno utworzyć komunikat potwierdzenia przy użyciu czterech pól na poprzedniej liście, aby wskazać rzeczywisty stan urządzenia zgodnie z opisem w poniższej tabeli:

Status(ac)	Version(av)	Value(value)	Opis (av)
200	Żądana wersja	Żądana wartość	Zaakceptowana wartość żądanej właściwości
202	Żądana wersja	Wartość zaakceptowana przez urządzenie	Zaakceptowana wartość żądanej właściwości, aktualizacja w toku (powinna zakończyć się 200)
203	0	Wartość ustawiona przez urządzenie	Właściwość ustawiona z urządzenia, która nie odzwierciedla żadnego żądanego elementu
400	Żądana wersja	Rzeczywista wartość używana przez urządzenie	Nie zaakceptowano żądanej wartości właściwości
500	Żądana wersja	Rzeczywista wartość używana przez urządzenie	Wyjątek podczas stosowania właściwości

Gdy urządzenie zostanie uruchomione, powinno zażądać bliźniaczej reprezentacji urządzenia i sprawdzić, czy nie ma aktualizacji właściwości zapisywalnych. Jeśli wersja właściwości zapisywalnej wzrosła, gdy urządzenie było w trybie offline, urządzenie powinno wysłać zgłoszoną odpowiedź właściwości, aby potwierdzić, że otrzymała aktualizację.

Gdy urządzenie jest uruchamiane po raz pierwszy, może wysłać początkową wartość zgłaszanej właściwości, jeśli nie otrzyma początkowej żądanej właściwości z centrum IoT. W takim przypadku urządzenie może wysłać wartość av domyślną do 0 i ac do 203. Na przykład:

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

Urządzenie może użyć zgłaszanej właściwości, aby przekazać inne informacje do centrum. Na przykład urządzenie może odpowiedzieć serią komunikatów w toku, takich jak:

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

Gdy urządzenie osiągnie temperaturę docelową, wysyła następujący komunikat:

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

Urządzenie może zgłosić błąd, taki jak:

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

Object type

Jeśli właściwość zapisywalna jest zdefiniowana jako obiekt, usługa musi wysłać pełny obiekt do urządzenia. Urządzenie powinno potwierdzić aktualizację, wysyłając wystarczające informacje z powrotem do usługi, aby zrozumieć, w jaki sposób urządzenie działało w ramach aktualizacji. Ta odpowiedź może obejmować:

Cały obiekt.
Tylko pola zaktualizowane przez urządzenie.
Podzbiór pól.

W przypadku dużych obiektów rozważ zminimalizowanie rozmiaru obiektu uwzględnionego w potwierdzeniu.

W poniższym przykładzie przedstawiono właściwość zapisywalną zdefiniowaną jako z czterema Object polami:

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
}

Aby zaktualizować tę właściwość zapisywalną, wyślij pełny obiekt z usługi, która wygląda jak w poniższym przykładzie:

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

Urządzenie odpowiada potwierdzeniem, które wygląda jak w poniższym przykładzie:

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

Przykładowa właściwość nie można zapisywać składników

Gdy urządzenie odbiera wiele żądanych właściwości w jednym ładunku, może wysyłać zgłoszone odpowiedzi właściwości w wielu ładunkach lub łączyć odpowiedzi w jeden ładunek.

Urządzenie lub moduł może wysyłać dowolny prawidłowy kod JSON zgodny z regułami 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
    }
  ]
}

Przykładowy ładunek żądanej właściwości:

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

Pierwszy ładunek przykładowej zgłoszonej właściwości:

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

Przykładowa zgłoszona właściwość drugiego ładunku:

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

Uwaga

Możesz połączyć te dwa zgłoszone ładunki właściwości w jeden ładunek.

Przykładowa właściwość zapisywalna wielu składników

Urządzenie lub moduł musi dodać {"__t": "c"} znacznik, aby wskazać, że element odwołuje się do składnika.

Znacznik jest wysyłany tylko dla aktualizacji właściwości zdefiniowanych w składniku. Aktualizacje właściwości zdefiniowanych w składniku domyślnym nie zawierają znacznika, zobacz Przykładowa właściwość nie można zapisywać składników.

Gdy urządzenie odbiera wiele zgłoszonych właściwości w jednym ładunku, może wysyłać zgłoszone odpowiedzi właściwości w wielu ładunkach lub łączyć odpowiedzi w jeden ładunek.

Urządzenie lub moduł powinien potwierdzić, że odebrał właściwości, wysyłając zgłoszone właściwości:

DTDL, który odwołuje się do składnika:

{
  "@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 definiujący składnik:

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

Przykładowy ładunek żądanej właściwości:

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

Pierwszy ładunek przykładowej zgłoszonej właściwości:

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

Przykładowa zgłoszona właściwość drugiego ładunku:

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

Uwaga

Możesz połączyć te dwa zgłoszone ładunki właściwości w jeden ładunek.

Aby uzyskać więcej przykładów właściwości zapisywalnych, zobacz Właściwości ładunków>.

Polecenia

Żadne interfejsy składników nie używają nazwy polecenia bez prefiksu.

Na urządzeniu lub module wiele interfejsów składników używa nazw poleceń w następującym formacie: componentName*commandName.

Aby uzyskać więcej przykładów poleceń, zobacz Payloads Commands (Polecenia ładunków>).

Napiwek

Usługa IoT Central ma własne konwencje implementowania długotrwałych poleceń i poleceń offline.

Następne kroki

Teraz, gdy znasz już konwencje IoT Plug and Play, oto kilka innych zasobów:

Konwencje technologii IoT Plug and Play

Identyfikowanie modelu

Telemetria

Właściwości tylko do odczytu

Przykładowa właściwość bez składnika tylko do odczytu

Przykładowa właściwość tylko do odczytu wielu składników

Właściwości z możliwością zapisu

Odpowiedzi na potwierdzenie

Object type

Przykładowa właściwość nie można zapisywać składników

Przykładowa właściwość zapisywalna wielu składników

Polecenia

Następne kroki

Dodatkowe zasoby