Tutorial - Usar o MQTT para desenvolver um cliente do dispositivo IoT sem usar um SDK do dispositivo
Você deve usar um dos SDKs do Dispositivo IoT do Azure para criar seus clientes do 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 desse tutorial usam a biblioteca MQTT do Eclipse Mosquitto.
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 Windows ou Linux para concluir as etapas desse tutorial.
Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Pré-requisitos
Preparar o ambiente para a CLI do Azure
Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.
Pré-requisitos do computador de desenvolvimento
Se estiver usando o Windows:
Instale o Visual Studio (Community, Professional ou Enterprise). Certifique-se de habilitar a carga de trabalho Desenvolvimento de área de trabalho com C++.
Instale o CMake. Habilite a opção Adicionar o CMake ao CAMINHO do sistema para todos os usuários.
Instale a versão x64 do Mosquitto.
Se estiver usando o Linux:
Execute o seguinte comando para instalar as ferramentas do build:
sudo apt install cmake g++Execute o seguinte comando para instalar a biblioteca de clientes do Mosquitto:
sudo apt install libmosquitto-dev
Configurar seu ambiente
Se você ainda não tiver um hub IoT, execute os seguintes comandos para criar um de camada gratuita 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 em seu hub IoT. O comando a seguir registra um dispositivo chamado mqtt-dev-01 em um hub IoT chamado my-hub. Certifique-se de usar 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. Certifique-se de usar 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 se parece com 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 opção --du 7200 no comando anterior estende a duração do token para duas horas. Se 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.
Clone o repositório de amostra
Use o seguinte comando para clonar o repositório de exemplo em um local adequado no computador local:
git clone https://github.com/Azure-Samples/IoTMQTTSample.git
O repositório também inclui:
- Um exemplo do Python que usa a biblioteca
paho-mqtt. - Instruções para usar a CLI
mosquitto_pubpara interagir com o hub IoT.
Compilar os exemplos de C
Antes de compilar o exemplo, adicione 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. Certifique-se de usar 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. Certifique-se de usar 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 obtidos 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 função main define o nome de usuário e a senha para autenticar com o hub IoT. A senha é o token SAS que você criou para o 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 Envio de mensagens do dispositivo para 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. Certifique-se de usar 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 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 do 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, confira Usar o MQTT para receber mensagens de nuvem para dispositivo.
Atualizar um dispositivo gêmeo
O exemplo 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 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 função message_callback é 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 abaixo mostra a função message_callback:
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, confira Usar o MQTT para atualizar uma propriedade relatada do dispositivo gêmeo e Usar o MQTT para recuperar uma propriedade do dispositivo gêmeo.
Limpar 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 MQTT do Mosquitto para se comunicar com o hub IoT, uma próxima etapa sugerida é examinar: