Definir um novo tipo de dispositivo IoT em seu aplicativo do Azure IoT Central

Um modelo de dispositivo é um blueprint que define as características e os comportamentos de um tipo de dispositivo que se conecta a um aplicativo Azure IoT Central.

Este artigo descreve como criar um modelo de dispositivo no IoT Central. Por exemplo, você pode criar um modelo de dispositivo para um sensor que envia telemetria, como temperatura, e propriedades, como local. Nesse modelo de dispositivo, um operador pode criar e conectar dispositivos reais.

A seguinte captura de tela mostra um exemplo de modelo de dispositivo:

Captura de tela que mostra um modelo de dispositivo.

O modelo de dispositivo inclui as seguintes seções:

  • Modelo – use o modelo para definir como seu dispositivo interage com o aplicativo IoT Central. Cada modelo tem uma ID de modelo exclusiva e define os recursos do dispositivo. Os recursos são agrupados em interfaces. As interfaces permitem que você reutilize componentes entre modelos ou use a herança para estender o conjunto de recursos.
  • Propriedades de nuvem – use as propriedades de nuvem para definir as informações que o aplicativo do IoT Central armazena sobre seus dispositivos. Por exemplo, uma propriedade de nuvem pode registrar a data da última manutenção de um dispositivo.
  • Exibições – use as exibições para visualizar os dados do dispositivo e formulários para gerenciar e controlar um dispositivo.

Para saber mais, confira O que são modelos de dispositivo?.

Para saber como gerenciar modelos de dispositivo usando a API REST do IoT Central, consulte Como usar a API REST do IoT Central para gerenciar modelos de dispositivo.

Criar um modelo de dispositivo

Você tem várias opções para criar modelos de dispositivo:

  • Crie o modelo de dispositivo na GUI de IoT Central.
  • Importe um modelo de dispositivo do catálogo de dispositivos Certificado para IoT do Azure. Como opção, personalize o modelo de dispositivo de acordo com seus requisitos no IoT Central.
  • Quando o dispositivo se conecta ao IoT Central, faça ele enviar o ID do modelo que ele implementa. O IoT Central usa a ID do modelo para recuperar o modelo do repositório de modelos e para criar um modelo de dispositivo. Adicione quaisquer propriedades de nuvem e exibições que seu aplicativo IoT Central precisa ao modelo de dispositivo.
  • Quando o dispositivo se conecta a IoT Central, permita que o IoT Central gere automaticamente uma definição de modelo de dispositivo a partir dos dados enviados pelo dispositivo.
  • Crie um modelo de dispositivo usando o DTDL (Linguagem de Definição de Gêmeos Digitais) V2. Importe manualmente o modelo do dispositivo em seu aplicativo de IoT Central. Em seguida, adicione as propriedades da nuvem e visualize as necessidades do seu aplicativo IoT Central.
  • Você também pode adicionar modelos de dispositivo a um aplicativo IoT Central usando a API REST ou a CLI.

Observação

Em cada caso, o código do dispositivo deve implementar os recursos definidos no modelo. A implementação do código do dispositivo não é afetada pelas seções de propriedades e visualizações da nuvem do modelo de dispositivo.

Esta seção mostra como importar um modelo de dispositivo do catálogo e como personalizá-lo usando a GUI de IoT Central. Este exemplo usa o modelo de dispositivo ESP32-Azure IoT Kit do catálogo de dispositivos:

  1. Para adicionar um novo modelo de dispositivo, selecione + Novo na página Modelos de dispositivo.
  2. Na página Selecionar tipo, role-a para baixo até encontrar o bloco ESP32-Azure IoT Kit na seção Usar um modelo de dispositivo pré-configurado.
  3. Selecione o bloco ESP32-Azure IoT Kit e, em seguida, Avançar: Análise.
  4. Na página Examinar, selecione Criar. O nome do modelo criado é Controlador de Sensor. O modelo inclui componentes como Controlador de Sensor, SensorTemp e Interface de Informações do Dispositivo. Os componentes definem as funcionalidades de um dispositivo ESP32. Os recursos incluem a telemetria, propriedades e comandos.

Captura de tela que mostra o Modelo de dispositivo do controlador de sensor.

Gerar automaticamente um modelo de dispositivo

Você também pode criar automaticamente um modelo de dispositivo a partir de um dispositivo conectado que ainda não foi atribuído a um modelo de dispositivo. A IoT Central usa os valores de telemetria e propriedade que o dispositivo envia para inferir um modelo de dispositivo.

Observação

Atualmente, essa versão prévia do recurso não pode usar telemetria e propriedades de componentes. Ele só pode gerar recursos de telemetria e propriedades raiz.

