Criar um modelo de dispositivo em seu aplicativo do Azure IoT Central

Um modelo do dispositivo é um esquema que define as características e comportamentos de um tipo de dispositivo que é ligado a uma aplicação do Azure IoT Central. Por exemplo, você pode criar um modelo de dispositivo para um sensor que envia telemetria, como temperatura e propriedades, como localização. Para saber mais, consulte O que são modelos de dispositivo?.

Este artigo descreve algumas das maneiras de criar um modelo de dispositivo no IoT Central, como gerar automaticamente um modelo de dispositivo a partir de uma mensagem de telemetria ou definir um na interface do usuário do IoT Central.

A partir de um modelo de dispositivo, um operador pode criar e conectar dispositivos reais.

A captura de tela a seguir mostra um exemplo de um modelo de dispositivo:

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

• Modelo - Use o modelo para definir como seu dispositivo interage com seu aplicativo IoT Central. Cada modelo tem um ID de modelo exclusivo e define as capacidades do dispositivo. Os recursos são agrupados em interfaces. As interfaces permitem reutilizar componentes entre modelos ou usar herança para estender o conjunto de recursos.
• Dados brutos - Visualize os dados brutos enviados pelo dispositivo de visualização designado. Essa exibição é útil quando você está depurando ou solucionando problemas de um modelo de dispositivo.
• Modos de exibição - Use modos de exibição para visualizar os dados do dispositivo e formulários para gerenciar e controlar um 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.

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

• Crie o modelo de dispositivo na interface do usuário do IoT Central.
• Importe um modelo de dispositivo da lista de modelos de dispositivo em destaque. Opcionalmente, personalize o modelo de dispositivo de acordo com seus requisitos no IoT Central.
• Quando o dispositivo se conectar ao IoT Central, peça que ele envie a ID do modelo que implementa. O IoT Central usa o ID do modelo para recuperar o modelo do repositório de modelos e criar um modelo de dispositivo. Adicione quaisquer propriedades de nuvem e visualizações de que seu aplicativo IoT Central precisa ao modelo de dispositivo.
• Quando o dispositivo se conectar ao 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 DTDL (Digital Twin Definition Language) v2 e a extensão DTDL do IoT Central. Importe manualmente o modelo do dispositivo para seu aplicativo IoT Central. Em seguida, adicione as propriedades da nuvem e visualize suas necessidades de aplicativo do IoT Central.
• Você também pode adicionar modelos de dispositivo a um aplicativo do IoT Central usando a opção Como usar a API REST do IoT Central para gerenciar modelos de dispositivo.

Nota

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 exibições da nuvem do modelo de dispositivo.

Importar um modelo de dispositivo

Esta seção mostra como importar um modelo de dispositivo da lista de modelos de dispositivo em destaque e como personalizá-lo usando a interface do usuário do IoT Central. Este exemplo usa o modelo de dispositivo Onset Hobo MX-100 Temp Sensor da lista de modelos de dispositivo em destaque:

1. Para adicionar um novo modelo de dispositivo, selecione + Novo na página Modelos de dispositivo .
2. Na página Selecionar tipo, role para baixo até encontrar o bloco Sensor Temp Onset Hobo MX-100 na seção Modelos de dispositivo em destaque.
3. Selecione o bloco Onset Hobo MX-100 Temp Sensor e, em seguida, selecione Next: Review.
4. Na página Revisão, selecione Criar. O nome do modelo que você criou é Hobo MX-100. O modelo inclui componentes como Hobo MX-100 e IotDevice. Os componentes definem as capacidades de um dispositivo Hobo MX-100. Os recursos podem incluir telemetria, propriedades e comandos. Este dispositivo só tem capacidades 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. O IoT Central usa os valores de telemetria e propriedade que o dispositivo envia para inferir um modelo de dispositivo.

Nota

Atualmente, esse recurso de visualização não pode usar telemetria e propriedades de componentes. Ele só pode gerar recursos a partir de telemetria raiz e propriedades.

As etapas a seguir mostram como usar esse recurso:

1. Conecte seu dispositivo ao IoT Central e comece a enviar os dados. Quando você vir os dados na visualização Dados brutos , selecione Modelo de criação automática na lista suspensa Gerenciar modelo :

   

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

   

3. O 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 mais alterações no modelo de dispositivo, como renomeá-lo ou adicionar recursos, na página Modelos de dispositivo:

   

Gerenciar modelos de dispositivo na interface do usuário

Você pode criar, editar, renomear ou excluir um modelo da página do editor do modelo.

Depois de definir o modelo, você pode publicá-lo. Até que o modelo seja publicado, não é possível conectar um dispositivo a ele e ele não aparece na página Dispositivos .

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

Modelos

O modelo define como seu dispositivo interage com seu aplicativo 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:

• Use o IoT Central para criar um modelo personalizado do zero.
• Importe 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 dispositivos em destaque. Esta opção importa o modelo de dispositivo que o fabricante publicou para este dispositivo. Um modelo de dispositivo importado como este é publicado automaticamente.

1. Para visualizar o ID do modelo, selecione a interface raiz no modelo e selecione Editar identidade:

   

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

Para saber mais, consulte o guia de modelagem IoT Plug and Play.

Interfaces e componentes

Para visualizar e gerir as interfaces no modelo do seu dispositivo:

1. Vá para a página Modelos de dispositivo e selecione o modelo de dispositivo que você criou. As interfaces são listadas na seção Modelos do modelo de dispositivo. A captura de tela a seguir mostra um exemplo da interface raiz do Sensor Controller em um modelo de dispositivo:

   

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

   

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

4. Para exibir ou editar a DTDL de uma interface ou recurso, selecione Editar DTDL.

Capacidades

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

Telemetria

Telemetria é um fluxo de valores enviados do dispositivo, normalmente de um sensor. Por exemplo, um sensor pode relatar a temperatura ambiente, conforme mostrado na captura de tela a seguir:

A tabela a seguir mostra as definições de configuração para um recurso de telemetria:

Campo	Descrição
Nome a Apresentar	O nome para exibição do valor de telemetria usado em modos de exibição e formulários.
Nome	O nome do campo na mensagem de telemetria. O IoT Central gera um valor para esse campo a partir do nome para exibição, mas você pode escolher seu próprio valor, se necessário. Este campo tem de ser alfanumérico.
Tipo de Capacidade	Telemetria.
Tipo de Semântica	O tipo semântico da telemetria, como temperatura, estado ou evento. A escolha do tipo semântico determina qual dos seguintes campos está disponível.
Esquema	O tipo de dados de telemetria, como double, string 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.
Gravidade	Disponível apenas para o tipo semântico de evento. As gravidades são Erro, Informação ou Aviso.
Valores do Estado	Disponível apenas para o tipo semântico de estado. Defina os valores de estado possíveis, cada um dos quais tem nome para exibição, nome, tipo de enumeração e valor.
Unit	Uma unidade para o valor de telemetria, como mph, %ou °C.
Unidade de visualização	Uma unidade de exibição para uso em modos de exibição e formulários.
Comentário	Quaisquer comentários sobre a capacidade de telemetria.
Description	Uma descrição da capacidade de telemetria.

Propriedades

As propriedades representam valores point-in-time. Você pode definir propriedades graváveis a partir do IoT Central. Por exemplo, um dispositivo pode usar uma propriedade gravável para permitir que um operador defina a temperatura de destino, conforme mostrado na captura de tela a seguir:

A tabela a seguir mostra as definições de configuração para um recurso de propriedade:

Campo	Descrição
Nome a Apresentar	O nome para exibição do valor da propriedade usada em modos de exibição e formulários.
Nome	O nome da propriedade. O IoT Central gera um valor para esse campo a partir do nome para exibição, mas você pode escolher seu próprio valor, se necessário. Este campo tem de ser alfanumérico.
Tipo de Capacidade	Imóvel.
Tipo de Semântica	O tipo semântico da propriedade, como temperatura, estado ou evento. A escolha do tipo semântico determina qual dos seguintes campos está disponível.
Esquema	O tipo de dados da propriedade, como double, string 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.
Writable (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.
Gravidade	Disponível apenas para o tipo semântico de evento. As gravidades são Erro, Informação ou Aviso.
Valores do Estado	Disponível apenas para o tipo semântico de estado. Defina os valores de estado possíveis, cada um dos quais tem nome para exibição, nome, tipo de enumeração e valor.
Unit	Uma unidade para o valor da propriedade, como mph, %, ou °C.
Unidade de visualização	Uma unidade de exibição para uso em modos de exibição e formulários.
Comentário	Quaisquer comentários sobre a capacidade da propriedade.
Description	Uma descrição da capacidade da propriedade.
Cor	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 de dispositivo a partir do 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 reiniciar um dispositivo em 10 segundos, conforme mostrado na captura de tela a seguir:

A tabela a seguir mostra as definições de configuração para um recurso de comando:

Campo	Descrição
Nome a Apresentar	O nome para exibição do comando usado em modos de exibição e formulários.
Nome	O nome do comando. O IoT Central gera um valor para esse campo a partir do nome para exibição, mas você pode escolher seu próprio valor, se necessário. Este campo tem de ser alfanumérico.
Tipo de Capacidade	Comandos
Fila se estiver offline	Se ativado, você pode chamar o comando mesmo se o dispositivo estiver offline. Se não estiver ativado, só pode chamar o comando quando o dispositivo estiver online.
Comentário	Quaisquer comentários sobre a capacidade de comando.
Description	Uma descrição da capacidade de comando.
Pedir	Se habilitado, uma definição do parâmetro request, incluindo: nome, nome de exibição, esquema, unidade e unidade de exibição.
Response	Se habilitado, uma definição da resposta do comando, incluindo: nome, nome para exibição, esquema, unidade e unidade de exibição.
Valor inicial	O valor do parâmetro padrão. Este parâmetro é uma extensão do IoT Central para DTDL.

Para saber mais sobre como os dispositivos implementam comandos, consulte Telemetria, propriedade e cargas úteis de > comando Comandos e comandos de longa execução.

Comandos offline

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

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

Mensagens da nuvem para o dispositivo:

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

Nota

Os comandos offline são marcados como durable se você exportasse o modelo como DTDL.

Propriedades da cloud

Use as propriedades da nuvem para armazenar informações sobre dispositivos no IoT Central. As propriedades da nuvem nunca são enviadas para 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.

Gorjeta

Você só pode adicionar propriedades de nuvem ao componente Raiz no modelo.

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

Campo	Descrição
Nome a Apresentar	O nome para exibição do valor da propriedade de nuvem usado em modos de exibição e formulários.
Nome	O nome da propriedade cloud. O IoT Central gera um valor para esse campo a partir do nome para exibição, mas você pode escolher seu próprio valor, se necessário.
Tipo de Semântica	O tipo semântico da propriedade, como temperatura, estado ou evento. A escolha do tipo semântico determina qual dos seguintes campos está disponível.
Esquema	O tipo de dados de propriedade de nuvem, como double, string ou vetor. O tipo semântico determina as opções disponíveis.

Visualizações

As vistas permitem-lhe definir vistas e formulários que permitem a um operador monitorizar e interagir com um dispositivo. As exibições usam visualizações, como gráficos, para mostrar valores de telemetria e propriedade.

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

Modos de exibição padrão

• Comandos: uma vista com comandos do dispositivo e permite ao seu operador enviá-los para o seu dispositivo.
• Visão geral: uma exibição com telemetria do dispositivo, exibindo gráficos e métricas.
• Sobre: Uma exibição com informações do dispositivo, exibindo as propriedades do dispositivo.

Depois de selecionar Gerar vistas predefinidas, estas são adicionadas automaticamente na secção Vistas do seu modelo de dispositivo.

Vistas personalizadas

Adicione visualizações a um modelo de dispositivo para permitir que os operadores visualizem um dispositivo usando gráficos e métricas. Pode adicionar as suas próprias vistas personalizadas a um modelo de dispositivo.

Para adicionar uma vista a um modelo de dispositivo:

1. Aceda ao modelo do dispositivo e selecione Vistas .
2. Selecione Visualizar o dispositivo.
3. Introduza um nome para a vista em Ver nome.
4. Selecione Iniciar com um visual em Adicionar blocos e escolha o tipo de visual para 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 dispositivo de visualização. Esse recurso permite que você veja a exibição como um operador a vê depois que ela publica. Use esse recurso para validar se suas visualizações mostram os dados corretos. Escolha entre 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 o 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ó Visualizações e, em seguida, selecione o bloco Dispositivo de edição e dados na nuvem para adicionar uma nova exibição.

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

3. Selecione as propriedades e as propriedades da nuvem a serem adicionadas ao formulário. Em seguida, selecione Adicionar seção.

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

Publicar um modelo de dispositivo

Antes de conectar um dispositivo que implementa seu modelo de dispositivo, você deve publicar seu modelo de dispositivo.

Para publicar um modelo de dispositivo, vá para o modelo de dispositivo e selecione Publicar.

Depois de publicar um modelo de dispositivo, um operador pode ir para a página Dispositivos e adicionar dispositivos reais ou simulados que usam seu modelo de dispositivo. Pode continuar a modificar e guardar o modelo do dispositivo à medida que faz alterações. Quando quiser enviar essas alterações para o operador exibir na página Dispositivos , selecione Publicar sempre.