Enhetsimplementering och metodtips för IoT Central

  • Artikel

Den här artikeln innehåller information om hur du implementerar enheter som ansluter till ditt centrala IoT-program. Den innehåller också några metodtips. Mer information om den övergripande anslutningsprocessen finns i Anslut en enhet.

Exempel på kod för enhetsimplementering finns i Självstudie: Skapa och ansluta ett klientprogram till ditt Azure IoT Central-program.

Implementera enheten

Enheter som ansluter till IoT Central bör följa IoT Plug and Play-konventionerna. En av dessa konventioner är att en enhet ska skicka modell-ID :t för den enhetsmodell som den implementerar när den ansluter. Med modell-ID:t kan IoT Central-programmet tilldela enheten till rätt enhetsmall.

En IoT Central-enhetsmall innehåller en modell som anger de beteenden som en enhet av den typen ska implementera. Beteenden omfattar telemetri, egenskaper och kommandon.

Varje modell har en unik modellidentifierare för digitala tvillingar (DTMI), till exempel dtmi:com:example:Thermostat;1. När en enhet ansluter till IoT Central skickar den DTMI för den modell som den implementerar. IoT Central kan sedan tilldela rätt enhetsmall till enheten.

IoT Plug and Play definierar en uppsättning konventioner som en enhet ska följa när den implementerar en DTDL-modell (Digital Twin Definition Language).

Azure IoT-enhets-SDK:er har stöd för IoT Plug and Play-konventionerna.

Enhetsmodell

En enhetsmodell definieras med hjälp av modellspråket DTDL V2 . Med det här språket kan du definiera:

  • Telemetrin som enheten skickar. Definitionen innehåller telemetrins namn och datatyp. En enhet skickar till exempel temperaturtelemetri som en dubbel.
  • Egenskaperna som enheten rapporterar till IoT Central. En egenskapsdefinition innehåller dess namn och datatyp. En enhet rapporterar till exempel tillståndet för en ventil som boolesk.
  • Egenskaperna som enheten kan ta emot från IoT Central. Du kan också markera en egenskap som skrivbar. Till exempel skickar IoT Central en måltemperatur som en dubbel till en enhet.
  • Kommandona som en enhet svarar på. Definitionen innehåller namnet på kommandot och namn och datatyper för alla parametrar. En enhet svarar till exempel på ett omstartskommando som anger hur många sekunder som ska vänta innan omstarten.

Kommentar

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

En DTDL-modell kan vara en icke-komponent eller en modell med flera komponenter :

  • Modell utan komponent: En enkel modell använder inte inbäddade eller överlappande komponenter. Alla telemetri, egenskaper och kommandon definieras som en enda rotkomponent. Ett exempel finns i termostatmodellen .
  • Modell med flera komponenter. En mer komplex modell som innehåller två eller flera komponenter. Dessa komponenter innehåller en enskild rotkomponent och en eller flera kapslade komponenter. Ett exempel finns i temperaturstyrenhetsmodellen.

Dricks

Du kan importera och exportera en fullständig enhetsmodell eller ett enskilt gränssnitt från en IoT Central-enhetsmall som en DTDL v2-fil.

Mer information om enhetsmodeller finns i modelleringsguiden för IoT Plug and Play

Praxis

En enhet bör följa IoT Plug and Play-konventionerna när den utbyter data med IoT Central. Konventionerna omfattar:

  • Skicka DTMI när den ansluter till IoT Central.
  • Skicka korrekt formaterade JSON-nyttolaster och metadata till IoT Central.
  • Svara korrekt på skrivbara egenskaper och kommandon från IoT Central.
  • Följ namngivningskonventionerna för komponentkommandon.

Kommentar

För närvarande stöder IoT Central inte helt DTDL-matrisenoch geospatiala datatyper.

Mer information om IoT Plug and Play-konventionerna finns i IoT Plug and Play-konventioner.

Mer information om formatet för JSON-meddelanden som en enhet byter med IoT Central finns i Nyttolaster för telemetri, egenskap och kommando.

Enhets-SDK:er

Använd en av SDK:erna för Azure IoT-enheter för att implementera enhetens beteende. Koden bör:

  • Registrera enheten med DPS och använd informationen från DPS för att ansluta till den interna IoT-hubben i ditt IoT Central-program.
  • Meddela DTMI för modellen som enheten implementerar.
  • Skicka telemetri i det format som enhetsmodellen anger. IoT Central använder modellen i enhetsmallen för att avgöra hur telemetrin ska användas för visualiseringar och analys.
  • Synkronisera egenskapsvärden mellan enheten och IoT Central. Modellen anger egenskapsnamn och datatyper så att IoT Central kan visa informationen.
  • Implementera kommandohanterare för de kommandon som anges i modellen. Modellen anger de kommandonamn och parametrar som enheten ska använda.

