Vad är enhetsmallar?

  • Artikel

En enhetsmall i Azure IoT Central är en skiss som definierar egenskaperna och beteendena för en typ av enhet som ansluter till ditt program. Enhetsmallen definierar till exempel telemetrin som en enhet skickar så att IoT Central kan skapa visualiseringar som använder rätt enheter och datatyper.

En lösningsbyggare lägger till enhetsmallar i ett IoT Central-program. En enhetsutvecklare skriver enhetskoden som implementerar de beteenden som definieras i enhetsmallen. Mer information om de data som en enhet utbyter med IoT Central finns i Nyttolaster för telemetri, egenskap och kommando.

En enhetsmall innehåller följande avsnitt:

  • En enhetsmodell. Den här delen av enhetsmallen definierar hur enheten interagerar med ditt program. Varje enhetsmodell har ett unikt ID. En enhetsutvecklare implementerar de beteenden som definierats i modellen.
    • Rotkomponent. Varje enhetsmodell har en rotkomponent. Rotkomponentens gränssnitt beskriver funktioner som är specifika för enhetsmodellen.
    • Komponenter. En enhetsmodell kan innehålla komponenter utöver rotkomponenten för att beskriva enhetsfunktioner. Varje komponent har ett gränssnitt som beskriver komponentens funktioner. Komponentgränssnitt kan återanvändas i andra enhetsmodeller. Till exempel kan flera telefonenhetsmodeller använda samma kameragränssnitt.
    • Ärvda gränssnitt. En enhetsmodell innehåller ett eller flera gränssnitt som utökar funktionerna i rotkomponenten.
  • Visningar. Med den här delen av enhetsmallen kan lösningsutvecklaren definiera visualiseringar för att visa data från enheten och formulär för att hantera och kontrollera en enhet. Vyer påverkar inte koden som en enhetsutvecklare skriver för att implementera enhetsmodellen.

Tilldela en enhet till en enhetsmall

För att en enhet ska kunna interagera med IoT Central måste den tilldelas till en enhetsmall. Den här tilldelningen görs på ett av fyra sätt:

  • När du registrerar en enhet på sidan Enheter kan du identifiera mallen som enheten ska använda.
  • När du massimportera en lista över enheter kan du välja enhetsmallen som alla enheter i listan ska använda.
  • Du kan tilldela en otilldelade enhet manuellt till en enhetsmall när den har anslutits.
  • Du kan automatiskt tilldela en enhet till en enhetsmall genom att skicka ett modell-ID när enheten först ansluter till ditt program.

Automatisk tilldelning

IoT Central kan automatiskt tilldela en enhet till en enhetsmall när enheten ansluter. En enhet bör skicka ett modell-ID när den ansluter. IoT Central använder modell-ID:t för att identifiera enhetsmallen för den specifika enhetsmodellen. Identifieringsprocessen fungerar på följande sätt:

  1. Om enhetsmallen redan har publicerats i IoT Central-programmet tilldelas enheten till enhetsmallen.

  2. Om enhetsmallen inte redan har publicerats i IoT Central-programmet letar IoT Central efter enhetsmodellen på lagringsplatsen för den offentliga enhetsmodellen. Om IoT Central hittar modellen använder den den för att generera en grundläggande enhetsmall.

  3. Om IoT Central inte hittar modellen på lagringsplatsen för den offentliga modellen markeras enheten som Ej tilldelad. En operator kan:

    • Skapa en enhetsmall för enheten och migrera sedan den otilldelade enheten till den nya enhetsmallen.
    • Skapa en enhetsmall automatiskt baserat på de data som enheten skickar.

Följande skärmbild visar hur du visar modell-ID för en enhetsmall i IoT Central. I en enhetsmall väljer du en komponent och sedan Redigera identitet:

Skärmbild som visar modell-ID i termostatenhetsmall.

Du kan visa termostatmodellen på lagringsplatsen för den offentliga modellen. Modell-ID-definitionen ser ut så här:

"@id": "dtmi:com:example:Thermostat;1"

Använd följande DPS-nyttolast för att tilldela enheten till en enhetsmall:

{
  "modelId":"dtmi:com:example:TemperatureController;2"
}

