IoT Plug and Play en Azure Device Update for IoT Hub
Device Update para IoT Hub utiliza IoT Plug and Play para detectar y administrar dispositivos que admiten actualizaciones de forma inalámbrica. En este artículo se describe cómo el servicio Device Update envía y recibe propiedades y mensajes hacia y desde dispositivos mediante interfaces de IoT Plug and Play.
Para obtener más información, consulte la Guía para desarrolladores de dispositivos de IoT Plug and Play y Cómo compilar el agente de Device Update.
Modelos de Device Update
Los dispositivos inteligentes usan identificadores de modelo de IoT Plug and Play para anunciar sus funcionalidades a las aplicaciones de Azure IoT. Device Update necesita que el Smart Device de IoT Plug and Play anuncie un identificador de modelo como parte de la conexión del dispositivo. Para obtener más información, consulte anuncio de Id. de modelo.
Device Update tiene varios modelos de IoT Plug and Play definidos que admiten características de Device Update. El modelo de Device Update **dtmi:azure:iot:deviceUpdateContractModel;3** admite la funcionalidad principal de Device Update y usa la interfaz principal de Device Update para enviar acciones y metadatos de actualización a los dispositivos y recibir el estado de actualización de los dispositivos.
El otro modelo compatible es **dtmi:azure:iot:deviceUpdateModel;3**, que amplía **deviceUpdateContractModel;3** y también usa interfaces de IoT Plug and Play que envían información de propiedades del dispositivo y habilitan las características de diagnóstico. Para estas y otras versiones, consulte Modelos de Device Update de Azure IoT Plug and Play.
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 de Device Update . Este modelo admite la versión 5.0 del modelo de importación. Los manifiestos más antiguos funcionan con los agentes más recientes, pero las nuevas características requieren la versión más reciente del manifiesto.
Metadatos del agente
El agente de Device Update usa los siguientes campos de metadatos del agente para enviar información a los servicios de Device Update.
| Nombre | Schema | Dirección | Descripción |
|---|---|---|---|
| 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 Propiedades del dispositivo para obtener más información. |
| compatPropertyNames | Cadena (separada por comas) | entre el dispositivo y la nube | Hasta cinco propiedades que se usan para comprobar la compatibilidad del dispositivo con el fin de establecer como destino la implementación de actualizaciones. Ejemplo: "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Asignación | entre el dispositivo y la nube | El resultado notificado por el agente, que contiene el código de resultado, el código de resultado extendido y los detalles del resultado de la actualización principal y otras actualizaciones de 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. Ejemplo: 700 |
| extendedResultCode | integer | entre el dispositivo y la nube | Código que contiene más información sobre el resultado. Se puede especificar para indicar si la operación se ha realizado correcta o incorrectamente. Ejemplo: 0x80004005 |
| resultDetails | string | entre el dispositivo y la nube | Cadena de forma libre proporcionada por el usuario para proporcionar más detalles de los resultados. 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 de pasos. Ejemplo: "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| estado | integer | entre el dispositivo y la nube | Entero que indica el estado actual del agente de Device Update. Consulte Estado para obtener más información. |
| flujo de trabajo | complejas | entre el dispositivo y la nube | Conjunto de valores que indican la implementación en la que el agente está trabajando actualmente, el identificador de la implementación instalada actualmente y la confirmación de cualquier solicitud de reintento enviada desde el servicio al agente. El id. de workflow notifica un valor de "nodeployment" una vez que se cancela una implementación. Ejemplo: "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 implementación de Device Update instalada actualmente. Este valor captura el id. de actualización JSON o null para un dispositivo que nunca tuvo una actualización a través de Device Update. Ejemplo: "installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}" |
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.
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.La interfaz de DeviceUpdateCore primero intenta leer el valor de aduc_manufacturer del archivo de configuración. Si el valor no se rellena en el archivo de configuración, la interfaz informa de forma predeterminada la definición en tiempo de compilación para 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. La interfaz de DeviceUpdateCore primero intenta leer el valor de aduc_model del archivo de configuración. Si el valor no se rellena en el archivo de configuración, la interfaz informa de forma predeterminada la definición en tiempo de compilación para ADUC_DEVICEPROPERTIES_MODEL. Esta propiedad solo se informa en tiempo de arranque. Valor predeterminado "Video". |
| contractModelId | string | entre el dispositivo y la nube | Propiedad que usa el servicio para identificar la versión del modelo base que el agente de Device Update usa para administrar y comunicarse con el agente. Valor: dtmi:azure:iot:deviceUpdateContractModel;3 para dispositivos que usan la versión 1.1.0 del agente de Device Update. Nota: los agentes de 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 se lee de la compilación solo si ENABLE_ADU_TELEMETRY_REPORTING está establecido en 1 (true) durante el tiempo de compilación. Puede optar por no participar en los informes de versiones estableciendo el valor en 0 (false). Para obtener más información, consulte Cómo compilar el agente de Device Update. |
| doVer | string | entre el dispositivo y la nube | Versión del agente de Optimización de distribución que se ejecuta en el dispositivo. El valor se lee de la compilación solo si ENABLE_ADU_TELEMETRY_REPORTING está establecido en 1 (true) durante el tiempo de compilación. Puede optar por no participar en los informes de versiones estableciendo el valor en 0 (false). Para obtener más información, consulte Personalización de las propiedades del agente de optimización de distribución. |
| Propiedades de compatibilidad personalizadas | Definidas por el usuario | entre el dispositivo y la nube | Otras propiedades de dispositivo definidas por el usuario que se usarán para la comprobación de compatibilidad al dirigirse a la implementación de actualizaciones. |
Estado
El estado es el estado notificado por el agente de Device Update en respuesta a una Acción enviada al agente de Device Update desde el servicio Device Update. Para obtener más información sobre las solicitudes que fluyen entre el servicio Device Update y el agente de Device Update, consulte el Flujo de trabajo del agente.
| NOMBRE | valor | Descripción |
|---|---|---|
| Inactivo | 0 | El dispositivo está listo para recibir una acción del servicio Device Update. Después de una actualización correcta, el estado vuelve al estado Idle. |
| DeploymentInprogress | 6 | Implementación en curso. |
| Con error | 255 | Se produjo un error durante la actualización. |
| DownloadSucceeded | 2 | Se ha producido una descarga correcta. Solo los dispositivos con la versión del agente 0.7.0 o versiones anteriores notifican este estado. |
| InstallSucceeded | 4 | Se ha producido una instalación correcta. Solo los dispositivos con la versión del agente 0.7.0 o versiones anteriores notifican este estado. |
Action
La acción representa la acción que debe realizar el agente de Device Update según lo indicado por el servicio de Device Update. El agente de Device Update informa de un estado para procesar la acción que recibe. Para obtener más información sobre las solicitudes que fluyen entre el servicio Device Update y el agente de Device Update, consulte el Flujo de trabajo del agente.
| NOMBRE | valor | Descripción |
|---|---|---|
| applyDeployment | 3 | 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 | Descargue el contenido publicado o la actualización, y cualquier otro contenido necesario. Esta acción solo se envía a dispositivos con la versión del agente 0.7.0 o una versión anterior. |
| install | 1 | Instale el contenido o la actualización, normalmente para llamar al instalador para el contenido o la actualización. Device Update envía esta acción solo a dispositivos con la versión del agente 0.7.0 o una versión anterior. |
| apply | 2 | Finalice la actualización reiniciando si es necesario. Device Update envía esta acción solo a dispositivos con la versión del agente 0.7.0 o una versión anterior. |
Metadatos de servicio
Los metadatos del servicio contienen campos que el servicio Device Update usa para comunicar 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 Acción para obtener más información. |
| updateManifest | string | entre la nube y el dispositivo | Describe el contenido de una actualización. Se genera a partir del manifiesto de importación. |
| updateManifestSignature | Objeto JSON | entre la nube y el dispositivo | Una firma web JSON (JWS) con claves web JSON que se usarán para la comprobación de origen. |
| 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. |
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. La interfaz contiene propiedades de dispositivo a la nube que proporcionan información sobre el hardware del dispositivo y el sistema operativo. Device Update usa las propiedades DeviceInformation.manufacturer y DeviceInformation.model para los datos de telemetría y los diagnósticos. Para obtener un ejemplo de la interfaz de información del dispositivo, vea https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json.
Al implementar esta interfaz, el nombre del componente esperado en el modelo es deviceInformation. Para obtener más información, consulte la Guía de modelado de 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. El fabricante podría ser el mismo 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 |