O que são modelos de dispositivo?
Um modelo de dispositivo no Azure IoT Central é um blueprint que define as características e os comportamentos de um tipo de dispositivo que se conecta ao seu aplicativo. Por exemplo, o modelo de dispositivo define a telemetria que um dispositivo envia para que o IoT Central crie visualizações que usam as unidades e os tipos de dados corretos.
Um construtor de solução adiciona modelos de dispositivo a um aplicativo no IoT Central. Um desenvolvedor de dispositivos grava o código de dispositivo que implementa os comportamentos definidos no modelo de dispositivo. Para saber mais sobre os dados que um dispositivo troca com o IoT Central, confira Telemetria, propriedade e conteúdos de comando.
Um modelo de dispositivo inclui as seguintes seções:
- Um modelo do dispositivo. Esta parte do modelo de dispositivo define como o dispositivo interage com seu aplicativo. Cada modelo de dispositivo tem uma ID exclusiva. Um desenvolvedor de dispositivo implementa os comportamentos definidos no modelo.
- Componente raiz. Todo modelo de dispositivo tem um componente raiz. A interface do componente raiz descreve recursos que são específicos do modelo do dispositivo.
- Componentes. Um modelo de dispositivo pode incluir componentes além do componente raiz para descrever os recursos do dispositivo. Cada componente tem uma interface que descreve os recursos do componente. As interfaces do componente podem ser reutilizadas em outros modelos de dispositivo. Por exemplo, vários modelos de dispositivo de telefone podem usar a mesma interface de câmera.
- Interface herdada. Um modelo de dispositivo contém uma ou mais interfaces que estendem os recursos do componente padrão.
- Exibições. Esta parte do modelo de dispositivo permite que o desenvolvedor da solução defina visualizações para exibir dados do dispositivo e formulários para gerenciar e controlar um dispositivo. As exibições não afetam o código que um desenvolvedor de dispositivo grava para implementar o modelo de dispositivo.
Atribuir um dispositivo a um modelo de dispositivo
Para que um dispositivo interaja com o IoT Central, ele precisa ser atribuído a um modelo de dispositivo. Essa atribuição é feita de uma destas quatro maneiras:
- Ao registrar um dispositivo na página Dispositivos, você pode identificar o modelo que o dispositivo deve usar.
- Ao importar em massa uma lista de dispositivos, você pode escolher o modelo de dispositivo que todos os dispositivos na lista devem usar.
- Você poderá atribuir manualmente um dispositivo não atribuído a um modelo de dispositivo depois que ele se conectar.
- Você pode atribuir automaticamente um dispositivo a um modelo de dispositivo enviando uma ID de modelo quando o dispositivo se conecta pela primeira vez ao seu aplicativo.
Atribuição automática
O IoT Central atribui automaticamente um dispositivo a um modelo de dispositivo quando o dispositivo se conecta. Um dispositivo deve enviar uma ID de modelo quando ele se conecta. O IoT Central usa a ID do modelo para identificar o modelo de dispositivo para esse modelo de dispositivo específico. O processo de descoberta funciona da seguinte maneira:
Caso o modelo de dispositivo já esteja publicado no aplicativo do IoT Central, o dispositivo é atribuído ao modelo de dispositivo.
Se o modelo de dispositivo ainda não estiver publicado no aplicativo IoT Central, o IoT Central procurará o modelo de dispositivo no repositório público de modelos de dispositivo. Se o IoT Central encontrar o modelo, ele o usará para gerar um modelo de dispositivo básico.
Se o IoT Central não encontrar o modelo no repositório de modelos públicos, o dispositivo será marcado como Não atribuído. Um operador pode:
- Criar um modelo de dispositivo e, em seguida, migrar o dispositivo não atribuído para o novo modelo de dispositivo.
- Gerar automaticamente um modelo de dispositivo com base nos dados que o dispositivo envia.
A captura de tela a seguir mostra como ver a ID de um modelo de dispositivo no IoT Central. Em um modelo de dispositivo, selecione um componente e clique em Editar identidade:
É possível ver o modelo termostato no repositório de modelos públicos. A definição de ID do modelo é semelhante a:
"@id": "dtmi:com:example:Thermostat;1"
Use o seguinte conteúdo do DPS para atribuir o dispositivo a um modelo de dispositivo:
{
"modelId":"dtmi:com:example:TemperatureController;2"
}
Para saber mais sobre o conteúdo de DPS, confira o código de exemplo usado em Tutorial: criar e conectar um aplicativo cliente ao seu aplicativo Azure IoT Central.
Modelos de dispositivo
Um modelo de dispositivo define como um dispositivo interage com o aplicativo no IoT Central. O desenvolvedor do dispositivo deve garantir que o dispositivo implemente os comportamentos definidos no modelo para que IoT Central possa monitorar e gerenciar o dispositivo. Um modelo de dispositivo é composto de uma ou mais interfaces e cada interface pode definir uma coleção de tipos de telemetria, propriedades de dispositivo e comandos. Um desenvolvedor de soluções pode:
- Importar um arquivo JSON que define um modelo de dispositivo completo ou uma interface individual para um modelo de dispositivo.
- Usar a interface do usuário da web no IoT Central para criar ou editar um modelo de dispositivo.
Observação
O IoT Central aceita qualquer conteúdo JSON válido de um dispositivo, mas só pode usar os dados para visualizações se eles corresponderem a uma definição no modelo do dispositivo. Você pode exportar dados que não correspondem a uma definição, confira Exportar dados de IoT para destinos de nuvem usando o Armazenamento de Blobs.
Para saber mais sobre como editar um modelo de dispositivo, consulte Editar um modelo de dispositivo existente
Um desenvolvedor de solução também pode exportar um arquivo JSON do modelo de dispositivo que contém um modelo de dispositivo completo ou uma interface individual. Um desenvolvedor de dispositivos pode usar este documento JSON para entender como o dispositivo deve se comunicar com o aplicativo no IoT Central.
O arquivo JSON que define o modelo de dispositivo usa o DTDL (linguagem de definição de gêmeo digital) V2. O IoT Central espera que o arquivo JSON contenha o modelo de dispositivo com as interfaces definidas como embutidas, em vez de arquivos separados. Os modelos criados no IoT Central têm o contexto dtmi:iotcentral:context;2 definido para indicar que o modelo foi criado no IoT Central:
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
Para saber mais sobre os modelos DTDL, confira o Guia de modelagem do IoT Plug and Play.
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.
Propriedades
Por padrão, as propriedades são somente leitura. Propriedades somente leitura significam que o valor da propriedade de relatórios do dispositivo é atualizado para seu aplicativo no IoT Central. O aplicativo no IoT Central não pode definir o valor de uma propriedade somente leitura.
Você também pode marcar uma propriedade como gravável em uma interface. Um dispositivo pode receber uma atualização para uma propriedade gravável do seu aplicativo no IoT Central e reportar atualizações de valor de propriedade para o aplicativo.
Os dispositivos não precisam estar conectados para definir valores de propriedade. Os valores atualizados são transferidos quando o dispositivo se conecta ao aplicativo. Esse comportamento se aplica a propriedades somente leitura e graváveis.
Não use propriedades para enviar telemetria do seu dispositivo. Por exemplo, uma propriedade somente leitura, como temperatureSetting=80, significa que a temperatura do dispositivo foi definida como 80 e o dispositivo está tentando chegar ou permanecer nessa temperatura.
Para propriedades graváveis, o aplicativo do dispositivo retorna um código de status, versão e descrição de estado desejado para indicar se ele recebeu e aplicou o valor da propriedade.
Propriedades de nuvem
Você também pode adicionar propriedades de nuvem ao componente raiz do modelo. As propriedades de nuvem permitem que você especifique todos os metadados de dispositivo a serem armazenados no aplicativo no IoT Central. Os valores das propriedades de nuvem são armazenados no aplicativo IoT Central e nunca são sincronizados com um dispositivo. As propriedades da nuvem não afetam o código que um desenvolvedor de dispositivo grava para implementar o modelo de dispositivo.
Um desenvolvedor de soluções pode adicionar propriedades de nuvem a painéis e exibições junto com as propriedades do dispositivo para permitir que um operador gerencie os dispositivos conectados ao aplicativo. Um desenvolvedor de soluções também pode usar propriedades de nuvem como parte de uma definição de regra para tornar um valor de limite editável por um operador.
O trecho DTDL a seguir mostra um exemplo de definição de propriedade de nuvem:
{
"@id": "dtmi:azureiot:Thermostat:CustomerName",
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": {
"en": "Customer Name"
},
"name": "CustomerName",
"schema": "string"
}
Telemetria
O IoT Central permite exibir a telemetria em exibições e gráficos de dispositivo, e usa regras para disparar ações quando os limites são atingidos. O IoT Central usa as informações no modelo de dispositivo, como tipos de dados, unidades e nomes de exibição, para determinar como exibir valores de telemetria. Você também pode exibir valores de telemetria em dashboards pessoais e de aplicativos.
Você pode usar o recurso de exportação de dados no IoT Central para transmitir telemetria para outros destinos, como armazenamento ou Hubs de Eventos.
Comandos
Um comando deve ser executado dentro de 30 segundos por padrão e o dispositivo deve estar conectado quando o comando chegar. Se o dispositivo responder dentro do tempo ou se ele não estiver conectado, o comando falhará.
Os comandos podem ter parâmetros de solicitação e retornar uma resposta.
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.
Os comandos offline são notificações unidirecionais para o dispositivo da sua solução. Comandos offline podem ter parâmetros de solicitação, mas não retornam uma resposta.
Observação
Os comandos offline serão marcados como durable se você exportar o modelo como DTDL.
Comandos offline usam mensagens da nuvem para o dispositivo do Hub IoT para enviar o comando e o conteúdo para o dispositivo.
O payload da mensagem que o dispositivo recebe é o valor bruto do parâmetro. Uma propriedade personalizada chamada method-name armazena o nome do comando IoT Central. A tabela a seguir mostra cargas de exemplo:
| Esquema de solicitação do IoT Central | Carga de exemplo recebida pelo dispositivo |
|---|---|
| Sem parâmetro de solicitação | @ |
| Double | 1.23 |
| String | sample string |
| Objeto | {"StartTime":"2021-01-05T08:00:00.000Z","Bank":2} |
O snippet de um modelo de dispositivo abaixo mostra a definição de um comando: O comando tem um parâmetro de objeto com um campo datetime e uma enumeração:
{
"@type": "Command",
"displayName": {
"en": "Generate Diagnostics"
},
"name": "GenerateDiagnostics",
"request": {
"@type": "CommandPayload",
"displayName": {
"en": "Payload"
},
"name": "Payload",
"schema": {
"@type": "Object",
"displayName": {
"en": "Object"
},
"fields": [
{
"displayName": {
"en": "StartTime"
},
"name": "StartTime",
"schema": "dateTime"
},
{
"displayName": {
"en": "Bank"
},
"name": "Bank",
"schema": {
"@type": "Enum",
"displayName": {
"en": "Enum"
},
"enumValues": [
{
"displayName": {
"en": "Bank 1"
},
"enumValue": 1,
"name": "Bank1"
},
{
"displayName": {
"en": "Bank2"
},
"enumValue": 2,
"name": "Bank2"
},
{
"displayName": {
"en": "Bank3"
},
"enumValue": 3,
"name": "Bank3"
}
],
"valueSchema": "integer"
}
}
]
}
}
}
Ao habilitar a opção Enfileirar se offline na interface do usuário do modelo de dispositivo para o comando no snippet anterior, a mensagem recebida incluirá as seguintes propriedades:
| Nome da propriedade | Valor de exemplo |
|---|---|
custom_properties |
{'method-name': 'GenerateDiagnostics'} |
data |
{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2} |
Exibições
Um desenvolvedor de soluções cria exibições que permitem que os operadores monitorem e gerenciem dispositivos conectados. As exibições fazem parte do modelo de dispositivo, então uma exibição é associada a um tipo de dispositivo específico. Uma exibição pode incluir:
- Gráficos para plotar a telemetria.
- Blocos para exibir propriedades de dispositivo somente leitura.
- Blocos para permitir que o operador edite as propriedades graváveis do dispositivo.
- Blocos para permitir que o operador edite as propriedades de nuvem.
- Blocos para permitir que o operador chame comandos, incluindo comandos que esperam um conteúdo.
- Blocos para exibir rótulos, imagens ou texto markdown.
Próximas etapas
Agora que você aprendeu sobre modelos de dispositivo, recomendamos ler os Conteúdos de telemetria, propriedade e comando para saber mais sobre os dados que um dispositivo troca com o IoT Central.