Plug and Play IoT in Aggiornamento dispositivi di Azure per hub IoT
Aggiornamento dei dispositivi per hub IoT usa Plug and Play IoT per individuare e gestire i dispositivi che supportano l'aggiornamento over-the-air. Questo articolo descrive come il servizio Aggiornamento dispositivi invia e riceve proprietà e messaggi da e verso i dispositivi usando interfacce Plug and Play IoT.
Per altre informazioni, vedere la guida per gli sviluppatori di dispositivi Plug and Play IoT e Come compilare l'agente di aggiornamento dispositivi.
Modelli di aggiornamento dei dispositivi
I dispositivi intelligenti usano Plug and Play IoT ID modello per annunciare le proprie funzionalità alle applicazioni IoT di Azure. Aggiornamento dispositivi richiede che il Plug and Play IoT smart device annunci un ID modello come parte della connessione del dispositivo. Per altre informazioni, vedere Annuncio id modello.
Aggiornamento dispositivi include diversi modelli di Plug and Play IoT definiti che supportano le funzionalità di Aggiornamento dispositivi. Il modello **dtmi:azure:iot:deviceUpdateContractModel;3** Aggiornamento dispositivi supporta la funzionalità di aggiornamento dei dispositivi di base e usa l'interfaccia principale di Aggiornamento dispositivi per inviare azioni di aggiornamento e metadati ai dispositivi e ricevere lo stato di aggiornamento dai dispositivi.
L'altro modello supportato è **dtmi:azure:iot:deviceUpdateModel;3**, che estende **deviceUpdateContractModel;3** e usa anche interfacce Plug and Play IoT che inviano informazioni sulle proprietà del dispositivo e abilitano le funzionalità di diagnostica. Per queste e altre versioni, vedere Modelli di aggiornamento dei dispositivi di Azure Plug and Play IoT.
L'agente di Aggiornamento dispositivi usa **dtmi:azure:iot:deviceUpdateModel;3** che supporta tutte le funzionalità più recenti nella versione Device Update 1.1.0. Questo modello supporta l'importazione del manifesto versione 5.0. I manifesti meno recenti funzionano con gli agenti più recenti, ma le nuove funzionalità richiedono la versione più recente del manifesto.
Metadati dell'agente
L'agente di Aggiornamento dispositivi usa i campi di metadati dell'agente seguenti per inviare informazioni ai servizi Aggiornamento dispositivi.
| Nome | Schema | Direzione | Descrizione |
|---|---|---|---|
| deviceProperties | Mappa | da dispositivo a cloud | Set di proprietà che contengono il produttore, il modello e altre informazioni sul dispositivo. Per informazioni dettagliate, vedere Proprietà del dispositivo. |
| compatPropertyNames | Stringa (delimitata da virgole) | da dispositivo a cloud | Fino a cinque proprietà usate per verificare la compatibilità dei dispositivi per la distribuzione degli aggiornamenti. Esempio: "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Mappa | da dispositivo a cloud | Risultato segnalato dall'agente, contenente il codice del risultato, il codice del risultato esteso e i dettagli dei risultati per l'aggiornamento principale e altri aggiornamenti dei passaggi. |
| resultCode | integer | da dispositivo a cloud | Codice che contiene informazioni sul risultato dell'ultima azione di aggiornamento. Può essere popolato per esito positivo o negativo. Esempio: 700 |
| extendedResultCode | integer | da dispositivo a cloud | Codice che contiene altre informazioni sul risultato. Può essere popolato per esito positivo o negativo. Esempio: 0x80004005 |
| resultDetails | string | da dispositivo a cloud | Stringa a mano libera fornita dall'utente per fornire altri dettagli sui risultati. Restituito al gemello senza analizzare. |
| stepResults | mappa | da dispositivo a cloud | Risultato segnalato dall'agente, contenente il codice del risultato, il codice del risultato esteso e i dettagli dei risultati per gli aggiornamenti dei passaggi. Esempio: "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| state | integer | da dispositivo a cloud | Intero che indica lo stato corrente dell'agente di Aggiornamento dispositivi. Per informazioni dettagliate, vedere State (Stato ). |
| workflow | complex | da dispositivo a cloud | Set di valori che indicano la distribuzione in cui l'agente sta attualmente lavorando, l'ID della distribuzione attualmente installata e il riconoscimento di qualsiasi richiesta di ripetizione dei tentativi inviata dal servizio all'agente. L'ID segnala un "nodeployment" valore dopo l'annullamento workflow di una distribuzione. Esempio: "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "20222-01-26T11:33:29.9680598Z"} |
| installedUpdateId | string | da dispositivo a cloud | ID della distribuzione di Aggiornamento dispositivi attualmente installata. Questo valore acquisisce il codice JSON dell'ID aggiornamento o null per un dispositivo che non ha mai avuto un aggiornamento tramite Aggiornamento dispositivi. Esempio: "installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}" |
esempio di dispositivo gemello hub IoT:
"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\"}"
},
Nota
Il dispositivo o il modulo deve aggiungere l'indicatore {"__t": "c"} per indicare che l'elemento fa riferimento a un componente. Per altre informazioni, vedere convenzioni di Plug and Play IoT.
Proprietà dei dispositivi
Il campo deviceProperties contiene le informazioni sul produttore e sul modello per un dispositivo.
| Nome | Schema | Direzione | Descrizione |
|---|---|---|---|
| manufacturer | string | da dispositivo a cloud | Produttore del dispositivo, segnalato tramite deviceProperties.L'interfaccia DeviceUpdateCore tenta innanzitutto di leggere il aduc_manufacturer valore dal file di configurazione. Se il valore non viene popolato nel file di configurazione, per impostazione predefinita l'interfaccia segnala la definizione in fase di compilazione per ADUC_DEVICEPROPERTIES_MANUFACTURER. Questa proprietà viene segnalata solo al momento dell'avvio. Valore predefinito: 'Contoso' |
| modello | string | da dispositivo a cloud | Modello di dispositivo del dispositivo, segnalato tramite deviceProperties. L'interfaccia DeviceUpdateCore tenta innanzitutto di leggere il aduc_model valore dal file di configurazione. Se il valore non viene popolato nel file di configurazione, per impostazione predefinita l'interfaccia segnala la definizione in fase di compilazione per ADUC_DEVICEPROPERTIES_MODEL. Questa proprietà viene segnalata solo al momento dell'avvio. Valore predefinito: 'Video' |
| contractModelId | string | da dispositivo a cloud | Proprietà utilizzata dal servizio per identificare la versione del modello di base usata dall'agente di Aggiornamento dispositivi per gestire e comunicare con l'agente. Valore: dtmi:azure:iot:deviceUpdateContractModel;3 per i dispositivi che usano l'agente di Aggiornamento dispositivi versione 1.1.0. Nota: gli agenti che usano dtmi:azure:iot:deviceUpdateModel;2 devono segnalare contractModelId come dtmi:azure:iot:deviceUpdateContractModel;3, perché deviceUpdateModel;3 viene esteso da deviceUpdateContractModel;3. |
| aduVer | string | da dispositivo a cloud | Versione dell'agente di Aggiornamento dispositivi in esecuzione nel dispositivo. Questo valore viene letto dalla compilazione solo se ENABLE_ADU_TELEMETRY_REPORTING è impostato su 1 (true) durante la fase di compilazione. È possibile scegliere di rifiutare esplicitamente la segnalazione della versione impostando il valore su 0 (false). Per altre informazioni, vedere Come compilare l'agente di aggiornamento dispositivi. |
| Dover | string | da dispositivo a cloud | Versione dell'agente di ottimizzazione recapito in esecuzione nel dispositivo. Il valore viene letto dalla compilazione solo se ENABLE_ADU_TELEMETRY_REPORTING è impostato su 1 (true) durante la fase di compilazione. È possibile scegliere di rifiutare esplicitamente la segnalazione della versione impostando il valore su 0 (false). Per altre informazioni, vedere Come personalizzare le proprietà dell'agente di Ottimizzazione recapito. |
| Proprietà di compatibilità personalizzate | personalizzato | da dispositivo a cloud | Altre proprietà del dispositivo definite dall'utente da usare per il controllo della compatibilità quando è destinata alla distribuzione degli aggiornamenti. |
Provincia
Il campo stato è lo stato segnalato dall'agente di Aggiornamento dispositivi in risposta a un'azione inviata all'agente di aggiornamento dispositivi dal servizio Aggiornamento dispositivi. Per altre informazioni sulle richieste che passano tra il servizio Aggiornamento dispositivi e l'agente di Aggiornamento dispositivi, vedere il flusso di lavoro dell'agente.
| Nome | valore | Descrizione |
|---|---|---|
| Idle | 0 | Il dispositivo è pronto per ricevere un'azione dal servizio Aggiornamento dispositivi. Dopo un aggiornamento riuscito, lo stato torna allo Idle stato. |
| DeploymentInprogress | 6 | È in corso una distribuzione. |
| Non riuscito | 255 | Si è verificato un errore durante l'aggiornamento. |
| DownloadSucceeded | 2 | Si è verificato un download riuscito. Solo i dispositivi con la versione 0.7.0 o precedente dell'agente segnalano questo stato. |
| InstallSucceeded | 4 | Si è verificata un'installazione riuscita. Solo i dispositivi con la versione 0.7.0 o precedente dell'agente segnalano questo stato. |
Azione
Il campo azione rappresenta l'azione che l'agente di Aggiornamento dispositivi deve eseguire come indicato dal servizio Aggiornamento dispositivi. L'agente di Aggiornamento dispositivi segnala uno stato per l'elaborazione dell'azione ricevuta. Per altre informazioni sulle richieste che passano tra il servizio Aggiornamento dispositivi e l'agente di Aggiornamento dispositivi, vedere il flusso di lavoro dell'agente.
| Nome | valore | Descrizione |
|---|---|---|
| applyDeployment | 3 | Applicare l'aggiornamento distribuito. |
| cancel | 255 | Interrompere l'elaborazione dell'azione corrente e tornare a o indicare a Idleun agente nello Failed stato di tornare a Idle. |
| download | 0 | Scaricare il contenuto pubblicato o aggiornare e qualsiasi altro contenuto necessario. Questa azione viene inviata solo ai dispositivi con la versione 0.7.0 o precedente dell'agente. |
| installazione | 1 | Installare il contenuto o l'aggiornamento, in genere per chiamare il programma di installazione per il contenuto o l'aggiornamento. Aggiornamento dispositivo invia questa azione solo ai dispositivi con versione 0.7.0 o precedente dell'agente. |
| apply | 2 | Finalizzare l'aggiornamento riavviando, se necessario. Aggiornamento dispositivo invia questa azione solo ai dispositivi con versione 0.7.0 o precedente dell'agente. |
Metadati del servizio
I metadati del servizio contengono campi usati dal servizio Aggiornamento dispositivi per comunicare azioni e dati all'agente di Aggiornamento dispositivi.
| Nome | Schema | Direzione | Descrizione |
|---|---|---|---|
| action | integer | da cloud a dispositivo | Intero che corrisponde a un'azione che l'agente deve eseguire. Per informazioni dettagliate, vedere Azione . |
| updateManifest | string | da cloud a dispositivo | Descrive il contenuto di un aggiornamento. Generato dal manifesto di importazione. |
| updateManifestSignature | Oggetto JSON | da cloud a dispositivo | Una firma Web JSON (JWS) con chiavi Web JSON da usare per la verifica dell'origine. |
| fileUrls | Mappa | da cloud a dispositivo | Mappa di FileID a DownloadUrl. Indica all'agente quali file scaricare e l'hash da usare per verificare che i file siano stati scaricati correttamente. |
Interfaccia delle informazioni sul dispositivo
L'interfaccia delle informazioni sul dispositivo è un concetto usato all'interno dell'architettura Plug and Play IoT. L'interfaccia contiene proprietà da dispositivo a cloud che forniscono informazioni sull'hardware del dispositivo e sul sistema operativo. Device Update usa le proprietà e DeviceInformation.model per la DeviceInformation.manufacturer telemetria e la diagnostica. Per un esempio dell'interfaccia delle informazioni sul dispositivo, vedere https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json.
Quando si implementa questa interfaccia, il nome del componente previsto nel modello è deviceInformation. Per altre informazioni, vedere la guida alla modellazione Plug and Play IoT.
| Nome | Type | Schema | Direzione | Descrizione | Esempio |
|---|---|---|---|---|---|
| manufacturer | Proprietà | string | da dispositivo a cloud | Nome della società del produttore del dispositivo. Il produttore potrebbe essere uguale al nome del produttore di apparecchiature originali (OEM). | Contoso |
| model | Proprietà | string | da dispositivo a cloud | Nome o ID del modello di dispositivo. | Dispositivo IoT Edge |
| swVersion | Proprietà | string | da dispositivo a cloud | Versione del software nel dispositivo. swVersion potrebbe essere la versione del firmware. | 4.15.0-122 |
| osName | Proprietà | string | da dispositivo a cloud | Nome del sistema operativo nel dispositivo. | Ubuntu Server 18.04 |
| processorArchitecture | Proprietà | string | da dispositivo a cloud | Architettura del processore nel dispositivo. | ARM64 |
| processorManufacturer | Proprietà | string | da dispositivo a cloud | Nome del produttore del processore nel dispositivo. | Microsoft |
| totalStorage | Proprietà | string | da dispositivo a cloud | Spazio di archiviazione totale disponibile nel dispositivo in kilobyte. | 2048 |
| totalMemory | Proprietà | string | da dispositivo a cloud | Memoria totale disponibile nel dispositivo in kilobyte. | 256 |