After getting my hands on the pre-release version of the MKR1000 as part of the Worlds Largest Arduino Maker Challenge yesterday, I was trying to get it running with the Azure IoT Hub. This guide lays out some of the things that I learned that might help out others out there trying to get their projects running with Azure IoT.

This guide doesn’t use AMQP or MQTT. This uses the simple HTTP interfaces available for Azure IoT Hub. This assumes that you have already signed up for the Azure IoT Hub and created it. This guide will walk you through the following steps to get you going.

Getting the Arduino Environment ready for MKR1000 Setting up the WiFi101 library Understanding the HTTP REST API for the Azure IoT Hub Getting the SAS token from the Device Explorer for Azure IoT Hub Setting up the SSL for Azure IoT Hub on the MKR1000 WiFi Walk through of the Arduino Sketch that you will run on the MKR1000 Testing by Sending Messages to Azure IoT Hub with Device Explorer

Update 2/29/2016: Part 2 of this Azure IoT Hub interface using HTTP to complete/reject/abandon a received message is here. Be sure to read that as well after this.

Getting the Arduino Environment Ready for MKR1000

1. Install/upgrade to the latest version of the Arduino IDE.

2. Install the SAMD board using the Boards Manager.. That’s SAMD not SAM

You should now be able to run the blink sketch (on board LED is on Pin 6 and not on Pin13) and verify that the simplest sketch is working on the MKR1000.

Setting up the WiFi101 library

MKR1000 sketches need the WiFi101 library. Particularly version 0.8. As of this writing, the default Arduino IDE installation didn’t have the latest library. You can verify it by going to Sketch > Include Libraries > Manage Libraries and search for Wifi101.. if you see version 0.8.0 and above installed you are fine. Otherwise try to get the library updated. If you don’t see the “Update” button on the Libraries Manager, you might have to do it manually by:

Deleting the WiFi101 folder from the Arduino libraries folder. On windows its at C:\Users\yourusername\Documents\Arduino\libraries Download the latest WiFi101 library zip file from Github Install using Sketch > Include Libraries > Add .Zip Library menu

Understanding the HTTP REST API for the Azure IoT Hub

Microsoft Azure IoT Hub is accessible through HTTP, AMQP or MQTT. The HTTP REST API’s makes it easier for connecting and polling for messages on the Azure IoT Hub using just Http clients. The following two REST http endpoints would allow us to perform basic tasks from the devices.

Purpose HTTP Verb URI Receive or Poll for a Message GET https://{IoTHubName}.azure-devices.net/devices/{deviceId}/messages/devicebound?api-version={api-version} Send a message POST https://{IoTHubName}.azure-devices.net/devices/{deviceId}/messages/events?api-version={api-version}

The highlighted fields are described below. They are needed for the Sketch configuration.

Field description IoTHubName This is your IoT hub Host name. Can get it from the Azure Portal Example: yourTestIotHub.azure-devices.net deviceId Name of the device that you created using Device Explorer (see below) api-version As of this writing (on Feb 19, 2016) its “2016-02-03”

There are 3 more endpoints available for dealing with the messages (Complete, Reject, Abondon). You can read about them here.

Microsoft Azure IoT uses Shared Access Signatures (SAS) to secure the Azure endpoints. These are expiring signatures that can be used to securely access the Azure IoT device queues without the need for passwords. These have to be passed in the HTTP headers when making the request.

Though this signature needs to be created on fly with a very short expiration, when you install the Device Explorer utility you will be able to create the shared access key with a longer expiration. You will then be able to use this static key in your sketch with out having to generate them in the code.

Getting the SAS token from the Device Explorer for Azure IoT Hub

Device Explorer is a small utility that makes it easy to manage devices connecting to your IoT hub. You can add/remove devices, create SAS token, send/receive messages for specific device identities.

The Device explorer GUI runs only on Windows. You can install it from here.

For other OS, you can install the IoThub explorer tool using npm.

I am using the Windows Version. For configuring the Device Explorer, you need to obtain the IoT Hub Connection string and use it in the configuration tab of the device explorer. After that you will be able to access the “Management” tab to view and create the devices. This is where you can select a particular device and create the SAS token for it as well. Refer to the how to use guide here.

I created a device named “MyMKR1000” and created the SAS Token with the TTL set to 5 days. I might have to update the sketch later once the SAS token expires. You need to copy only the part that starts with the second SharedAccessSignature. For example the SAS key in the screenshot that i will use in the MKR1000 sketch is:

SharedAccessSignature sr=UPPHub.azure-devices.net%2fdevices%2fMyMKR1000&sig=JeQBhIBmFQrHBTmwainLMSmDc35rZ2hoGPbEmM9QEDQ%3d&se=1455974333



(In the screen shot I am using 0 just so that the share access key expire by the time this post goes online.)

