Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Como parte do ciclo de vida do dispositivo, talvez seja necessário configurar seus dispositivos IoT a partir do serviço back-end. Ao enviar uma configuração desejada para seus dispositivos, você também deseja receber atualizações de status e conformidade desses dispositivos. Por exemplo, você pode definir um intervalo de temperatura operacional de destino para um dispositivo ou coletar informações de versão de firmware de seus dispositivos.
Para sincronizar informações de estado entre um dispositivo e um hub IoT, use gêmeos de dispositivo. Um gêmeo de dispositivo é um documento JSON, associado a um dispositivo específico e armazenado pelo Hub IoT na nuvem, onde você pode consultá-los . Um dispositivo gêmeo contém propriedades desejadas, propriedades relatadas e tags.
- Uma propriedade desejada é definida por uma aplicação back-end e lida por um dispositivo.
- Uma propriedade relatada é definida por um dispositivo e lida por uma aplicação de back-end.
- Uma tag é definida por um aplicativo back-end e nunca é enviada para um dispositivo. Você usa tags para organizar seus dispositivos.
Este tutorial mostra como usar as propriedades desejadas e relatadas para sincronizar informações de estado.
Neste tutorial, vai realizar as seguintes tarefas:
- Crie um hub IoT e adicione um dispositivo de teste ao registro de identidade.
- Use as propriedades desejadas para enviar informações de estado para o dispositivo simulado.
- Use as propriedades relatadas para receber informações de estado do seu dispositivo simulado.
Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Pré-requisitos
Este tutorial usa a CLI do Azure para criar recursos de nuvem. Se você já tiver um hub IoT com um dispositivo registrado nele, poderá ignorar essas etapas. Há duas maneiras de executar comandos da CLI:
Use o ambiente Bash na Azure Cloud Shell. Para obter mais informações, consulte Azure Cloud Shell Quickstart - Bash.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se você estiver executando no Windows ou macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
- Entre na CLI do Azure usando o comando az login .
- Quando lhe for pedido, instale as extensões do CLI do Azure durante a primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
- Execute az version para descobrir a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.
Os dois aplicativos de exemplo que você executa neste tutorial são escritos usando Node.js. Você precisa Node.js v10.x.x ou posterior em sua máquina de desenvolvimento.
Pode descarregar o Node.js para várias plataformas a partir de nodejs.org.
Pode verificar qual a versão atual do Node.js no seu computador de desenvolvimento através do seguinte comando:
node --version
Clone ou baixe o projeto de exemplo de Node.js dos exemplos do Azure IoT para Node.js.
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo neste tutorial usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode estar bloqueada em alguns ambientes de rede corporativa e educacional. Para obter mais informações e maneiras de contornar esse problema, consulte Conectando-se ao Hub IoT (MQTT).
Configurar recursos do Azure
Para concluir este tutorial, sua assinatura do Azure deve conter um hub IoT com um dispositivo adicionado ao registro de identidade do dispositivo. A entrada no registro de identidade do dispositivo permite que o dispositivo simulado executado neste tutorial se conecte ao seu hub.
Se você ainda não tiver um hub IoT configurado em sua assinatura, poderá configurá-lo com o seguinte script CLI. Esse script usa o nome tutorial-iot-hub com um número aleatório anexado para o nome do hub IoT. Você pode substituir esse nome por seu próprio nome globalmente exclusivo ao executá-lo. O script cria o grupo de recursos e o hub na região dos EUA Central , que você pode alterar para uma região mais próxima de você. O script recupera sua cadeia de conexão de serviço de hub IoT, que você usa no exemplo de back-end para se conectar ao seu hub IoT:
let "randomIdentifier=$RANDOM*$RANDOM"
hubname="tutorial-iot-hub-$randomIdentifier"
location=centralus
# Install the IoT extension if it's not already installed:
az extension add --name azure-iot
# Create a resource group:
az group create --name tutorial-iot-hub-rg --location $location
# Create your free-tier IoT hub. You can only have one free IoT hub per subscription.
# Change the sku to S1 to create a standard-tier hub if necessary.
az iot hub create --name $hubname --location $location --resource-group tutorial-iot-hub-rg --partition-count 2 --sku F1
# Make a note of the service connection string, you need it later:
az iot hub connection-string show --hub-name $hubname --policy-name service -o table
Este tutorial usa um dispositivo simulado chamado MyTwinDevice. O script a seguir adiciona esse dispositivo ao seu registro de identidade e recupera sua cadeia de conexão:
# Create the device in the identity registry:
az iot hub device-identity create --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg
# Retrieve the device connection string, you need this later:
az iot hub device-identity connection-string show --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg -o table
Enviar informações de estado para um dispositivo
Você usa as propriedades desejadas para enviar informações de estado de um aplicativo back-end para um dispositivo. Nesta seção, você verá como:
- Configure um dispositivo para receber e processar as propriedades desejadas.
- Envie as propriedades desejadas de um aplicativo back-end para um dispositivo.
Propriedades desejadas da amostra
Você pode estruturar as propriedades desejadas de qualquer maneira que seja conveniente para sua aplicação. Este exemplo usa uma propriedade de nível superior chamada fanOn e agrupa as propriedades restantes em componentes separados. O trecho JSON a seguir mostra a estrutura das propriedades desejadas usadas neste tutorial. O JSON está no arquivo desired.json.
{
"fanOn": "true",
"components": {
"system": {
"id": "17",
"units": "farenheit",
"firmwareVersion": "9.75"
},
"wifi" : {
"channel" : "6",
"ssid": "my_network"
},
"climate" : {
"minTemperature": "68",
"maxTemperature": "76"
}
}
}
Receber as propriedades desejadas em um aplicativo de dispositivo
Para visualizar o código de exemplo de dispositivo simulado que recebe as propriedades desejadas, navegue até a pasta iot-hub/Tutorials/DeviceTwins no projeto de Node.js de exemplo que você baixou. Em seguida, abra o arquivo SimulatedDevice.js em um editor de texto.
As seções a seguir descrevem o código executado no dispositivo simulado que responde às alterações de propriedade desejadas enviadas do aplicativo back-end.
Recuperar o objeto gêmeo do dispositivo
Quando registou o seu dispositivo no hub IoT, obteve uma string de conexão do dispositivo como resultado. Uma cadeia de conexão de dispositivo é usada pelo dispositivo para autenticar com sua identidade registrada na nuvem. O código a seguir se conecta ao seu hub IoT usando uma cadeia de conexão de dispositivo:
// Get the device connection string from a command line argument
var connectionString = process.argv[2];
O código a seguir obtém um gêmeo do objeto cliente:
// Get the device twin
client.getTwin(function(err, twin) {
if (err) {
console.error(chalk.red('Could not get device twin'));
} else {
console.log(chalk.green('Device twin created'));
Criar manipuladores
Você pode criar manipuladores para atualizações de propriedade desejadas que respondem a atualizações em diferentes níveis na hierarquia JSON. Por exemplo, esse manipulador vê todas as alterações de propriedade desejadas enviadas para o dispositivo a partir de um aplicativo back-end. A variável delta contém as propriedades desejadas enviadas do back-end da solução:
// Handle all desired property updates
twin.on('properties.desired', function(delta) {
console.log(chalk.yellow('\nNew desired properties received in patch:'));
O manipulador a seguir só reage às alterações feitas na propriedade desejada fanOn :
// Handle changes to the fanOn desired property
twin.on('properties.desired.fanOn', function(fanOn) {
console.log(chalk.green('\nSetting fan state to ' + fanOn));
// Update the reported property after processing the desired property
reportedPropertiesPatch.fanOn = fanOn ? fanOn : '{unknown}';
});
Manipuladores para várias propriedades
No exemplo de propriedades desejadas JSON para este tutorial, o nó de clima sob componentes contém duas propriedades, minTemperature e maxTemperature.
O objeto gêmeo local de um dispositivo armazena um conjunto completo de propriedades desejadas e relatadas. O delta enviado do back-end pode atualizar apenas um subconjunto de propriedades desejadas. No trecho de código a seguir, se o dispositivo simulado receber uma atualização para apenas um de minTemperature e maxTemperature, ele usará o valor no gêmeo local para o outro valor para configurar o dispositivo:
// Handle desired properties updates to the climate component
twin.on('properties.desired.components.climate', function(delta) {
if (delta.minTemperature || delta.maxTemperature) {
console.log(chalk.green('\nUpdating desired tempertures in climate component:'));
console.log('Configuring minimum temperature: ' + twin.properties.desired.components.climate.minTemperature);
console.log('Configuring maximum temperture: ' + twin.properties.desired.components.climate.maxTemperature);
// Update the reported properties and send them to the hub
reportedPropertiesPatch.minTemperature = twin.properties.desired.components.climate.minTemperature;
reportedPropertiesPatch.maxTemperature = twin.properties.desired.components.climate.maxTemperature;
sendReportedProperties();
}
});
Manipular operações de inserção, atualização e exclusão
As propriedades desejadas enviadas do back-end não indicam qual operação está a ser executada numa certa propriedade desejada. Seu código precisa inferir a operação a partir do conjunto atual de propriedades desejadas armazenadas localmente e as alterações enviadas do hub.
O trecho a seguir mostra como o dispositivo simulado manipula operações de inserção, atualização e exclusão na lista de componentes nas propriedades desejadas. Você pode ver como usar valores nulos para indicar que um componente deve ser excluído:
// Keep track of all the components the device knows about
var componentList = {};
// Use this componentList list and compare it to the delta to infer
// if anything was added, deleted, or updated.
twin.on('properties.desired.components', function(delta) {
if (delta === null) {
componentList = {};
}
else {
Object.keys(delta).forEach(function(key) {
if (delta[key] === null && componentList[key]) {
// The delta contains a null value, and the
// device has a record of this component.
// Must be a delete operation.
console.log(chalk.green('\nDeleting component ' + key));
delete componentList[key];
} else if (delta[key]) {
if (componentList[key]) {
// The delta contains a component, and the
// device has a record of it.
// Must be an update operation.
console.log(chalk.green('\nUpdating component ' + key + ':'));
console.log(JSON.stringify(delta[key]));
// Store the complete object instead of just the delta
componentList[key] = twin.properties.desired.components[key];
} else {
// The delta contains a component, and the
// device has no record of it.
// Must be an add operation.
console.log(chalk.green('\nAdding component ' + key + ':'));
console.log(JSON.stringify(delta[key]));
// Store the complete object instead of just the delta
componentList[key] = twin.properties.desired.components[key];
}
}
});
}
});
Enviar propriedades desejadas de uma aplicação back-end
Você viu como um dispositivo implementa manipuladores para receber atualizações de propriedade desejadas. Esta seção mostra como enviar as alterações de propriedade desejadas para um dispositivo a partir de um aplicativo back-end.
Para visualizar o código de exemplo de dispositivo simulado que recebe as propriedades desejadas, navegue até a pasta iot-hub/Tutorials/DeviceTwins no projeto de Node.js de exemplo que você baixou. Em seguida, abra o arquivo ServiceClient.js em um editor de texto.
O trecho de código a seguir mostra como se conectar ao registro de identidade do dispositivo e acessar o gêmeo para um dispositivo específico:
// Create a device identity registry object
var registry = Registry.fromConnectionString(connectionString);
// Get the device twin and send desired property update patches at intervals.
// Print the reported properties after some of the desired property updates.
registry.getTwin(deviceId, async (err, twin) => {
if (err) {
console.error(err.message);
} else {
console.log('Got device twin');
O trecho seguinte mostra os diferentes patches de propriedades desejadas que a aplicação back-end envia para o dispositivo.
// Turn the fan on
var twinPatchFanOn = {
properties: {
desired: {
patchId: "Switch fan on",
fanOn: "false",
}
}
};
// Set the maximum temperature for the climate component
var twinPatchSetMaxTemperature = {
properties: {
desired: {
patchId: "Set maximum temperature",
components: {
climate: {
maxTemperature: "92"
}
}
}
}
};
// Add a new component
var twinPatchAddWifiComponent = {
properties: {
desired: {
patchId: "Add WiFi component",
components: {
wifi: {
channel: "6",
ssid: "my_network"
}
}
}
}
};
// Update the WiFi component
var twinPatchUpdateWifiComponent = {
properties: {
desired: {
patchId: "Update WiFi component",
components: {
wifi: {
channel: "13",
ssid: "my_other_network"
}
}
}
}
};
// Delete the WiFi component
var twinPatchDeleteWifiComponent = {
properties: {
desired: {
patchId: "Delete WiFi component",
components: {
wifi: null
}
}
}
};
O trecho a seguir mostra como o aplicativo back-end envia uma atualização de propriedade desejada para um dispositivo:
// Send a desired property update patch
async function sendDesiredProperties(twin, patch) {
twin.update(patch, (err, twin) => {
if (err) {
console.error(err.message);
} else {
console.log(chalk.green(`\nSent ${twin.properties.desired.patchId} patch:`));
console.log(JSON.stringify(patch, null, 2));
}
});
}
Receber informações de estado de um dispositivo
Seu aplicativo back-end recebe informações de estado de um dispositivo como propriedades relatadas. Um dispositivo define as propriedades relatadas e as envia para o hub. Um aplicativo back-end pode ler os valores atuais das propriedades relatadas do dispositivo gêmeo armazenado em seu hub.
Enviar propriedades relatadas de um dispositivo
Você pode enviar atualizações para valores de propriedade relatados como um patch. O trecho a seguir mostra um modelo para o patch que o dispositivo simulado envia. O dispositivo simulado atualiza os campos no patch antes de enviá-lo para o hub:
// Create a patch to send to the hub
var reportedPropertiesPatch = {
firmwareVersion:'1.2.1',
lastPatchReceivedId: '',
fanOn:'',
minTemperature:'',
maxTemperature:''
};
O dispositivo simulado usa a seguinte função para enviar o patch que contém as propriedades relatadas para o hub:
// Send the reported properties patch to the hub
function sendReportedProperties() {
twin.properties.reported.update(reportedPropertiesPatch, function(err) {
if (err) throw err;
console.log(chalk.blue('\nTwin state reported'));
console.log(JSON.stringify(reportedPropertiesPatch, null, 2));
});
}
Processar propriedades relatadas
Uma aplicação back-end acede aos valores de propriedades atualmente reportados para um dispositivo através do gémeo digital do dispositivo. O trecho a seguir mostra como o aplicativo back-end lê os valores de propriedade relatados para o dispositivo simulado:
// Display the reported properties from the device
function printReportedProperties(twin) {
console.log("Last received patch: " + twin.properties.reported.lastPatchReceivedId);
console.log("Firmware version: " + twin.properties.reported.firmwareVersion);
console.log("Fan status: " + twin.properties.reported.fanOn);
console.log("Min temperature set: " + twin.properties.reported.minTemperature);
console.log("Max temperature set: " + twin.properties.reported.maxTemperature);
}
Executar as aplicações
Nesta seção, você executa os dois aplicativos de exemplo para observar como um aplicativo back-end envia atualizações de propriedade desejadas para um aplicativo de dispositivo simulado.
Para executar o dispositivo simulado e os aplicativos back-end, você precisa das cadeias de conexão de dispositivo e serviço. Você anotou as cadeias de conexão quando criou os recursos no início deste tutorial.
Para executar o aplicativo de dispositivo simulado, abra uma janela de shell ou prompt de comando e navegue até a pasta iot-hub/Tutorials/DeviceTwins no projeto Node.js que você baixou. Em seguida, execute os seguintes comandos:
npm install
node SimulatedDevice.js "{your device connection string}"
Para executar a aplicação back-end, abra outro terminal ou janela de prompt de comando. Em seguida, navegue até a pasta iot-hub/Tutorials/DeviceTwins no projeto Node.js que você baixou. Em seguida, execute os seguintes comandos:
npm install
node ServiceClient.js "{your service connection string}"
Acompanhe as atualizações das propriedades desejadas
A captura de ecrã seguinte mostra o resultado da aplicação do dispositivo simulado e destaca como uma atualização para a propriedade desejada maxTemperature é tratada. Você pode ver como o manipulador de nível superior e os manipuladores de componentes de clima são executados:
A captura de ecrã seguinte mostra a saída da aplicação back-end e destaca como ela envia uma atualização para a propriedade maxTemperature desejada:
Observe as atualizações de propriedade relatadas
A captura de tela a seguir mostra a saída do aplicativo de dispositivo simulado e destaca como ele envia uma atualização de propriedade relatada para seu hub:
A captura de tela a seguir mostra a saída do aplicativo back-end e destaca como ele recebe e processa uma atualização de propriedade relatada de um dispositivo:
Limpar recursos
Se você planeja concluir o próximo tutorial, deixe o grupo de recursos e o hub IoT para reutilizá-los mais tarde.
Se já não precisar do Hub IoT, elimine-o, bem como ao grupo de recursos, no portal. Para fazer isso, selecione o grupo de recursos tutorial-iot-hub-rg que contém seu hub IoT e selecione Excluir.
Em alternativa, utilize a CLI:
# Delete your resource group and its contents
az group delete --name tutorial-iot-hub-rg
Próximos passos
Neste tutorial, você aprendeu como sincronizar informações de estado entre seus dispositivos e seu hub IoT. Avance para o próximo tutorial para aprender a usar gêmeos de dispositivo para implementar o processo de atualização de dispositivo.