Mer information om enhetsmallarnas roll finns i Vad är enhetsmallar?.

I följande tabell sammanfattas hur Azure IoT Central-enhetsfunktioner mappas till IoT Hub-funktioner:

Azure IoT Central Azure IoT Hub
Telemetri Meddelanden från enhet till moln
Offlinekommandon Meddelanden från moln till enhet
Property Rapporterade egenskaper för enhetstvilling
Egenskap (skrivbar) Önskade och rapporterade egenskaper för enhetstvillingar
Command Direkta metoder

Kommunikationsprotokoll

Kommunikationsprotokoll som en enhet kan använda för att ansluta till IoT Central inkluderar MQTT, AMQP och HTTPS. Internt använder IoT Central en IoT-hubb för att aktivera enhetsanslutning. Mer information om de kommunikationsprotokoll som IoT Hub stöder för enhetsanslutning finns i Välj ett kommunikationsprotokoll.

Om enheten inte kan använda något av de protokoll som stöds använder du Azure IoT Edge för att utföra protokollkonvertering. IoT Edge stöder andra scenarier med intelligens på gränsen för att avlasta bearbetning från Azure IoT Central-programmet.

Tidsstämplar för telemetri

Som standard använder IoT Central meddelandets köade tid när telemetri visas på instrumentpaneler och diagram. Den köade tiden för meddelanden anges internt när IoT Central tar emot meddelandet från enheten.

En enhet kan ange egenskapen iothub-creation-time-utc när den skapar ett meddelande som ska skickas till IoT Central. Om den här egenskapen finns använder IoT Central den när den visar telemetri på instrumentpaneler och diagram.

Du kan exportera både den köade tiden och iothub-creation-time-utc egenskapen när du exporterar telemetri från ditt IoT Central-program.

Mer information om meddelandeegenskaper finns i Systemegenskaper för IoT Hub-meddelanden från enhet till moln.

Bästa praxis

De här rekommendationerna visar hur du implementerar enheter för att dra nytta av den inbyggda höga tillgängligheten , haveriberedskapen och den automatiska skalningen i IoT Central.

Hantera anslutningsfel

För skalning eller haveriberedskap kan IoT Central uppdatera sina underliggande IoT-hubbar. För att upprätthålla anslutningen bör enhetskoden hantera specifika anslutningsfel genom att upprätta en anslutning till en ny IoT Hub-slutpunkt.

Om enheten får något av följande fel när den ansluter bör den återskapa enheten med DPS för att få en ny anslutningssträng. Dessa fel innebär att anslutningssträng inte längre är giltig:

  • IoT Hub-slutpunkten kan inte nås.
  • Säkerhetstoken har upphört att gälla.
  • Enheten är inaktiverad i IoT Hub.

Om enheten får något av följande fel när den ansluter bör den använda en back-off-strategi för att försöka ansluta igen. Dessa fel innebär att anslutningssträng fortfarande är giltig, men tillfälliga villkor hindrar enheten från att ansluta:

  • Operatorn blockerade enheten.
  • Internt fel 500 från tjänsten.

Mer information om enhetsfelkoder finns i Felsöka enhetsanslutningar.

Mer information om hur du implementerar automatiska återanslutningar finns i Hantera enhetsåteranslutningar för att skapa motståndskraftiga program.

Testa redundansfunktioner

Med Azure CLI kan du testa redundansfunktionerna i din enhetskod. CLI-kommandot fungerar genom att tillfälligt växla en enhetsregistrering till en annan intern IoT-hubb. Kontrollera att enhetens redundans fungerade genom att kontrollera att enheten fortfarande skickar telemetri och svarar på kommandon.

Kör följande kommando för att köra redundanstestet för enheten:

az iot central device manual-failover \
    --app-id {Application ID of your IoT Central application} \
    --device-id {Device ID of the device you're testing} \
    --ttl-minutes {How to wait before moving the device back to it's original IoT hub}

Dricks

Du hittar program-ID:t genom att gå till Programhantering > i ditt IoT Central-program.

Om kommandot lyckas ser du utdata som ser ut som i följande exempel:

Command group 'iot central device' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
{
  "hubIdentifier": "6bd4...bafa",
  "message": "Success! This device is now being failed over. You can check your device'’'s status using 'iot central device registration-info' command. The device will revert to its original hub at Tue, 18 May 2021 11:03:45 GMT. You can choose to failback earlier using device-manual-failback command. Learn more: https://aka.ms/iotc-device-test"
}

Mer information om CLI-kommandot finns i az iot central device manual-failover(az iot central device manual-failover).

Nu kan du kontrollera att telemetrin från enheten fortfarande når ditt IoT Central-program.

Dricks

Information om hur du ser exempel på enhetskod som hanterar redundansväxlingar på olika programmeringsspråk finns i Klienter med hög tillgänglighet i IoT Central.

Nästa steg

Några föreslagna nästa steg är att: