IoT Hub Pi Hands On Lab (HOL)

Overview

This Hands On Lab (HOL) demonstrates connecting a Raspberry Pi running Raspian to [Azure IoT Hub] (https://azure.microsoft.com/en-us/services/iot-hub/) and sending telemetry to Azure IoT Hub from either:

• a physical Sense HAT connected to the Raspberry Pi; or
• a Sense HAT Emulator installed on the Raspberry Pi.

Completing this HOL will provide you with the basic skills needed to connect and securely send telemetry from a physical device (e.g. a field device or field gateway) to the Azure IoT Hub. This HOL does not demonstrate what can be done with the data after it arrives at the Azure IoT Hub. Having said that, you can do almost anything including complex event processing, stream processing, saving telemetry to blob storage or databases, analytics, training of Machine Learning models etc.

Why Sense HAT?

We didn't want you to mess around with breadboards, jumper cables, resistors etc. This just wastes time and adds nothing to the goal of connecting a sensor to Azure IoT Hub. The Sense HAT has all the necessary components installed on the circuit board, including a ready to use library, and a series of sensors to play with.

Why HTTPS and REST?

For simplicity and to avoid downloading/compiling SDKs during the HOL, we chose to send the Sense Hat telemetry to Azure IoT Hub using the IoT Hub REST API over HTTPS. Of course, you can use one of the many device SDKs available, which support sending messages over AMQP and MQTT. If you want to use the device SDKs, refer to the Using the .NET Device SDK section below.

Requirements

• Raspberry Pi 3 Model B (Pi 2 Model B with USB Wi-Fi dongle will probably work as well) with latest version of Raspian installed on the micro SD card. Using NOOBS works fine.
• Sense HAT Emulator (which comes with the Raspian O/S)
• Sense HAT (optional - for those that want to play with real hardware). You can order the Sense HAT from a variety of online sites such as adafruit.com, amazon.com etc. Please order yours 3-4 weeks in advance of the HOL so it will arrive in time.
• Laptop (running whatever operating system you desire) but ideally running Windows so you can install/run Device Explorer.
• An Azure subscription. You can create a free trial Azure subscription, or you can use an MSDN Azure subscription or a subscription from your company.
• A basic understanding of Python and Linux.
• TBD

Advance Setup (Must be completed in advance of the HOL)

Please perform the following steps in advance of the HOL otherwise you will waste the entire HOL session performing these steps.

• Ensure your Raspberry Pi can boot [Raspian] (https://www.raspberrypi.org/downloads/) from the SD card.
• Ensure Sense HAT Emulator is installed (by default it is installed with Raspian). Verify by checking under 'Programming' in the Raspian GUI.
• Install Device Explorer on your Winbdows laptop. Device Explorer is a great tool to see messages coming into the IoT Hub from your Raspberry Pi.
• Ensure your Azure subscription login is working and you have sufficient permissions to create resources.
• Download and install PuTTY.

Steps (Performed by students during HOL)

1. Connect to Wifi.
2. Connect your Raspberry Pi to a monitor.
3. Click on the wifi icon in the top right.

   

4. Enter the correct wifi credentials
5. Retrieve the ip address.
6. Click on the command prompt

   

7. Retrieve the ip address with the following command: ifconfig
   
8. Disconnect from the monitor.
9. Using your laptop, verify you connection by connecting to the Rasberry Pi using PuTTY.
10. Setup your Azure IoT Hub.
11. Go to the Azure Portal.
12. Select the IoT Hub Service.
13. Click on "Add".
14. Enter the properties for your IoT Hub. 1. Enter a name for your hub. eg. TerrysFirstIoTHub 1. Choose the "Free" pricing tier. This will allow you up to 5,000 messages per day. 1. For the Free tier, the "IoT Hub units" will default to 1. 1. If you have more than 1 subscription, choose the one you wish to use. 1. Create a new Resource group for your hub. It can have the same name as the IoT Hub. 1. Select the "West US" Location. 1. Click the "Pin to dashboard" button. 1. Click the "Create" button.
15. Wait for the hub to be created. You will be notified in the "Notifications" section when it is complete.

    

16. Create (configure) your device in Azure IoT Hub.
17. Click on your new IoT Hub in the Azure Portal Dashboard.
18. Click on the "Shared access policies".
19. Click on the "iothubowner" policy.
20. Copy the primary key connection string. Save the primary key connection string for later.

    

21. Open Device Explorer
22. In the "Connection information" tab paste the primary key connection string into the "IoT Hub Connection String" text box.
23. Click on "Update".
24. Click on the "Management" tab.
25. In the "Actions" section, select "Create".
26. Enter a name for your device. Save the device name for later.

    

27. Click "Create".
28. Configure the Raspberry Pi to send messages to the IoT Hub.
29. Copy the Python code from this HOL to a file. Save the file as SenseHat_IoTHub_Http.py and open it with a text editor such as Notepad. 1. Alternatively you can download the file directly to your Raspberry Pi using: git clone https://github.com/khilscher/IoTHubPiHackathon.git and edit the SenseHat_IoTHub_Http.py using a text editor such as Nano.
30. Update the file with the primary key connection string. Look for connectionString = and paste in the primary key connection string you copied earlier. Then look for deviceId = and paste in the Device Name you created earlier.
31. Copy SenseHat_IoTHub_Http.py to your Raspberry Pi using PuTTY. The pscp executable will be in your PuTTY directory.
    pscp SenseHat_IoTHub_Http.py userid@server_name:/path/SenseHat_IoTHub_Http.py
32. Log into the Raspberry Pi using PuTTY.
33. Verify that the file was transfered by listing the directory: ls -l
34. Start sending messages by invoking the script in Python

    pi@raspberrypi:~ $ python SenseHat_IoTHub_Http.py
    

35. On your laptop, open Device Explorer, click the Data tab, select your device from the Device ID list, and click Monitor. If you see messages arriving then Congratulations, your Raspberry Pi is now sending data to Azure IoT Hub.
36. Referring to the Sense Hat API, update the code to send other telemetry to IoT Hub from the Sense HAT.
37. Update the SenseHat_IoTHub_Http.py code to send multiple telemetry data points (e.g. Yaw, Pitch, Roll, or Temperature, Pressure, Humidity) in a single JSON-formatted message to IoT Hub. See [sample_payload.json] (sample_payload.json). Solution source code - Authorized MSFT personnel only SenseHat_IoTHub_Http_JSON.py.
38. Update SenseHat_IoTHub_Http.py to display the HTTP response code from the IoT Hub message onto the Sense HAT LED display. Solution source code - Authorized MSFT personnel only SenseHat_IoTHub_Http_JSON_LED.py.
39. To send messages from IoT Hub back to your Raspberry Pi:
40. Copy the SenseHat_IoTHub_Http_C2D_LED.py file to your Raspberry Pi using pscp or download it directly using git clone.
41. Update the file with the primary key connection string. Look for connectionString = and paste in the primary key connection string you copied earlier. Then look for deviceId = and paste in the Device Name you created earlier. Save the file.
42. Run the file using pi@raspberrypi:~ $ python SenseHat_IoTHub_Http_C2D_LED.py
43. On your laptop, open Device Explorer, click the Messages to Device tab, select your device from the Device ID list, type in a message into the Message textbox and click Send. You should see the message appear on the Sense HAT LED display.

Using the Python Device SDK

IoT Hub also supports MQTT and AMQP protocols. These are generally more efficient and scale better than using the HTTP REST API. In order to use MQTT or AMQP with Python, you will need to download and compile the Python Device SDK on your Raspian operating system.

The full instructions are [here] (https://github.com/Azure/azure-iot-sdk-python/blob/master/doc/python-devbox-setup.md) with some Python SDK examples [here] (https://github.com/Azure/azure-iot-sdk-python/tree/master/device/samples).

In summary:

• git clone --recursive https://github.com/Azure/azure-iot-sdk-python.git
• cd azure-iot-sdk-python/build_all/linux
• sudo ./setup.sh
• sudo ./build.sh

After a successful build, the iothub_client.so Python extension module is copied to the device/samples and service/samples folders. The iothub_client.so must be in the same folder as your IoT Hub client python script or in the common shared libraries folder such as /usr/local/lib or /usr/lib.