Simulate Azure IoT Telemetry And Device Twin using MQTT Directly

TLDR;

In this post I show how to simulate Azure IoT device D2C (Device to cloud) messages telemetry, and Device Twin Reported Properties using MQTTX CLI.

Introduction

I have been working in several Azure IoT projects in the past 3 years, where MQTT was the preferred device/server communication protocol. In these projects, there has been a repeatable need to generate MQTT messages to simulate devices’ telemetry, without going through the Azure CLI.

One of the tools that I found recently was MQTTX CLI, which is a light-weight client that can subscribe to and publish topics to MQTT broker, and has a solid and dynamic templating functionality based on JavaScript that makes generating telemetry easy.
Quoting from their website:

“MQTTX CLI is an open source MQTT 5.0 CLI Client and MQTTX on the command line. Designed to help develop and debug MQTT services and applications faster without the need to use a graphical interface.“

Let’s have a look at the Simulate feature.

MQTTX CLI Simulate Feature

The Simulate feature can publish messages with dynamic content generated based on your template file.  The feature uses the simulate command. Let’s examine the parameters to.

Note: behind the scenes, the Simulate command depends on the Publish command, so make sure to check the Publish parameters necessary, e.g. hostname, username, password..etc

In addition to the basic parameters to publish messages, the Simulates command has the following parameters to control the simulation:

• –count: Number of connections: represents the number of MQTT connections that will be created in the process.
• –interval-message: interval of publishing message to the broker (default: 1000ms)
• –limit: the number of messages to publish, 0 means unlimited (default: 0)
• –client-id: the client id, support %i (index) variable. Check the --count parameter above to see how it is used.
• –topic: the message topic. If your topic will depend on the User, Client ID, or the count of simulated messages, then you can use %u (username), %c (client id), %i (index) variables in the value.
• –file: the JavaScript Module file that will be used to generate the payload. This JavaScript has a specific contract that you should adhere to so that it can be used to MQTTX CLI to generate the payload.

Note: that all the connections will be established by the same client id unless you pass “%i”, if you do then each connection will have its unique generated client id based on the count. e.g. clientid_1, clientid_2…etc.

Let’s have a look at the example template file in the docs, this simple simulator generates a simple payload with “temp” and “hum” properties. (in order to use it you pass the name of the file to the --file parameter).

/**
 * MQTTX Scenario file example
 *
 * This script generates random temperature and humidity data.
 */
function generator(faker, options) {
  return {
    // If no topic is returned, use the topic in the command line parameters.
    // Topic format: 'mqttx/simulate/myScenario/' + clientId,
    message: JSON.stringify({
      temp: faker.number.int({ min: 20, max: 80 }), // Generate a random temperature between 20 and 80.
      hum: faker.number.int({ min: 40, max: 90 }), // Generate a random humidity between 40 and 90.
    })
  }
}
// Export the scenario module
module.exports = {
  name: 'myScenario', // Name of the scenario
  generator, // Generator function
}

You can see that the generator function is the contract that will be used by the tool to generate the simulated payload. It takes two parameters: faker that you can use to generate random and fake values, and options if you want use any of the passed options to the command.

All what you need to do in your own file is to implement the generator function with your custom logic to generate the payload. For more inspiration you can look at some of the built-in simulation files.

Simulate Azure D2C Message

Now comes the most important part, sending simulated telemetry to Azure IoT Hub. Microsoft already provided some code samples to use MQTT directly to send messages. The highlight is that we need to send a message to the topic devices/{device_id}/messages/events/

We need to send a message with the following parameters (make sure to replace the placeholder tokens with yours):

• Host: “{iothub_name}.azure-devices.net”
• Port: 8883
• Client Id: “{device_id}”
• User: “{iothub_name}.azure-devices.net/{device_id}/?api-version=2018-06-30”
• Password: “{sas_token}” (this is generated by this command, choose a duration value that suits the lifetime of your test).
• Topic: “devices/{device_id}/messages/events/”
• Message: The payload of your telemetry
• CA certificate: if you want to validate the IoT Hub’s certificate, then you can provide the certificate that can be found here. Otherwise you can pass the --insecure parameter to ignore validating the certificate.
• MQTT Version: this is necessary with MQTTX CLI as its default protocol version is 5.0, while Azure IoT Hub’s one is 3.1.1.

Assuming that we have a device called “emad”, and an Azure IoT Hub called “youriothub”, and a template file called “simulatedTelemetry.js”, then the final command should look like this:

mqttx simulate \
  --file simulatedTelemetry.js \
  -c 10 \
  --interval-message 1000 \
  --insecure \
  -q 1 \
  -V 3.1.1 \
  -h "youriothub.azure-devices.net" \
  -t "devices/emad/messages/events/" \
  --client-id "emad" \
  -u 'youriothub.azure-devices.net/emad/?api-version=2018-06-30' \
  -P 'long-sharedaccesstoken' \
  -l mqtts

Simulate Azure IoT Device Twin Reported Properties

We can also use the same technique above for the Device Twin Reported Properties. The only difference will be the topic value which should be \$iothub/twin/PATCH/properties/reported/.

If you don’t want to use simulation to send the Reported Properties and just send it once with a specific payload, you can use the pub command with a simple JSON payload. Like the following:

mqttx pub \
  --file-read devicePropertyPayload.json \
  --insecure \
  -q 1 \
  -V 3.1.1 \
  -h "youriothub.azure-devices.net" \
  -t "devices/emad/messages/events/" \
  --client-id "emad" \
  -u 'youriothub.azure-devices.net/emad/?api-version=2018-06-30' \
  -P 'long-sharedaccesstoken' \
  -l mqtts

Conclusion

By this, I hope you can use MQTTX CLI to simulate device telemetry and Device Twins Reported Properties.