O que são modelos de dispositivo?
Um modelo de dispositivo no Azure IoT Central é um modelo que define as características e 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 possa criar visualizações que usam as unidades e os tipos de dados corretos.
Um construtor de soluções adiciona modelos de dispositivo a um aplicativo do IoT Central. Um desenvolvedor de dispositivo grava o código do dispositivo que implementa os comportamentos definidos no modelo de dispositivo. Para saber mais sobre os dados que um dispositivo troca com o IoT Central, consulte Telemetria, propriedade e cargas úteis de comando.
Um modelo de dispositivo inclui as seguintes seções:
- Um modelo de dispositivo. Esta parte do modelo de dispositivo define como o dispositivo interage com seu aplicativo. Cada modelo de dispositivo tem um ID exclusivo. Um desenvolvedor de dispositivo implementa os comportamentos definidos no modelo.
- Componente raiz. Cada modelo de dispositivo tem um componente raiz. A interface do componente raiz descreve os recursos que são específicos para o 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 de componentes podem ser reutilizadas noutros modelos de dispositivos. Por exemplo, vários modelos de dispositivos telefónicos podem utilizar a mesma interface de câmara.
- Interfaces herdadas. Um modelo de dispositivo contém uma ou mais interfaces que estendem os recursos do componente raiz.
- Vistas. 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 escreve para implementar o modelo de dispositivo.
Atribuir um dispositivo a um modelo de dispositivo
Para que um dispositivo interaja com o IoT Central, ele deve ser atribuído a um modelo de dispositivo. Esta tarefa é feita de 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ê pode 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 pode atribuir automaticamente um dispositivo a um modelo de dispositivo quando o dispositivo se conecta. Um dispositivo deve enviar um ID de modelo quando se conecta. O IoT Central usa o ID do modelo para identificar o modelo de dispositivo para esse modelo de dispositivo específico. O processo de descoberta funciona da seguinte maneira:
Se o modelo de dispositivo já estiver publicado no aplicativo IoT Central, o dispositivo será 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 de modelo de dispositivo público. 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úblico, o dispositivo será marcado como Não atribuído. Um operador pode:
- Crie um modelo de dispositivo para o dispositivo e, em seguida, migre o dispositivo não atribuído para o novo modelo de dispositivo.
- Gere automaticamente um modelo de dispositivo com base nos dados enviados pelo dispositivo.
A captura de tela a seguir mostra como exibir a ID do modelo de um modelo de dispositivo no IoT Central. Num modelo de dispositivo, selecione um componente e, em seguida, selecione Editar identidade:
Você pode visualizar o modelo de termostato no repositório de modelo público. A definição de ID do modelo tem a seguinte aparência:
"@id": "dtmi:com:example:Thermostat;1"
Use a seguinte carga útil DPS para atribuir o dispositivo a um modelo de dispositivo:
{
"modelId":"dtmi:com:example:TemperatureController;2"
}
Para saber mais sobre a carga útil do DPS, consulte o código de exemplo usado no Tutorial: Criar e conectar um aplicativo cliente ao seu aplicativo do Azure IoT Central.
Modelos de dispositivos
Um modelo de dispositivo define como um dispositivo interage com seu aplicativo IoT Central. O desenvolvedor do dispositivo deve certificar-se de que o dispositivo implementa os comportamentos definidos no modelo de dispositivo para que o IoT Central possa monitorar e gerenciar o dispositivo. Um modelo de dispositivo é composto por 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:
- Importe um arquivo JSON que define um modelo de dispositivo completo ou interface individual para um modelo de dispositivo.
- Use a interface do usuário da Web no IoT Central para criar ou editar um modelo de dispositivo.
Nota
O IoT Central aceita qualquer carga JSON válida de um dispositivo, mas só pode usar os dados para visualizações se corresponder a uma definição no modelo do dispositivo. Você pode exportar dados que não correspondem a uma definição, consulte Exportar dados de IoT para destinos na nuvem usando o Armazenamento de Blob.
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 interface individual. Um desenvolvedor de dispositivo pode usar este documento JSON para entender como o dispositivo deve se comunicar com o aplicativo IoT Central.
O arquivo JSON que define o modelo de dispositivo usa a Digital Twin Definition Language (DTDL) V2. O IoT Central espera que o arquivo JSON contenha o modelo de dispositivo com as interfaces definidas em linha, em vez de em 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 modelos DTDL, consulte o guia de modelagem IoT Plug and Play.
Nota
O IoT Central define algumas extensões para a linguagem DTDL v2. Para saber mais, consulte Extensão do IoT Central.
Propriedades
Por padrão, as propriedades são somente leitura. Propriedades somente leitura significam que o dispositivo relata atualizações de valor de propriedade para seu aplicativo IoT Central. Seu aplicativo 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 IoT Central e relatar atualizações de valor de propriedade para seu 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 deve significar 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 de dispositivo retorna um código de status de estado desejado, versão e descrição para indicar se recebeu e aplicou o valor da propriedade.
Propriedades da cloud
Você também pode adicionar propriedades de nuvem ao componente raiz do modelo. As propriedades de nuvem permitem especificar quaisquer metadados de dispositivo para armazenar no aplicativo IoT Central. Os valores de propriedade de nuvem são armazenados no aplicativo IoT Central e nunca são sincronizados com um dispositivo. As propriedades de nuvem não afetam o código que um desenvolvedor de dispositivo escreve para implementar o modelo de dispositivo.
Um desenvolvedor de soluções pode adicionar propriedades de nuvem a exibições e formulários de dispositivos ao lado de propriedades de dispositivos 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 visualizar a telemetria em visualizações e gráficos de dispositivos e usar regras para acionar 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 painéis de aplicativos e pessoais.
Você pode usar o recurso de exportação de dados do 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 ser conectado quando o comando chegar. Se o dispositivo responder a tempo, ou se o dispositivo não estiver conectado, o comando falhará.
Os comandos podem ter parâmetros de solicitação e retornar uma resposta.
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.
Os comandos offline são notificações unidirecionais para o dispositivo a partir da sua solução. Os comandos offline podem ter parâmetros de solicitação, mas não retornam uma resposta.
Nota
Os comandos offline são marcados como durable se você exportasse o modelo como DTDL.
Os comandos offline usam mensagens de nuvem para dispositivo do Hub IoT para enviar o comando e a carga útil para o dispositivo.
A carga útil 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 alguns exemplos de cargas úteis:
| Esquema de solicitação do IoT Central | Exemplo de carga útil recebida por dispositivo |
|---|---|
| Sem parâmetro de solicitação | @ |
| Duplo | 1.23 |
| String | sample string |
| Object | {"StartTime":"2021-01-05T08:00:00.000Z","Bank":2} |
O trecho a seguir de um modelo de dispositivo mostra a definição de um comando. O comando tem um parâmetro object 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"
}
}
]
}
}
}
Se você habilitar a opção Fila se estiver offline na interface do usuário do modelo de dispositivo para o comando no trecho anterior, a mensagem que o dispositivo recebe 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} |
Visualizações
Um desenvolvedor de soluções cria exibições que permitem que os operadores monitorem e gerenciem dispositivos conectados. As vistas fazem parte do modelo de dispositivo, pelo que uma vista está associada a um tipo de dispositivo específico. Uma vista pode incluir:
- Gráficos para plotar telemetria.
- Blocos para exibir propriedades do 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 da nuvem.
- Blocos para permitir que o operador chame comandos, incluindo comandos que esperam uma carga útil.
- Blocos para exibir rótulos, imagens ou texto de marcação.
Próximos passos
Agora que você já aprendeu sobre modelos de dispositivo, uma próxima etapa sugerida é ler Telemetria, propriedade e cargas úteis de comando para saber mais sobre os dados que um dispositivo troca com o IoT Central.