Konwencje technologii IoT Plug and Play

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, które urządzenie IoT Plug and Play implementuje za pomocą modelu języka DTDL (Digital Twins Definition Language). 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ładnik z więcej danymi telemetrycznymi, właściwościami i poleceniami.

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, dodając go do pola USERNAME.

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

• Pole cyfrowego bliźniaka modelId urządzenia.
• Pole cyfrowego bliźniaka $metadata.$model.
• Powiadomienie o zmianie cyfrowego bliźniaka.

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 właściwość $.sub z nazwą składnika do tematu telemetrii, a następnie system dodaje właściwość dt-subject.
• Aby korzystać z protokołu AMQP, dodaj właściwość dt-subject z nazwą składnika jako adnotację wiadomości.

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 atrybut tylko do odczytu, który następnie zgłasza do aplikacji zaplecza.

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

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ładowe zgłoszone dane właściwości:

"reported" :
{
  "temperature" : 21.3
}

Przykładowa właściwość tylko do odczytu dla 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ładowe zgłoszone dane 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 > ł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ł powinny potwierdzić otrzymanie właściwości, wysyłając odpowiedni komunikat. 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. W przesyłce JSON żądanej właściwości można znaleźć tę wartość.
• 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:

Gdy urządzenie zostanie uruchomione, powinno zażądać cyfrowego bliźniaka urządzenia i sprawdzić, czy istnieją aktualizacje zapisywalnych właściwości. 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."
  }
}

Typ obiektu

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 Object, która zawiera cztery pola:

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ład właściwości, której nie można zapisywać do żadnego składnika

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

Przykładowa właściwość zapisywalna dla 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 domyślnym składniku nie zawierają znacznika, zobacz Przykład właściwości niezapisywalnej składnika.

Gdy urządzenie odbiera wiele zgłoszonych właściwości w jednym ładunku, może wysyłać odpowiedzi na zgłoszone 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ładowe dane żądanej właściwości:

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

Pierwszy pakiet 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"
    }
  }
}

Aby uzyskać więcej przykładów właściwości zapisywalnych, zobacz > ł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>).

Następne kroki

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

• Język definicji cyfrowych reprezentacji bliźniaczych (DTDL, Digital Twins Definition Language)
• Zestaw SDK urządzeń dla języka C
• IoT REST API
• Przewodnik modelowania technologii IoT Plug and Play