Dela via

IoT Plug and Play i Azure Device Update för IoT Hub

  • Artikel

Enhetsuppdatering för IoT Hub använder IoT Plug and Play för att identifiera och hantera enheter som kan uppdateras över luften. Den här artikeln beskriver hur tjänsten Enhetsuppdatering skickar och tar emot egenskaper och meddelanden till och från enheter med hjälp av IoT Plug and Play-gränssnitt.

Mer information finns i utvecklarhandboken för IoT Plug and Play-enheten och Skapa enhetsuppdateringsagenten.

Enhetsuppdateringsmodeller

Smarta enheter använder IoT Plug and Play-modell-ID:n för att annonsera sina funktioner till Azure IoT-program. Enhetsuppdatering kräver att den smarta IoT Plug and Play-enheten meddelar ett modell-ID som en del av enhetsanslutningen. Mer information finns i Meddelande om modell-ID.

Enhetsuppdatering har flera definierade IoT Plug and Play-modeller som stöder enhetsuppdateringsfunktioner. Enhetsuppdateringsmodellen **dtmi:azure:iot:deviceUpdateContractModel;3** har stöd för grundläggande funktioner för enhetsuppdatering och använder kärngränssnittet för enhetsuppdatering för att skicka uppdateringsåtgärder och metadata till enheter och ta emot uppdateringsstatus från enheter.

Den andra modellen som stöds är **dtmi:azure:iot:deviceUpdateModel;3**, som utökar **deviceUpdateContractModel;3** och även använder IoT Plug and Play-gränssnitt som skickar information om enhetsegenskap och aktiverar diagnostikfunktioner. Dessa och andra versioner finns i Azure IoT Plug and Play Device Update Models (Azure IoT Plug and Play Device Update Models).

Enhetsuppdateringsagenten använder **dtmi:azure:iot:deviceUpdateModel;3** som stöder alla de senaste funktionerna i enhetsuppdatering 1.1.0-versionen. Den här modellen stöder importmanifestversion 5.0. Äldre manifest fungerar med de senaste agenterna, men nya funktioner kräver den senaste manifestversionen.

Agentmetadata

Enhetsuppdateringsagenten använder följande agentmetadatafält för att skicka information till Enhetsuppdateringstjänster.

Name Schema Riktning beskrivning
deviceProperties Mappning enhet till molnet Den uppsättning egenskaper som innehåller tillverkaren, modellen och annan enhetsinformation. Mer information finns i Enhetsegenskaper .
compatPropertyNames Sträng (kommaavgränsad) enhet till molnet Upp till fem egenskaper som används för att söka efter enhetskompatibilitet för att rikta in sig på uppdateringsdistributionen.
Exempel: "compatPropertyNames": "manufacturer,model"
lastInstallResult Mappning enhet till molnet Resultatet som rapporterats av agenten, som innehåller resultatkod, utökad resultatkod och resultatinformation för huvuduppdatering och andra steguppdateringar.
resultCode integer 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.
Exempel: 700
extendedResultCode integer enhet till molnet En kod som innehåller mer information om resultatet. Kan fyllas i för antingen lyckade eller misslyckade.
Exempel: 0x80004005
resultDetails sträng enhet till molnet En frihandssträng som tillhandahålls av användaren för att ge mer resultatinformation. Återvände 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.
Exempel: "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""}
tillstånd integer enhet till molnet Ett heltal som anger aktuellt tillstånd för enhetsuppdateringsagenten. Mer information finns i Tillstånd .
arbetsflöde komplex enhet till molnet En uppsättning värden som anger den distribution som agenten för närvarande arbetar med, ID:t för den distribution som för närvarande är installerad och bekräftelse av alla begäranden om återförsök som skickas från tjänsten till agenten. ID workflow :t rapporterar ett "nodeployment" värde när en distribution har avbrutits.
Exempel: "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 den för närvarande installerade enhetsuppdateringsdistributionen. Det här värdet samlar in uppdaterings-ID:t JSON eller null för en enhet som aldrig har haft en uppdatering via Enhetsuppdatering.
Exempel: "installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}"

Exempel på IoT Hub-enhetstvilling:

"deviceUpdate": {
                "__t": "c",
                "agent": {
                    "deviceProperties": {
                        "manufacturer": "contoso",
                        "model": "virtual-vacuum-v1",
                        "contractModelId": "dtmi:azure:iot:deviceUpdateContractModel;3",
                        "aduVer": "DU;agent/1.1.0",
                        },
                    "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\"}"
                },

Kommentar

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.

Enhetsegenskaper

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

Name Schema Riktning beskrivning
manufacturer sträng enhet till molnet Enhetens tillverkare, rapporterad via deviceProperties.
Gränssnittet DeviceUpdateCore försöker först läsa värdet aduc_manufacturer från konfigurationsfilen. Om värdet inte är ifyllt i konfigurationsfilen rapporterar gränssnittet 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, rapporterad via deviceProperties. Gränssnittet DeviceUpdateCore försöker först läsa värdet aduc_model från konfigurationsfilen. Om värdet inte är ifyllt i konfigurationsfilen rapporterar gränssnittet som standard kompileringstidsdefinitionen för ADUC_DEVICEPROPERTIES_MODEL. Den här egenskapen rapporteras endast vid start.
Standardvärde: "Video"
contractModelId sträng enhet till molnet Egenskapen som tjänsten använder för att identifiera basmodellversionen som enhetsuppdateringsagenten använder för att hantera och kommunicera med agenten.
Värde: dtmi:azure:iot:deviceUpdateContractModel;3 för enheter som använder enhetsuppdateringsagent version 1.1.0.
Obs! Agenter som använder dtmi:azure:iot:deviceUpdateModel;2 måste rapportera contractModelId som dtmi:azure:iot:deviceUpdateContractModel;3, eftersom deviceUpdateModel;3 utökas från deviceUpdateContractModel;3.
aduVer sträng enhet till molnet Version av enhetsuppdateringsagenten som körs på enheten. Det här värdet skrivs endast från bygget om ENABLE_ADU_TELEMETRY_REPORTING det är inställt på 1 (sant) under kompileringstiden. Du kan välja att avregistrera dig från versionsrapportering genom att ange värdet till 0 (false). Mer information finns i Skapa 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 det är inställt på 1 (sant) under kompileringstiden. Du kan välja att avregistrera dig från versionsrapportering genom att ange värdet till 0 (false). Mer information finns i Anpassa agentegenskaper för leveransoptimering.
Anpassade kompatibilitetsegenskaper Användardefinierad enhet till molnet Andra användardefinierade enhetsegenskaper som ska användas för kompatibilitetskontrollen när du riktar in dig på uppdateringsdistributionen.

Tillstånd

Tillståndsfältet är statusen som rapporteras av enhetsuppdateringsagenten som svar på en åtgärd som skickats till enhetsuppdateringsagenten från enhetsuppdateringstjänsten. Mer information om begäranden som flödar mellan enhetsuppdateringstjänsten och enhetsuppdateringsagenten finns i agentarbetsflö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 har gjorts. Endast enheter med agentversion 0.7.0 eller äldre rapporterar den här statusen.
InstallSucceeded 4 En lyckad installation har inträffat. Endast enheter med agentversion 0.7.0 eller äldre rapporterar den här statusen.

Åtgärd

Åtgärdsfältet representerar den åtgärd som enhetsuppdateringsagenten ska vidta enligt instruktioner från enhetsuppdateringstjänsten. Enhetsuppdateringsagenten rapporterar ett tillstånd för bearbetning av den åtgärd som den tar emot. Mer information om begäranden som flödar mellan enhetsuppdateringstjänsten och enhetsuppdateringsagenten finns i agentarbetsflödet.

Name Värde beskrivning
applyDeployment 3 Tillämpa den distribuerade uppdateringen.
annullera 255 Sluta bearbeta den aktuella åtgärden och gå tillbaka till Idleeller be en agent i Failed tillståndet att gå tillbaka till Idle.
download 0 Ladda ned publicerat innehåll eller uppdatering och allt 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, vanligtvis för att anropa installationsprogrammet för innehållet eller uppdateringen. Enhetsuppdatering skickar endast den här åtgärden till enheter med agentversion 0.7.0 eller äldre.
apply 2 Slutför uppdateringen genom att starta om vid behov. Enhetsuppdatering skickar endast den här åtgärden till enheter med agentversion 0.7.0 eller äldre.

Tjänstmetadata

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

Name Schema Riktning beskrivning
åtgärd integer moln till enhet Ett heltal som motsvarar en åtgärd som agenten ska utföra. Mer information finns i Åtgärd .
updateManifest sträng moln till enhet Beskriver innehållet i en uppdatering. Genereras från importmanifestet.
updateManifestSignature JSON-objekt moln till enhet En JSON-webbsignatur (JWS) med JSON-webbnycklar som ska användas för källverifiering.
fileUrls Mappning 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.

Gränssnitt för enhetsinformation

Gränssnittet för enhetsinformation är ett begrepp som används i IoT Plug and Play-arkitekturen. Gränssnittet innehåller egenskaper från enhet till moln som ger information om enhetens maskinvara och operativsystem. Enhetsuppdatering använder DeviceInformation.manufacturer egenskaperna och DeviceInformation.model för telemetri och diagnostik. Ett exempel på enhetsinformationsgränssnittet finns i https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json.

När du implementerar det här gränssnittet är det förväntade komponentnamnet i din modell deviceInformation. Mer information finns i modelleringsguiden för IoT Plug and Play.

Namn Type Schema Riktning beskrivning Exempel
manufacturer Property sträng enhet till molnet Enhetstillverkarens företagsnamn. Tillverkaren kan vara samma som namnet på den ursprungliga utrustningstillverkaren (OEM). Contoso
modell Property sträng enhet till molnet Enhetsmodellnamn eller ID. IoT Edge-enhet
swVersion Property sträng enhet till molnet Version av programvaran på enheten. swVersion kan vara versionen av din inbyggda programvara. 4.15.0-122
osName Property sträng enhet till molnet Namnet på operativsystemet på enheten. Ubuntu Server 18.04
processorArchitecture Property sträng enhet till molnet Processorns arkitektur på enheten. ARM64
processorManufacturer Property sträng enhet till molnet Namnet på processortillverkaren på enheten. Microsoft
totalStorage Property sträng enhet till molnet Totalt tillgängligt lagringsutrymme på enheten i kilobyte. 2048
totalMemory Property sträng enhet till molnet Totalt tillgängligt minne på enheten i kilobyte. 256

Relaterat innehåll