Enhetsuppdatering för IoT Hub och IoT-Plug and Play

Artikel
1/26/2022

Enhetsuppdatering för IoT Hub använder IoT-Plug and Play för att identifiera och hantera enheter som är trådlösa uppdateringskompatibla. Enhetsuppdateringstjänsten skickar och tar emot egenskaper och meddelanden till och från enheter med hjälp av IoT-Plug and Play gränssnitt. Enhetsuppdatering för IoT Hub kräver att IoT-enheter implementerar följande gränssnitt och modell-ID.

Mer information:

Förstå IoT-Plug and Play-enhetsklienten.
Se hur enhetsuppdateringsagenten implementeras.

Kärngränssnitt för enhetsuppdatering

Gränssnittet DeviceUpdateCore används för att skicka uppdateringsåtgärder och metadata till enheter och ta emot uppdateringsstatus från enheter. DeviceUpdateCore-gränssnittet är uppdelat i två objektegenskaper.

Det förväntade komponentnamnet i din modell är "deviceUpdate" när det här gränssnittet implementeras. Läs mer om Azure IoT Plug and Play-komponenter.

Agentmetadata

Enhetsuppdateringsagenten använder agentens metadatafält för att skicka information till enhetsuppdateringstjänster.

Name	Schema	Riktning	Beskrivning	Exempel
deviceProperties	Karta	enhet till molnet	Den uppsättning egenskaper som innehåller tillverkare, modell och annan enhetsinformation.	Mer information finns i avsnittet Enhetsegenskaper .
compatPropertyNames	Sträng (kommaavgränsad)	enhet till molnet	Enheten rapporterade egenskaper som används för att kontrollera enhetens kompatibilitet för att rikta uppdateringsdistributionen. Begränsad till fem enhetsegenskaper.	"compatPropertyNames": "manufacturer,model"
lastInstallResult	Karta	enhet till molnet	Resultatet som rapporterats av agenten. Den innehåller resultatkod, utökad resultatkod och resultatinformation för huvuduppdatering och andra steguppdateringar.
resultCode	heltal	enhet till molnet	En kod som innehåller information om resultatet av den senaste uppdateringsåtgärden. Kan fyllas i för antingen lyckade eller misslyckade.	700
extendedResultCode	heltal	enhet till molnet	En kod som innehåller ytterligare information om resultatet. Kan fyllas i för antingen lyckade eller misslyckade.	0x80004005
resultDetails	sträng	enhet till molnet	Kunddefinierad kostnadsfri formulärsträng för att ge ytterligare resultatinformation. Returneras till tvillingen utan parsning
stepResults	map	enhet till molnet	Resultatet som rapporterats av agenten som innehåller resultatkod, utökad resultatkod och resultatinformation för steguppdateringar.	"step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""}
state	heltal	enhet till molnet	Ett heltal som anger aktuellt tillstånd för enhetsuppdateringsagenten.	Mer information finns i avsnittet Tillstånd .
arbetsflöde	Komplexa	enhet till molnet	En uppsättning värden som anger vilken distribution agenten för närvarande arbetar med, ID för den aktuella distributionen och bekräftelse av en begäran om återförsök som skickas från tjänsten till agenten.	"workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"}
installedUpdateId	sträng	enhet till molnet	Ett ID för uppdateringen som är installerad (via enhetsuppdatering). Det här värdet är en sträng som samlar in JSON för uppdaterings-ID eller null för en enhet som aldrig har gjort en uppdatering via Enhetsuppdatering.	installedUpdateID{"provider":"contoso","name":"image-update","version":"1.0.0"}"

Enhetsegenskaper

Fältet deviceProperties innehåller information om tillverkare och modell för en enhet.

