Compartilhar via

Tutorial – Usar o MQTT para desenvolver um cliente de dispositivo IoT sem usar um SDK do dispositivo

Você deve usar um dos SDKs de Dispositivo IoT do Azure para criar seus clientes de dispositivo IoT, se possível. No entanto, em cenários como o uso de um dispositivo com restrição de memória, talvez seja necessário usar uma biblioteca MQTT para se comunicar com o hub IoT.

Os exemplos neste tutorial usam a biblioteca Eclipse Mosquitto MQTT.

Neste tutorial, você aprenderá como:

  • Crie os aplicativos de exemplo do cliente do dispositivo de linguagem C.
  • Execute um exemplo que usa a biblioteca MQTT para enviar telemetria.
  • Execute um exemplo que usa a biblioteca MQTT para processar uma mensagem de nuvem para dispositivo enviada do hub IoT.
  • Execute um exemplo que usa a biblioteca MQTT para gerenciar o dispositivo gêmeo no dispositivo.

Você pode usar um computador de desenvolvimento do Windows ou do Linux para concluir as etapas neste tutorial.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

Pré-requisitos do computador de desenvolvimento

  1. Instale o Visual Studio (Comunidade, Profissional ou Enterprise). Certifique-se de habilitar a carga de trabalho Desenvolvimento da área de trabalho com C++.

  2. Instale o CMake. Habilite a opção Adicionar CMake ao PATH do sistema para todos os usuários .

  3. Instale a versão x64 do Mosquitto.

Preparar o ambiente para a CLI do Azure

Configure seu ambiente

Se você ainda não tiver um hub IoT, execute os comandos a seguir para criar um hub IoT de camada livre em um grupo de recursos chamado mqtt-sample-rg. O comando usa o nome my-hub como um exemplo para o nome do hub IoT a ser criado. Escolha um nome exclusivo para o hub IoT a ser usado no lugar de my-hub:

az group create --name mqtt-sample-rg --location eastus
az iot hub create --name my-hub --resource-group mqtt-sample-rg --sku F1

Anote o nome do hub IoT, você precisará dele mais tarde.

Registre um dispositivo no hub IoT. O comando a seguir registra um dispositivo chamado mqtt-dev-01 em um hub IoT chamado my-hub. Use o nome do hub IoT:

az iot hub device-identity create --hub-name my-hub --device-id mqtt-dev-01

Use o comando a seguir para criar um token SAS que conceda ao dispositivo acesso ao hub IoT. Use o nome do hub IoT:

az iot hub generate-sas-token --device-id mqtt-dev-01 --hub-name my-hub --du 7200

Anote o token SAS que o comando gera, pois você precisará dele mais tarde. O token SAS tem a aparência SharedAccessSignature sr=my-hub.azure-devices.net%2Fdevices%2Fmqtt-dev-01&sig=%2FnM...sNwtnnY%3D&se=1677855761

Dica

Por padrão, o token SAS é válido por 60 minutos. A --du 7200 opção no comando anterior estende a duração do token para duas horas. Se ele expirar antes de você estar pronto para usá-lo, gere um novo. Você também pode criar um token com uma duração mais longa. Para saber mais, confira az iot hub generate-sas-token.

Importante

Este artigo inclui etapas para conectar um dispositivo usando uma assinatura de acesso compartilhado, também chamada de autenticação de chave simétrica. Esse método de autenticação é conveniente para teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, confira as melhores práticas de segurança para segurança de conexão de soluções > de IoT.

Clone o repositório de amostra

Use o seguinte comando para clonar o repositório de exemplo em um local adequado em seu computador local:

git clone https://github.com/Azure-Samples/IoTMQTTSample.git

O repositório também inclui:

  • Um exemplo do Python que usa a paho-mqtt biblioteca.
  • Instruções para usar a mosquitto_pub CLI para interagir com o hub IoT.

Compilar os exemplos de C

Antes de compilar o exemplo, você precisa adicionar os detalhes do hub IoT e do dispositivo. No repositório IoTMQTTSample clonado, abra o arquivo mosquitto/src/config.h . Adicione o nome do hub IoT, a ID do dispositivo e o token SAS da seguinte maneira. Use o nome do hub IoT:

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

#define IOTHUBNAME "my-hub"
#define DEVICEID   "mqtt-dev-01"
#define SAS_TOKEN  "SharedAccessSignature sr=my-hub.azure-devices.net%2Fdevices%2Fmqtt-dev-01&sig=%2FnM...sNwtnnY%3D&se=1677855761"

#define CERTIFICATEFILE CERT_PATH "IoTHubRootCA.crt.pem"

Observação

O arquivo IoTHubRootCA.crt.pem inclui os certificados raiz da AC na conexão TLS.

Salve as alterações no arquivo mosquitto/src/config.h .

Para compilar os exemplos, execute os seguintes comandos no shell:

cd mosquitto
cmake -Bbuild
cmake --build build

No Linux, os binários estão na pasta ./build abaixo da pasta mosquitto .

No Windows, os binários estão na pasta .\build\Debug abaixo da pasta mosquitto .

Enviar telemetria

O exemplo mosquitto_telemetry mostra como enviar uma mensagem de telemetria do dispositivo para nuvem para o hub IoT usando a biblioteca MQTT.

Antes de executar o aplicativo de exemplo, execute o comando a seguir para iniciar o monitor de eventos do hub IoT. Use o nome do hub IoT:

az iot hub monitor-events --hub-name my-hub

Execute o exemplo mosquitto_telemetry. Por exemplo, no Linux:

./build/mosquitto_telemetry

O az iot hub monitor-events gera a seguinte saída que mostra o conteúdo enviado pelo dispositivo:

Starting event monitor, use ctrl-c to stop...
{
    "event": {
        "origin": "mqtt-dev-01",
        "module": "",
        "interface": "",
        "component": "",
        "payload": "Bonjour MQTT from Mosquitto"
    }
}

Agora você pode interromper o monitor de eventos.

Examine o código

Os snippets a seguir são retirados do arquivo mosquitto/src/mosquitto_telemetry.cpp .

As instruções a seguir definem as informações de conexão e o nome do tópico MQTT que você usa para enviar a mensagem de telemetria:

#define HOST IOTHUBNAME ".azure-devices.net"
#define PORT 8883
#define USERNAME HOST "/" DEVICEID "/?api-version=2020-09-30"

#define TOPIC "devices/" DEVICEID "/messages/events/"

A main função define o nome de usuário e a senha para autenticar com o hub IoT. A senha é o token SAS que você criou para seu dispositivo:

mosquitto_username_pw_set(mosq, USERNAME, SAS_TOKEN);

O exemplo usa o tópico MQTT para enviar uma mensagem de telemetria para o hub IoT:

int msgId  = 42;
char msg[] = "Bonjour MQTT from Mosquitto";

// once connected, we can publish a Telemetry message
printf("Publishing....\r\n");
rc = mosquitto_publish(mosq, &msgId, TOPIC, sizeof(msg) - 1, msg, 1, true);
if (rc != MOSQ_ERR_SUCCESS)
{
    return mosquitto_error(rc);
}
printf("Publish returned OK\r\n");

Para saber mais, confira Como enviar mensagens do dispositivo para a nuvem.

Receber uma mensagem de nuvem para dispositivo

O exemplo mosquitto_subscribe mostra como assinar tópicos MQTT e receber uma mensagem de nuvem para dispositivo do hub IoT usando a biblioteca MQTT.

Execute o exemplo mosquitto_subscribe. Por exemplo, no Linux:

./build/mosquitto_subscribe

Execute o comando a seguir para enviar uma mensagem de nuvem para dispositivo do hub IoT. Use o nome do hub IoT:

az iot device c2d-message send --hub-name my-hub --device-id mqtt-dev-01 --data "hello world"

A saída de mosquitto_subscribe se parece com o seguinte exemplo:

Waiting for C2D messages...
C2D message 'hello world' for topic 'devices/mqtt-dev-01/messages/devicebound/%24.mid=d411e727-...f98f&%24.to=%2Fdevices%2Fmqtt-dev-01%2Fmessages%2Fdevicebound&%24.ce=utf-8&iothub-ack=none'
Got message for devices/mqtt-dev-01/messages/# topic

Examine o código

Os snippets a seguir são obtidos do arquivo mosquitto/src/mosquitto_subscribe.cpp .

A instrução a seguir define o filtro de tópico que o dispositivo usa para receber mensagens de nuvem para dispositivo. O # é um curinga de vários níveis:

#define DEVICEMESSAGE "devices/" DEVICEID "/messages/#"

A função main usa a função mosquitto_message_callback_set para definir um retorno de chamada para manipular mensagens enviadas do hub IoT e usa a função mosquitto_subscribe para assinar todas as mensagens. O snippet abaixo mostra a função de retorno de chamada:

void message_callback(struct mosquitto* mosq, void* obj, const struct mosquitto_message* message)
{
    printf("C2D message '%.*s' for topic '%s'\r\n", message->payloadlen, (char*)message->payload, message->topic);

    bool match = 0;
    mosquitto_topic_matches_sub(DEVICEMESSAGE, message->topic, &match);

    if (match)
    {
        printf("Got message for " DEVICEMESSAGE " topic\r\n");
    }
}

Para saber mais, consulte Usar MQTT para receber mensagens de nuvem para dispositivo.

Atualizar um dispositivo gêmeo

O exemplo de mosquitto_device_twin mostra como definir uma propriedade relatada em um dispositivo gêmeo e, em seguida, ler a propriedade novamente.

Execute o exemplo mosquitto_device_twin. Por exemplo, no Linux:

./build/mosquitto_device_twin

A saída de mosquitto_device_twin se parece com o seguinte exemplo:

Setting device twin reported properties....
Device twin message '' for topic '$iothub/twin/res/204/?$rid=0&$version=2'
Setting device twin properties SUCCEEDED.

Getting device twin properties....
Device twin message '{"desired":{"$version":1},"reported":{"temperature":32,"$version":2}}' for topic '$iothub/twin/res/200/?$rid=1'
Getting device twin properties SUCCEEDED.

Examine o código

Os snippets a seguir são obtidos do arquivo mosquitto/src/mosquitto_device_twin.cpp .

As instruções a seguir definem os tópicos que o dispositivo usa para assinar atualizações do dispositivo gêmeo, ler o dispositivo gêmeo e atualizar o dispositivo gêmeo:

#define DEVICETWIN_SUBSCRIPTION  "$iothub/twin/res/#"
#define DEVICETWIN_MESSAGE_GET   "$iothub/twin/GET/?$rid=%d"
#define DEVICETWIN_MESSAGE_PATCH "$iothub/twin/PATCH/properties/reported/?$rid=%d"

A função main usa a função mosquitto_connect_callback_set para definir um retorno de chamada para manipular mensagens enviadas do hub IoT e usa a função mosquitto_subscribe para assinar o tópico $iothub/twin/res/#.

O snippet a seguir mostra a função connect_callback que usa mosquitto_publish para definir uma propriedade relatada no dispositivo gêmeo. O dispositivo publica a mensagem no tópico $iothub/twin/PATCH/properties/reported/?$rid=%d. O valor %d é incrementado sempre que o dispositivo publica uma mensagem no tópico:

