Enhetsuppdatering för IoT Hub och IoT Plug and Play
Enhetsuppdatering för IoT Hub använder IoT Plug and Play för att identifiera och hantera enheter som kan uppdateras över luften. 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:
- Förstå IoT Plug and Play-enhetsklienten.
- Se hur enhetsuppdateringsagenten implementeras.
Enhetsuppdateringsmodeller
Modell-ID är hur smarta enheter annonserar sina funktioner till Azure IoT-program med IoT Plug och Play.To lära sig mer om hur du skapar smarta enheter för att annonsera deras funktioner till Azure IoT-program besöker IoT Plug and Play-enhetsutvecklarguiden.
Enhetsuppdatering för IoT Hub kräver att den smarta IoT Plug and Play-enheten meddelar ett modell-ID som en del av enhetsanslutningen. Lär dig hur du tillkännager ett modell-ID.
Enhetsuppdatering har flera PnP-modeller som har definierats som stöder DU-funktioner. Enhetsuppdateringsmodellen dtmi:azure:iot:deviceUpdateContractModel; 3' stöder kärnfunktionerna och använder enhetsuppdateringens kärngränssnitt 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 använder även andra PnP-gränssnitt som skickar enhetsegenskaper och information och aktiverar diagnostikfunktioner. Läs mer om [Enhetsuppdateringsmodeller och gränssnittsversioner] (https://github.com/Azure/iot-plugandplay-models/tree/main/dtmi/azure/iot).
Enhetsuppdateringsagenten använder dtmi:azure:iot:deviceUpdateModel; 3 som stöder alla de senaste funktionerna i 1.1.0-versionen. Den här modellen stöder V5-manifestversionen. Äldre manifest fungerar med de senaste agenterna, men nya funktioner kräver användning av den senaste manifestversionen.
Agentmetadata
Enhetsuppdateringsagenten använder agentmetadatafält för att skicka information till Enhetsuppdateringstjänster.
| Name | Schema | Riktning | beskrivning | Exempel |
|---|---|---|---|---|
| deviceProperties | Mappning | enhet till molnet | Den uppsättning egenskaper som innehåller tillverkaren, modellen 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 in sig på uppdateringsdistributionen. Begränsad till fem enhetsegenskaper. | "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Mappning | enhet till molnet | Resultatet som rapporterats av agenten. Den 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. | 700 |
| extendedResultCode | integer | 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": ""} |
| tillstånd | integer | 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 aktuell distribution och bekräftelse av eventuella begäranden om återförsök som skickas från tjänsten till agenten. Observera att arbetsflödes-ID:t rapporterar ett "nodeployment"-värde när distributionen har avbrutits. | "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 för närvarande ä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 tagit 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 | beskrivning |
|---|---|---|---|
| manufacturer | sträng | enhet till molnet | Enhetens tillverkare, rapporterad via deviceProperties. Den här egenskapen läss 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 är ifyllt 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, rapporterad via deviceProperties. Den här egenskapen läss 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 är ifyllt i konfigurationsfilen rapporterar det 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 | Den här egenskapen används av tjänsten för att identifiera den basmodellversion som används av enhetsuppdateringsagenten för att hantera och kommunicera med agenten. Värde: 'dtmi:azure:iot:deviceUpdateContractModel; 3' för enheter som använder DU-agent version 1.1.0. Obs! Agenter som använder 'dtmi:azure:iot:deviceUpdateModel; 2" måste rapportera contractModelId som "dtmi:azure:iot:deviceUpdateContractModel; 3' som 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 versionen 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). Så här anpassar du egenskaper för enhetsuppdateringsagenten. |
| Dover | sträng | enhet till molnet | Version av leveransoptimeringsagenten som körs på enheten. 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 avregistrera sig från versionsrapportering genom att ange värdet till 0 (falskt). Så här anpassar du agentegenskaper för leveransoptimering. |
| Anpassade kompatibilitetsegenskaper | Användardefinierad | enhet till molnet | Implementer kan definiera andra enhetsegenskaper som ska användas för kompatibilitetskontrollen när du riktar in dig på uppdateringsdistributionen. |
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.
Tillstånd
Fältet Tillstånd är statusen som rapporteras av DU-agenten (Device Update) efter att en åtgärd har tagits emot från enhetsuppdateringstjänsten. Tillståndet 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 returneras 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änstmetadata innehåller fält som enhetsuppdateringstjänsterna 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 avsnittet Åtgärd . |
| 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 | 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. |
Åtgärd
Åtgärdsfältet representerar de åtgärder som vidtas av enhetsuppdateringsagenten enligt instruktioner 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. Den signalerar till enheten att tillämpa den distribuerade uppdateringen |
| Avbryt | 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 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 om det behövs. 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-arkitekturen. 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å enhetsinformationsgränssnittet.
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-komponenter
| Namn | Type | Schema | Riktning | beskrivning | Exempel |
|---|---|---|---|---|---|
| manufacturer | Property | sträng | enhet till molnet | Enhetstillverkarens företagsnamn. Den här egenskapen kan vara samma som namnet på den ursprungliga tillverkaren av utrustningen (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 |