Name	Schema	Riktning	Description
manufacturer	sträng	enhet till molnet	Enhetens enhetstillverkare, som rapporteras via `deviceProperties`. Den här egenskapen har lästs från en av två platser – först försöker deviceUpdateCore-gränssnittet läsa värdet "aduc_manufacturer" från konfigurationsfilen. Om värdet inte fylls i i konfigurationsfilen rapporterar det som standard kompileringstidsdefinitionen för ADUC_DEVICEPROPERTIES_MANUFACTURER. Den här egenskapen rapporteras endast vid start. Standardvärde: "Contoso".
modell	sträng	enhet till molnet	Enhetens enhetsmodell, som rapporteras via `deviceProperties`. Den här egenskapen har lästs från en av två platser – först försöker deviceUpdateCore-gränssnittet läsa värdet "aduc_model" från konfigurationsfilen. Om värdet inte fylls i i konfigurationsfilen rapporteras som standard kompileringstidsdefinitionen för ADUC_DEVICEPROPERTIES_MODEL. Den här egenskapen rapporteras endast vid start. Standardvärde: Video
interfaceId	sträng	enhet till molnet	Den här egenskapen används av tjänsten för att identifiera den gränssnittsversion som används av enhetsuppdateringsagenten. Gränssnitts-ID krävs av enhetsuppdateringstjänsten för att hantera och kommunicera med agenten. Standardvärde: "dtmi:azure:iot:deviceUpdate;1" för enheter som använder DU-agentversion 0.8.0.
aduVer	sträng	enhet till molnet	Version av enhetsuppdateringsagenten som körs på enheten. Det här värdet skrivs endast från versionen om ENABLE_ADU_TELEMETRY_REPORTING är inställt på 1 (sant) under kompileringstiden. Kunder kan välja att inte rapportera versioner genom att ange värdet till 0 (falskt). Anpassa egenskaper för enhetsuppdateringsagenten.
Dover	sträng	enhet till molnet	Version av leveransoptimeringsagenten som körs på enheten. Värdet skrivs endast från bygget om ENABLE_ADU_TELEMETRY_REPORTING anges till 1 (sant) under kompileringstiden. Kunder kan välja att avregistrera sig från versionsrapportering genom att ange värdet till 0 (falskt). Anpassa egenskaper för leveransoptimeringsagenten.
Anpassade kompatibilitetsegenskaper	Användardefinierad	enhet till molnet	Implementeraren kan definiera andra enhetsegenskaper som ska användas för kompatibilitetskontrollen när uppdateringsdistributionen riktas.

IoT Hub exempel på enhetstvilling:

"deviceUpdate": {
                "__t": "c",
                "agent": {
                    "deviceProperties": {
                        "manufacturer": "contoso",
                        "model": "virtual-vacuum-v1",
                        "interfaceId": "dtmi:azure:iot:deviceUpdateModel;1",
                        "aduVer": "DU;agent/0.8.0-rc1-public-preview",
                        "doVer": "DU;lib/v0.6.0+20211001.174458.c8c4051,DU;agent/v0.6.0+20211001.174418.c8c4051"
                    },
                    "compatPropertyNames": "manufacturer,model",
                    "lastInstallResult": {
                        "resultCode": 700,
                        "extendedResultCode": 0,
                        "resultDetails": "",
                        "stepResults": {
                            "step_0": {
                                "resultCode": 700,
                                "extendedResultCode": 0,
                                "resultDetails": ""
                            }
                        }
                    },
                    "state": 0,
                    "workflow": {
                        "action": 3,
                        "id": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01",
                        "retryTimestamp": "2022-01-26T11:33:29.9680598Z"
                    },
                    "installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"Virtual-Vacuum\",\"version\":\"5.0\"}"
                },

Anteckning

Enheten eller modulen måste lägga till {"__t": "c"} markören för att indikera att elementet refererar till en komponent. Mer information finns i IoT Plug and Play konventioner.

Tillstånd

Fältet Tillstånd är statusen som rapporteras av DU-agenten (Device Update) efter att ha tagit emot en åtgärd från enhetsuppdateringstjänsten. Tillstånd rapporteras som svar på en åtgärd (se åtgärdsavsnittet för mer information) som skickas till enhetsuppdateringsagenten från enhetsuppdateringstjänsten. Mer information om begäranden som flödar mellan enhetsuppdateringstjänsten och enhetsuppdateringsagenten finns i översiktsarbetsflödet.

Name	Värde	Beskrivning
Inaktiv	0	Enheten är redo att ta emot en åtgärd från enhetsuppdateringstjänsten. Efter en lyckad uppdatering återgår tillståndet till tillståndet `Idle` .
DeploymentInprogress	6	En distribution pågår.
Misslyckad	255	Ett fel uppstod under uppdateringen.
DownloadSucceeded	2	En lyckad nedladdning. Den här statusen rapporteras endast av enheter med agentversion 0.7.0 eller äldre.
InstallSucceeded	4	En lyckad installation. Den här statusen rapporteras endast av enheter med agentversion 0.7.0 eller äldre.

Tjänstmetadata

Tjänstens metadata innehåller fält som enhetsuppdateringstjänsterna använder för att kommunicera åtgärder och data till enhetsuppdateringsagenten.

Name	Schema	Riktning	Description
åtgärd	heltal	moln till enhet	Ett heltal som motsvarar en åtgärd som agenten ska utföra. Mer information finns i åtgärdsavsnittet.
updateManifest	sträng	moln till enhet	Används för att beskriva innehållet i en uppdatering. Genereras från importmanifestet.
updateManifestSignature	JSON-objekt	moln till enhet	En JSON-webbsignatur (JWS) med JSON-webbnycklar som används för källverifiering.
fileUrls	Karta	moln till enhet	`FileID` Karta över till `DownloadUrl`. Talar om för agenten vilka filer som ska laddas ned och vilken hash som ska användas för att verifiera att filerna har laddats ned korrekt.

Åtgärd

Åtgärdsfältet representerar de åtgärder som vidtas av enhetsuppdateringsagenten enligt instruktionerna från enhetsuppdateringstjänsten. Enhetsuppdateringsagenten rapporterar ett tillstånd för bearbetning av den mottagna åtgärden. Mer information om begäranden som flödar mellan enhetsuppdateringstjänsten och enhetsuppdateringsagenten finns i översiktsarbetsflödet.

Name	Värde	Beskrivning
applyDeployment	3	Tillämpa uppdateringen. Det signalerar till enheten att tillämpa den distribuerade uppdateringen
avbryt	255	Sluta bearbeta den aktuella åtgärden och gå tillbaka till `Idle`eller be en agent i tillståndet `Failed` att gå tillbaka till `Idle`.
ladda ned	0	Ladda ned publicerat innehåll eller uppdatering och annat innehåll som behövs. Den här åtgärden skickas endast till enheter med agentversion 0.7.0 eller äldre.
installera	1	Installera innehållet eller uppdateringen. Normalt innebär den här åtgärden att anropa installationsprogrammet för innehållet eller uppdateringen. Den här åtgärden skickas endast till enheter med agentversion 0.7.0 eller äldre.
apply	2	Slutför uppdateringen. Det signalerar systemet att starta om vid behov. Den här åtgärden skickas endast till enheter med agentversion 0.7.0 eller äldre.

Gränssnitt för enhetsinformation

Gränssnittet för enhetsinformation är ett begrepp som används i IoT Plug and Play arkitektur. Den innehåller egenskaper från enhet till moln som ger information om enhetens maskinvara och operativsystem. Enhetsuppdatering för IoT Hub använder DeviceInformation.manufacturer egenskaperna och DeviceInformation.model för telemetri och diagnostik. Mer information finns i det här exemplet på gränssnittet för enhetsinformation.

Det förväntade komponentnamnet i din modell är deviceInformation när det här gränssnittet implementeras. Läs mer om Azure IoT Plug and Play Components

Namn	Typ	Schema	Riktning	Beskrivning	Exempel
manufacturer	Egenskap	sträng	enhet till molnet	Enhetstillverkarens företagsnamn. Den här egenskapen kan vara samma som namnet på oem-tillverkaren (Original Equipment Manufacturer).	Contoso
modell	Egenskap	sträng	enhet till molnet	Enhetsmodellnamn eller ID.	IoT Edge enhet
swVersion	Egenskap	sträng	enhet till molnet	Version av programvaran på enheten. swVersion kan vara versionen av din inbyggda programvara.	4.15.0-122
osName	Egenskap	sträng	enhet till molnet	Namnet på operativsystemet på enheten.	Ubuntu Server 18.04
processorArchitecture	Egenskap	sträng	enhet till molnet	Processorns arkitektur på enheten.	ARM64
processorManufacturer	Egenskap	sträng	enhet till molnet	Namnet på tillverkaren av processorn på enheten.	Microsoft
totalStorage	Egenskap	sträng	enhet till molnet	Totalt tillgängligt lagringsutrymme på enheten i kilobyte.	2048
totalMemory	Egenskap	sträng	enhet till molnet	Totalt tillgängligt minne på enheten i kilobyte.	256

Modell-ID

Modell-ID är hur smarta enheter annonserar sina funktioner till Azure IoT-program med IoT-Plug and Play. Mer information om hur du skapar smarta enheter för att annonsera deras funktioner till Azure IoT-program finns i guiden för IoT-Plug and Play enhetsutvecklare.

Enhetsuppdatering för IoT Hub kräver att IoT-Plug and Play smart enhet meddelar ett modell-ID med värdet "dtmi:azure:iot:deviceUpdateModel;1" som en del av enhetsanslutningen. Lär dig hur du tillkännager ett modell-ID.

Dela via