void connect_callback(struct mosquitto* mosq, void* obj, int result)
{
    // ... other code ...  

    printf("\r\nSetting device twin reported properties....\r\n");

    char msg[] = "{\"temperature\": 32}";
    char mqtt_publish_topic[64];
    snprintf(mqtt_publish_topic, sizeof(mqtt_publish_topic), DEVICETWIN_MESSAGE_PATCH, device_twin_request_id++);

    int rc = mosquitto_publish(mosq, NULL, mqtt_publish_topic, sizeof(msg) - 1, msg, 1, true);
    if (rc != MOSQ_ERR_SUCCESS)

    // ... other code ...  
}

O dispositivo assina o tópico $iothub/twin/res/#, e, quando recebe uma mensagem do hub IoT, a função message_callback o manipula. Quando você executa o exemplo, a message_callback função é chamada duas vezes. Na primeira vez, o dispositivo recebe uma resposta do hub IoT para a atualização da propriedade relatada. Em seguida, o dispositivo solicita o dispositivo gêmeo. Na segunda vez, o dispositivo recebe o dispositivo gêmeo solicitado. O snippet a seguir mostra a message_callback função:

void message_callback(struct mosquitto* mosq, void* obj, const struct mosquitto_message* message)
{
    printf("Device twin message '%.*s' for topic '%s'\r\n", message->payloadlen, (char*)message->payload, message->topic);

    const char patchTwinTopic[] = "$iothub/twin/res/204/?$rid=0";
    const char getTwinTopic[]   = "$iothub/twin/res/200/?$rid=1";

    if (strncmp(message->topic, patchTwinTopic, sizeof(patchTwinTopic) - 1) == 0)
    {
        // Process the reported property response and request the device twin
        printf("Setting device twin properties SUCCEEDED.\r\n\r\n");

        printf("Getting device twin properties....\r\n");

        char msg[] = "{}";
        char mqtt_publish_topic[64];
        snprintf(mqtt_publish_topic, sizeof(mqtt_publish_topic), DEVICETWIN_MESSAGE_GET, device_twin_request_id++);

        int rc = mosquitto_publish(mosq, NULL, mqtt_publish_topic, sizeof(msg) - 1, msg, 1, true);
        if (rc != MOSQ_ERR_SUCCESS)
        {
            printf("Error: %s\r\n", mosquitto_strerror(rc));
        }
    }
    else if (strncmp(message->topic, getTwinTopic, sizeof(getTwinTopic) - 1) == 0)
    {
        // Process the device twin response and stop the client
        printf("Getting device twin properties SUCCEEDED.\r\n\r\n");

        mosquitto_loop_stop(mosq, false);
        mosquitto_disconnect(mosq); // finished, exit program
    }
}

Para saber mais, consulte Usar MQTT para atualizar uma propriedade relatada do dispositivo gêmeo e usar MQTT para recuperar uma propriedade do dispositivo gêmeo.

Limpar os recursos

Se planeja continuar com mais artigos para desenvolvedores de dispositivos, guarde e use novamente os recursos usados nesse artigo. Caso contrário, exclua os recursos criados neste artigo para evitar mais encargos.

Você pode excluir o hub e o dispositivo registrado ao mesmo tempo excluindo o grupo de recursos inteiro com o comando da CLI do Azure a seguir. Não use esse comando se esses recursos estiverem compartilhando um grupo de recursos com outros recursos que você desejar manter.

az group delete --name <YourResourceGroupName>

Para excluir apenas o hub IoT, execute o seguinte comando usando a CLI do Azure:

az iot hub delete --name <YourIoTHubName>

Para excluir apenas a identidade do dispositivo registrada no hub IoT, execute o seguinte comando usando a CLI do Azure:

az iot hub device-identity delete --hub-name <YourIoTHubName> --device-id <YourDeviceID>

Talvez você também queira remover os arquivos de exemplo clonados do seu computador de desenvolvimento.

Próximas etapas

Agora que você aprendeu a usar a biblioteca Mosquitto MQTT para se comunicar com o Hub IoT, uma próxima etapa sugerida é examinar os exemplos de aplicativo MQTT no GitHub.