As seguintes etapas mostram como usar estes comandos:

  1. Conecte seu dispositivo para IoT Central e comece a enviar os dados. Ao ver os dados na exibição Dados brutos, selecione Criar modelo automaticamente no menu suspenso Gerenciar modelo:

    Captura de tela que mostra os dados brutos do dispositivo não atribuído.

  2. Na página Visualização de dados, faça as alterações necessárias nos dados brutos e selecione Criar modelo:

    Captura de tela que mostra a alteração da visualização de dados que permite editar dados que a IoT Central usa para gerar o modelo de dispositivo.

  3. A IoT Central gera um modelo com base no formato de dados mostrado na página Visualização de dados e atribui o dispositivo a ele. Você pode fazer alterações adicionais no modelo de dispositivo, como renomeá-lo ou adicionar recursos, na página Modelos de dispositivo:

    Captura de tela que mostra como renomear o modelo de dispositivo gerado automaticamente.

Gerenciar um modelo de dispositivo

Você pode renomear ou excluir um modelo na página de editor do modelo.

Após definir o modelo, você poderá publicá-lo. Até que o modelo seja publicado, você não pode conectar um dispositivo a ele, e ele não aparece na página Dispositivos.

Para saber mais sobre como modificar e controlar a versão dos modelos de dispositivo, confira Editar um modelo de dispositivo existente.

Modelos

O modelo define como um dispositivo interage com o aplicativo na IoT Central. Personalize seu modelo com mais recursos, adicione interfaces para herdar recursos ou adicione novos componentes baseados em outras interfaces.

Para criar um modelo de dispositivo, você pode:

  • Usar o IoT Central para criar um modelo personalizado do zero.
  • Importar um modelo DTDL de um arquivo JSON. Um construtor de dispositivo pode ter usado o Visual Studio Code para criar um modelo de dispositivo para seu aplicativo.
  • Selecionar um dos dispositivos no catálogo de dispositivos. Essa opção importa o modelo de dispositivo que o fabricante publicou para esse dispositivo. Um modelo de dispositivo importado como este é publicado automaticamente.
  1. Para exibir a ID do modelo, selecione a interface raiz no modelo e selecione Editar identidade:

    Captura de tela que mostra a ID do modelo da interface raiz do modelo do dispositivo.

  2. Para exibir a ID do componente, selecione Editar Identidade em qualquer uma das interfaces de componente no modelo.

Para saber mais, confira o Guia de modelagem do IoT Plug and Play.

Interfaces e componentes

Para exibir e gerenciar as interfaces em seu modelo de dispositivo:

  1. Vá para página Modelos de Dispositivo e selecione o modelo de dispositivo criado. As interfaces são listadas na seção Modelos do modelo de dispositivo. A seguinte captura de tela mostra um exemplo da interface raiz do Controlador de Sensor em um modelo de dispositivo:

    Captura de tela que mostra a interface raiz de um modelo

  2. Selecione as reticências para adicionar uma interface ou um componente herdado à interface raiz. Para saber mais sobre interfaces e componentes, confira vários componentes no guia de modelagem.

    Como adicionar interface ou componente

  3. Para exportar um modelo ou interface, selecione Exportar.

  4. Para exibir ou editar o DTDL para uma interface ou um recurso, selecione Editar DTDL.

Funcionalidades

Selecione + Adicionar capacidade para adicionar capacidade a uma interface ou componente. Por exemplo, você pode adicionar o recurso de Temperatura alvo a um componente SensorTemp.

Como adicionar capacidade

Telemetria

A telemetria é um fluxo de valores enviado do dispositivo, normalmente de um sensor. Por exemplo, um sensor pode relatar a temperatura ambiente, como mostrado na seguinte captura de tela:

Como adicionar telemetria

A seguinte tabela mostra as definições de configuração para uma funcionalidade de telemetria:

Campo Descrição
Nome de exibição O nome de exibição do valor de telemetria usado em exibições e formulários.
Nome O nome do campo na mensagem de telemetria. O IoT Central gera um valor para esse campo com base no nome de exibição, mas você pode escolher seu próprio valor, se necessário. Este campo precisa ser alfanumérico.
Tipo de Funcionalidade Telemetria.
Tipo Semântico O tipo semântico da telemetria, como temperatura, estado ou evento. A escolha do tipo semântico determina quais dos campos a seguir estão disponíveis.
Esquema O tipo de dados telemétricos, como duplo, cadeia de caracteres ou vetor. As opções disponíveis são determinadas pelo tipo semântico. O esquema não está disponível para os tipos semânticos de evento e estado.
Severidade Disponível somente para o tipo semântico de evento. As severidades são Erro, Informação ou Aviso.
Valores de Estado Disponível apenas para o tipo de estado semântico. Defina os valores de estado possíveis, cada um dos quais com o nome de exibição, o nome, o tipo de enumeração e o valor.
Unidade Uma unidade para o valor de telemetria, como mph, % ou °C.
Unidade de exibição Uma unidade de exibição para uso em exibições e formulários.
Comentário Comentários sobre a funcionalidade de telemetria.
Descrição Uma descrição da funcionalidade de telemetria.