Setting up the SSL for Azure IoT Hub on the MKR1000 WiFi

Now that the SAS token is available, we almost have everything we need to configure the sketch. The last thing we need is the SSL certificate configured.

Azure IoT Hub (and for that matter most of the IoT Services) uses SSL to secure the communication. On the Arduino MKR1000 board, when the sketch runs, it needs to establish an SSL communication with the Azure IoT hub first before it can proceed further. The MKR1000’s WiFi chip doesn’t have that much memory. It cannot possible store a large number of SSL certificates like your computer does. So we need to first upload the SSL certificate to the WiFi chip. Not a big deal.

Get the latest version of WiFi101 Firmware updater from here. Extract the contents of the zip file to a folder. You should see “winc1500-uploader-gui” in that folder. You can also use the console application found there. On the Arduino IDE, choose the FirmwareUpdater sketch from File > Examples > WiFi101 > FirmwareUpdater With the MKR1000 connected run this sketch. Your MKR1000 will now be ready to accept the new WiFi Firmware. Run the “winc1500-uploader-gui” application On the Ip or Domain name field provide the name of your IoTHub host name. Click download to get the SSL certificate. Select the COM port that MKR1000 is connected to. Press upload certificates to send the certificate to the WiFi module. Once the certificates are uploaded you are all set for MKR1000 Azure IoT Hub interfacing.

MKR1000 Arduino Sketch

Following are the basic configuration that need to be set on the sketch for WiFi connection and Azure IoT Hub Connection.

///*** WiFi Network Config ***/// char ssid[] = "YourWiFiNetworkSSID"; // your network SSID (name) char pass[] = "YourWiFiNetworkPasswd"; // your network password (use for WPA, or use as key for WEP) ///*** Azure IoT Hub Config ***/// char hostname[] = "YourIoTHubName.azure-devices.net"; // host name address for your Azure IoT Hub char feeduri[] = "/devices/YourDeviceName/messages/devicebound?api-version=2016-02-03"; //feed URI char authSAS[] = "YourSharedAccessKey"; ///*** Azure IoT Hub Config ***///

The main part of the sketch that deals with making HTTP requests to Azure IoT hub is the following. The sketch uses the WiFiSSLClient to establish a SSL handshake to the hostname via port 443. Once Connection is established, it makes a GET request to the devicebound URI to receive messages. When establishing the GET request, the “Authorization” header is also added which contains the value for the SAS token.

// this method makes an HTTPS connection to the Azure IOT Hub Server: void azureHttpRequest() { // close any connection before send a new request. // This will free the socket on the WiFi shield client.stop(); // if there's a successful connection: if (client.connect(hostname, 443)) { //make the GET request to the Azure IOT device feed uri client.print("GET "); //Do a GET client.print(feeduri); // On the feedURI client.println(" HTTP/1.1"); client.print("Host: "); client.println(hostname); //with hostname header client.print("Authorization: "); client.println(authSAS); //Authorization SAS token obtained from Azure IoT device explorer client.println("Connection: close"); client.println(); // note the time that the connection was made: lastConnectionTime = millis(); } else { // if you couldn't make a connection: Serial.println("connection failed"); } }

On the main loop, the response, if available, is read. If the response contains the 204 response code, it means there was no new message. Else there is a message and I just blink the LED on pin #6. I have configured a polling interval and the code loops through to repeatedly check for messages. We can do more with the response, but for this post i just kept it simple.

void loop() { String response = ""; char c; ///read response if WiFi Client is available while (client.available()) { c = client.read(); response.concat(c); } if (!response.equals("")) { //if there are no messages in the IoT Hub Device queue, Azure will return 204 status code. if (response.startsWith("HTTP/1.1 204")) { //turn off onboard LED digitalWrite(MKR1000_LED, LOW); } else { //turn on onboard LED digitalWrite(MKR1000_LED, HIGH); } } // polling..if pollingInterval has passed if (millis() - lastConnectionTime > pollingInterval) { digitalWrite(MKR1000_LED, LOW); azureHttpRequest(); } }

The complete sketch is available in Github at MKR1000Azure.

Sending Messages to Azure IoT Hub

After uploading the sketch to MKR1000, I used the Device Explorer to send some messages to the IoT Hub.

I could see the MKR1000 receiving the messages from Azure IoT hub and activating the LED.

(Note: The MKR1000 is hiding in its box due to the request from Arduino not to take pictures of the MKR1000)

Now that a simple GET is possible, sending messages and dealing with other uses cases around Azure IoT Hub interface should be easier.

Update 2/29/2016: Part 2 of this Azure IoT Hub interface using HTTP to complete/reject/abandon a received message is here. Be sure to read that as well after this to ensure received messages are properly de-queued in Azure IoT Hub.

Hopefully this guide is useful for the community. Like it says on the MKR1000 box, “Open-Source is Love”.