Skip to content

Files

Latest commit

timlttimlt
Update assigned PM authors
Sep 30, 2021
7a9f670 · Sep 30, 2021

History

History
154 lines (99 loc) · 7.61 KB

tutorial-use-mqtt.md

File metadata and controls

154 lines (99 loc) · 7.61 KB
title description author ms.author ms.date ms.topic ms.service services
Tutorial - Use MQTT to create an Azure IoT Plug and Play device client | Microsoft Docs
Tutorial - Use the MQTT protocol directly to create an IoT Plug and Play device client without using the Azure IoT Device SDKs
ryanwinter
rywinter
05/13/2020
tutorial
iot-develop
iot-develop

Tutorial - Use MQTT to develop an IoT Plug and Play device client

You should use one of the Azure IoT Device SDKs to build your IoT Plug and Play device clients if at all possible. However, in scenarios such as using a memory constrained device, you may need to use an MQTT library to communicate with your IoT hub.

The sample in this tutorial uses the Eclipse Mosquitto MQTT library and Visual Studio. The steps in this tutorial assume you're using Windows on your development machine.

In this tutorial, you learn how to:

[!div class="checklist"]

  • Download and build the Eclipse Mosquitto library.
  • Modify the C-based MQTT sample code to make the device an IoT Plug and Play device.
  • Identify the MQTT topics that an IoT Plug and Play device uses.

Prerequisites

[!INCLUDE iot-pnp-prerequisites]

To complete this tutorial on Windows, install the following software on your local Windows environment:

Use the Azure IoT explorer tool to add a new device to your IoT Hub. You configured your IoT hub and the Azure IoT explorer tool when you completed Set up your environment for the IoT Plug and Play quickstarts and tutorials:

  1. Launch the Azure IoT explorer tool.
  2. On the IoT hubs page, select View devices in this hub.
  3. On the Devices page, select + New.
  4. Create a device called my-mqtt-device that uses an autogenerated symmetric key.
  5. On the Device identity page, expand Connection string with SAS token.
  6. Choose the Primary key to use as the Symmetric key, set the expiration time to 60 minutes, and select Generate.
  7. Copy the generated SAS token connection string, you use this value later in the tutorial.

Clone sample repo

Use the following command to clone the sample repository to a suitable location on your local machine:

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

Install MQTT library

Use the vcpkg tool to download and build the Eclipse Mosquitto library.

Use the following command to clone the Vcpkg repository to a suitable location on your local machine:

git clone https://github.com/Microsoft/vcpkg.git

Use the following commands to prepare the vcpkg environment. You need an elevated command prompt when you run vcpkg integrate install:

cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg integrate install

Use the following command to download and build the Eclipse Mosquitto library:

.\vcpkg install mosquitto:x64-windows

Migrate the sample to IoT Plug and Play

Review the non-IoT Plug and Play sample code

Update the code with details of your IoT hub and device before you build and run it.

To view the sample code in Visual Studio, open the MQTTWin32.sln solution file in the IoTMQTTSample\src\Windows folder.

In Solution Explorer, right-click on the TelemetryMQTTWin32 project and select Set as Startup Project.

In the TelemetryMQTTWin32 project, open the MQTT_Mosquitto.cpp source file. Update the connection information definitions with the device details you made a note of previously. Replace the token string placeholders for the:

  • IOTHUBNAME identifier with the name of your IoT hub.
  • DEVICEID identifier with my-mqtt-device.
  • PWD identifier with the correct part of the SAS token connection string you generated for the device. Use the part of the connection string from SharedAccessSignature sr= through to the end.

Verify the code is working correctly, by starting Azure IoT explorer, start listening the telemetry.

Run the application (Ctrl+F5), after couple of seconds you see output that looks like:

:::image type="content" source="media/tutorial-use-mqtt/mqtt-sample-output.png" alt-text="Output from MQTT sample application":::

In Azure IoT explorer, you can see that the device isn't an IoT Plug and Play device:

:::image type="content" source="media/tutorial-use-mqtt/non-pnp-iot-explorer.png" alt-text="Non-IoT Plug and Play device in Azure IoT explorer":::

Make the device an IoT Plug and Play device

IoT Plug and Play device must follow a set of simple conventions. If a device sends a model ID when it connects, it becomes an IoT Plug and Play device.

In this sample, you add a model ID to the MQTT connection packet. You pass the model ID as querystring parameter in the USERNAME and change the api-version to 2020-09-30:

// computed Host Username and Topic
//#define USERNAME IOTHUBNAME ".azure-devices.net/" DEVICEID "/?api-version=2018-06-30"
#define USERNAME IOTHUBNAME ".azure-devices.net/" DEVICEID "/?api-version=2020-09-30&model-id=dtmi:com:example:Thermostat;1"
#define PORT 8883
#define HOST IOTHUBNAME //".azure-devices.net"
#define TOPIC "devices/" DEVICEID "/messages/events/"

Rebuild and run the sample.

The device twin now includes the model ID:

:::image type="content" source="media/tutorial-use-mqtt/model-id-iot-explorer.png" alt-text="View the model ID in Azure IoT explorer":::

You can now navigate the IoT Plug and Play component:

:::image type="content" source="media/tutorial-use-mqtt/components-iot-explorer.png" alt-text="View components in Azure IoT explorer":::

You can now modify your device code to implement the telemetry, properties, and commands defined in your model. To see an example implementation of the thermostat device using the Mosquitto library, see Using MQTT PnP with Azure IoTHub without the IoT SDK on Windows on GitHub.

Note

The client uses the IoTHubRootCA_Baltimore.pem root certificate file to verify the identity of the IoT hub it connects to.

MQTT topics

The following definitions are for the MQTT topics the device uses to send information to the IoT hub. To learn more, see Communicate with your IoT hub using the MQTT protocol:

  • The DEVICE_CAPABILITIES_MESSAGE defines the topic the device uses to report the interfaces it implements.
  • The DEVICETWIN_PATCH_MESSAGE defines the topic the device uses to report property updates to the IoT hub.
  • The DEVICE_TELEMETRY_MESSAGE defines the topic the device uses to send telemetry to your IoT hub.

For more information about MQTT, visit the MQTT Samples for Azure IoT GitHub repository.

Clean up resources

[!INCLUDE iot-pnp-clean-resources]

Next steps

In this tutorial, you learned how to modify an MQTT device client to follow the IoT Plug and Play conventions. To learn more about IoT Hub support for the MQTT protocol, see:

[!div class="nextstepaction"] Communicate with your IoT hub using the MQTT protocol