Tutorial: Conectar um IoT Plug and Play vários aplicativos de dispositivo componente em execução no Linux ou Windows ao Hub IoT

Este tutorial mostra como criar um aplicativo de dispositivo IoT Plug and Play de exemplo com componentes, conectá-lo ao seu hub IoT e usar a ferramenta Azure IoT explorer para exibir as informações que ele envia para o hub. O aplicativo de exemplo é escrito em C e está incluído no SDK do dispositivo IoT do Azure para C. Um construtor de soluções pode usar a ferramenta Azure IoT explorer para entender os recursos de um dispositivo IoT Plug and Play sem a necessidade de exibir qualquer código de dispositivo.

Neste tutorial:

Pré-requisitos

Antes de continuar, certifique-se de que configurou o seu ambiente, incluindo o seu hub IoT.

Você pode concluir este tutorial no Linux ou Windows. Os comandos shell neste tutorial seguem a convenção do Linux para separadores de caminho '/', se você estiver acompanhando no Windows, certifique-se de trocar esses separadores por '\'.

Os pré-requisitos diferem de acordo com o sistema operacional:

Linux

Este tutorial assume que você está usando o Ubuntu Linux. As etapas neste tutorial foram testadas usando o Ubuntu 18.04.

Para concluir este tutorial no Linux, instale o seguinte software em seu ambiente Linux local:

Instale GCC, Git, cmake e todas as dependências necessárias usando o apt-get comando:

sudo apt-get update
sudo apt-get install -y git cmake build-essential curl libcurl4-openssl-dev libssl-dev uuid-dev

Verifique se a versão do está acima de cmake 2.8.12 e a versão do GCC está acima de 4.4.7.

cmake --version
gcc --version

Windows

Para concluir este tutorial no Windows, instale o seguinte software em seu ambiente Windows local:

• Visual Studio (Community, Professional ou Enterprise) - certifique-se de incluir o Desktop Development com carga de trabalho C++ ao instalar o Visual Studio.
• Git.
• CMake.

Transferir o código

Se você concluiu o Tutorial: Conectar um aplicativo de dispositivo IoT Plug and Play de exemplo em execução no Linux ou Windows ao Hub IoT (C), você já baixou o código.

Neste tutorial, você prepara um ambiente de desenvolvimento que pode usar para clonar e criar o SDK C do Dispositivo do Hub IoT do Azure.

Abra um prompt de comando em uma pasta de sua escolha. Execute o seguinte comando para clonar os SDKs do Azure IoT C e o repositório GitHub de bibliotecas neste local:

git clone https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init

Espere que esta operação demore vários minutos a concluir.

Compilar e executar o código

Você pode criar e executar o código usando o Visual Studio ou cmake na linha de comando.

Utilizar o Visual Studio

1. Abra a pasta raiz do repositório clonado. Após alguns segundos, o suporte a CMake no Visual Studio cria tudo o que você precisa para executar e depurar o projeto.

2. Quando o Visual Studio estiver pronto, no Gerenciador de Soluções, navegue até o exemplo iothub_client/samples/pnp/pnp_temperature_controller/.

3. Clique com o botão direito do mouse no arquivo pnp_temperature_controller.c e selecione Adicionar configuração de depuração. Selecione Padrão.

4. O Visual Studio abre o arquivo launch.vs.json . Edite esse arquivo conforme mostrado no trecho a seguir para definir as variáveis de ambiente necessárias. Você anotou o ID do escopo e a chave primária de registro quando concluiu Configurar seu ambiente para os tutoriais e inícios rápidos do IoT Plug and Play:

   {
     "version": "0.2.1",
     "defaults": {},
     "configurations": [
       {
         "type": "default",
         "project": "iothub_client\\samples\\pnp\\pnp_temperature_controller\\pnp_temperature_controller.c",
         "projectTarget": "",
         "name": "pnp_temperature_controller.c",
         "env": {
           "IOTHUB_DEVICE_SECURITY_TYPE": "DPS",
           "IOTHUB_DEVICE_DPS_ID_SCOPE": "<Your ID scope>",
           "IOTHUB_DEVICE_DPS_DEVICE_ID": "my-pnp-device",
           "IOTHUB_DEVICE_DPS_DEVICE_KEY": "<Your enrollment primary key>"
         }
       }
     ]
   }
   

5. Clique com o botão direito do mouse no arquivo pnp_temperature_controller.c e selecione Definir como item de inicialização.

6. Para rastrear a execução de código no Visual Studio, adicione um ponto de interrupção para a main função no arquivo pnp_temperature_controller.c .

7. Agora você pode executar e depurar o exemplo no menu Depurar .

O dispositivo agora está pronto para receber comandos e atualizações de propriedade e começou a enviar dados de telemetria para o hub. Mantenha o exemplo em execução enquanto conclui as próximas etapas.

Uso cmake na linha de comando

Para criar o exemplo:

1. Crie uma subpasta cmake na pasta raiz do SDK do dispositivo clonado e navegue até essa pasta:

   cd azure-iot-sdk-c
   mkdir cmake
   cd cmake
   

2. Execute os seguintes comandos para gerar e compilar os arquivos de projeto para SDK e exemplos:

   cmake ..
   cmake --build .
   

Em Configurar seu ambiente, você criou quatro variáveis de ambiente para configurar o exemplo para usar o DPS (Serviço de Provisionamento de Dispositivo) para se conectar ao seu hub IoT:

• IOTHUB_DEVICE_SECURITY_TYPE com o valorDPS
• IOTHUB_DEVICE_DPS_ID_SCOPE com o escopo DPS ID.
• IOTHUB_DEVICE_DPS_DEVICE_ID com o valor my-pnp-device.
• IOTHUB_DEVICE_DPS_DEVICE_KEY com a chave primária de inscrição.
• IOTHUB_DEVICE_DPS_ENDPOINT com o valor global.azure-devices-provisioning.net.

Para saber mais sobre a configuração de exemplo, consulte o Leiame de exemplo.

Para executar o exemplo:

1. A partir da pasta cmake , navegue até a pasta que contém o arquivo executável e execute-o:

   # Bash
   cd iothub_client/samples/pnp/pnp_temperature_controller
   ./pnp_temperature_controller
   

   REM Windows
   cd iothub_client\samples\pnp\pnp_temperature_controller\Debug
   pnp_temperature_controller.exe
   

O dispositivo agora está pronto para receber comandos e atualizações de propriedade e começou a enviar dados de telemetria para o hub. Mantenha o exemplo em execução enquanto conclui as próximas etapas.

Usar o Azure IoT explorer para validar o código

Depois que o exemplo de cliente de dispositivo for iniciado, use a ferramenta Azure IoT explorer para verificar se está funcionando.

1. Abra o explorador do Azure IoT.

2. Na página Hubs IoT, se você ainda não adicionou uma conexão ao seu hub IoT, selecione + Adicionar conexão. Insira a cadeia de conexão para o hub IoT que você criou anteriormente e selecione Salvar.

3. Na página Configurações do IoT Plug and Play, selecione + Adicionar > pasta local e selecione a pasta de modelos locais onde você salvou seus arquivos de modelo.

4. Na página Hubs IoT, clique no nome do hub com o qual você deseja trabalhar. Você verá uma lista de dispositivos registrados no hub IoT.

5. Clique no ID do dispositivo que você criou anteriormente.

6. O menu à esquerda mostra os diferentes tipos de informações disponíveis para o dispositivo.

7. Selecione Componentes IoT Plug and Play para visualizar as informações do modelo do seu dispositivo.

8. Você pode visualizar os diferentes componentes do dispositivo. O componente padrão e quaisquer outros extras. Selecione um componente para trabalhar.

9. Selecione a página Telemetria e, em seguida, selecione Iniciar para exibir os dados de telemetria que o dispositivo está enviando para esse componente.

10. Selecione a página Propriedades (somente leitura) para exibir as propriedades somente leitura relatadas para este componente.

11. Selecione a página Propriedades (graváveis) para exibir as propriedades graváveis que você pode atualizar para esse componente.

12. Selecione uma propriedade pelo nome, insira um novo valor para ela e selecione Atualizar valor desejado.

13. Para ver o novo valor aparecer, selecione o botão Atualizar .

14. Selecione a página Comandos para visualizar todos os comandos deste componente.

15. Selecione o comando que deseja testar, defina o parâmetro, se houver. Selecione Enviar comando para chamar o comando no dispositivo. Você pode ver seu dispositivo responder ao comando na janela do prompt de comando onde o código de exemplo está sendo executado.

Rever o código

Este exemplo implementa um dispositivo controlador de temperatura IoT Plug and Play. Este exemplo implementa um modelo com vários componentes. O arquivo de modelo DTDL (Digital Twins Definition Language) para o dispositivo de temperatura define a telemetria, as propriedades e os comandos que o dispositivo implementa.

Funções auxiliares do IoT Plug and Play

Para este exemplo, o código usa algumas funções auxiliares da pasta /common :

pnp_device_client_ll contém o método connect para IoT Plug and Play com o model-id incluído como parâmetro: PnP_CreateDeviceClientLLHandle.

pnp_protocol: contém as funções auxiliares do IoT Plug and Play:

• PnP_CreateReportedProperty
• PnP_CreateReportedPropertyWithStatus
• PnP_ParseCommandName
• PnP_CreateTelemetryMessageHandle
• PnP_ProcessTwinData
• PnP_CopyPayloadToString
• PnP_CreateDeviceClientLLHandle_ViaDps

Essas funções auxiliares são genéricas o suficiente para serem usadas em seu próprio projeto. Este exemplo os usa nos três arquivos que correspondem a cada componente do modelo:

• pnp_deviceinfo_component
• pnp_temperature_controller
• pnp_thermostat_component

Por exemplo, no arquivo pnp_deviceinfo_component , a SendReportedPropertyForDeviceInformation função usa duas das funções auxiliares:

if ((jsonToSend = PnP_CreateReportedProperty(componentName, propertyName, propertyValue)) == NULL)
{
    LogError("Unable to build reported property response for propertyName=%s, propertyValue=%s", propertyName, propertyValue);
}
else
{
    const char* jsonToSendStr = STRING_c_str(jsonToSend);
    size_t jsonToSendStrLen = strlen(jsonToSendStr);

    if ((iothubClientResult = IoTHubDeviceClient_LL_SendReportedState(deviceClientLL, (const unsigned char*)jsonToSendStr, jsonToSendStrLen, NULL, NULL)) != IOTHUB_CLIENT_OK)
    {
        LogError("Unable to send reported state for property=%s, error=%d", propertyName, iothubClientResult);
    }
    else
    {
        LogInfo("Sending device information property to IoTHub.  propertyName=%s, propertyValue=%s", propertyName, propertyValue);
    }
}

Cada componente da amostra segue este padrão.

Fluxo de código

A main função inicializa a conexão e envia o ID do modelo:

deviceClient = CreateDeviceClientAndAllocateComponents();

O código usa PnP_CreateDeviceClientLLHandle para se conectar ao hub IoT, definido modelId como uma opção, e configurar o método de dispositivo e manipuladores de retorno de chamada gêmeos de dispositivo para métodos diretos e atualizações de gêmeos de dispositivo:

g_pnpDeviceConfiguration.deviceMethodCallback = PnP_TempControlComponent_DeviceMethodCallback;
g_pnpDeviceConfiguration.deviceTwinCallback = PnP_TempControlComponent_DeviceTwinCallback;
g_pnpDeviceConfiguration.modelId = g_temperatureControllerModelId;
...

deviceClient = PnP_CreateDeviceClientLLHandle(&g_pnpDeviceConfiguration);

&g_pnpDeviceConfiguration também contém as informações de conexão. A variável de ambiente IOTHUB_DEVICE_SECURITY_TYPE determina se o exemplo usa uma cadeia de conexão ou o serviço de provisionamento de dispositivo para se conectar ao hub IoT.

Quando o dispositivo envia um ID de modelo, ele se torna um dispositivo IoT Plug and Play.

Com os manipuladores de retorno de chamada instalados, o dispositivo reage a atualizações gêmeas e chamadas diretas de método:

• Para o retorno de chamada gêmeo do dispositivo, o PnP_TempControlComponent_DeviceTwinCallback chama a PnP_ProcessTwinData função para processar os dados. PnP_ProcessTwinData usa o padrão de visitante para analisar o JSON e, em seguida, visitar cada propriedade, chamando PnP_TempControlComponent_ApplicationPropertyCallback cada elemento.

• Para o retorno de chamada de comandos, a PnP_TempControlComponent_DeviceMethodCallback função usa a função auxiliar para analisar os nomes de comandos e componentes:

  PnP_ParseCommandName(methodName, &componentName, &componentNameSize, &pnpCommandName);
  

  Em PnP_TempControlComponent_DeviceMethodCallback seguida, a função chama o comando no componente:

  LogInfo("Received PnP command for component=%.*s, command=%s", (int)componentNameSize, componentName, pnpCommandName);
  if (strncmp((const char*)componentName, g_thermostatComponent1Name, g_thermostatComponent1Size) == 0)
  {
      result = PnP_ThermostatComponent_ProcessCommand(g_thermostatHandle1, pnpCommandName, rootValue, response, responseSize);
  }
  else if (strncmp((const char*)componentName, g_thermostatComponent2Name, g_thermostatComponent2Size) == 0)
  {
      result = PnP_ThermostatComponent_ProcessCommand(g_thermostatHandle2, pnpCommandName, rootValue, response, responseSize);
  }
  else
  {
      LogError("PnP component=%.*s is not supported by TemperatureController", (int)componentNameSize, componentName);
      result = PNP_STATUS_NOT_FOUND;
  }
  

A main função inicializa as propriedades somente leitura enviadas para o hub IoT:

PnP_TempControlComponent_ReportSerialNumber_Property(deviceClient);
PnP_DeviceInfoComponent_Report_All_Properties(g_deviceInfoComponentName, deviceClient);
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(g_thermostatHandle1, deviceClient);
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(g_thermostatHandle2, deviceClient);

A main função insere um loop para atualizar dados de evento e telemetria para cada componente:

while (true)
{
    PnP_TempControlComponent_SendWorkingSet(deviceClient);
    PnP_ThermostatComponent_SendTelemetry(g_thermostatHandle1, deviceClient);
    PnP_ThermostatComponent_SendTelemetry(g_thermostatHandle2, deviceClient);
}

A PnP_ThermostatComponent_SendTelemetry função mostra como usar o PNP_THERMOSTAT_COMPONENT struct. A amostra usa essa estrutura para armazenar informações sobre os dois termostatos no controlador de temperatura. O código usa a PnP_CreateTelemetryMessageHandle função para preparar a mensagem e enviá-la:

messageHandle = PnP_CreateTelemetryMessageHandle(pnpThermostatComponent->componentName, temperatureStringBuffer);
...
iothubResult = IoTHubDeviceClient_LL_SendEventAsync(deviceClientLL, messageHandle, NULL, NULL);

A main função finalmente destrói os diferentes componentes e fecha a conexão com o hub.

Este tutorial mostra como criar um aplicativo de dispositivo IoT Plug and Play de exemplo com componentes, conectá-lo ao seu hub IoT e usar a ferramenta Azure IoT explorer para exibir as informações que ele envia para o hub. O aplicativo de exemplo é escrito em C# e está incluído no SDK do dispositivo IoT do Azure para C#. Um construtor de soluções pode usar a ferramenta Azure IoT explorer para entender os recursos de um dispositivo IoT Plug and Play sem a necessidade de exibir qualquer código de dispositivo.

Neste tutorial:

Pré-requisitos

Antes de continuar, certifique-se de que configurou o seu ambiente, incluindo o seu hub IoT.

Você pode executar este tutorial no Linux ou Windows. Os comandos shell neste tutorial seguem a convenção do Linux para separadores de caminho '/', se você estiver acompanhando no Windows, certifique-se de trocar esses separadores por '\'.

• O SDK .NET mais recente para sua plataforma.
• Git.

Clone o repositório do SDK com o código de exemplo

Se você concluiu o Tutorial: Conectar um aplicativo de dispositivo IoT Plug and Play de exemplo em execução no Windows ao Hub IoT (C#), já clonou o repositório.

Clone os exemplos do repositório GitHub de Exemplos do Azure IoT para C#. Abra um prompt de comando em uma pasta de sua escolha. Execute o seguinte comando para clonar o Microsoft Azure IoT SDK para repositório .NET GitHub:

git clone https://github.com/Azure/azure-iot-sdk-csharp.git

Compilar o código

Agora você pode compilar o exemplo e executá-lo. Execute os seguintes comandos para criar o exemplo:

cd azure-iot-sdk-csharp/iothub/device/samples/solutions/PnpDeviceSamples/TemperatureController
dotnet build

Executar o exemplo de dispositivo

Para executar o exemplo, execute o seguinte comando:

dotnet run

O dispositivo agora está pronto para receber comandos e atualizações de propriedade e começou a enviar dados de telemetria para o hub. Mantenha o exemplo em execução enquanto conclui as próximas etapas.

Usar o Azure IoT explorer para validar o código

Depois que o exemplo de cliente de dispositivo for iniciado, use a ferramenta Azure IoT explorer para verificar se está funcionando.

1. Abra o explorador do Azure IoT.

2. Na página Hubs IoT, se você ainda não adicionou uma conexão ao seu hub IoT, selecione + Adicionar conexão. Insira a cadeia de conexão para o hub IoT que você criou anteriormente e selecione Salvar.

3. Na página Configurações do IoT Plug and Play, selecione + Adicionar > pasta local e selecione a pasta de modelos locais onde você salvou seus arquivos de modelo.

4. Na página Hubs IoT, clique no nome do hub com o qual você deseja trabalhar. Você verá uma lista de dispositivos registrados no hub IoT.

5. Clique no ID do dispositivo que você criou anteriormente.

6. O menu à esquerda mostra os diferentes tipos de informações disponíveis para o dispositivo.

7. Selecione Componentes IoT Plug and Play para visualizar as informações do modelo do seu dispositivo.

8. Você pode visualizar os diferentes componentes do dispositivo. O componente padrão e quaisquer outros extras. Selecione um componente para trabalhar.

9. Selecione a página Telemetria e, em seguida, selecione Iniciar para exibir os dados de telemetria que o dispositivo está enviando para esse componente.

10. Selecione a página Propriedades (somente leitura) para exibir as propriedades somente leitura relatadas para este componente.

11. Selecione a página Propriedades (graváveis) para exibir as propriedades graváveis que você pode atualizar para esse componente.

12. Selecione uma propriedade pelo nome, insira um novo valor para ela e selecione Atualizar valor desejado.

13. Para ver o novo valor aparecer, selecione o botão Atualizar .

14. Selecione a página Comandos para visualizar todos os comandos deste componente.

15. Selecione o comando que deseja testar, defina o parâmetro, se houver. Selecione Enviar comando para chamar o comando no dispositivo. Você pode ver seu dispositivo responder ao comando na janela do prompt de comando onde o código de exemplo está sendo executado.

Rever o código

Este exemplo implementa um dispositivo controlador de temperatura IoT Plug and Play. O modelo que este exemplo implementa usa vários componentes. O arquivo de modelo DTDL (Digital Twins Definition Language) para o dispositivo de temperatura define a telemetria, as propriedades e os comandos que o dispositivo implementa.

O código do dispositivo se conecta ao seu hub IoT usando o método padrão CreateFromConnectionString . O dispositivo envia o ID do modelo DTDL que implementa na solicitação de conexão. Um dispositivo que envia um ID de modelo é um dispositivo IoT Plug and Play:

private static DeviceClient InitializeDeviceClient(string hostname, IAuthenticationMethod authenticationMethod)
{
    var options = new ClientOptions
    {
        ModelId = ModelId,
    };

    var deviceClient = DeviceClient.Create(hostname, authenticationMethod, TransportType.Mqtt, options);
    deviceClient.SetConnectionStatusChangesHandler((status, reason) =>
    {
        s_logger.LogDebug($"Connection status change registered - status={status}, reason={reason}.");
    });

    return deviceClient;
}

O ID do modelo é armazenado no código conforme mostrado no seguinte trecho:

private const string ModelId = "dtmi:com:example:TemperatureController;1";

Depois que o dispositivo se conecta ao hub IoT, o código registra os manipuladores de comando. O reboot comando é definido no componente padrão. O getMaxMinReport comando é definido em cada um dos dois componentes do termostato:

await _deviceClient.SetMethodHandlerAsync("reboot", HandleRebootCommandAsync, _deviceClient, cancellationToken);
await _deviceClient.SetMethodHandlerAsync("thermostat1*getMaxMinReport", HandleMaxMinReportCommandAsync, Thermostat1, cancellationToken);
await _deviceClient.SetMethodHandlerAsync("thermostat2*getMaxMinReport", HandleMaxMinReportCommandAsync, Thermostat2, cancellationToken);

Existem manipuladores separados para as atualizações de propriedade desejadas nos dois componentes do termostato:

_desiredPropertyUpdateCallbacks.Add(Thermostat1, TargetTemperatureUpdateCallbackAsync);
_desiredPropertyUpdateCallbacks.Add(Thermostat2, TargetTemperatureUpdateCallbackAsync);

O código de exemplo envia telemetria de cada componente do termostato:

await SendTemperatureAsync(Thermostat1, cancellationToken);
await SendTemperatureAsync(Thermostat2, cancellationToken);

O SendTemperatureTelemetryAsync método usa a PnpHhelper classe para criar mensagens para cada componente:

using Message msg = PnpHelper.CreateIothubMessageUtf8(telemetryName, JsonConvert.SerializeObject(currentTemperature), componentName);

A PnpHelper classe contém outros métodos de exemplo que você pode usar com um modelo de vários componentes.

Use a ferramenta Azure IoT explorer para exibir a telemetria e as propriedades dos dois componentes do termostato:

Você também pode usar a ferramenta Azure IoT explorer para chamar comandos em qualquer um dos dois componentes do termostato ou no componente padrão.

Este tutorial mostra como criar um aplicativo de dispositivo IoT Plug and Play de exemplo com componentes, conectá-lo ao seu hub IoT e usar a ferramenta Azure IoT explorer para exibir as informações que ele envia para o hub. O aplicativo de exemplo é escrito em Java e está incluído no SDK do dispositivo IoT do Azure para Java. Um construtor de soluções pode usar a ferramenta Azure IoT explorer para entender os recursos de um dispositivo IoT Plug and Play sem a necessidade de exibir qualquer código de dispositivo.

Neste tutorial:

Pré-requisitos

Antes de continuar, certifique-se de que configurou o seu ambiente, incluindo o seu hub IoT.

Você pode executar este tutorial no Linux ou Windows. Os comandos shell neste tutorial seguem a convenção do Linux para separadores de caminho '/', se você estiver acompanhando no Windows, certifique-se de trocar esses separadores por '\'.

Para concluir este tutorial, instale o seguinte software em seu ambiente de desenvolvimento local:

• Java SE Development Kit 8 ou posterior.
• Apache Maven 3.

Transferir o código

Se você concluiu o Tutorial: Conectar um aplicativo de dispositivo IoT Plug and Play de exemplo ao Hub IoT (Java), já clonou o repositório.

Abra um prompt de comando no diretório de sua escolha. Execute o seguinte comando para clonar os SDKs Java do Azure IoT e o repositório GitHub de bibliotecas neste local:

git clone https://github.com/Azure/azure-iot-sdk-java.git

Espere que esta operação demore vários minutos a concluir.

Compilar o código

Navegue até a pasta raiz do exemplo do controlador de temperatura no repositório clonado do Java SDK e construa-o:

cd azure-iot-sdk-java/device/iot-device-samples/pnp-device-sample/temperature-controller-device-sample
mvn clean package

Executar o exemplo de dispositivo

Em Configurar seu ambiente, você criou quatro variáveis de ambiente para configurar o exemplo para usar o DPS (Serviço de Provisionamento de Dispositivo) para se conectar ao seu hub IoT:

• IOTHUB_DEVICE_SECURITY_TYPE com o valorDPS
• IOTHUB_DEVICE_DPS_ID_SCOPE com o escopo DPS ID.
• IOTHUB_DEVICE_DPS_DEVICE_ID com o valor my-pnp-device.
• IOTHUB_DEVICE_DPS_DEVICE_KEY com a chave primária de inscrição.
• IOTHUB_DEVICE_DPS_ENDPOINT com o valor global.azure-devices-provisioning.net.

Para executar o aplicativo de exemplo, navegue até a pasta /device/iot-device-samples/pnp-device-sample/temperature-controller-device-sample e execute o seguinte comando:

mvn exec:java -Dexec.mainClass="samples.com.microsoft.azure.sdk.iot.device.TemperatureController"

O dispositivo agora está pronto para receber comandos e atualizações de propriedade e começou a enviar dados de telemetria para o hub. Mantenha o exemplo em execução enquanto conclui as próximas etapas.

Usar o Azure IoT explorer para validar o código

Depois que o exemplo de cliente de dispositivo for iniciado, use a ferramenta Azure IoT explorer para verificar se está funcionando.

1. Abra o explorador do Azure IoT.

2. Na página Hubs IoT, se você ainda não adicionou uma conexão ao seu hub IoT, selecione + Adicionar conexão. Insira a cadeia de conexão para o hub IoT que você criou anteriormente e selecione Salvar.

3. Na página Configurações do IoT Plug and Play, selecione + Adicionar > pasta local e selecione a pasta de modelos locais onde você salvou seus arquivos de modelo.

4. Na página Hubs IoT, clique no nome do hub com o qual você deseja trabalhar. Você verá uma lista de dispositivos registrados no hub IoT.

5. Clique no ID do dispositivo que você criou anteriormente.

6. O menu à esquerda mostra os diferentes tipos de informações disponíveis para o dispositivo.

7. Selecione Componentes IoT Plug and Play para visualizar as informações do modelo do seu dispositivo.

8. Você pode visualizar os diferentes componentes do dispositivo. O componente padrão e quaisquer outros extras. Selecione um componente para trabalhar.

9. Selecione a página Telemetria e, em seguida, selecione Iniciar para exibir os dados de telemetria que o dispositivo está enviando para esse componente.

10. Selecione a página Propriedades (somente leitura) para exibir as propriedades somente leitura relatadas para este componente.

11. Selecione a página Propriedades (graváveis) para exibir as propriedades graváveis que você pode atualizar para esse componente.

12. Selecione uma propriedade pelo nome, insira um novo valor para ela e selecione Atualizar valor desejado.

13. Para ver o novo valor aparecer, selecione o botão Atualizar .

14. Selecione a página Comandos para visualizar todos os comandos deste componente.

15. Selecione o comando que deseja testar, defina o parâmetro, se houver. Selecione Enviar comando para chamar o comando no dispositivo. Você pode ver seu dispositivo responder ao comando na janela do prompt de comando onde o código de exemplo está sendo executado.

Rever o código

Este exemplo implementa um dispositivo controlador de temperatura IoT Plug and Play. O modelo que este exemplo implementa usa vários componentes. O arquivo de modelo DTDL (Digital Twins Definition Language) para o dispositivo de temperatura define a telemetria, as propriedades e os comandos que o dispositivo implementa.

O código do dispositivo usa a classe padrão DeviceClient para se conectar ao seu hub IoT. O dispositivo envia o ID do modelo DTDL que implementa na solicitação de conexão. Um dispositivo que envia um ID de modelo é um dispositivo IoT Plug and Play:

private static void initializeDeviceClient() throws URISyntaxException, IOException {
    ClientOptions options = new ClientOptions();
    options.setModelId(MODEL_ID);
    deviceClient = new DeviceClient(deviceConnectionString, protocol, options);

    deviceClient.registerConnectionStatusChangeCallback((status, statusChangeReason, throwable, callbackContext) -> {
        log.debug("Connection status change registered: status={}, reason={}", status, statusChangeReason);

        if (throwable != null) {
            log.debug("The connection status change was caused by the following Throwable: {}", throwable.getMessage());
            throwable.printStackTrace();
        }
    }, deviceClient);

    deviceClient.open();
}

O ID do modelo é armazenado no código conforme mostrado no seguinte trecho:

private static final String MODEL_ID = "dtmi:com:example:Thermostat;1";

Depois que o dispositivo se conecta ao hub IoT, o código registra os manipuladores de comando.

deviceClient.subscribeToDeviceMethod(new MethodCallback(), null, new MethodIotHubEventCallback(), null);

Existem manipuladores separados para as atualizações de propriedade desejadas nos dois componentes do termostato:

deviceClient.startDeviceTwin(new TwinIotHubEventCallback(), null, new GenericPropertyUpdateCallback(), null);
Map<Property, Pair<TwinPropertyCallBack, Object>> desiredPropertyUpdateCallback = Stream.of(
        new AbstractMap.SimpleEntry<Property, Pair<TwinPropertyCallBack, Object>>(
                new Property(THERMOSTAT_1, null),
                new Pair<>(new TargetTemperatureUpdateCallback(), THERMOSTAT_1)),
        new AbstractMap.SimpleEntry<Property, Pair<TwinPropertyCallBack, Object>>(
                new Property(THERMOSTAT_2, null),
                new Pair<>(new TargetTemperatureUpdateCallback(), THERMOSTAT_2))
).collect(Collectors.toMap(AbstractMap.SimpleEntry::getKey, AbstractMap.SimpleEntry::getValue));

deviceClient.subscribeToTwinDesiredProperties(desiredPropertyUpdateCallback);

O código de exemplo envia telemetria de cada componente do termostato:

sendTemperatureReading(THERMOSTAT_1);
sendTemperatureReading(THERMOSTAT_2);

O sendTemperatureReading método usa a PnpHhelper classe para criar mensagens para cada componente:

Message message = PnpHelper.createIotHubMessageUtf8(telemetryName, currentTemperature, componentName);

A PnpHelper classe contém outros métodos de exemplo que você pode usar com um modelo de vários componentes.

Use a ferramenta Azure IoT explorer para exibir a telemetria e as propriedades dos dois componentes do termostato:

Você também pode usar a ferramenta Azure IoT explorer para chamar comandos em qualquer um dos dois componentes do termostato ou no componente padrão.

Este tutorial mostra como criar um aplicativo de dispositivo IoT Plug and Play de exemplo com componentes, conectá-lo ao seu hub IoT e usar a ferramenta Azure IoT explorer para exibir as informações que ele envia para o hub. O aplicativo de exemplo foi escrito para Node.js e está incluído no SDK de Dispositivo do Hub IoT do Azure para Node.js. Um construtor de soluções pode usar a ferramenta Azure IoT explorer para entender os recursos de um dispositivo IoT Plug and Play sem a necessidade de exibir qualquer código de dispositivo.

Neste tutorial:

Pré-requisitos

Antes de continuar, certifique-se de que configurou o seu ambiente, incluindo o seu hub IoT.

Para concluir este tutorial, você precisa Node.js em sua máquina de desenvolvimento. Você pode baixar a versão recomendada mais recente para várias plataformas do nodejs.org.

Pode verificar qual a versão atual do Node.js no seu computador de desenvolvimento através do seguinte comando:

node --version

Transferir o código

Se você concluiu o Tutorial: Conectar um aplicativo de dispositivo IoT Plug and Play de exemplo em execução no Windows ao Hub IoT (Nó), já clonou o repositório.

Abra um prompt de comando no diretório de sua escolha. Execute o seguinte comando para clonar o SDK do Microsoft Azure IoT para Node.js repositório GitHub neste local:

git clone https://github.com/Azure/azure-iot-sdk-node

Instalar bibliotecas necessárias

Use o SDK do dispositivo para criar o código de exemplo incluído. O aplicativo que você cria simula um dispositivo Plug and Play com vários componentes que se conecta a um hub IoT. O aplicativo envia telemetria e propriedades e recebe comandos.

1. Em uma janela de terminal local, vá para a pasta do repositório clonado e navegue até a pasta /azure-iot-sdk-node/device/samples/javascript . Em seguida, execute o seguinte comando para instalar as bibliotecas necessárias:

npm install

Este comando instala os arquivos npm relevantes necessários para executar os exemplos na pasta.

Rever o código

Navegue até a pasta azure-iot-sdk-node/device/samples/javascript .

A pasta azure-iot-sdk-node/device/samples/javascript contém o código de exemplo para o dispositivo controlador de temperatura IoT Plug and Play.

O código no arquivo pnp_temperature_controller.js implementa um dispositivo controlador de temperatura IoT Plug and Play. O modelo que este exemplo implementa usa vários componentes. O arquivo de modelo DTDL (Digital Twins Definition Language) para o dispositivo de temperatura define a telemetria, as propriedades e os comandos que o dispositivo implementa.

Abra o arquivo pnp_temperature_controller.js em um editor de código de sua escolha. O código de exemplo mostra como:

• Defina o modelId que é a DTMI para o dispositivo que você está implementando. Esta DTMI é definida pelo usuário e deve corresponder à DTMI do modelo DTDL do controlador de temperatura.

• Implemente os componentes definidos no modelo DTDL do controlador de temperatura. Os componentes de um controlador de temperatura real devem implementar estas duas interfaces. Estas duas interfaces já estão publicadas num repositório central. Neste exemplo, as duas interfaces são:

  • Termóstato
  • Informações do dispositivo desenvolvidas pelo Azure

• Defina nomes de componentes. Esta amostra tem dois termostatos e um componente de informação do dispositivo.

• Defina nomes de comandos para os comandos aos quais o dispositivo responde.

• Defina a serialNumber constante. O é fixo serialNumber qualquer dispositivo dado.

• Defina os manipuladores de comando.

• Defina as funções para enviar respostas de comando.

• Defina funções auxiliares para registrar solicitações de comando.

• Defina uma função auxiliar para criar as propriedades.

• Defina um ouvinte para atualizações de propriedade.

• Defina uma função para enviar telemetria a partir deste dispositivo. Tanto os termostatos quanto o componente padrão enviam telemetria. Esta função recebe o nome do componente como parâmetro.

• Defina uma main função que:

  • Usa o SDK do dispositivo para criar um cliente de dispositivo e conectar-se ao seu hub IoT. O dispositivo fornece o para que o modelId Hub IoT possa identificar o dispositivo como um dispositivo IoT Plug and Play.

  • Começa a escutar solicitações de comando usando a onDeviceMethod função. A função configura um ouvinte para solicitações de comando do serviço:

    • O dispositivo DTDL define os reboot comandos e getMaxMinReport .
    • A commandHandler função define como o dispositivo responde a um comando.

  • Começa a enviar telemetria usando setInterval e sendTelemetry.

  • Usa a helperCreateReportedPropertiesPatch função para criar as propriedades e para updateComponentReportedProperties atualizar as propriedades.

  • Usa desiredPropertyPatchListener para ouvir atualizações de propriedade.

  • Desativa todos os ouvintes e tarefas e sai do loop quando você pressiona Q ou q.

Em Configurar seu ambiente, você criou quatro variáveis de ambiente para configurar o exemplo para usar o DPS (Serviço de Provisionamento de Dispositivo) para se conectar ao seu hub IoT:

• IOTHUB_DEVICE_SECURITY_TYPE com o valorDPS
• IOTHUB_DEVICE_DPS_ID_SCOPE com o escopo DPS ID.
• IOTHUB_DEVICE_DPS_DEVICE_ID com o valor my-pnp-device.
• IOTHUB_DEVICE_DPS_DEVICE_KEY com a chave primária de inscrição.
• IOTHUB_DEVICE_DPS_ENDPOINT com o valor global.azure-devices-provisioning.net.

Para saber mais sobre a configuração de exemplo, consulte o Leiame de exemplo.

Agora que você viu o código, use o seguinte comando para executar o exemplo:

node pnp_temperature_controller.js

Você verá a saída a seguir, indicando que o dispositivo começou a enviar dados de telemetria para o hub e agora está pronto para receber comandos e atualizações de propriedade.

Mantenha o exemplo em execução enquanto conclui as próximas etapas.

Usar o Azure IoT explorer para validar o código

Depois que o exemplo de cliente de dispositivo for iniciado, use a ferramenta Azure IoT explorer para verificar se está funcionando.

1. Abra o explorador do Azure IoT.

2. Na página Hubs IoT, se você ainda não adicionou uma conexão ao seu hub IoT, selecione + Adicionar conexão. Insira a cadeia de conexão para o hub IoT que você criou anteriormente e selecione Salvar.

3. Na página Configurações do IoT Plug and Play, selecione + Adicionar > pasta local e selecione a pasta de modelos locais onde você salvou seus arquivos de modelo.

4. Na página Hubs IoT, clique no nome do hub com o qual você deseja trabalhar. Você verá uma lista de dispositivos registrados no hub IoT.

5. Clique no ID do dispositivo que você criou anteriormente.

6. O menu à esquerda mostra os diferentes tipos de informações disponíveis para o dispositivo.

7. Selecione Componentes IoT Plug and Play para visualizar as informações do modelo do seu dispositivo.

8. Você pode visualizar os diferentes componentes do dispositivo. O componente padrão e quaisquer outros extras. Selecione um componente para trabalhar.

9. Selecione a página Telemetria e, em seguida, selecione Iniciar para exibir os dados de telemetria que o dispositivo está enviando para esse componente.

10. Selecione a página Propriedades (somente leitura) para exibir as propriedades somente leitura relatadas para este componente.

11. Selecione a página Propriedades (graváveis) para exibir as propriedades graváveis que você pode atualizar para esse componente.

12. Selecione uma propriedade pelo nome, insira um novo valor para ela e selecione Atualizar valor desejado.

13. Para ver o novo valor aparecer, selecione o botão Atualizar .

14. Selecione a página Comandos para visualizar todos os comandos deste componente.

15. Selecione o comando que deseja testar, defina o parâmetro, se houver. Selecione Enviar comando para chamar o comando no dispositivo. Você pode ver seu dispositivo responder ao comando na janela do prompt de comando onde o código de exemplo está sendo executado.

Este tutorial mostra como criar um aplicativo de dispositivo IoT Plug and Play de exemplo com componentes, conectá-lo ao seu hub IoT e usar a ferramenta Azure IoT explorer para exibir as informações que ele envia para o hub. O aplicativo de exemplo é escrito em Python e está incluído no SDK do dispositivo IoT do Azure para Python. Um construtor de soluções pode usar a ferramenta Azure IoT explorer para entender os recursos de um dispositivo IoT Plug and Play sem a necessidade de exibir qualquer código de dispositivo.

Neste tutorial:

Pré-requisitos

Antes de continuar, certifique-se de que configurou o seu ambiente, incluindo o seu hub IoT.

Você pode executar este tutorial no Linux ou Windows. Os comandos shell neste tutorial seguem a convenção do Linux para separadores de caminho '/', se você estiver acompanhando no Windows, certifique-se de trocar esses separadores por '\'.

Para concluir este tutorial, você precisa do Python instalado em sua máquina de desenvolvimento. Verifique o SDK do Python do Azure IoT para obter os requisitos de versão atuais do Python. Você pode verificar sua versão do Python com o seguinte comando:

python --version

Você pode baixar a versão recomendada mais recente para várias plataformas do python.org.

Transferir o código

O pacote azure-iot-device é publicado como um PIP.

Em seu ambiente Python local, instale o pacote da seguinte maneira:

pip install azure-iot-device

Se você concluiu o Tutorial: Conectar um aplicativo de dispositivo IoT Plug and Play de exemplo em execução no Windows ao Hub IoT (Python), já clonou o repositório.

Clone o repositório Python SDK IoT:

git clone --branch v2 https://github.com/Azure/azure-iot-sdk-python

Rever o código

Este exemplo implementa um dispositivo controlador de temperatura IoT Plug and Play. O modelo que este exemplo implementa usa vários componentes. O arquivo de modelo DTDL (Digital Twins Definition Language) para o dispositivo de temperatura define a telemetria, as propriedades e os comandos que o dispositivo implementa.

A pasta azure-iot-sdk-python/samples/pnp contém o código de exemplo para o dispositivo IoT Plug and Play. Os arquivos para a amostra do controlador de temperatura são:

• temp_controller_with_thermostats.py
• pnp_helper.py

O controlador de temperatura tem vários componentes e um componente padrão, baseado no modelo DTDL do controlador de temperatura.

Abra o arquivo temp_controller_with_thermostats.py em um editor de sua escolha. O código neste arquivo:

1. Importa pnp_helper.py para ter acesso a métodos auxiliares.

2. Define dois identificadores de modelo de gêmeo digital (DTMIs) que representam exclusivamente duas interfaces diferentes, definidas no modelo DTDL. Os componentes de um controlador de temperatura real devem implementar estas duas interfaces. Estas duas interfaces já estão publicadas num repositório central. Essas DTMIs devem ser conhecidas pelo usuário e variar dependendo do cenário de implementação do dispositivo. Para o exemplo atual, essas duas interfaces representam:

   • Um termostato
   • Informações do dispositivo desenvolvidas pelo Azure.

3. Define a DTMI model_id para o dispositivo que está sendo implementado. A DTMI é definida pelo usuário e deve corresponder à DTMI no arquivo de modelo DTDL.

4. Define os nomes dados aos componentes no arquivo DTDL. Existem dois termostatos na DTDL e um componente de informação do dispositivo. Uma constante chamada serial_number também é definida no componente padrão. Um serial_number dispositivo não pode ser alterado.

5. Define implementações do manipulador de comandos. Esses manipuladores definem o que o dispositivo faz quando recebe solicitações de comando.

6. Define funções para criar uma resposta de comando. Essas funções definem como o dispositivo responde às solicitações de comando. Você cria funções de resposta de comando se um comando precisar enviar uma resposta personalizada de volta para o hub IoT. Se uma função de resposta para um comando não for fornecida, uma resposta genérica será enviada. Neste exemplo, apenas o comando getMaxMinReport tem uma resposta personalizada.

7. Define uma função para enviar telemetria a partir deste dispositivo. Tanto os termostatos quanto o componente padrão enviam telemetria. Esta função tem um parâmetro opcional de nome de componente para permitir identificar qual componente enviou a telemetria.

8. Define um ouvinte para solicitações de comando.

9. Define um ouvinte para atualizações de propriedade desejadas.

10. Tem uma main função que:

    • Usa o SDK do dispositivo para criar um cliente de dispositivo e conectar-se ao seu hub IoT. O dispositivo envia o model_id para que o hub IoT possa identificar o dispositivo como um dispositivo IoT Plug and Play.

    • Usa a create_reported_properties função no arquivo auxiliar para criar as propriedades. Passe o nome do componente e as propriedades como pares de valores de chave para essa função.

    • Atualiza as propriedades legíveis de seus componentes chamando patch_twin_reported_properties.

    • Começa a escutar solicitações de comando usando a execute_command_listener função. A função configura um ouvinte para solicitações de comando do serviço. Ao configurar o ouvinte, você fornece um method_name, user_command_handlere um opcional create_user_response_handler como parâmetros.

      • O method_name define a solicitação de comando. Neste exemplo, o modelo define os comandos reboot e getMaxMinReport.
      • A user_command_handler função define o que o dispositivo deve fazer quando recebe um comando.
      • A create_user_response_handler função cria uma resposta a ser enviada ao seu hub IoT quando um comando é executado com êxito. Pode ver esta resposta no portal. Se essa função não for fornecida, uma resposta genérica será enviada ao serviço.

    • Usa execute_property_listener para ouvir atualizações de propriedade.

    • Começa a enviar telemetria usando send_telemetryo . O código de exemplo usa um loop para chamar três funções de envio de telemetria. Cada um é chamado a cada oito segundos

    • Desativa todos os ouvintes e tarefas e sai do loop quando você pressiona Q ou q.

Em Configurar seu ambiente, você criou quatro variáveis de ambiente para configurar o exemplo para usar o DPS (Serviço de Provisionamento de Dispositivo) para se conectar ao seu hub IoT:

• IOTHUB_DEVICE_SECURITY_TYPE com o valorDPS
• IOTHUB_DEVICE_DPS_ID_SCOPE com o escopo DPS ID.
• IOTHUB_DEVICE_DPS_DEVICE_ID com o valor my-pnp-device.
• IOTHUB_DEVICE_DPS_DEVICE_KEY com a chave primária de inscrição.
• IOTHUB_DEVICE_DPS_ENDPOINT com o valor global.azure-devices-provisioning.net.

Para saber mais sobre a configuração de exemplo, consulte o Leiame de exemplo.

Use o seguinte comando para executar o exemplo:

python temp_controller_with_thermostats.py

O dispositivo de exemplo envia mensagens de telemetria a cada poucos segundos para seu hub IoT.

Você verá a saída a seguir, que indica que o dispositivo está enviando dados de telemetria para o hub e agora está pronto para receber comandos e atualizações de propriedade.

Mantenha o exemplo em execução enquanto conclui as próximas etapas.

Usar o Azure IoT explorer para validar o código

Depois que o exemplo de cliente de dispositivo for iniciado, use a ferramenta Azure IoT explorer para verificar se está funcionando.

1. Abra o explorador do Azure IoT.

2. Na página Hubs IoT, se você ainda não adicionou uma conexão ao seu hub IoT, selecione + Adicionar conexão. Insira a cadeia de conexão para o hub IoT que você criou anteriormente e selecione Salvar.

3. Na página Configurações do IoT Plug and Play, selecione + Adicionar > pasta local e selecione a pasta de modelos locais onde você salvou seus arquivos de modelo.

4. Na página Hubs IoT, clique no nome do hub com o qual você deseja trabalhar. Você verá uma lista de dispositivos registrados no hub IoT.

5. Clique no ID do dispositivo que você criou anteriormente.

6. O menu à esquerda mostra os diferentes tipos de informações disponíveis para o dispositivo.

7. Selecione Componentes IoT Plug and Play para visualizar as informações do modelo do seu dispositivo.

8. Você pode visualizar os diferentes componentes do dispositivo. O componente padrão e quaisquer outros extras. Selecione um componente para trabalhar.

9. Selecione a página Telemetria e, em seguida, selecione Iniciar para exibir os dados de telemetria que o dispositivo está enviando para esse componente.

10. Selecione a página Propriedades (somente leitura) para exibir as propriedades somente leitura relatadas para este componente.

11. Selecione a página Propriedades (graváveis) para exibir as propriedades graváveis que você pode atualizar para esse componente.

12. Selecione uma propriedade pelo nome, insira um novo valor para ela e selecione Atualizar valor desejado.

13. Para ver o novo valor aparecer, selecione o botão Atualizar .

14. Selecione a página Comandos para visualizar todos os comandos deste componente.

15. Selecione o comando que deseja testar, defina o parâmetro, se houver. Selecione Enviar comando para chamar o comando no dispositivo. Você pode ver seu dispositivo responder ao comando na janela do prompt de comando onde o código de exemplo está sendo executado.