Propriedades

As propriedades representam valores de ponto no tempo. Você pode definir propriedades graváveis no IoT Central. Por exemplo, um dispositivo pode usar uma propriedade gravável para permitir que um operador defina a temperatura desejada, conforme mostrado na seguinte captura de tela:

Como adicionar propriedade

A seguinte tabela mostra as definições de configuração para uma funcionalidade de propriedade:

Campo Descrição
Nome de exibição O nome de exibição do valor da propriedade usado em exibições e formulários.
Nome O nome da propriedade. O IoT Central gera um valor para esse campo com base no nome de exibição, mas você pode escolher seu próprio valor, se necessário. Este campo precisa ser alfanumérico.
Tipo de Funcionalidade Propriedade.
Tipo Semântico O tipo semântico da propriedade, como temperatura, estado ou evento. A escolha do tipo semântico determina quais dos campos a seguir estão disponíveis.
Esquema O tipo de dados de propriedade, como duplo, cadeia de caracteres ou vetor. As opções disponíveis são determinadas pelo tipo semântico. O esquema não está disponível para os tipos semânticos de evento e estado.
Gravável Se a propriedade não for gravável, o dispositivo poderá relatar valores de propriedade para o IoT Central. Se a propriedade for gravável, o dispositivo poderá relatar valores de propriedade para o IoT Central, e o IoT Central poderá enviar atualizações de propriedade para o dispositivo.
Severidade Disponível somente para o tipo semântico de evento. As severidades são Erro, Informação ou Aviso.
Valores de Estado Disponível apenas para o tipo de estado semântico. Defina os valores de estado possíveis, cada um dos quais com o nome de exibição, o nome, o tipo de enumeração e o valor.
Unidade Uma unidade para o valor da propriedade, como mph, % ou °C.
Unidade de exibição Uma unidade de exibição para uso em exibições e formulários.
Comentário Comentários sobre a funcionalidade de propriedade.
Descrição Uma descrição da funcionalidade de propriedade.
Color Esta é uma extensão do IoT Central para DTDL.
Valor mínimo Definir valor mínimo - Esta é uma extensão do IoT Central para DTDL.
Valor máximo Definir valor máximo - Esta é uma extensão do IoT Central para DTDL.
Casas decimais Esta é uma extensão do IoT Central para DTDL.

Comandos

Você pode chamar comandos do dispositivo no IoT Central. Opcionalmente, os comandos passam parâmetros para o dispositivo e recebem uma resposta do dispositivo. Por exemplo, você pode chamar um comando para reinicializar um dispositivo em 10 segundos, conforme mostrado na seguinte captura de tela:

Como adicionar comandos

A seguinte tabela mostra as definições de configuração para uma funcionalidade de comando:

Campo Descrição
Nome de exibição O nome de exibição do comando usado em exibições e formulários.
Nome O nome do comando. O IoT Central gera um valor para esse campo com base no nome de exibição, mas você pode escolher seu próprio valor, se necessário. Este campo precisa ser alfanumérico.
Tipo de Funcionalidade Comando.
Fila se estiver offline Se habilitado, você pode invocar o comando mesmo se o dispositivo estiver offline. Se não estiver habilitado, você só poderá chamar o comando quando o dispositivo estiver online.
Comentário Comentários sobre a funcionalidade de comando.
Descrição Uma descrição da funcionalidade de comando.
Solicitação Se habilitada, uma definição do parâmetro de solicitação, incluindo nome, nome de exibição, esquema, unidade e unidade de exibição.
Resposta Se habilitada, uma definição da resposta do comando, incluindo nome, nome de exibição, esquema, unidade e unidade de exibição.
Valor inicial O valor de parâmetro padrão. Esta é uma extensão do IoT Central para DTDL.

Para saber mais sobre como os dispositivos implementam comandos, confira Cargas de telemetria, propriedade e comando > Comandos e comandos de execução prolongada.

Comandos offline

Se um dispositivo estiver offline no momento, você pode escolher os comandos de fila habilitando a opção Fila se estiver offline para um comando no modelo de dispositivo.

Como adicionar comandos offline

Essa opção usa mensagens da nuvem para dispositivo do Hub IoT para enviar notificações para dispositivos. Para saber mais, confira o artigo do Hub IoT Enviar mensagens da nuvem para dispositivo.

Mensagens de nuvem para dispositivo:

  • São notificações unidirecionais para o dispositivo da sua solução.
  • Garantia de entrega de mensagem pelo menos uma vez. O Hub IoT mantém as mensagens da nuvem para dispositivo em filas por dispositivo, garantindo a resiliência contra falhas de conectividade e de dispositivo.
  • Exige que o dispositivo implemente um manipulador de mensagens para processar a mensagem da nuvem para dispositivo.