Mer information om DPS-nyttolasten finns i exempelkoden som används i Självstudie: Skapa och ansluta ett klientprogram till ditt Azure IoT Central-program.

Enhetsmodeller

En enhetsmodell definierar hur en enhet interagerar med ditt IoT Central-program. Enhetsutvecklaren måste se till att enheten implementerar de beteenden som definierats i enhetsmodellen så att IoT Central kan övervaka och hantera enheten. En enhetsmodell består av ett eller flera gränssnitt och varje gränssnitt kan definiera en samling telemetrityper , enhetsegenskaper och kommandon. En lösningsutvecklare kan:

  • Importera en JSON-fil som definierar en fullständig enhetsmodell eller ett enskilt gränssnitt till en enhetsmall.
  • Använd webbgränssnittet i IoT Central för att skapa eller redigera en enhetsmodell.

Kommentar

IoT Central accepterar en giltig JSON-nyttolast från en enhet, men den kan bara använda data för visualiseringar om den matchar en definition i enhetsmodellen. Du kan exportera data som inte matchar en definition. Mer information finns i Exportera IoT-data till molnmål med bloblagring.

Mer information om hur du redigerar en enhetsmodell finns i Redigera en befintlig enhetsmall

En lösningsutvecklare kan också exportera en JSON-fil från enhetsmallen som innehåller en fullständig enhetsmodell eller ett enskilt gränssnitt. En enhetsutvecklare kan använda det här JSON-dokumentet för att förstå hur enheten ska kommunicera med IoT Central-programmet.

JSON-filen som definierar enhetsmodellen använder DTDL V2 (Digital Twin Definition Language). IoT Central förväntar sig att JSON-filen innehåller enhetsmodellen med de gränssnitt som definierats infogat i stället för i separata filer. Modeller som skapats i IoT Central har den kontext dtmi:iotcentral:context;2 som definierats för att indikera att modellen skapades i IoT Central:

"@context": [
  "dtmi:iotcentral:context;2",
  "dtmi:dtdl:context;2"
]

Mer information om DTDL-modeller finns i modelleringsguiden för IoT Plug and Play.

Kommentar

IoT Central definierar vissa tillägg till språket DTDL v2. Mer information finns i IoT Central-tillägget.

Egenskaper

Som standard är egenskaperna skrivskyddade. Skrivskyddade egenskaper innebär att enheten rapporterar att egenskapsvärdet uppdateras till ditt IoT Central-program. Ditt IoT Central-program kan inte ange värdet för en skrivskyddad egenskap.

Du kan också markera en egenskap som skrivbar i ett gränssnitt. En enhet kan ta emot en uppdatering av en skrivbar egenskap från ditt IoT Central-program och rapportera egenskapsvärdeuppdateringar till ditt program.

Enheter behöver inte vara anslutna för att ange egenskapsvärden. De uppdaterade värdena överförs när enheten ansluter till programmet. Det här beteendet gäller både skrivskyddade och skrivbara egenskaper.

Använd inte egenskaper för att skicka telemetri från enheten. Till exempel innebär en skrivskyddad egenskap som temperatureSetting=80 bör innebära att enhetens temperatur har angetts till 80 och att enheten försöker komma till eller stanna kvar vid den här temperaturen.

För skrivbara egenskaper returnerar enhetsprogrammet en önskad tillståndsstatuskod, version och beskrivning för att ange om det tog emot och tillämpade egenskapsvärdet.

Molnegenskaper

Du kan också lägga till molnegenskaper i modellens rotkomponent. Med molnegenskaper kan du ange alla enhetsmetadata som ska lagras i IoT Central-programmet. Molnegenskapsvärden lagras i IoT Central-programmet och synkroniseras aldrig med en enhet. Molnegenskaper påverkar inte den kod som en enhetsutvecklare skriver för att implementera enhetsmodellen.

En lösningsutvecklare kan lägga till molnegenskaper i enhetsvyer och formulär tillsammans med enhetsegenskaper så att en operatör kan hantera de enheter som är anslutna till programmet. En lösningsutvecklare kan också använda molnegenskaper som en del av en regeldefinition för att göra ett tröskelvärde redigerbart av en operatör.

Följande DTDL-kodfragment visar ett exempel på molnegenskapsdefinition:

