Implementação de dispositivo e melhores práticas para o IoT Central

  • Artigo

Este artigo fornece informações sobre como implementar dispositivos que se conectam ao seu Aplicativo IoT Central. Ele também inclui melhores práticas. Para saber mais sobre o processo de conexão geral, confira Conectar um dispositivo.

Para obter amostra de código de implementação, consulte Tutorial: Criar e conectar um aplicativo cliente ao seu Aplicativo do Azure IoT Central.

Implementar o dispositivo

Os dispositivos que se conectam ao IoT Central devem seguir as convenções do IoT Plug and Play. Uma dessas convenções é que um dispositivo precisa enviar a ID de modelo do dispositivo que ele implementa quando se conecta. A ID do modelo permite que o Aplicativo IoT Central associe o dispositivo ao modelo de dispositivo correto.

Um modelo de dispositivo IoT Central inclui um modelo que especifica os comportamentos que um dispositivo desse tipo deve implementar. Os comportamentos incluem telemetria, propriedades e comandos.

Cada modelo tem um DTMI (identificador de modelo gêmeo digital) exclusivo, como dtmi:com:example:Thermostat;1. Quando um dispositivo se conecta ao IoT Central, ele envia o DTMI do modelo que ele implementa. O IoT Central pode associar o modelo de dispositivo correto ao dispositivo.

O IoT Plug and Play define um conjunto de convenções que um dispositivo precisa seguir ao implementar um modelo DTDL (Linguagem de Definição de Gêmeo Digital).

Os SDKs do dispositivo IoT do Azure incluem suporte para as convenções do IoT Plug and Play.

Modelo do dispositivo

Um modelo de dispositivo é definido usando a linguagem de modelagem DTDL V2. Essa linguagem permite que você defina:

  • A telemetria enviada pelo dispositivo. A definição inclui o nome e o tipo de dados da telemetria. Por exemplo, um dispositivo envia a telemetria de temperatura como um double.
  • As propriedades que o dispositivo relata ao IoT Central. Uma definição de propriedade inclui o nome e tipo de dados dela. Por exemplo, um dispositivo relata o estado de uma válvula como um booliano.
  • As propriedades que o dispositivo pode receber do IoT Central. Opcionalmente, você pode marcar uma propriedade como gravável. Por exemplo, IoT Central envia uma temperatura de destino como um double para um dispositivo.
  • Os comandos aos quais um dispositivo responde. A definição inclui o nome do comando e os nomes e tipos de dados de parâmetros. Por exemplo, um dispositivo responde a um comando de reinicialização que especifica o número de segundos de espera antes da reinicialização.

Observação

O IoT Central define algumas extensões para a linguagem DTDL v2. Para obter mais informações, confira Extensão do IoT Central.

Um modelo de DTDL pode ser um modelo com nenhum componente ou vários componentes:

  • Modelo sem componentes: um modelo simples não usa componentes inseridos nem em cascata. Toda a telemetria, propriedades e comandos são definidos como um componente raiz. Para obter um exemplo, confira o modelo Termostato.
  • Modelo com vários componentes. Um modelo mais complexo que inclui dois ou mais componentes. Esses componentes incluem um componente raiz e um ou mais componentes aninhados. Para obter um exemplo, confira o modelo Controlador de Temperatura.

Dica

Você pode importar e exportar um modelo de dispositivo completo ou uma interface individual de um modelo de dispositivo IoT Central como um arquivo DTDL v2.

Para saber mais sobre os modelos de dispositivo, confira o Guia de modelagem do IoT Plug and Play

Convenções

Um dispositivo deve seguir as convenções de IoT Plug and Play quando troca dados com o IoT Central. As convenções incluem:

  • Enviar o DTMI quando ele se conectar ao IoT Central.
  • Enviar os metadados e o conteúdo JSON formatado corretamente para o IoT Central.
  • Responder corretamente a propriedades e comandos graváveis do IoT Central.
  • Seguir as convenções de nomenclatura para comandos de componente.

Observação

Atualmente, o IoT Central não dá suporte total aos tipos de dados Matriz e Geoespacial da DTDL.

Para saber mais sobre as convenções do IoT Plug and Play, confira Convenções do IoT Plug and Play.

Para saber mais sobre o formato das mensagens JSON que um dispositivo troca com o IoT Central, confira Telemetria, propriedade e conteúdos de comando.

SDKs de dispositivo

Use um dos SDKs do dispositivo IoT do Azure para implementar o comportamento de seu dispositivo. O código deve:

  • Registrar o dispositivo com o DPS e usar as informações do DPS para se conectar ao Hub IoT interno em seu aplicativo do IoT Central.
  • Comunicar o DTMI do modelo implementado pelo dispositivo.
  • Enviar a telemetria no formato especificado pelo modelo de dispositivo. O IoT Central usa o modelo no modelo de dispositivo para determinar como usar a telemetria para visualizações e análises.
  • Sincronizar valores de propriedade entre o dispositivo e o IoT Central. O modelo especifica os nomes de propriedade e os tipos de dados para que o IoT Central possa exibir as informações.
  • Implementar manipuladores de comandos para os comandos especificados no modelo. O modelo especifica os nomes de comando e parâmetros que o dispositivo deve usar.

Para obter mais informações sobre a função de modelos de dispositivo, confira O que são modelos de dispositivo?.

A tabela a seguir resume como os recursos do dispositivo Azure IoT Central são mapeados para os recursos do Hub IoT:

Azure IoT Central Hub IoT do Azure
Telemetria Mensagens de dispositivo para nuvem
Comandos offline Mensagens de nuvem para dispositivo
Propriedade Propriedades relatadas do dispositivo gêmeo
Propriedade (gravável) Propriedades desejadas e relatadas do dispositivo gêmeo
Comando Métodos diretos

Protocolos de comunicação

Os protocolos de comunicação que um dispositivo pode usar para se conectar ao IoT Central incluem MQTT, AMQP e HTTPS. Internamente, o IoT Central usa um hub IoT para habilitar a conectividade do dispositivo. Para obter mais informações sobre os protocolos de comunicação a que o Hub IoT dá suporte para conectividade de dispositivo, confira Escolher um protocolo de comunicação.

Se o dispositivo não puder usar nenhum dos protocolos compatíveis, use o Azure IoT Edge para fazer a conversão de protocolo. O IoT Edge é compatível com outros cenários de inteligência na borda para transferir o processamento o aplicativo Azure IoT Central.

Carimbos de data/hora de telemetria

Por padrão, o IoT Central usa o tempo enfileirado da mensagem quando exibe telemetria em painéis e gráficos. O tempo enfileirado da mensagem é definido internamente quando o IoT Central recebe a mensagem do dispositivo.

Um dispositivo pode definir a propriedade iothub-creation-time-utc quando cria uma mensagem para enviar ao IoT Central. Se essa propriedade estiver presente, o IoT Central vai usá-la quando exibir telemetria em painéis e gráficos.

Você pode exportar o tempo enfileirado e a propriedade iothub-creation-time-utc ao exportar a telemetria do aplicativo IoT Central.

Para saber mais sobre as propriedades de mensagem, confira Propriedades do sistema de mensagens do Hub IoT do dispositivo para nuvem.

Práticas recomendadas

Essas recomendações mostram como implementar dispositivos para aproveitar os recursos integrados de alta disponibilidade, recuperação de desastre e escala automática no IoT Central.

Tratar falhas de conexão

Para fins de escala ou recuperação de desastre, o IoT Central pode atualizar os hubs IoT subjacentes. Para manter a conectividade, o código do dispositivo deve tratar erros de conexão específicos, estabelecendo uma conexão com o novo ponto de extremidade do hub IoT.

Se o dispositivo receber qualquer um dos erros a seguir ao se conectar, ele deverá ser reprovisionado com o DPS para obter uma nova cadeia de conexão. Esses erros significam que a cadeia de conexão não é mais válida:

  • Ponto de extremidade do Hub IoT inalcançável.
  • Token de segurança expirado.
  • Dispositivo desabilitado no Hub IoT.

Se o dispositivo obtiver qualquer um dos erros a seguir ao se conectar, ele deverá usar uma estratégia de retirada para tentar a conexão novamente. Esses erros significam que a cadeia de conexão ainda é válida, mas condições transitórias estão impedindo o dispositivo de se conectar:

  • Dispositivo bloqueado pelo operador.
  • Erro interno 500 do serviço.

Para saber mais sobre os códigos de erro do dispositivo, confira Solução de problemas de conexões de dispositivos.

Para saber mais sobre como implementar reconexões automáticas, confira Gerenciar reconexões de dispositivo para criar aplicativos resilientes.

Funcionalidades de failover de teste

A CLI do Azure permite testar as funcionalidades de failover do código do dispositivo. O comando da CLI funciona alternando temporariamente um registro de dispositivo para um hub IoT interno diferente. Para verificar se o failover do dispositivo funcionou, verifique se o dispositivo ainda envia telemetria e responde a comandos.

Para executar o teste de failover para o dispositivo, execute o seguinte comando:

az iot central device manual-failover \
    --app-id {Application ID of your IoT Central application} \
    --device-id {Device ID of the device you're testing} \
    --ttl-minutes {How to wait before moving the device back to it's original IoT hub}

Dica

Para encontrar a ID do Aplicativo, acesse Aplicativo > Gerenciamento no seu aplicativo do IoT Central.

Se o comando for bem-sucedido, você verá uma saída parecida com o seguinte exemplo:

Command group 'iot central device' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
{
  "hubIdentifier": "6bd4...bafa",
  "message": "Success! This device is now being failed over. You can check your device'’'s status using 'iot central device registration-info' command. The device will revert to its original hub at Tue, 18 May 2021 11:03:45 GMT. You can choose to failback earlier using device-manual-failback command. Learn more: https://aka.ms/iotc-device-test"
}

Para saber mais sobre o comando da CLI, confira az iot central device manual-failover.

Agora você pode verificar se a telemetria do dispositivo ainda está chegando ao seu aplicativo do IoT Central.

Dica

Para ver o código do dispositivo de exemplo que lida com failovers em várias linguagens de programação, confira Clientes de alta disponibilidade do IoT Central.

Próximas etapas

Sugestão de próximas etapas: