Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jimbobbennett/mxchip-workshop

A hands on workshop to get started with an MXChip board 🤖
https://github.com/jimbobbennett/mxchip-workshop

azure azure-functions azure-iot c mxchip-board mxchip-iot-devkit

Last synced: about 6 hours ago
JSON representation

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

Awesome Lists containing this project

README 

        
# 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](http://mxchip.com/az3166) and the [Azure IoT Hub](https://azure.microsoft.com/services/iot-hub/?WT.mc_id=mxchipworkshop-github-jabenn).



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](https://azure.microsoft.com/services/cosmos-db/?WT.mc_id=mxchipworkshop-github-jabenn). This value can be retrieved via an API built using [Azure functions](https://azure.microsoft.com/services/functions/?WT.mc_id=mxchipworkshop-github-jabenn). 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](https://docs.microsoft.com/azure/iot-hub/tutorial-device-twins/?WT.mc_id=mxchipworkshop-github-jabenn).



## 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.



![The MXChip board with a list of components](./Images/MXChipBoard.png)



## 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](https://azure.microsoft.com/services/iot-hub/?WT.mc_id=mxchipworkshop-github-jabenn)



## 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](https://github.com/jimbobbennett/MXChip-Workshop/issues/1).



### 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](https://amzn.to/2CdVgB1)

* [DFRobot](https://www.dfrobot.com/product-1616.html)

* [Seeed](https://www.seeedstudio.com/AZ3166-IOT-Developer-Kit-p-2922.html)



### Software



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



* [Visual Studio Code](https://code.visualstudio.com/Download/?WT.mc_id=mxchipworkshop-github-jabenn)

* [Arduino IDE](https://www.arduino.cc/en/Main/Software) - **NOTE** On Windows DO NOT install using the Windows store, instead use the *Windows Installer, for Windows XP and up*.

* [.NET Core SDK](https://dotnet.microsoft.com/download)

* [Azure Functions Core Tools](https://docs.microsoft.com/azure/azure-functions/functions-run-local/?WT.mc_id=mxchipworkshop-github-jabenn)

* 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](http://www.st.com/en/development-tools/stsw-link009.html).



  * macOS: No driver is required for macOS.



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



    ```bash

    # 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/](https://azure.microsoft.com/free/?WT.mc_id=mxchipworkshop-github-jabenn). 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](https://azure.microsoft.com/free/students/?WT.mc_id=mxchipworkshop-github-jabenn). 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](./Steps) folder.



1. [Configure the MXChip board](./Steps/ConfigureTheBoard.md)

2. [Configure Visual Studio Code](./Steps/ConfigureVSCode.md)

3. [Show the temperature](./Steps/ShowingTheTemperature.md)

4. [Send the temperature to Azure IoT Hub](./Steps/SendingTheTemperature.md)

5. [Store the temperature using Azure Functions and Cosmos DB](./Steps/StoreTheTemperature.md)

6. [Expose the temperature using Azure Functions](./Steps/ExposeTheTemperature.md)

7. [Configure the LED colour threshold using Device Twins](./Steps/ControlTheLEDThreshold.md)

8. [Clean up](./Steps/CleanUp.md)



### The code



You can find the code created in this workshop in the [Code](./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](./Code/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](https://github.com/jimbobbennett/InternetConnectedFan) adding a fan to the set up, turning this on and off as well as controlling the LED when the temperature crosses the threshold.



![A fan connected to an MXChip](https://github.com/jimbobbennett/InternetConnectedFan/raw/master/Images/PhotoOfFinalHardware.jpg)



### 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/](https://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](https://developer.microsoft.com/advocates/index.html?WT.mc_id=mxchipworkshop-github-jabenn) who can help host this event.