Atualização de Dispositivo para Hub IoT e IoT Plug and Play
A Atualização de Dispositivo para Hub IoT usa o IoT Plug and Play para descobrir e gerenciar dispositivos com capacidade para atualização remota. O serviço de Atualização de Dispositivo envia e recebe propriedades e mensagens em dispositivos usando interfaces IoT Plug and Play.
Para mais informações:
- Entenda o cliente do dispositivo IoT Plug and Play.
- Veja como o agente de Atualização de Dispositivo é implementado.
Modelos de Atualização de Dispositivo
A ID do modelo é como os dispositivos inteligentes anunciam seus recursos para os aplicativos IoT do Azure com o IoT Plug and Play. Para saber mais sobre como criar dispositivos inteligentes para anunciar seus recursos aos aplicativos IoT do Azure, visite o Guia do desenvolvedor de dispositivos do IoT Plug and Play.
A Atualização de Dispositivo para Hub IoT exige que o dispositivo inteligente de IoT Plug and Play anuncie uma ID de modelo com parte da conexão do dispositivo. Saiba como anunciar uma ID de modelo.
A Atualização de Dispositivo tem vários modelos PnP definidos que dão suporte a recursos de DU. O modelo de Atualização de Dispositivo, "dtmi:azure:iot:deviceUpdateContractModel;3", dá suporte à funcionalidade principal e usa a interface principal de atualização do dispositivo para enviar ações de atualização e metadados para dispositivos e receber o status de atualização de dispositivos.
O outro modelo com suporte é dtmi:azure:iot:deviceUpdateModel;3, que estende deviceUpdateContractModel;3 e também usa outras interfaces PnP que enviam propriedades e informações do dispositivo e habilitam recursos de diagnóstico. Saiba mais sobre as [versões de interfaces e modelos de Atualização de Dispositivo] (https://github.com/Azure/iot-plugandplay-models/tree/main/dtmi/azure/iot).
O agente de Atualização de Dispositivo usa o dtmi:azure:iot:deviceUpdateModel;3, que dá suporte a todos os recursos mais recentes na versão 1.1.0. Este modelo dá suporte à versão do manifesto V5. Manifestos mais antigos funcionarão com os agentes mais recentes, mas novos recursos exigem o uso da versão mais recente do manifesto.
Metadados do agente
O agente de Atualização de Dispositivo usa campos de metadados do agente para enviar informações aos serviços de Atualização de Dispositivo.
| Nome | Esquema | Direção | Descrição | Exemplo |
|---|---|---|---|---|
| deviceProperties | Map | Dispositivo para nuvem | O conjunto de propriedades que contêm o fabricante, o modelo e outras informações do dispositivo. | Consulte a seção Propriedades do dispositivo para obter detalhes. |
| compatPropertyNames | Cadeia de caracteres (separada por vírgula) | Dispositivo para nuvem | O dispositivo relatou propriedades que são usadas para verificar a compatibilidade do dispositivo para direcionar a implantação de atualização. Limitado a cinco propriedades de dispositivo. | "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Map | Dispositivo para nuvem | O resultado relatado pelo agente. Ele contém código de resultado, código de resultado estendido e detalhes de resultado para atualização principal e outras atualizações de etapa. | |
| resultCode | Número inteiro | Dispositivo para nuvem | Um código que contém informações sobre o resultado da última ação de atualização. Pode ser preenchido com êxito ou falha. | 700 |
| extendedResultCode | Número inteiro | Dispositivo para nuvem | Um código que contém informações adicionais sobre o resultado. Pode ser preenchido com êxito ou falha. | 0x80004005 |
| resultDetails | string | Dispositivo para nuvem | Cadeia de caracteres de forma livre definida pelo cliente para fornecer detalhes de resultado adicionais. Devolvido para o gêmeo sem análise | |
| stepResults | mapa | Dispositivo para nuvem | O resultado relatado pelo agente que contém o código de resultado, código de resultado estendido e detalhes de resultado para atualizações de etapa. | "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| state | Número inteiro | Dispositivo para nuvem | Um inteiro que indica o estado atual do agente de Atualização de Dispositivo. | Confira a seção de Status para obter detalhes. |
| fluxo de trabalho | complex | Dispositivo para nuvem | Um conjunto de valores que indica em qual implantação o agente está trabalhando no momento, a ID da implantação atual e a confirmação de qualquer solicitação de repetição enviada do serviço para o agente. Observe que a ID do fluxo de trabalho relata um valor de "nodeployment" depois que a implantação é cancelada. | "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"} |
| installedUpdateId | string | Dispositivo para nuvem | Uma ID da atualização instalada atualmente (por meio da Atualização de Dispositivo). Esse valor é uma cadeia de caracteres capturando a ID de Atualização JSON ou nula para um dispositivo que nunca fez uma atualização por meio da Atualização de Dispositivo. | installedUpdateID{"provider":"contoso","name":"image-update","version":"1.0.0"}" |
Propriedades do dispositivo
O campo deviceProperties contém as informações do fabricante e do modelo para um dispositivo.
| Nome | Esquema | Direção | Descrição |
|---|---|---|---|
| fabricante | string | Dispositivo para nuvem | O fabricante do dispositivo, relatado por meio do deviceProperties. Essa propriedade é lida em um dos dois locais. Primeiro, a interface DeviceUpdateCore tenta ler o valor 'aduc_manufacturer' do arquivo de configuração. Se o valor não for preenchido no arquivo de configuração, é padrão relatar a definição de tempo de compilação para ADUC_DEVICEPROPERTIES_MANUFACTURER. Essa propriedade é relatada somente no momento da inicialização. Valor padrão: 'Contoso'. |
| modelo | string | Dispositivo para nuvem | O modelo do dispositivo, relatado por meio de deviceProperties. Essa propriedade é lida em um dos dois locais. Primeiro, a interface DeviceUpdateCore tenta ler o valor 'aduc_model' do arquivo de configuração. Se o valor não for preenchido no arquivo de configuração, é padrão relatar a definição de tempo de compilação para ADUC_DEVICEPROPERTIES_MODEL. Essa propriedade é relatada somente no momento da inicialização. Valor padrão: 'Video' |
| contractModelId | string | Dispositivo para nuvem | Essa propriedade é usada pelo serviço para identificar a versão do modelo base que está sendo usada pelo agente de Atualização de Dispositivo para gerenciar e se comunicar com o agente. Valor: "dtmi:azure:iot:deviceUpdateContractModel; 3" para dispositivos que usam o agente de DU versão 1.1.0. Observação: agentes que usam o "dtmi:azure:iot:deviceUpdateModel;2" deve relatar contractModelId como "dtmi:azure:iot:deviceUpdateContractModel;3" já que deviceUpdateModel;3 é estendido de deviceUpdateContractModel;3 |
| aduVer | string | Dispositivo para 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 for definido como 1 (true) durante o tempo de compilação. Os clientes podem optar por recusar a emissão de relatórios de versão definindo o valor como 0 (falso). Como personalizar as propriedades do agente de Atualização de Dispositivo. |
| doVer | string | Dispositivo para nuvem | Versão do agente Otimização de Entrega em execução no dispositivo. O valor é lido da compilação somente se ENABLE_ADU_TELEMETRY_REPORTING for definido como 1 (true) durante o tempo de compilação. Os clientes podem optar por recusar a emissão de relatórios de versão definindo o valor como 0 (falso). Como personalizar as propriedades do agente de Otimização de Entrega. |
| Propriedades de compatibilidade personalizadas | User Defined | Dispositivo para nuvem | O implementador pode definir outras propriedades de dispositivo a serem usadas para a verificação de compatibilidade ao direcionar a implantação de atualização. |
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\"}"
},
Observação
O dispositivo ou módulo devem adicionar o{"__t": "c"}marcador para indicar de que elemento refere-se a um componente. Para obter mais informações, confira as Convenções de IoT Plug and Play.
Estado
O campo Status é o status relatado pelo agente de DU (Atualização de Dispositivo) após receber uma ação do serviço de Atualização de Dispositivo. O Status é relatado em resposta a uma Ação (confira a seção Ação para obter detalhes) enviada para o 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, confira o fluxo de trabalho de visão geral.
| Nome | Valor | Descrição |
|---|---|---|
| Ocioso | 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 estado é retornado para o Idle. |
| DeploymentInprogress | 6 | Uma implantação está em andamento. |
| Com falha | 255 | Ocorreu uma falha durante a atualização. |
| DownloadSucceeded | 2 | Um download bem-sucedido. Esse status só é relatado por dispositivos com a versão do agente 0.7.0 ou anteriores. |
| InstallSucceeded | 4 | Uma instalação bem-sucedida. Esse status só é relatado por dispositivos com a versão do agente 0.7.0 ou anteriores. |
Metadados de serviço
Os metadados de serviço contêm campos que os serviços de Atualização de Dispositivo usam para comunicar ações e dados ao agente de Atualização de Dispositivo.
| Nome | Esquema | Direção | Descrição |
|---|---|---|---|
| ação | Número inteiro | Nuvem para o dispositivo | Um inteiro que corresponde a uma ação que o agente deve executar. Consulte a seção Ação para obter detalhes. |
| updateManifest | string | Nuvem para o dispositivo | Usado para descrever o conteúdo de uma atualização. Gerado do Manifesto de Importação. |
| updateManifestSignature | Objeto JSON | Nuvem para o dispositivo | Uma JWS (Assinatura Web JSON) com Chaves Web JSON usadas para verificação de origem. |
| fileUrls | Map | Nuvem para o dispositivo | Mapa de FileID para DownloadUrl. Indica ao agente quais os arquivos a transferir e o hash a utilizar para verificar se os arquivos foram transferidos corretamente. |
Ação
O campo de ação representa as ações realizadas pelo agente de Atualização de Dispositivo, conforme instruído pelo serviço de Atualização de Dispositivo. O agente de Atualização de Dispositivo relatará um status para processar a ação recebida. 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, confira o fluxo de trabalho de visão geral.
| Nome | Valor | Descrição |
|---|---|---|
| ApplyDeployment | 3 | Aplicar a atualização. Sinaliza para o dispositivo aplicar a atualização implantada |
| cancel | 255 | Pare de processar a ação atual e volte para Idle, ou diga a um agente no status Failed para voltar para Idle. |
| download | 0 | Baixar ou atualizar conteúdo publicado ou qualquer outro conteúdo necessário. Essa ação só é enviada para dispositivos com a versão do agente 0.7.0 ou anterior. |
| instalar | 1 | Instale o conteúdo ou atualize. Normalmente, essa ação significa chamar o instalador para o conteúdo ou atualização. Essa ação só é enviada para dispositivos com a versão do agente 0.7.0 ou anterior. |
| aplicar | 2 | Finalize a atualização. Ele sinaliza o sistema para reinicializar, se necessário. Essa ação só é enviada para dispositivos com a versão do agente 0.7.0 ou anterior. |
Interface de informações do dispositivo
A interface de informações do dispositivo é um conceito usado na arquitetura de IoT Plug and Play. Ela 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 para Hub IoT usa as propriedades DeviceInformation.manufacturer e DeviceInformation.model para telemetria e diagnóstico. Para saber mais, confira este exemplo da interface de informações do dispositivo.
O nome do componente esperado em seu modelo é deviceInformation quando essa interface é implementada. Aprenda sobre os componentes IoT Plug and Play do Azure
| Nome | Tipo | Esquema | Direção | Descrição | Exemplo |
|---|---|---|---|---|---|
| fabricante | Propriedade | string | Dispositivo para nuvem | Nome da empresa do fabricante do dispositivo. Essa propriedade pode ser o mesma que o nome do OEM (fabricante original de equipamentos). | Contoso |
| modelo | Propriedade | string | Dispositivo para nuvem | Nome ou ID do modelo de dispositivo. | Dispositivo do IoT Edge |
| swVersion | Propriedade | string | Dispositivo para nuvem | Versão do software em seu dispositivo. swVersion pode ser a versão do firmware. | 4.15.0-122 |
| osName | Propriedade | string | Dispositivo para nuvem | O nome do sistema operacional no dispositivo. | Ubuntu Server 18.04 |
| processorArchitecture | Propriedade | string | Dispositivo para nuvem | Arquitetura do processador no dispositivo. | ARM64 |
| processorManufacturer | Propriedade | string | Dispositivo para nuvem | Nome do fabricante do processador no dispositivo. | Microsoft |
| totalStorage | Propriedade | string | Dispositivo para nuvem | Total de armazenamento disponível no dispositivo, em kilobytes. | 2.048 |
| totalMemory | Propriedade | string | Dispositivo para nuvem | Memória total disponível no dispositivo, em kilobytes. | 256 |