Device Update para IoT Hub e IoT Plug and Play
Device Update para IoT Hub utiliza IoT Plug and Play para detectar y administrar dispositivos que admiten actualizaciones de forma inalámbrica. El servicio Device Update envía propiedades y mensajes a los dispositivos y los recibe de estos utilizando interfaces de IoT Plug and Play.
Para obtener más información:
- Comprenda el cliente de dispositivo de IoT Plug and Play.
- Vea cómo se implementa el agente de Device Update.
Modelos de Device Update
El identificador del modelo es la forma en que Smart Devices anuncia sus funcionalidades a las aplicaciones de IoT de Azure con IoT plug and Play. Si necesita más información sobre la creación de Smart Devices para anunciar sus funcionalidades en aplicaciones de Azure IoT, visite la guía para desarrolladores de dispositivos IoT Plug and Play.
Device Update for IoT Hub necesita que el Smart Device de IoT Plug and Play anuncie un identificador de modelo como parte de la conexión del dispositivo. Descubra cómo se anuncia un identificador de modelo.
Device Update tiene varios modelos PnP definidos que admiten características de DU. El modelo de Device Update, "dtmi:azure:iot:deviceUpdateContractModel;3", admite la funcionalidad principal y usa la interfaz principal de actualización de dispositivos para enviar acciones de actualización y metadatos a los dispositivos y recibir el estado de actualización de los dispositivos.
El otro modelo admitido es dtmi:azure:iot:deviceUpdateModel;3, que extiende deviceUpdateContractModel;3 y también usa otras interfaces PnP que envían propiedades e información del dispositivo y habilitan características de diagnóstico. Obtenga más información sobre las [Versiones de interfaces y modelos de Device Update] (https://github.com/Azure/iot-plugandplay-models/tree/main/dtmi/azure/iot).
El agente de Device Update usa dtmi:azure:iot:deviceUpdateModel;3, que admite todas las características más recientes de la versión 1.1.0. Este modelo admite la versión del manifiesto V5. Los manifiestos más antiguos funcionarán con los agentes más recientes, pero las nuevas características requieren el uso de la versión más reciente del manifiesto.
Metadatos del agente
El agente de Device Update usa los campos de metadatos del agente para enviar información a los servicios de Device Update.
| Nombre | Schema | Dirección | Descripción | Ejemplo |
|---|---|---|---|---|
| deviceProperties | Asignación | entre el dispositivo y la nube | Conjunto de propiedades que contienen el fabricante, el modelo y otra información del dispositivo. | Consulte la sección Propiedades del dispositivo para obtener más información. |
| compatPropertyNames | Cadena (separada por comas) | entre el dispositivo y la nube | Las propiedades notificadas del dispositivo que se usan para comprobar la compatibilidad del dispositivo con el destino de la implementación de actualizaciones. Limitado a cinco propiedades de dispositivo. | "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Asignación | entre el dispositivo y la nube | Resultado notificado por el agente. Contiene código de resultado, código de resultado extendido y detalles del resultado para la actualización principal y otras actualizaciones por pasos. | |
| resultCode | integer | entre el dispositivo y la nube | Código que contiene información sobre el resultado de la última acción de actualización. Se puede especificar para indicar si la operación se ha realizado correcta o incorrectamente. | 700 |
| extendedResultCode | integer | entre el dispositivo y la nube | Código que contiene información adicional sobre el resultado. Se puede especificar para indicar si la operación se ha realizado correcta o incorrectamente. | 0x80004005 |
| resultDetails | string | entre el dispositivo y la nube | Cadena de forma libre definida por el cliente para proporcionar detalles adicionales del resultado. Se devuelve al gemelo sin analizar. | |
| stepResults | mapa | entre el dispositivo y la nube | Resultado notificado por el agente que contiene el código de resultado, el código de resultado extendido y los detalles del resultado de las actualizaciones por pasos. | "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| state | integer | entre el dispositivo y la nube | Entero que indica el estado actual del agente de Device Update. | Consulte la sección Estado para más información. |
| flujo de trabajo | complejas | entre el dispositivo y la nube | Conjunto de valores que indica en qué implementación está trabajando actualmente el agente, el id. de la implementación actual y la confirmación de cualquier solicitud de reintento enviada desde el servicio al agente. Tenga en cuenta que el id. de flujo de trabajo notifica un valor de "nodeployment" una vez cancelada la implementación. | "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"} |
| installedUpdateId | string | entre el dispositivo y la nube | Identificador de la actualización que está instalada actualmente (mediante Device Update). Este valor es una cadena que captura el valor de la instrucción JSON Update ID o un valor NULL en el caso de un dispositivo que nunca ha aplicado una actualización a través de Device Update. | installedUpdateID{"provider":"contoso","name":"image-update","version":"1.0.0"}" |
Propiedades de dispositivo
El campo deviceProperties contiene la información del fabricante y modelo de un dispositivo.
| Nombre | Schema | Dirección | Descripción |
|---|---|---|---|
| fabricante | string | entre el dispositivo y la nube | Fabricante del dispositivo notificado mediante deviceProperties. Esta propiedad puede leerse en uno de los dos lugares. En primer lugar, la interfaz DeviceUpdateCore intenta leer primero el valor "aduc_manufacturer" del archivo de configuración. Si el valor no figura en el archivo de configuración, se establece de forma predeterminada en un valor que informe del tiempo de compilación de ADUC_DEVICEPROPERTIES_MANUFACTURER. Esta propiedad solo se informa en tiempo de arranque. Valor predeterminado "Contoso". |
| model | string | entre el dispositivo y la nube | Modelo del dispositivo, que se notifica mediante deviceProperties. Esta propiedad puede leerse en uno de los dos lugares en los que, en primer lugar, la interfaz DeviceUpdateCore intenta leer el valor de "aduc_model" del archivo de configuración. Si el valor no figura en el archivo de configuración, se establece de forma predeterminada en un valor que informe del tiempo de compilación de ADUC_DEVICEPROPERTIES_MODEL. Esta propiedad solo se informa en tiempo de arranque. Valor predeterminado "Video". |
| contractModelId | string | entre el dispositivo y la nube | El servicio usa esta propiedad para identificar la versión del modelo base que usa el agente de Device Update para la administración y comunicación con el agente. Valor: "dtmi:azure:iot:deviceUpdateContractModel;3" para dispositivos que usan la versión 1.1.0 del agente de DU. Nota: Los agentes que usan "dtmi:azure:iot:deviceUpdateModel;2" deben notificar el contractModelId como "dtmi:azure:iot:deviceUpdateContractModel;3", ya que deviceUpdateModel;3 se extiende desde deviceUpdateContractModel;3 |
| aduVer | string | entre el dispositivo y la nube | Versión de Device Update Agent que se ejecuta en el dispositivo. Este valor solamente se obtiene de la compilación si ENABLE_ADU_TELEMETRY_REPORTING está establecido en 1 (true) durante el tiempo de compilación. Los clientes pueden desactivar los informes de la versión al establecer el valor en 0 (false). Personalización de las propiedades de Device Update Agent. |
| doVer | string | entre el dispositivo y la nube | Versión del agente de Optimización de distribución que se ejecuta en el dispositivo. Este valor solamente se obtiene de la compilación si ENABLE_ADU_TELEMETRY_REPORTING está establecido en 1 (true) durante el tiempo de compilación. Los clientes pueden desactivar el reporte de la versión al establecer el valor en 0 (false). Personalización de las propiedades del agente de Optimización de distribución. |
| Propiedades de compatibilidad personalizadas | User Defined | entre el dispositivo y la nube | El implementador puede definir otras propiedades de dispositivo que se usarán para la comprobación de compatibilidad al abordar la implementación de actualizaciones. |
El siguiente ejemplo es de un dispositivo gemelo de IoT Hub:
"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
El dispositivo o módulo debe agregar el marcador {"__t": "c"} para indicar que el elemento hace referencia a un componente. Para más información, consulte Convenciones de IoT Plug and Play.
State
El agente de Device Update (DU) notifica el campo Estado después de recibir una acción del servicio de Device Update. El estado se notifica en respuesta a una Acción (consulte la sección Acción para más información) y se envía al agente de Device Update desde el servicio de Device Update. Para más información sobre las solicitudes que fluyen entre el servicio y el agente de Device Update, consulte el flujo de trabajo general.
| Nombre | valor | Descripción |
|---|---|---|
| Inactivo | 0 | El dispositivo está listo para recibir una acción del servicio Device Update. Cuando una actualización se realiza correctamente, el estado vuelve a ser Idle. |
| DeploymentInprogress | 6 | Implementación en curso. |
| Con error | 255 | Se produjo un error durante la actualización. |
| DownloadSucceeded | 2 | Descarga correcta. Este estado solo lo notifican los dispositivos con la versión del agente 0.7.0 o anterior. |
| InstallSucceeded | 4 | Instalación correcta. Este estado solo lo notifican los dispositivos con la versión del agente 0.7.0 o anterior. |
Metadatos de servicio
Los metadatos de servicio contienen campos que los servicios de Device Update utilizan para notificar acciones y datos al agente de Device Update.
| Nombre | Schema | Dirección | Descripción |
|---|---|---|---|
| action | integer | entre la nube y el dispositivo | Entero que se corresponde con una acción que el agente debe realizar. Consulte la sección Acción para obtener más información. |
| updateManifest | string | entre la nube y el dispositivo | Se usa para describir el contenido de una actualización. Se genera a partir del manifiesto de importación. |
| updateManifestSignature | Objeto JSON | entre la nube y el dispositivo | JSON Web Signature (JWS, firma web de JSON) con las JSON Web Keys (claves web de JSON) que se utilizan para comprobar el código fuente. |
| fileUrls | Asignación | entre la nube y el dispositivo | Asignación de FileID a DownloadUrl. Indica al agente qué archivos se van a descargar y el hash que se va a usar para comprobar que los archivos se descargaron correctamente. |
Acción
El campo acción representa las acciones realizadas por el agente de Device Update conforme a las instrucciones del servicio de Device Update. El agente de Device Update notificará un estado para procesar la acción recibida. Para más información sobre las solicitudes que fluyen entre el servicio y el agente de Device Update, consulte el flujo de trabajo general.
| Nombre | valor | Descripción |
|---|---|---|
| applyDeployment | 3 | Aplique la actualización. Indica al dispositivo que aplique la actualización implementada. |
| cancel | 255 | Detenga el procesamiento de la acción actual y vuelva a Idle, o indique a un agente en el estadoFailed que vuelva a Idle. |
| descarga | 0 | Descarga la actualización o el contenido que están publicados y cualquier otro contenido necesario. Esta acción solo se envía a dispositivos con la versión del agente 0.7.0 o anterior. |
| instalar | 1 | Instala el contenido o la actualización. Normalmente, esta acción significa llamar al instalador para el contenido o la actualización. Esta acción solo se envía a dispositivos con la versión del agente 0.7.0 o anterior. |
| apply | 2 | Finaliza la actualización. Indica al sistema que debe reiniciarse, si es necesario. Esta acción solo se envía a dispositivos con la versión del agente 0.7.0 o anterior. |
Interfaz de información del dispositivo
La interfaz de información del dispositivo es un concepto que se utiliza en la arquitectura de IoT Plug and Play. Contiene las propiedades del dispositivo a la nube que proporcionan información sobre el hardware y el sistema operativo del dispositivo. Device Update for IoT Hub usa las propiedades DeviceInformation.manufacturer y DeviceInformation.model para los datos de telemetría y los diagnósticos. Para más información, consulte este ejemplo de la interfaz de información del dispositivo.
Cuando se implementa esta interfaz, el nombre que el modelo espera para el componente es deviceInformation. Información sobre los componentes de Azure IoT Plug and Play
| Nombre | Tipo | Schema | Dirección | Descripción | Ejemplo |
|---|---|---|---|---|---|
| fabricante | Propiedad | string | entre el dispositivo y la nube | Nombre de la compañía del fabricante del dispositivo. Esta propiedad puede ser igual que el nombre del fabricante de equipo original (OEM). | Contoso |
| model | Propiedad | string | entre el dispositivo y la nube | Nombre o identificador del modelo del dispositivo. | Dispositivo de IoT Edge |
| swVersion | Propiedad | string | entre el dispositivo y la nube | Versión del software del dispositivo. El valor de swVersion podría ser la versión del firmware. | 4.15.0-122 |
| osName | Propiedad | string | entre el dispositivo y la nube | Nombre del sistema operativo del dispositivo. | Ubuntu Server 18.04 |
| processorArchitecture | Propiedad | string | entre el dispositivo y la nube | Arquitectura del procesador del dispositivo. | ARM64 |
| processorManufacturer | Propiedad | string | entre el dispositivo y la nube | Nombre del fabricante del procesador del dispositivo. | Microsoft |
| totalStorage | Propiedad | string | entre el dispositivo y la nube | Almacenamiento total en kilobytes disponible en el dispositivo. | 2048 |
| totalMemory | Propiedad | string | entre el dispositivo y la nube | Memoria total en kilobytes disponible en el dispositivo. | 256 |