{
    "@id": "dtmi:azureiot:Thermostat:CustomerName",
    "@type": [
        "Property",
        "Cloud",
        "StringValue"
    ],
    "displayName": {
        "en": "Customer Name"
    },
    "name": "CustomerName",
    "schema": "string"
}

Telemetri

Med IoT Central kan du visa telemetri i enhetsvyer och diagram och använda regler för att utlösa åtgärder när tröskelvärden nås. IoT Central använder informationen i enhetsmodellen, till exempel datatyper, enheter och visningsnamn, för att avgöra hur telemetrivärden ska visas. Du kan också visa telemetrivärden på program- och personliga instrumentpaneler.

Du kan använda funktionen för dataexport i IoT Central för att strömma telemetri till andra mål, till exempel lagring eller Event Hubs.

Kommandon

Ett kommando måste köras inom 30 sekunder som standard och enheten måste vara ansluten när kommandot anländer. Om enheten svarar i tid, eller om enheten inte är ansluten, misslyckas kommandot.

Kommandon kan ha begäransparametrar och returnera ett svar.

Offlinekommandon

Du kan välja kökommandon om en enhet för närvarande är offline genom att aktivera alternativet Kö om offline för ett kommando i enhetsmallen.

Offlinekommandon är enkelriktade meddelanden till enheten från din lösning. Offlinekommandon kan ha begäransparametrar men returnerar inte något svar.

Kommentar

Offlinekommandon markeras som durable om du exporterar modellen som DTDL.

Offlinekommandon använder IoT Hub-meddelanden från moln till enhet för att skicka kommandot och nyttolasten till enheten.

Nyttolasten för meddelandet som enheten tar emot är parameterns råvärde. En anpassad egenskap med namnet method-name lagrar namnet på IoT Central-kommandot. I följande tabell visas några exempel på nyttolaster:

IoT Central-begärandeschema Exempel på nyttolast som tas emot av enheten
Ingen parameter för begäran @
Dubbel 1.23
String sample string
Objekt {"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

Följande kodfragment från en enhetsmodell visar definitionen av ett kommando. Kommandot har en objektparameter med ett datetime-fält och en uppräkning:

{
  "@type": "Command",
  "displayName": {
    "en": "Generate Diagnostics"
  },
  "name": "GenerateDiagnostics",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "Payload"
    },
    "name": "Payload",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "StartTime"
          },
          "name": "StartTime",
          "schema": "dateTime"
        },
        {
          "displayName": {
            "en": "Bank"
          },
          "name": "Bank",
          "schema": {
            "@type": "Enum",
            "displayName": {
              "en": "Enum"
            },
            "enumValues": [
              {
                "displayName": {
                  "en": "Bank 1"
                },
                "enumValue": 1,
                "name": "Bank1"
              },
              {
                "displayName": {
                  "en": "Bank2"
                },
                "enumValue": 2,
                "name": "Bank2"
              },
              {
                "displayName": {
                  "en": "Bank3"
                },
                "enumValue": 3,
                "name": "Bank3"
              }
            ],
            "valueSchema": "integer"
          }
        }
      ]
    }
  }
}

Om du aktiverar alternativet Kö om offline i användargränssnittet för enhetsmallen för kommandot i föregående kodavsnitt innehåller meddelandet som enheten tar emot följande egenskaper:

Egenskapsnamn Exempelvärde
custom_properties {'method-name': 'GenerateDiagnostics'}
data {"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

Vyer

En lösningsutvecklare skapar vyer som låter operatörer övervaka och hantera anslutna enheter. Vyer är en del av enhetsmallen, så en vy är associerad med en viss enhetstyp. En vy kan innehålla:

  • Diagram för att rita telemetri.
  • Paneler för att visa skrivskyddade enhetsegenskaper.
  • Paneler så att operatorn kan redigera skrivbara enhetsegenskaper.
  • Paneler som låter operatören redigera molnegenskaper.
  • Paneler som låter operatorn anropa kommandon, inklusive kommandon som förväntar sig en nyttolast.
  • Paneler för att visa etiketter, bilder eller markdown-text.

Nästa steg

Nu när du har lärt dig om enhetsmallar är ett föreslaget nästa steg att läsa nyttolaster för telemetri, egenskap och kommando för att lära dig mer om de data som en enhet utbyter med IoT Central.