IoT Plug and Play na Atualização de Dispositivo do Azure para o Hub IoT
A Atualização de Dispositivo para o Hub IoT usa o IoT Plug and Play para descobrir e gerenciar dispositivos com capacidade de atualização over-the-air. Este artigo descreve como o serviço de Atualização de Dispositivo envia e recebe propriedades e mensagens de e para dispositivos usando interfaces IoT Plug and Play.
Para obter mais informações, consulte o Guia do desenvolvedor de dispositivos IoT Plug and Play e Como criar o Device Update Agent.
Modelos de atualização de dispositivo
Os dispositivos inteligentes usam IDs de modelo IoT Plug and Play para anunciar seus recursos para aplicativos IoT do Azure. A Atualização de Dispositivo requer que o dispositivo inteligente IoT Plug and Play anuncie um ID de modelo como parte da conexão do dispositivo. Para obter mais informações, consulte Anúncio de ID do modelo.
A Atualização de Dispositivo tem vários modelos IoT Plug and Play definidos que suportam recursos de Atualização de Dispositivo. O modelo **dtmi:azure:iot:deviceUpdateContractModel;3** de Atualização de Dispositivo suporta a funcionalidade principal de Atualização de Dispositivo e usa a interface principal de Atualização de Dispositivo para enviar ações de atualização e metadados para dispositivos e receber status de atualização de dispositivos.
O outro modelo suportado é **dtmi:azure:iot:deviceUpdateModel;3**o , que estende **deviceUpdateContractModel;3** e também usa interfaces IoT Plug and Play que enviam informações de propriedade do dispositivo e habilitam recursos de diagnóstico. Para essas e outras versões, consulte Modelos de atualização de dispositivo Plug and Play do Azure IoT.
O agente de Atualização de Dispositivo usa **dtmi:azure:iot:deviceUpdateModel;3** que suporta todos os recursos mais recentes na versão 1.1.0 da Atualização de Dispositivo. Este modelo suporta manifesto de importação versão 5.0. Os manifestos mais antigos funcionam com os agentes mais recentes, mas os novos recursos exigem a versão mais recente do manifesto.
Metadados do agente
O agente de Atualização de Dispositivo usa os seguintes campos de metadados do agente para enviar informações aos serviços de Atualização de Dispositivo.
| Nome | Esquema | Direção | Description |
|---|---|---|---|
| deviceProperties | Mapa | Do dispositivo para a nuvem | O conjunto de propriedades que contêm o fabricante, o modelo e outras informações do dispositivo. Consulte Propriedades do dispositivo para obter detalhes. |
| compatPropertyNames | String (separada por vírgula) | Do dispositivo para a nuvem | Até cinco propriedades que são usadas para verificar a compatibilidade do dispositivo para direcionar a implantação da atualização. Exemplo: "compatPropertyNames": "fabricante,modelo" |
| lastInstallResult | Mapa | Do dispositivo para a nuvem | O resultado relatado pelo agente, contendo código de resultado, código de resultado estendido e detalhes do resultado para atualização principal e outras atualizações de etapa. |
| Código de resultados | integer | Do dispositivo para a nuvem | Um código que contém informações sobre o resultado da última ação de atualização. Pode ser preenchido para sucesso ou fracasso. Exemplo: 700 |
| extendedResultCode | integer | Do dispositivo para a nuvem | Um código que contém mais informações sobre o resultado. Pode ser preenchido para sucesso ou fracasso. Exemplo: 0x80004005 |
| resultDetalhes | string | Do dispositivo para a nuvem | Uma cadeia de caracteres de forma livre fornecida pelo usuário para fornecer mais detalhes do resultado. Voltou para o gêmeo sem analisar. |
| stepResultados | map | Do dispositivo para a nuvem | O resultado relatado pelo agente, contendo código de resultado, código de resultado estendido e detalhes do resultado para atualizações de etapa. Exemplo: "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| state | integer | Do dispositivo para a nuvem | Um inteiro que indica o estado atual do agente de Atualização de Dispositivo. Consulte Estado para obter detalhes. |
| fluxo de trabalho | complexo | Do dispositivo para a nuvem | Um conjunto de valores que indicam a implantação na qual o agente está trabalhando no momento, a ID da implantação instalada atualmente e a confirmação de qualquer solicitação de repetição enviada de serviço para agente. O workflow ID relata um "nodeployment" valor quando uma implantação é cancelada. Exemplo: "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"} |
| instaladoUpdateId | string | Do dispositivo para a nuvem | Uma ID da implantação da Atualização de Dispositivo atualmente instalada. Esse valor captura a ID de atualização JSON ou null para um dispositivo que nunca teve uma atualização por meio da Atualização de Dispositivo. Exemplo: "installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}" |
Exemplo de dispositivo gêmeo do 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
O dispositivo ou módulo deve adicionar o {"__t": "c"} marcador para indicar que o elemento se refere a um componente. Para obter mais informações, consulte Convenções IoT Plug and Play.
Propriedades do dispositivo
O campo deviceProperties contém as informações do fabricante e do modelo de um dispositivo.
| Nome | Esquema | Direção | Description |
|---|---|---|---|
| fabricante | string | Do dispositivo para a nuvem | O fabricante do dispositivo, informado através devicePropertiesde .A DeviceUpdateCore interface primeiro tenta ler o aduc_manufacturervalor do arquivo de configuração. Se o valor não for preenchido no arquivo de configuração, a interface assumirá como padrão relatar a definição em tempo de compilação para ADUC_DEVICEPROPERTIES_MANUFACTURER. Esta propriedade é relatada somente no momento da inicialização. Valor padrão: 'Contoso' |
| modelo | string | Do dispositivo para a nuvem | O modelo do dispositivo, relatado através devicePropertiesdo . A DeviceUpdateCore interface primeiro tenta ler o aduc_modelvalor do arquivo de configuração. Se o valor não for preenchido no arquivo de configuração, a interface assumirá como padrão relatar a definição em tempo de compilação para ADUC_DEVICEPROPERTIES_MODEL. Esta propriedade é relatada somente no momento da inicialização. Valor padrão: 'Vídeo' |
| contractModelId | string | Do dispositivo para a nuvem | Propriedade que o serviço usa para identificar a versão do modelo base que o agente de Atualização de Dispositivo está usando para gerenciar e se comunicar com o agente. Valor: dtmi:azure:iot:deviceUpdateContractModel;3 para dispositivos que usam o agente de Atualização de Dispositivo versão 1.1.0. Nota: Os agentes que usam dtmi:azure:iot:deviceUpdateModel;2 devem relatar o contractModelId como dtmi:azure:iot:deviceUpdateContractModel;3, porque deviceUpdateModel;3 é estendido de deviceUpdateContractModel;3. |
| aduVer | string | Do dispositivo para a nuvem | Versão do agente de Atualização de Dispositivo em execução no dispositivo. Esse valor é lido da compilação somente se ENABLE_ADU_TELEMETRY_REPORTING estiver definido como 1 (true) durante o tempo de compilação. Você pode optar por desativar o relatório de versão definindo o valor como 0 (false). Para obter mais informações, consulte Como criar o Device Update Agent. |
| doVer | string | Do dispositivo para a nuvem | Versão do agente de Otimização de Entrega em execução no dispositivo. O valor é lido da compilação somente se ENABLE_ADU_TELEMETRY_REPORTING estiver definido como 1 (true) durante o tempo de compilação. Você pode optar por desativar o relatório de versão definindo o valor como 0 (false). Para obter mais informações, consulte Como personalizar as propriedades do agente de Otimização de Entrega. |
| Propriedades de compatibilidade personalizadas | Definidas pelo utilizador | Do dispositivo para a nuvem | Outras propriedades de dispositivo definidas pelo usuário a serem usadas para a verificação de compatibilidade ao direcionar a implantação da atualização. |
Estado
O campo de estado é o status relatado pelo agente de Atualização de Dispositivo em resposta a uma Ação enviada ao agente de Atualização de Dispositivo do serviço de Atualização de Dispositivo. Para obter mais informações sobre solicitações que fluem entre o serviço de Atualização de Dispositivo e o agente de Atualização de Dispositivo, consulte o fluxo de trabalho do Agente.
| Nome | valor | Description |
|---|---|---|
| Períodos | 0 | O dispositivo está pronto para receber uma ação do serviço de Atualização de Dispositivo. Após uma atualização bem-sucedida, o Idle estado retorna ao estado. |
| ImplantaçãoInprogress | 6 | Uma implantação está em andamento. |
| Com falhas | 255 | Ocorreu uma falha durante a atualização. |
| BaixarBem sucedido | 2 | Ocorreu um download bem-sucedido. Somente dispositivos com agente versão 0.7.0 ou anterior relatam esse status. |
| InstallSuccessful | 4 | Ocorreu uma instalação bem-sucedida. Somente dispositivos com agente versão 0.7.0 ou anterior relatam esse status. |
Ação
O campo de ação representa a ação que o agente de Atualização de Dispositivo deve executar conforme as instruções do serviço de Atualização de Dispositivo. O agente de Atualização de Dispositivo relata um estado para processar a ação que recebe. Para obter mais informações sobre solicitações que fluem entre o serviço de Atualização de Dispositivo e o agente de Atualização de Dispositivo, consulte o fluxo de trabalho do Agente.
| Nome | valor | Description |
|---|---|---|
| applyDeployment | 3 | Aplique a atualização implantada. |
| Cancelar | 255 | Pare de processar a ação atual e volte para Idle, ou diga a um agente no Failed estado para voltar para Idle. |
| download | 0 | Faça o download do conteúdo publicado ou atualize, e qualquer outro conteúdo necessário. Esta ação é enviada apenas para dispositivos com a versão 0.7.0 ou anterior do agente. |
| instalar | 1 | Instale o conteúdo ou atualize, normalmente para chamar o instalador para o conteúdo ou atualização. A Atualização de Dispositivo envia essa ação somente para dispositivos com a versão 0.7.0 ou anterior do agente. |
| apply | 2 | Finalize a atualização reinicializando, se necessário. A Atualização de Dispositivo envia essa ação somente para dispositivos com a versão 0.7.0 ou anterior do agente. |
Metadados do serviço
Os metadados do serviço contêm campos que o serviço de Atualização de Dispositivo usa para comunicar ações e dados ao agente de Atualização de Dispositivo.
| Nome | Esquema | Direção | Description |
|---|---|---|---|
| action | integer | nuvem para dispositivo | Um inteiro que corresponde a uma ação que o agente deve executar. Consulte Ação para obter detalhes. |
| updateManifest | string | nuvem para dispositivo | Descreve o conteúdo de uma atualização. Gerado a partir do manifesto de importação. |
| updateManifestSignature | Objeto JSON | nuvem para dispositivo | Uma assinatura da Web JSON (JWS) com chaves da Web JSON para usar na verificação do código-fonte. |
| fileUrls | Mapa | nuvem para dispositivo | Mapa de FileID até DownloadUrl. Informa ao agente quais arquivos baixar e o hash a ser usado para verificar se os arquivos baixados corretamente. |
Interface de informações do dispositivo
A interface de informações do dispositivo é um conceito usado dentro da arquitetura IoT Plug and Play. A interface contém propriedades de dispositivo para nuvem que fornecem informações sobre o hardware e o sistema operacional do dispositivo. A Atualização de Dispositivo usa as propriedades e DeviceInformation.model para telemetria DeviceInformation.manufacturer e diagnóstico. Para obter um exemplo da interface de informações do dispositivo, consulte https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json.
Quando você implementa essa interface, o nome do componente esperado em seu modelo é deviceInformation. Para obter mais informações, consulte o guia de modelagem IoT Plug and Play.
| Nome | Tipo | Esquema | Direção | Description | Exemplo |
|---|---|---|---|---|---|
| fabricante | Property | string | Do dispositivo para a nuvem | Nome da empresa do fabricante do dispositivo. Fabricante pode ser o mesmo que o nome do fabricante do equipamento original (OEM). | Contoso |
| modelo | Property | string | Do dispositivo para a nuvem | Nome ou ID do modelo do dispositivo. | Dispositivo IoT Edge |
| swVersion | Property | string | Do dispositivo para a nuvem | Versão do software no seu dispositivo. swVersion pode ser a versão do seu firmware. | 4.15.0-122 |
| osName | Property | string | Do dispositivo para a nuvem | Nome do sistema operativo no dispositivo. | Ubuntu Server 18.04 |
| processorArchitecture | Property | string | Do dispositivo para a nuvem | Arquitetura do processador no dispositivo. | ARM64 |
| processadorFabricante | Property | string | Do dispositivo para a nuvem | Nome do fabricante do processador no dispositivo. | Microsoft |
| totalArmazenamento | Property | string | Do dispositivo para a nuvem | Armazenamento total disponível no dispositivo em kilobytes. | 2048 |
| totalMemória | Property | string | Do dispositivo para a nuvem | Total de memória disponível no dispositivo em kilobytes. | 256 |