Observação

Os comandos offline serão marcados como durable se você exportar o modelo como DTDL.

Propriedades de nuvem

Use propriedades de nuvem para armazenar informações sobre dispositivos no IoT Central. As propriedades de nuvem nunca são enviadas a um dispositivo. Por exemplo, você pode usar propriedades de nuvem para armazenar o nome do cliente que instalou o dispositivo ou a data do último serviço do dispositivo.

Como adicionar propriedades da nuvem

A seguinte tabela mostra as definições de configuração para uma propriedade de nuvem:

Campo Descrição
Nome de exibição O nome de exibição do valor da propriedade na nuvem usado em exibições e formulários.
Nome O nome da propriedade de nuvem. O IoT Central gera um valor para esse campo com base no nome de exibição, mas você pode escolher seu próprio valor, se necessário.
Tipo Semântico O tipo semântico da propriedade, como temperatura, estado ou evento. A escolha do tipo semântico determina quais dos campos a seguir estão disponíveis.
Esquema O tipo de dados de propriedade de nuvem, como duplo, cadeia de caracteres ou vetor. As opções disponíveis são determinadas pelo tipo semântico.

Exibições

As exibições permitem definir exibições e formulários que permitem que um operador monitore e interaja com um dispositivo. As exibições usam visualizações como gráficos para mostrar os valores de propriedade e telemetria.

Gerar modos de exibição padrão é uma maneira rápida de visualizar as informações importantes do dispositivo. As três exibições padrão são:

Exibições padrão

  • Comandos: uma exibição com os comandos do dispositivo e permitem a expedição deles pelo operador ao dispositivo.
  • Visão geral: uma exibição com a telemetria do dispositivo, exibindo gráficos e métricas.
  • Sobre: uma exibição com informações sobre o dispositivo, exibindo as propriedades do dispositivo.

Depois de selecionar Gerar exibições padrão, elas serão adicionadas automaticamente na seção Exibições do seu modelo de dispositivo.

Modos de exibição personalizados

Adicione exibições a um modelo de dispositivo para permitir que os operadores visualizem um dispositivo usando gráficos e métricas. Você pode adicionar suas próprias exibições personalizadas a um modelo de dispositivo.

Para adicionar uma exibição a um modelo de dispositivo:

  1. Acesse o modelo de dispositivo e selecione Exibições.
  2. Selecione Visualizando o Dispositivo.
  3. Insira um nome para a exibição em Nome da exibição.
  4. Selecione Iniciar com um visual em adicionar blocos e escolha o tipo de visual para o seu bloco. Em seguida, selecione Adicionar bloco ou arraste e solte o visual na tela. Para configurar o bloco, selecione o ícone de engrenagem.

Como começar com um visual

configurar bloco

Para testar sua exibição, selecione Configurar o dispositivo de versão prévia. Este recurso permite que você veja a exibição como o operador a verá depois da publicação. Use esse recurso para validar se as exibições mostram os dados corretos. Escolha dentre as seguintes opções:

  • Nenhum dispositivo de visualização.
  • O dispositivo de teste real que você configurou para seu modelo de dispositivo.
  • Um dispositivo existente em seu aplicativo usando a ID do dispositivo.

Formulários

Adicione formulários a um modelo de dispositivo para permitir que os operadores gerenciem um dispositivo exibindo e definindo propriedades. Os operadores só podem editar propriedades de nuvem e propriedades de dispositivo graváveis. Você pode ter vários formulários para um modelo de dispositivo.

  1. Selecione o nó Exibições e, em seguida, selecione o bloco Editando dados de dispositivo e de nuvem para adicionar uma nova exibição.

  2. Altere o nome do formulário para Gerenciar dispositivo.

  3. Selecione as propriedades de nuvem Nome do Cliente e Data do Último Serviço, bem como a propriedade Temperatura de Destino. Em seguida, selecione Adicionar seção.

  4. Selecione Salvar para salvar seu novo formulário.

configurar formulário

Publicar um modelo de dispositivo

Antes de conectar um dispositivo que implementa o modelo de dispositivo, você precisará publicar o modelo de dispositivo.

Para publicar um modelo de dispositivo, acesse o modelo de dispositivo e selecione Publicar.

Depois que você publicar um modelo de dispositivo, um operador poderá acessar a página Dispositivos e adicionar dispositivos reais ou simulados que usam o modelo de dispositivo. Você pode continuar a modificar e salvar o modelo de dispositivo enquanto estiver fazendo alterações. Quando desejar enviar essas alterações por push para o operador visualizar na página Dispositivos, selecione Publicar a cada vez.

Próximas etapas

Uma próxima etapa sugerida é ler sobre como Fazer alterações em um modelo de dispositivo existente.