How To Send Commands to Azure IoT Hub Devices Using Losant

In my previous article, How to Send Device Telemetry Data From Azure IoT Hub to Losant, I covered how to send messages from a device connected to Azure IoT Hub to Losant. Being able to command a device from the cloud is extremely powerful. This article provides step-by-step instructions for how to send commands to your Azure IoT Hub devices from Losant.

Invoking Azure Direct Methods

IoT Hub gives you the ability to invoke direct methods on devices from the cloud. Direct methods are implemented on the device and referenced by their name. The nice thing is, it's just an HTTP API Call, which makes things very simple. Let's look at an example. In this article, to make things easy, everything you see is based on Azure's Quickstart: Control a device connected to an IoT hub. The device application code can be found on GitHub. 

In the quickstart, it just generates random temperature and humidity data and reports it to IoT Hub. However, this application is listening for direct methods. It accepts a direct method called "SetTelemetryInterval" that will change the frequency at which it sends random data. 

In that application, using the azure-iot-device library, you have the ability to set up a handler for a device method:

// Set up the handler for the SetTelemetryInterval direct method call.
client.onDeviceMethod('SetTelemetryInterval', onSetTelemetryInterval);

This simply means that whenever this device receives a command for "SetTelemetryInterval", it will call the function "onSetTelemetryInterval". This method will change the report interval.

To trigger this direct method using HTTP, it looks like this:

curl -X POST \
  https://iothubname.azure-devices.net/twins/myfirstdevice/methods?api-version=2018-06-30 \
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "SetTelemetryInterval",
    "responseTimeoutInSeconds": 200,
    "payload": 10
}'

When this request is made, it calls up the "SetTelemetryInterval" direct method and passes "payload" into the function you defined to be called by the method name, in this case "onSetTelemetryInterval". The payload in the curl example will change the interval to 10 seconds. 

Sending Commands to Devices From a Dashboard

Now, that we understand the anatomy of a direct method from Azure, let's implement this in Losant. Let's set things up so that you can trigger a direct method right from a Losant Dashboard. Using an Input Control Block, we can build a dashboard that includes a slider, which can represent the report interval. 

In the screenshot above, you can see the difference in the Time Series Graph when we changed the report interval from 2 seconds to 10 seconds. There is really only one important configuration for this dashboard. In the Input Control Block, here is the configuration for the button:

It's important to note that we configure the "Trigger Workflow" option. This will ensure that the payload we are configuring is used as input to our workflow. Here, as the payload we have:

{
    "interval": {{interval}},
    "device" : "{{device}}"
}

This template will use the other input controls as values in the payload. The variable "interval" comes from the slider. The variable "device" comes from the dropdown. 

Let's build the workflow that will make the direct method call to Azure IoT Hub. Here is what it looks like:

It's a simple workflow with a Virtual Button Trigger, HTTP Node, and Debug Node. The HTTP Node configuration is the most important:

Request Method: The method for this is "POST"

URL Template: This defines the API call made to Azure. Here is what it looks like:

https://YOUR_HUB_NAME.azure-devices.net/twins/{{data.device}}/methods?api-version=2018-06-30

You should replace "YOUR_HUB_NAME" with your hub name. We are also using templating here: "{{data.device}}". This will ensure that when we press the Virtual Button Node, the device name will be placed here in the URL. 

Body Template:

{
  'methodName': 'SetTelemetryInterval',
  'payload': {{data.interval}},
  'responseTimeoutInSeconds': 30
}

Request Headers - Content Type: This just needs to be "application/json"

Request Headers - Authorization: 

Here, we need to put in the authorization key to make a successful API call to Azure. We can use this command to generate it: 

az iot hub generate-sas-token -n YOUR_HUB_NAME

Now, we are all done with the workflow configuration. From your dashboard, if you press the input control button, the payload will look like this: 

As you can see, under "data", you can see the "device" and "interval" that was provided by the Input Control Block. If all went well, you should see a direct method call in your terminal:

At this point, you're successfully invoking Azure IoT Hub to send device commands. There's a lot of additional functionality in Losant, including Experiences, that can be used to wrap a powerful solution around IoT Hub's device management, telemetry, and commands. If you've built something interesting with the combination of Azure and Losant, we'd love to hear about it. Please let us know in the Losant Forums.