About Azure IoT Hub

Azure IoT Hub is a Platform as a Service (PaaS) that targets the IoT by providing device registry, data storage, and
security services. IoT hub establishes bi-directional communication with connected devices, using different protocols (MQTT, AMQP and HTTP). It also provides a service interface for IoT application development.

Prerequisites:
In the following we assume that you already have created an Azure IoT Hub account and that you have created at least one device for which you generated an access Key. For more on this topic, kindly refer to the following links: IoT Hub getstarted, Control access to IoT Hub.

Leveraging IoT Hub from scriptr.io

With scriptr.io you can easily communicate with the devices you are managing through IoT Hub:

  • You can subscribe any of your scripts to automatically consume messages (events) as soon as they are published on your IoT Hub device queues
  • You can publish messages to your IoT Hub queues from any scripts in your account

Consuming messages from IoT Hub into your scripts

In this use case, you need to configure your scriptr.io account to subscribe to your IoT Hub’s queues, then determine the scripts that will consume the incoming messages/events. This is done simply in three steps:

  1. Create an endpoint
  2. Bind the endpoint to a channel
  3. Subscribe your scripts to the channel

Create an endpoint

From your scriptr.io workspace, click on the arrow near your username of the top-right corner of the screen then select “Settings” from the drop-down. In the settings dialog, click on the “Endpoint” tab.

create-endpoint

Click on “Add External Endpoint Configuration”, then select Azure IoT from the drop-down list of the “Type” field. The form adapts to fit Azure IoT’s configuration.

create Azure IoT endpoint

– In the “Name” field, enter a name for your endpoint
– In the “URL” field, enter the URL of your Azure IoT Hub endpoint. It should be something similar to “publishSubscribe.azure-devices.net”
– In the “Access Key Name” field, enter the name of your device, as entered in Azure IoT Hub. This should be found in the IoT Devices > Device details section of your Azure IoT account
– In the “Access Key” file, enter one of the primary or secondary key that are associated to your device in Azure IoT (same section as above)
– In the Device Id field, enter the name of your device, as entered in Azure IoT Hub
– In the CA field, upload the root certificate
(remove the .txt extension. You can also find other root CA certificates from
here)

Validate your changes by clicking on the orange check box on the right.

Create a channel

A scriptr.io channel is an abstraction of publish/subscribe (broadcasting) and queuing mechanisms, regardless of the protocol you are using to implement them. A channel allows you to publish messages that will either be broadcast or queued to any subscriber of this channel, whether it is a script in your account or a client application.

To create a channel, simply go back to the “Settings” then select the “Channels” tab. Click on “Add channel” then enter a name for your channel and decide if it will accept anonymous publishing and subscriptions or not, respectively by checking or un-checking the corresponding options. Click on the orange checkbox to validate your changes.

create-channel

Subscribe your scripts to the channel

You can subscribe your scripts in two different ways:

– The simplest way is by opening the script in the editor and clicking the “subscribe” button on the top right corner of the edition area.

subcribe-script-to-channel

In the resulting dialog, move the toggle next to the channel to “on”.

subscribe-script-to-channel-2

– The second way to subscribe a script to a channel is programmatically, as described in the below code snippet. This of course has to be done from a script different from the one you need to subscribe to the channel. Subscription will occur upon the execution of that other script.

Once subscribed to the channel, your script will start receiving messages and event from Azure IoT Hub as they flow. You can retrieve the payload from the native “request” object in your script, using one of “request.body” if the payload is expected to be in JSON format, or “request.rawBody” otherwise.

subscribe("azure-iot-channel", "blog/azureiothub/subscriber");

Publish messages from your scripts to IoT Hub

Publishing messages from your scripts to Azure IoT Hub is a simple two-steps process:

  1. Create an endpoint
  2. Use the mqtt module to publish to the endpoint

Create an endpoint

This is done as described in the first step of the preceding paragraph. Note that once an endpoint has been created, you do not have to create it again.

Use the mqtt module to publish to the endpoint

In your script, require the “mqtt” module then create an instance of mqtt client using your endpoint’s configuration. Invoke the publish method of the mqtt client to publish to Azure IoT Hub, passing the Azure IoT endpoint you need to publish to, and your message (a string, can be a stringified JSON object). 

var mqtt = require("mqtt");
var mqttClient = mqtt.getInstance("azure-iot-hub");
// check if we obtained an error object instead of the client instance
if(mqttClient.metadata && mqttClient.metadata.status == "failure") {
    return mqttClient; // return the error object 
}

// no error, we got an instance of mqtt client, publish to an Azure IoT Hub endpoint
var endpoint = "/messages/events/readpipe";
var msg = JSON.stringify({"msg":"hi"}); // should be a simple string or stringified JSON
return mqttClient.publish(endpoint, msg);