jimbobbennett / mxchip-workshop

A hands on workshop to get started with an MXChip board 🤖

MXChip Workshop

This workshop is a hands-on lab for getting started building a cloud connected IoT device using the MXChip Iot DevKit prototyping board and the Azure IoT Hub.

The final project that will be created is an internet connected temperature sensor, with a warning light if the temperature is above a certain threshold. The temperature will be reported to Azure IoT Hub and stored in a Cosmos DB collection. This value can be retrieved via an API built using Azure functions. To control the LED, a threshold will be set using another Azure Function API, and this will sync to the device using a device twin.

What is the MXChip

The MXChip is an Arduino compatible prototyping board. It is an all-in-one board with a cortex-M micro-controller, WiFi, an array of sensors including temperature and pressure, LEDs, buttons, a screen, a microphone and headphone port. It is also designed to easily talk to Azure IoT Hub.

What is Azure IoT Hub

Azure IoT Hub is an Azure service that allows you to connect, monitor and manage IoT devices at scale, from a few to billions. IoT Hub is an open and flexible cloud platform as a service that supports open-source SDKs and multiple protocols.

You can read more at azure.microsoft.com/services/iot-hub

Getting started

Before you can work through this lab, you will need some hardware, software and an Azure account.

This workshop has been tested on Windows 10 and macOS Mojave. It should also work on Ubuntu, but this hasn't been validated yet.

Hardware

This workshop is based on the MXChip Iot DevKit, so you will need to purchase one of these boards. You can do so from:

• Amazon
• DFRobot
• Seeed

Software

You will need to install a few applications and tools to be able to program this board:

• Visual Studio Code

• Arduino IDE - NOTE On Windows DO NOT install using the Windows store, instead use the Windows Installer, for Windows XP and up.

• .NET Core SDK

• Azure Functions Core Tools

• You may need to install a USB driver or configure USB support to communicate with the MXChip.

  • Windows: Download and install USB driver from STMicro.

  • macOS: No driver is required for macOS.

  • Linux: Run the following in terminal and logout and login for the group change to take effect:

    # Copy the default rules. This grants permission to the group 'plugdev'
    sudo cp ~/.arduino15/packages/AZ3166/tools/openocd/0.10.0/linux/contrib/60-openocd.rules /etc/udev/rules.d/
    sudo udevadm control --reload-rules
    
    # Add yourself to the group 'plugdev'
    # Logout and log back in for the group to take effect
    sudo usermod -a -G plugdev $(whoami)

Azure account

To use Azure IoT Hub you will need an Azure subscription. If you don't have a subscription you can sign up for free at azure.microsoft.com/free/. You will need a credit card for verification purposes only, you will not be billed unless you decide to upgrade your account to a paid offering.

If you are a student aged 18 and up, or teacher and have an email address from an academic institution, you can sign up for the free Azure for Students offer at azure.microsoft.com/free/students. This gives you the same services and credit as the free account, but you don't need a credit card.

At the time of writing the free account will give you US$200 of free credit to spend on what you like in the first 30 days ($100 for the student account), 12 months of free services, plus a load of services that have tiers that are always free.

For this workshop you can use the free tier of IoT Hub. If you already have an Azure account you can use this, using a free tier IoT Hub.

The workshop

This workshop is implemented in both C and C#. The code running on the MXChip is in C, the code for the Azure Functions is in C#. The code does not have any error handling, it is intended to be as short as possible to help illustrate how to program the board as opposed to being production ready code.

The steps

The steps for the workshop are in the Steps folder.

1. Configure the MXChip board
2. Configure Visual Studio Code
3. Show the temperature
4. Send the temperature to Azure IoT Hub
5. Store the temperature using Azure Functions and Cosmos DB
6. Expose the temperature using Azure Functions
7. Configure the LED colour threshold using Device Twins
8. Clean up

The code

You can find the code created in this workshop in the Code folder. This is provided for reference only, you don't need to use this sample code as everything you need to write is covered in the workshop.

• Final - the final code you will create once you complete this workshop.

Next steps

This workshop is only a taster to get started programming the MXChip board and connecting it to the cloud using Azure Functions and Device Twins.

Extend the sample

Internet-connected fan

If you want to build more, check out this sample adding a fan to the set up, turning this on and off as well as controlling the LED when the temperature crosses the threshold.

Try some more samples

There is a growing catalog of projects from both the Microsoft IoT teams and the community available at microsoft.github.io/azure-iot-developer-kit/docs/projects/.

Host this workshop

Please get in touch if you would like to host this workshop at your meetup group or community event. There are Microsoft Cloud Advocates all around the world who can help host this event.

mxchip-workshop's Issues

Add timings

Add timings to each step so that a workshop can be built to suit based on available time

Create sample code for each step

Add sample code to the Code folder for each individual step

Add verification step to ensure setup is working

Be good to have a step people can run to verify that all the right bits are installed and configured.

Create video walkthrough and train the trainer materials

Create materials for anyone to learn how to give this workshop - both a written and video guide.

Add images for VS Code

Add more images to the steps, especially screenshots of the VS Code command palette, dialogs and output.

Test this workshop on Linux

Both Visual Studio Code and the Arduino IDE run on Linux, so test this workshop on Linux, updating instructions where required

Add stream analytics step

Add stream analytics step to analyse the data. Smooth out the temperature vs threshold and configure the fan on/off using this

Add javascript support

This workshop currently supports C# only. Would be good to have a javascript version as well.

Add time series insights step

Add time series insights step after uploading data to see it

Add troubleshooting

Whilst running this workshop, a few issues popped up a lot, usually due to not installing or configuring something.

Add trouble shooting for these kind of issues (e.g. no function code appearing - install the .NET SDK).