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:
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.
- Dados brutos – exiba os dados brutos enviados pelo dispositivo em versão prévia designado. Essa exibição é útil quando você está depurando ou solucionando problemas de um modelo de 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 da lista dos modelos de dispositivos em destaque. 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 a extensão Digital Twin Definition Language (DTDL) V2 e IoT Central DTDL. 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 do IoT Central usando Como usar a API REST do IoT Central para gerenciar modelos de dispositivo.
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 você deve importar um modelo de dispositivo da lista de modelos de dispositivo em destaque e como personalizá-lo usando a GUI da Central de IoT. Este exemplo usa o modelo de dispositivo Sensor Temporário do Hobo MX-100 Onset da lista de modelos de dispositivo em destaque:
- Para adicionar um novo modelo de dispositivo, selecione + Novo na página Modelos de dispositivo.
- Na página Selecionar tipo, role a página para baixo até encontrar o bloco do Sensor de temperatura Onset Hobo MX-100 na seção Modelos de dispositivo em destaque.
- Escolha o bloco do Sensor de temperatura Onset Hobo MX-100 e selecione Avançar: Revisar.
- Na página Examinar, selecione Criar. O nome do modelo criado é Hobo MX-100. O modelo inclui componentes, como Hobo MX-100 e IotDevice. Os componentes definem as funcionalidades de um dispositivo Hobo MX-100. Os recursos podem incluir telemetria, propriedades e comandos. Esse dispositivo tem apenas recursos de telemetria.
Gerar automaticamente um modelo de dispositivo
Você também pode criar automaticamente um modelo de dispositivo a partir de um dispositivo não atribuído no momento. 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:
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:
Na página Visualização de dados, faça as alterações necessárias nos dados brutos e selecione Criar modelo:
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:
Gerenciar um modelo de dispositivo
Você pode renomear ou excluir um modelo na página de editor do modelo.
Depois de 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 dispositivos pode usar o Visual Studio Code para criar um modelo de dispositivo para seu aplicativo.
- Selecione um dos dispositivos na lista de modelos de dispositivo em destaque. Essa opção importa o modelo do dispositivo publicado pelo fabricante para esse dispositivo. Um modelo de dispositivo importado como este é publicado automaticamente.
Para exibir a ID do modelo, selecione a interface raiz no modelo e selecione Editar identidade:
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:
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:
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.
Para exportar um modelo ou interface, selecione Exportar.
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.
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:
A seguinte tabela mostra as definições de configuração para uma funcionalidade de telemetria:
| Campo | Description |
|---|---|
| Nome para 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. O tipo semântico determina as opções disponíveis. 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:
A seguinte tabela mostra as definições de configuração para uma funcionalidade de propriedade:
| Campo | Description |
|---|---|
| Nome para 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. O tipo semântico determina as opções disponíveis. 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 ao 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 | Uma extensão do IoT Central para DTDL. |
| Valor mínimo | Definir valor mínimo - Uma extensão do IoT Central para DTDL. |
| Valor máximo | Definir valor máximo - Uma extensão do IoT Central para DTDL. |
| Casas decimais | 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:
A seguinte tabela mostra as definições de configuração para uma funcionalidade de comando:
| Campo | Description |
|---|---|
| Nome para 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. Esse parâmetro é 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.
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 as propriedades da nuvem para armazenar o nome do cliente que instalou o dispositivo ou a data do último serviço do dispositivo.
Dica
Você só pode adicionar propriedades de nuvem ao componente Raiz no modelo.
A seguinte tabela mostra as definições de configuração para uma propriedade de nuvem:
| Campo | Description |
|---|---|
| Nome para 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. O tipo semântico determina as opções disponíveis. |
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 modos de exibição padrão, eles serão automaticamente adicionados na seção Modos de Exibição 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:
- Acesse o modelo de dispositivo e selecione Exibições.
- Selecione Visualizando o Dispositivo.
- Insira um nome para a exibição em Nome da exibição.
- 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.
Para testar sua exibição, selecione Configurar o dispositivo de versão prévia. Esse recurso permite que você veja a visualização como um operador a vê após a 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.
Selecione o nó Exibições e, em seguida, selecione o bloco Editando dados de dispositivo e de nuvem para adicionar uma nova exibição.
Altere o nome do formulário para Gerenciar dispositivo.
Selecione as propriedades e as propriedades de nuvem a serem adicionadas ao formulário. Em seguida, selecione Adicionar seção.
Selecione Salvar para salvar seu novo 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.