IoT-Plug en Play in Azure Device Update voor IoT Hub
Apparaatupdate voor IoT Hub maakt gebruik van IoT-Plug en Play voor het detecteren en beheren van apparaten die over-the-air-updates geschikt zijn. In dit artikel wordt beschreven hoe de Device Update-service eigenschappen en berichten naar en van apparaten verzendt en ontvangt met behulp van IoT-Plug en Play-interfaces.
Zie de Handleiding voor ontwikkelaars van IoT-Plug en Play-apparaten en het bouwen van de Device Update-agent voor meer informatie.
Apparaatupdatemodellen
Slimme apparaten gebruiken IoT Plug en Play model-id's om hun mogelijkheden te adverteren naar Azure IoT-toepassingen. Apparaatupdate vereist dat het IoT-Plug en Play slim apparaat een model-id aankondigt als onderdeel van de apparaatverbinding. Zie de aankondiging van de model-id voor meer informatie.
Device Update heeft verschillende gedefinieerde IoT-Plug en Play-modellen die ondersteuning bieden voor Device Update-functies. Het Device Update-model **dtmi:azure:iot:deviceUpdateContractModel;3** ondersteunt de kernfunctionaliteit van Device Update en maakt gebruik van de coreinterface van Device Update om updateacties en metagegevens naar apparaten te verzenden en de updatestatus van apparaten te ontvangen.
Het andere ondersteunde model is**dtmi:azure:iot:deviceUpdateModel;3**, dat uitbreidt **deviceUpdateContractModel;3** en ook gebruikmaakt van IoT-Plug en Play-interfaces die apparaateigenschapsgegevens verzenden en diagnostische functies inschakelen. Zie Azure IoT Plug en Play Device Update Models voor deze en andere versies.
De Device Update-agent gebruikt **dtmi:azure:iot:deviceUpdateModel;3** die alle nieuwste functies in de release Device Update 1.1.0 ondersteunt. Dit model ondersteunt importmanifestversie 5.0. Oudere manifesten werken met de nieuwste agents, maar voor nieuwe functies is de meest recente manifestversie vereist.
Metagegevens van agent
De Device Update-agent gebruikt de volgende metagegevensvelden van de agent om informatie te verzenden naar Device Update-services.
| Naam | Schema | Richting | Beschrijving |
|---|---|---|---|
| deviceProperties | Overzicht | apparaat naar cloud | De set eigenschappen die de fabrikant, het model en andere apparaatgegevens bevatten. Zie Apparaateigenschappen voor meer informatie. |
| compatPropertyNames | Tekenreeks (door komma's gescheiden) | apparaat naar cloud | Maximaal vijf eigenschappen die worden gebruikt om te controleren op apparaatcompatibiliteit om de update-implementatie te richten. Voorbeeld: "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Overzicht | apparaat naar cloud | Het resultaat dat door de agent wordt gerapporteerd, met resultaatcode, uitgebreide resultaatcode en resultaatdetails voor de belangrijkste update en andere stapupdates. |
| resultCode | geheel getal | apparaat naar cloud | Een code die informatie bevat over het resultaat van de laatste updateactie. Kan worden ingevuld voor geslaagde of mislukte bewerkingen. Voorbeeld: 700 |
| extendedResultCode | geheel getal | apparaat naar cloud | Een code die meer informatie over het resultaat bevat. Kan worden ingevuld voor geslaagde of mislukte bewerkingen. Voorbeeld: 0x80004005 |
| resultDetails | tekenreeks | apparaat naar cloud | Een door de gebruiker geleverde vrije-vormtekenreeks om meer resultaatdetails op te geven. Geretourneerd naar de tweeling zonder parseren. |
| stepResults | map | apparaat naar cloud | Het resultaat dat door de agent wordt gerapporteerd, met resultaatcode, uitgebreide resultaatcode en resultaatdetails voor stapupdates. Voorbeeld: "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| staat | geheel getal | apparaat naar cloud | Een geheel getal dat de huidige status van de Device Update-agent aangeeft. Zie Status voor meer informatie. |
| werkstroom | complex | apparaat naar cloud | Een set waarden die aangeven aan welke implementatie de agent momenteel werkt, de id van de momenteel geïnstalleerde implementatie en bevestiging van een aanvraag voor opnieuw proberen die wordt verzonden van de service naar de agent. De workflow id rapporteert een "nodeployment" waarde zodra een implementatie is geannuleerd. Voorbeeld: "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"} |
| installedUpdateId | tekenreeks | apparaat naar cloud | Een id van de momenteel geïnstalleerde Device Update-implementatie. Met deze waarde wordt de JSON van de update-id vastgelegd, of null voor een apparaat dat nog nooit is bijgewerkt via Device Update. Voorbeeld: "installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}" |
Voorbeeld van IoT Hub-apparaatdubbel:
"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\"}"
},
Notitie
Het apparaat of de module moet de {"__t": "c"} markering toevoegen om aan te geven dat het element verwijst naar een onderdeel. Zie IoT Plug en Play conventies voor meer informatie.
Apparaateigenschappen
Het veld deviceProperties bevat de fabrikant en modelinformatie voor een apparaat.
| Naam | Schema | Richting | Beschrijving |
|---|---|---|---|
| fabrikant | tekenreeks | apparaat naar cloud | De fabrikant van het apparaat, gerapporteerd via deviceProperties.De DeviceUpdateCore interface probeert eerst de aduc_manufacturer waarde uit het configuratiebestand te lezen. Als de waarde niet is ingevuld in het configuratiebestand, wordt standaard de definitie van de compilatietijd gerapporteerd voor ADUC_DEVICEPROPERTIES_MANUFACTURER. Deze eigenschap wordt alleen gerapporteerd tijdens het opstarten. Standaardwaarde: 'Contoso' |
| model | tekenreeks | apparaat naar cloud | Het apparaatmodel van het apparaat, gerapporteerd via deviceProperties. De DeviceUpdateCore interface probeert eerst de aduc_model waarde uit het configuratiebestand te lezen. Als de waarde niet is ingevuld in het configuratiebestand, wordt standaard de definitie van de compilatietijd gerapporteerd voor ADUC_DEVICEPROPERTIES_MODEL. Deze eigenschap wordt alleen gerapporteerd tijdens het opstarten. Standaardwaarde: 'Video' |
| contractModelId | tekenreeks | apparaat naar cloud | Eigenschap die de service gebruikt om de basismodelversie te identificeren die de Device Update-agent gebruikt voor het beheren en communiceren met de agent. Waarde: dtmi:azure:iot:deviceUpdateContractModel;3 voor apparaten met device update-agent versie 1.1.0. Opmerking: Agents die de functie gebruiken dtmi:azure:iot:deviceUpdateModel;2 , moeten rapporteren contractModelId als dtmi:azure:iot:deviceUpdateContractModel;3, omdat deviceUpdateModel;3 is uitgebreid van deviceUpdateContractModel;3. |
| aduVer | tekenreeks | apparaat naar cloud | Versie van de Device Update-agent die op het apparaat wordt uitgevoerd. Deze waarde wordt alleen gelezen uit de build als deze is ingesteld 1 op ENABLE_ADU_TELEMETRY_REPORTING (true) tijdens het compileren. U kunt ervoor kiezen om u af te melden voor versierapportage door de waarde in te 0 stellen op (onwaar). Zie De Device Update-agent bouwen voor meer informatie. |
| Dover | tekenreeks | apparaat naar cloud | Versie van de Delivery Optimization-agent die op het apparaat wordt uitgevoerd. De waarde wordt alleen gelezen uit de build als deze is ingesteld 1 op ENABLE_ADU_TELEMETRY_REPORTING (true) tijdens het compileren. U kunt ervoor kiezen om u af te melden voor versierapportage door de waarde in te 0 stellen op (onwaar). Zie Eigenschappen van Delivery Optimization-agent aanpassen voor meer informatie. |
| Aangepaste compatibiliteitseigenschappen | Eigen definitie | apparaat naar cloud | Andere door de gebruiker gedefinieerde apparaateigenschappen die moeten worden gebruikt voor de compatibiliteitscontrole bij het implementeren van de update. |
Provincie
Het statusveld is de status die door de Device Update-agent wordt gerapporteerd als reactie op een actie die vanuit de Device Update-service naar de Device Update-agent is verzonden. Zie de werkstroom Agent voor meer informatie over aanvragen die stromen tussen de Device Update-service en de Device Update-agent.
| Naam | Weergegeven als | Beschrijving |
|---|---|---|
| Niet-actief | 0 | Het apparaat is klaar om een actie te ontvangen van de Device Update-service. Na een geslaagde update keert de status terug naar de Idle status. |
| DeploymentInprogress | 6 | Er wordt een implementatie uitgevoerd. |
| Mislukt | 255 | Er is een fout opgetreden tijdens het bijwerken. |
| DownloadSucceeded | 2 | Er is een geslaagde download opgetreden. Alleen apparaten met agentversie 0.7.0 of ouder rapporteren deze status. |
| InstallSucceededed | 4 | Er is een geslaagde installatie uitgevoerd. Alleen apparaten met agentversie 0.7.0 of ouder rapporteren deze status. |
Actie
Het actieveld vertegenwoordigt de actie die de Device Update-agent moet uitvoeren volgens de instructies van de Device Update-service. De Device Update-agent rapporteert een status voor het verwerken van de actie die wordt ontvangen. Zie de werkstroom Agent voor meer informatie over aanvragen die stromen tussen de Device Update-service en de Device Update-agent.
| Naam | Weergegeven als | Beschrijving |
|---|---|---|
| applyDeployment | 3 | Pas de geïmplementeerde update toe. |
| Annuleren | 255 | Stop de verwerking van de huidige actie en ga terug naar Idle, of vertel een agent in de Failed status om terug te gaan naar Idle. |
| downloadenen | 0 | Download gepubliceerde inhoud of update en andere benodigde inhoud. Deze actie wordt alleen verzonden naar apparaten met agentversie 0.7.0 of ouder. |
| installeren | 1 | Installeer de inhoud of update, meestal om het installatieprogramma aan te roepen voor de inhoud of update. Device Update verzendt deze actie alleen naar apparaten met agentversie 0.7.0 of ouder. |
| toepassen | 2 | Voltooi de update door indien nodig opnieuw op te starten. Device Update verzendt deze actie alleen naar apparaten met agentversie 0.7.0 of ouder. |
Servicemetagegevens
Servicemetagegevens bevatten velden die de Device Update-service gebruikt om acties en gegevens te communiceren met de Device Update-agent.
| Naam | Schema | Richting | Beschrijving |
|---|---|---|---|
| action | geheel getal | cloud naar apparaat | Een geheel getal dat overeenkomt met een actie die de agent moet uitvoeren. Zie Actie voor meer informatie. |
| updateManifest | tekenreeks | cloud naar apparaat | Beschrijft de inhoud van een update. Gegenereerd op basis van het importmanifest. |
| updateManifestSignature | JSON-object | cloud naar apparaat | Een JSON Web Signature (JWS) met JSON-websleutels die moeten worden gebruikt voor bronverificatie. |
| fileUrls | Overzicht | cloud naar apparaat | Kaart van FileID naar DownloadUrl. Geeft de agent aan welke bestanden moeten worden gedownload en welke hash moet worden gebruikt om te controleren of de bestanden correct zijn gedownload. |
Interface voor apparaatgegevens
De interface voor apparaatinformatie is een concept dat wordt gebruikt in IoT Plug en Play-architectuur. De interface bevat apparaat-naar-cloud-eigenschappen die informatie bieden over de hardware en het besturingssysteem van het apparaat. Device Update maakt gebruik van de DeviceInformation.manufacturer en DeviceInformation.model eigenschappen voor telemetrie en diagnostische gegevens. Zie voor een voorbeeld van de interface https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.jsonvoor apparaatinformatie.
Wanneer u deze interface implementeert, is de verwachte onderdeelnaam in uw model deviceInformation. Zie de Handleiding voor ioT-Plug en Play modellering voor meer informatie.
| Name | Type | Schema | Richting | Beschrijving | Voorbeeld |
|---|---|---|---|---|---|
| fabrikant | Eigenschappen | tekenreeks | apparaat naar cloud | Bedrijfsnaam van de fabrikant van het apparaat. De fabrikant kan hetzelfde zijn als de naam van de oorspronkelijke apparatuurfabrikant (OEM). | Contoso |
| model | Eigenschappen | tekenreeks | apparaat naar cloud | Naam of id van apparaatmodel. | IoT Edge-apparaat |
| swVersion | Eigenschappen | tekenreeks | apparaat naar cloud | Versie van de software op uw apparaat. swVersion kan de versie van uw firmware zijn. | 4.15.0-122 |
| osName | Eigenschappen | tekenreeks | apparaat naar cloud | Naam van het besturingssysteem op het apparaat. | Ubuntu Server 18.04 |
| processorArchitecture | Eigenschappen | tekenreeks | apparaat naar cloud | Architectuur van de processor op het apparaat. | ARM64 |
| processorManufacturer | Eigenschappen | tekenreeks | apparaat naar cloud | Naam van de fabrikant van de processor op het apparaat. | Microsoft |
| totalStorage | Eigenschappen | tekenreeks | apparaat naar cloud | Totale beschikbare opslag op het apparaat in kilobytes. | 2048 |
| totalMemory | Eigenschappen | tekenreeks | apparaat naar cloud | Totaal beschikbaar geheugen op het apparaat in kilobytes. | 256 |