IoT Workshop 2017 v2 - Australia

Welcome to our IoT workshop!

We are so glad to have you with us today. We put together this workshop to give you some hands-on experience with the Microsoft Azure IoT suite. Our goal is to get you up-to-speed on the latest developments so you can take the knowledge back to your office and start implementing IoT solutions with them.

Please note that the contents of this workshop have been updated to reflect the latest changes to IoT Edge. The old content is still available in /v1

Prerequisites

This is a technical workshop and you're expected to be comfortable writing and understanding code (we will chiefly use .NET Core). Also, you're expected to be comfortable around Linux, be able use SSH, bash, Visual Studio Code and know how to use text editors (such as vi or nano). Basic understanding of Docker Containers and Azure is essential, but not critical.

Please make sure to complete the following prerequisites prior to coming to the workshop

• Install PuTTY (Windows users only)
• Download Azure IoT Device Explorer (Windows only) or Install iothub-explorer, a command line utility
• Activate a free trial Azure subscription and familiarise yourself with the Azure Portal
• Install Visual Studio Code
• Install .NET SDK on your machine
• Register on Docker Hub
• Install Docker Community Edition

Agenda

Day 1:

• Azure IoT Suite: Level 300 intro
• Lab 0: Environment setup: azure subscription, SSH access to your Raspberry PI, set up prerequisites
• Lab 1: Deploy Simulated Device on IoT Edge
• Lab 2: Develop and deploy a custom C# module to connect to Sensor Tag on IoT Edge

Day 2:

• Lab 3: Deploy Azure Stream Analytics on IoT Edge
• Time for guided experimentation, try some of the challenges
• Wrap-up

Getting Started

Each group will be provided with a Raspberry Pi 3 running Raspbian Stretch with Desktop, a Texas Instruments(TI) Bluetooth Low Energy (BLE) Sensor Tag, and an Azure Subscription.

Proctors are available to help you work through these workshops, answer questions or talk tech.

What's in the Pre-baked Image

For your convenience we pre-baked an image that you can download and try at home. This image is based on stock standard Raspbian Stretch with Desktop with the following tweaks:

• VNC server has been enabled, you can access you RPI's GUI using VNC Viewer
• Crontab script notifying proctors when raspberry PIs receive or refresh an IP address to simplify the classroom process
• SSH enabled
• Swap increased to 1G

Lab 0: Environment Setup

1. Make sure you've completed the prerequisites before the workshop

2. Make sure you can access Azure Portal and have an active Azure Subscription

   speak to one of the proctors if you need an Azure Subscription or activate a free trial yourself

3. The procrotors will tell you the IP address of your Raspberry PI, make sure you can access it via SSH and VNC

   username: pi, password: raspberry

4. Install Docker on your Raspberry PI by running

   curl -sSL https://get.docker.com | sh

   • Check docker instalation by running

   sudo docker run hello-world

5. Install bluepy - a Python interface to Bluetooth LE on Linux

   sudo apt-get -y install python-pip libglib2.0-dev python-dev libffi-dev libssl-dev
   sudo pip install bluepy

6. Install redis - redis will be used as a pub/sub mechanism between the Sensor Tag (accessed via bluepy) and the IoT Edge

   sudo apt-get -y install redis-server
   sudo pip install redis

   • edit /etc/redis/redis.conf, commenting out the bind line to make Redis listen on all available ip addresses, adding a new line: maxmemory 512mb, and setting protected-mode to no. Save the config file
   • If you're feeling a little bit lazy, replace a configuration file by running

     sudo mv /etc/redis/redis.conf /etc/redis/redis.conf.default 
     curl -sSL https://raw.githubusercontent.com/iizotov/iot-workshop/master/src/aux-files/redis.conf | sudo tee /etc/redis/redis.conf

   • Bounce Redis and enable the service to start automatically

     sudo service redis-server restart
     sudo update-rc.d redis-server enable

   • (bonus challenge) to understand more about Redis Pub/Sub, follow this example

7. Grab a python script that will interface with the Sensor Tag

   curl -sSL https://raw.githubusercontent.com/iizotov/iot-workshop/master/src/iotedgebleadapter/sensortag.py | tee ~pi/sensortag.py

   • Note the mac address of your Sensor Tag and launch the Python script by running

     python ~pi/sensortag.py --all -t 0.5 --redisip 127.0.0.1 --redischannel data <mac address>

   • briefly push the power button on your Sensor Tag to initiate connection. Once established, you should see the telemetry being read from all sensors sequentially every 0.5 seconds and pushed into Redis running on 127.0.0.1, channel data
   • (bonus challenge) to explore the json data pushed into the data channel in Redis, use redis-cli in a separate SSH session, issuing the following command: SUBSCRIBE data

   If something's wrong, bounce bluetooth by running sudo /etc/init.d/bluetooth restart

Lab 1: Deploy Simulated Device on IoT Edge

1. Follow instructions here to:
   • Create an IoT hub

     it is recommended to create an S1 IoT Hub instance instead of an F1 - Free instance to avoid hittind the daily message quota

   • Register an IoT Edge device
   • Install and start the IoT Edge runtime
   • Deploy a simulated device to IoT Edge
2. Connect to the IoT Hub using either Azure IoT Device Explorer or iothub-explorer and monitor the telemetry flowing through
3. Emulate a container crash by noting down the id of one of the docker containers by killing it

   sudo docker kill tempSensor

   • observe how the IoT Edge Runtime heals itself by running

   sudo watch docker ps

Lab 2: Develop and deploy a custom C# module to connect to Sensor Tag on IoT Edge

Follow the instructions to create a custom C# module that will:

• Subscribe to Redis instance listening for telemetry from your Sensor Tag. The Redis channel and IP address will be specified vi the Module Twin capability
• Push the telemetry to the module output, to be further routed to the IoT Hub via the IoT Edge routes mechanism

TODO! Insert Image

In following the instructions, skip steps 7 - 12 in the Create an IoT Edge module project section and use the code from this location instead

• For simplicity, use Docker Hub for storing your docker image
• Since you'll be running this module on an ARM-based platform, change the FROM ... line in /Docker/linux-x64/Dockerfile to

  FROM microsoft/dotnet:2.0.0-runtime-stretch-arm32v7
  

• Since your code will be interfacing with Redis, add a dependency on the StackExchange.Redis Nuget package to the .cproj file:

  <PackageReference Include="StackExchange.Redis" Version="1.2.6" />
  

• Before deploying the module, grab the Docker gateway IP address (that is, the address that your module will use to connect to Redis) by running

  sudo docker network inspect --format='{{json .IPAM.Config}}' azure-iot-edge

• When deploying the module, specify the following desired properties in the module twin (replace <ip> with the gateway ip address)

  {
      "properties.desired": {
          "redisIPAddress":"<ip>",
          "redisChannelName": "data"
      }
  }

• When deploying the module, specify the following route (replace <module> with the name of your module)

  {
      "routes": {
          "route": "FROM /messages/modules/<module>/outputs/* INTO $upstream"
      }
  }

• Make sure the module is deployed correctly through Azure Portal and by running sudo watch docker ps
• You can review the container's logs by running sudo docker logs -f <container_id>
• Whilst following the logs, change the name of the Redis channel by submitting an update to set of desired properties via Azure Portal
• In a separate SSH session, launch the python script to start pushing telemetry messages into the Redis instance. Replace <mac address> with the MAC address of your Sentor Tag and <ip> with the Docker gateway ip address from one of the steps above:

  while true; do python ~pi/sensortag.py --all -t 0.5 --redisip <ip> <mac address> --redischannel data; sleep 1; done

  The infinite loop is used to reconnect when your Sensor Tag enters power saving mode. If you want to stop the script, hold Ctrl+C continuously

  If something's wrong, bounce bluetooth by running sudo /etc/init.d/bluetooth restart

• Connect to the IoT Hub using either Azure IoT Device Explorer or iothub-explorer and monitor the telemetry flowing through

Lab 3: Deploy Azure Stream Analytics on IoT Edge

TODO, unfinished

use https://docs.microsoft.com/en-us/azure/stream-analytics/stream-analytics-edge

create input input1
create output alert
create output cloud

define query: 
SELECT
    *
INTO
    [cloud]
FROM
    [input1]

SELECT
    'temperature alert' as alert_message,
    '30' as temp_ir_threshold,
    temp_ir,
    tag,
    [timestamp]
INTO
    [alert]
FROM
    [input1]
WHERE
    [input1].[temp_ir] >= 30.0
	
Create anew storage account and a private container for the ASA job,
Add a new ASA module to the edge, rename it to ASA or copy the auto-generated name (in which case adjust the routes below accordingly)

{
"routes": {                                              
	"sensorToAsa":   "FROM /messages/modules/iotedgeblemodule/* INTO BrokeredEndpoint(\"/modules/{ASA}/inputs/input1\")",
	"messagesToCloud": "FROM /messages/modules/{ASA}/outputs/cloud INTO $upstream",
	"AlertsToCloud": "FROM /messages/modules/{ASA}/outputs/alert INTO $upstream"

}
} 

Additional Challenges

TODO

Create an Stream Analytics Query in Azure

In addition to running ASA on the Edge, you can run it in the cloud

• Create an Azure Stream Analytics query that selects all the data from your IoT Hub and outputs the results to Power BI, displaying aggregate metrics and sending alerts (e.g. when temperature exceeds 37 degrees for longer that 15 consecutive seconds). Experiment with the ASA windowing functions and Azure Logic Apps to achieve it.
• How about making this temperature threshold dynamic? Hint: store it as reference data and use it in your queries.

Create a Power BI Dashboard

• Create a Power BI Dashboard that visualizes your Sensor Tag data in creative ways. Feel free to use any of the Power BI Custom Visuals available here. You can learn how to create Power BI Dashboards from a Stream Analytics Output here.

Time Series Insights

• Create a Time Series Insights environment and connect it to the Azure IoT Hub

Disclaimer

The code included in this workshop is not intended to be used in production. This is beyond the scope of this learning experience.

Related Links and Acknowledgments

• Sensor Tag Bluepy Example by @atotto

Contributors

• Fai Lai
• Igor Izotov