Tutorial - Menggunakan MQTT untuk mengembangkan klien perangkat IoT tanpa menggunakan SDK perangkat

2025-04-14

Anda harus menggunakan salah satu SDK Perangkat Azure IoT untuk membangun klien perangkat IoT Anda jika memungkinkan. Namun, dalam skenario seperti menggunakan perangkat yang dibatasi memori, Anda mungkin perlu menggunakan pustaka MQTT untuk berkomunikasi dengan hub IoT Anda.

Sampel dalam tutorial ini menggunakan pustaka Eclipse Mosquitto MQTT.

Dalam tutorial ini, Anda mempelajari cara:

Buat aplikasi sampel klien perangkat bahasa C.
Jalankan sampel yang menggunakan pustaka MQTT untuk mengirim telemetri.
Jalankan contoh yang menggunakan perpustakaan MQTT untuk memproses pesan dari cloud ke perangkat yang dikirim dari hub IoT Anda.
Run a sample that uses the MQTT library to manage the device twin on the device.

Anda dapat menggunakan mesin pengembangan Windows atau Linux untuk menyelesaikan langkah-langkah dalam tutorial ini.

Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

Prasyarat

Install Visual Studio (Community, Professional, or Enterprise). Be sure to enable the Desktop development with C++ workload.
Pasang CMake. Aktifkan opsi Tambahkan CMake ke PATH sistem untuk semua pengguna.
Install the x64 version of Mosquitto.

Persiapkan lingkungan Anda untuk Azure CLI

Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai menggunakan Azure Cloud Shell.
Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.
- Jika Anda menggunakan penginstalan lokal, masuk ke Azure CLI dengan menggunakan perintah az login. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Mengautentikasi ke Azure menggunakan Azure CLI.
- Saat diminta, instal ekstensi Azure CLI saat pertama kali digunakan. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan dan mengelola ekstensi dengan Azure CLI.
- Jalankan az version untuk mengetahui versi dan pustaka dependen yang terinstal. Untuk meningkatkan ke versi terbaru, jalankan az upgrade.

Siapkan lingkungan Anda

Jika Anda belum memiliki hub IoT, jalankan perintah berikut untuk membuat hub IoT tingkat bebas dalam grup sumber daya yang disebut mqtt-sample-rg. Perintah menggunakan nama my-hub sebagai contoh untuk nama hub IoT yang akan dibuat. Pilih nama unik untuk hub IoT Anda untuk digunakan sebagai ganti 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

Catat nama hub IoT Anda, Anda membutuhkannya nanti.

Daftarkan perangkat di hub IoT Anda. Perintah berikut mendaftarkan perangkat yang disebut mqtt-dev-01 di hub IoT yang disebut my-hub. Pastikan untuk menggunakan nama hub IoT Anda:

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

Gunakan perintah berikut untuk membuat token SAS yang memberikan akses perangkat ke hub IoT Anda. Pastikan untuk menggunakan nama hub IoT Anda:

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

Catat token SAS yang dihasilkan oleh perintah karena Anda akan membutuhkannya nanti. Token SAS terlihat seperti SharedAccessSignature sr=my-hub.azure-devices.net%2Fdevices%2Fmqtt-dev-01&sig=%2FnM...sNwtnnY%3D&se=1677855761

Petunjuk / Saran

Secara default, token SAS berlaku selama 60 menit. Opsi --du 7200 dalam perintah sebelumnya memperluas durasi token menjadi dua jam. Jika kedaluwarsa sebelum Anda siap menggunakannya, buat yang baru. Anda juga dapat membuat token dengan durasi yang lebih lama. To learn more, see az iot hub generate-sas-token.

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses berbagi, juga disebut autentikasi kunci simetris. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi > IoT Keamanan koneksi.

Clone the sample repository

Gunakan perintah berikut untuk mengkloning repositori sampel ke lokasi yang sesuai di komputer lokal Anda:

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

Repositori ini juga mencakup:

Sampel Python yang menggunakan pustaka paho-mqtt.
Instruksi untuk menggunakan CLI mosquitto_pub untuk berinteraksi dengan hub IoT Anda.

Membangun sampel C

Sebelum membuat sampel, Anda perlu menambahkan hub IoT dan detail perangkat. Di repositori IoTMQTTSample yang dikloning, buka file mosquitto/src/config.h. Tambahkan nama hub IoT, ID perangkat, dan token SAS Anda sebagai berikut. Pastikan untuk menggunakan nama hub IoT Anda:

// 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"

Nota

File IoTHubRootCA.crt.pem menyertakan sertifikat akar CA untuk koneksi TLS.

Simpan perubahan ke file mosquitto/src/config.h.

Untuk membuat sampel, jalankan perintah berikut di shell Anda:

cd mosquitto
cmake -Bbuild
cmake --build build

In Linux, the binaries are in the ./build folder underneath the mosquitto folder.

Di Windows, file biner berada di folder .\build\Debug di bawah folder mosquitto.

Send telemetry

The mosquitto_telemetry sample shows how to send a device-to-cloud telemetry message to your IoT hub by using the MQTT library.

Sebelum Anda menjalankan aplikasi sampel, jalankan perintah berikut untuk memulai pemantau peristiwa untuk hub IoT Anda. Pastikan untuk menggunakan nama hub IoT Anda:

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

Run the mosquitto_telemetry sample. Misalnya, di Linux:

./build/mosquitto_telemetry

az iot hub monitor-events menghasilkan output berikut yang menunjukkan payload yang dikirim oleh perangkat:

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

Anda sekarang dapat menghentikan monitor acara.

Meninjau kode

Cuplikan berikut diambil dari file mosquitto/src/mosquitto_telemetry.cpp.

Pernyataan berikut menentukan informasi koneksi dan nama topik MQTT yang Anda gunakan untuk mengirim pesan telemetri:

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

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

Fungsi main mengatur nama pengguna dan kata sandi untuk diautentikasi dengan hub IoT Anda. Kata sandi adalah token SAS yang Anda buat untuk perangkat Anda:

mosquitto_username_pw_set(mosq, USERNAME, SAS_TOKEN);

Sampel menggunakan topik MQTT untuk mengirim pesan telemetri ke hub IoT Anda:

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");

Untuk mempelajari selengkapnya, lihat Mengirim pesan perangkat ke cloud.

Menerima pesan dari cloud ke perangkat

The mosquitto_subscribe sample shows how to subscribe to MQTT topics and receive a cloud-to-device message from your IoT hub by using the MQTT library.

Run the mosquitto_subscribe sample. Misalnya, di Linux:

./build/mosquitto_subscribe

Jalankan perintah berikut untuk mengirim pesan cloud-ke-perangkat dari hub IoT Anda. Pastikan untuk menggunakan nama hub IoT Anda:

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

Hasil dari mosquitto_subscribe akan terlihat seperti contoh berikut:

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

Meninjau kode

Cuplikan berikut diambil dari file mosquitto/src/mosquitto_subscribe.cpp.

Pernyataan berikut menentukan filter topik yang digunakan perangkat untuk menerima pesan cloud ke perangkat. The # is a multi-level wildcard:

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

Fungsi main menggunakan fungsi mosquitto_message_callback_set untuk mengatur panggilan balik untuk menangani pesan yang dikirim dari hub IoT Anda dan menggunakan fungsi mosquitto_subscribe untuk berlangganan semua pesan. Cuplikan berikut menunjukkan fungsi panggilan balik:

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");
    }
}

Untuk mempelajari selengkapnya, lihat Cara menggunakan MQTT untuk menerima pesan dari cloud ke perangkat.

Update a device twin

The mosquitto_device_twin sample shows how to set a reported property in a device twin and then read the property back.

Run the mosquitto_device_twin sample. Misalnya, di Linux:

./build/mosquitto_device_twin

The output from mosquitto_device_twin looks like the following example:

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.

Meninjau kode

Cuplikan berikut diambil dari file mosquitto/src/mosquitto_device_twin.cpp.

The following statements define the topics the device uses to subscribe to device twin updates, read the device twin, and update the device twin:

#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"

Fungsi main menggunakan fungsi mosquitto_connect_callback_set untuk mengatur panggilan balik untuk menangani pesan yang dikirim dari hub IoT Anda dan menggunakan fungsi mosquitto_subscribe untuk berlangganan topik $iothub/twin/res/#.

The following snippet shows the connect_callback function that uses mosquitto_publish to set a reported property in the device twin. The device publishes the message to the $iothub/twin/PATCH/properties/reported/?$rid=%d topic. Nilai %d ditambahkan setiap kali perangkat menerbitkan pesan ke topik:

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 ...  
}

Perangkat berlangganan topik $iothub/twin/res/# dan ketika menerima pesan dari hub IoT Anda, fungsi message_callback menanganinya. Saat Anda menjalankan sampel, fungsi message_callback akan dipanggil dua kali. Pertama kali, perangkat menerima respons dari hub IoT ke pembaruan properti yang dilaporkan. The device then requests the device twin. The second time, the device receives the requested device twin. Cuplikan berikut menunjukkan fungsi 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
    }
}

To learn more, see Use MQTT to update a device twin reported property and Use MQTT to retrieve a device twin property.

Membersihkan sumber daya

Jika Anda berencana untuk melanjutkan dengan lebih banyak artikel pengembang perangkat, Anda dapat menyimpan dan menggunakan kembali sumber daya yang Anda gunakan dalam artikel ini. Jika tidak, Anda dapat menghapus sumber daya yang Anda buat di artikel ini untuk menghindari lebih banyak biaya.

Anda dapat menghapus hub dan perangkat terdaftar sekaligus dengan menghapus seluruh grup sumber daya dengan perintah Azure CLI berikut. Jangan gunakan perintah ini jika sumber daya ini berbagi grup sumber daya dengan sumber daya lain yang ingin Anda pertahankan.

az group delete --name <YourResourceGroupName>

Untuk menghapus hanya hub IoT, jalankan perintah berikut menggunakan Azure CLI:

az iot hub delete --name <YourIoTHubName>

Untuk menghapus hanya identitas perangkat yang Anda daftarkan dengan hub IoT Anda, jalankan perintah berikut menggunakan Azure CLI:

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

Anda mungkin juga ingin menghapus file sampel kloning dari mesin pengembangan Anda.

Langkah berikutnya

Sekarang setelah Anda mempelajari cara menggunakan pustaka MQTT Mosquitto untuk berkomunikasi dengan IoT Hub, langkah selanjutnya yang disarankan adalah meninjau sampel Aplikasi MQTT di GitHub.

Bagikan melalui

Tutorial - Menggunakan MQTT untuk mengembangkan klien perangkat IoT tanpa menggunakan SDK perangkat

Prasyarat

Prasyarat mesin pengembangan

Persiapkan lingkungan Anda untuk Azure CLI

Siapkan lingkungan Anda

Clone the sample repository

Membangun sampel C

Send telemetry

Meninjau kode

Menerima pesan dari cloud ke perangkat

Meninjau kode

Update a device twin

Meninjau kode

Membersihkan sumber daya

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: