Find file Copy path
298 lines (171 sloc) 12.9 KB

Get Started with MXChip IoT DevKit

For first-time users of the MXChip IoT DevKit (a.k.a. IoT DevKit), follow these quick steps to:

  • Prepare your development environment.
  • Send temperature and humidity data from built-in DevKit sensors to the Azure IoT Hub.

If you have already done this, you can try more samples from the Projects Catalog or build your own IoT application.

What you learn

  • How to connect the IoT DevKit to a wireless access point.
  • How to install the development environment.
  • How to create an IoT Hub and register a device for the IoT DevKit.
  • How to collect sensor data by running a sample application on the IoT DevKit.
  • How to send the IoT DevKit sensor data to your IoT hub.

What you need

Required hardware

Prepare your hardware

To connect the IoT DevKit to your computer:

  1. Connect the Micro-USB end to the IoT DevKit.
  2. Connect the USB end to your computer.
  3. The green LED for power confirms the connection.

Hardware connections

Configure Wi-Fi

IoT projects rely on internet connectivity. Use AP Mode on the DevKit to configure and connect to Wi-Fi.

  1. Hold down button B, push and release the Reset button, and then release button B. Your IoT DevKit enters AP mode for configuring the Wi-Fi connection. The screen displays the service set identifier (SSID) of the DevKit and the configuration portal IP address:

    Reset button, button B, and SSID

  2. Use a Web browser on a different Wi-Fi enabled device (computer or mobile phone) to connect to the IoT DevKit SSID displayed in the previous step. If it asks for a password, leave it empty.

    Network info and Connect button

  3. Open in the browser. Select the Wi-Fi network that you want the IoT DevKit to connect to, type the password for the Wi-Fi conection, and then click Connect.

    Password box and Connect button

  4. The IoT DevKit reboots in a few seconds. You then see the Wi-Fi name and assigned IP address on the screen of the IoT DevKit:

    Wi-Fi name and IP address

Note: After connected to internet, the currently-installed and latest available version of the IoT DevKit's firmware is displayed on the screen. If it's not running on the latest available version, follow the firmware upgrading guide to install the latest version.

Install development environment

We recommend Azure IoT Device Workbench extension for Visual Studio Code to develop on the IoT DevKit.

Azure IoT Device Workbench provides an integrated experience to develop IoT solutions. It helps both on device and cloud development using Azure IoT and other services. You can watch this Channel9 video to have an overview of what it does.

Follow these steps to prepare the development environment for the IoT DevKit:

  1. Download and install Arduino IDE. It provides the necessary toolchain for compiling and uploading Arduino code.

Note: Arduino IDE 1.8.7 has breaking changes, causing board package and library installation failures. It is recommended to that you install version 1.8.6

  • Windows: Use Windows Installer version
  • macOS: Drag and drop the Arduino into /Applications
  • Ubuntu: Unzip it into $HOME/Downloads/arduino-1.8.5
  1. Install Visual Studio Code, a cross platform source code editor with powerful developer tooling, like IntelliSense code completion and debugging.

  2. Look for Azure IoT Device Workbench in the extension marketplace and install it. Install IoT Device Workbench Together with the IoT Device Workbench, other dependent extensions will be installed.

  3. Open File > Preference > Settings and add following lines to set the configurations for Arduino.

    Config settings

    • Windows

       "arduino.path": "C:\\Program Files (x86)\\Arduino",
       "arduino.additionalUrls": ""
    • macOS

       "arduino.path": "/Application",
       "arduino.additionalUrls": ""
    • Ubuntu

       "arduino.path": "/home/{username}/Downloads/arduino-1.8.5",
       "arduino.additionalUrls": ""
  4. Use F1 or Ctrl+Shift+P (macOS: Cmd+Shift+P) to open the command palette, type and select Arduino: Board Manager. Search for AZ3166 and install the latest version.

    Install DevKit SDK

  5. ST-Link configuration. The ST-Link/V2 is the USB interface that IoT DevKit uses to communicate with your development machine. Follow the platform specific steps to allow the machine access to your device.

    • Windows Download and install USB driver from STMicro.

    • macOS No driver is required for macOS.

    • Unbutu 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)

Build your first project

Now you are all set with preparing and configuring your development environment. Let us build a "Hello World" sample for IoT: sending temperature telemetry data to Azure IoT Hub. Make sure your IoT DevKit is not connected to your computer. Start VS Code first, and then connect the IoT DevKit to your computer.

In the bottom right status bar, check the MXCHIP AZ3166 is shown as selected board and serial port with STMicroelectronics is used.

Select board and serial port

Open Azure IoT Device Workbench Examples

Use F1 orCtrl+Shift+P (macOS: Cmd+Shift+P) to open the command palette, type Azure IoT Device Workbench, and then select Open Examples....

IoT Device Workbench: Examples

Select IoT DevKit.

IoT Device Workbench: Examples -> Select board

Then the IoT Device Workbench Example window is shown up.

IoT Device Workbench, Examples window

Find Get Started and click Open Sample button. A new VS Code window with a project folder in it opens.

Open sample

Provision Azure service

In the solution window, open the command palette and select Azure IoT Device Workbench: Provision Azure Services....

IoT Device Workbench: Cloud -> Provision

Then VS Code guides you through provisioning the required Azure services.

IoT Device Workbench: Cloud -> Provision steps

The whole process includes:

  • Select an existing IoT Hub or create a new IoT Hub.
  • Select an existing IoT Hub device or create a new IoT Hub device.

Config IoT Hub Device Connection String

  1. Switch the IoT DevKit into Configuration mode. To do so:

    • Hold down button A.
    • Push and release the Reset button.
  2. The screen displays the DevKit ID and 'Configuration'.

    IoT DevKit Configuration Mode

  3. Open the command palette and select Azure IoT Device Workbench: Configure Device Settings....

    IoT Device Workbench: Device -> Settings

  4. Select Config Device Connection string.

  5. Then select Select IoT Hub Device Connection String.

    IoT Device Workbench: Device -> Connection string

    This sets the connection string that is retrieved from the Provision Azure services step.

  6. The configuration success notification popup bottom right corner once it's done.

    IoT DevKit Connection String OK

Build and upload the device code

  1. Open the command palette and select Azure IoT Device Workbench: Upload Device Code.

    IoT Device Workbench: Device -> Upload

  2. VS Code then starts verifying and uploading the code to your DevKit.

    IoT Device Workbench: Device -> Uploaded

  3. The DevKit reboots and starts running the code.

Serial monitor usage

Use status bar

  • Select Serial Port :

    Click the Select Serial Port on the status bar and choose COM port with STMicroelectronics :

    Serial port init

    Select port init

    And you will see selected port on status bar:

    After select port

  • Open Serial Monitor :

    Click the power plug icon on the status bar :

    Open serial monitor

    And you will see result in OUTPUT view:

    After open serial monitor

  • Change Baud Rate :

    Click the baud rate button on the status bar and choose new baud rate:

    Click baud rate

    Select baud rate

    And you will see new baud rate on status bar:

    After baud rate

  • Close Serial Monitor :

    Click the close icon on the status bar :

    Close serial monitor

    And you will see result in OUTPUT view:

    After close serial monitor

Use command palette

  • Arduino: Change Baud Rate : Change the baud rate of selected serial port.
  • Arduino: Close Serial Monitor : Stop serial monitor and release the serial port.
  • Arduino: Open Serial Monitor : Open serial monitor in the intergrated output window.
  • Arduino: Select Serial Port : Change the current serial port.
  • Arduino: Send Text to Serial Port : Send a line of text via the current serial port.

Test the project

Open serial monitor.

The sample application is running successfully when you see the following results:

  • The Serial Monitor displays the message sent to the IoT Hub.
  • The LED on the MXChip IoT DevKit is blinking.

Final output in VS Code

You can use Azure IoT Hub Toolkit to monitor device-to-cloud (D2C) messages in IoT Hub:

  1. Expand AZURE IOT HUB DEVICES on the bottom left corner, click the device that you have created at Provision Azure service step and open the context menu, then click IoT: Start monitoring D2C message in context menu.


  2. In OUTPUT pane, you can see the incoming D2C messages to the IoT Hub.


Problems and feedback

If you encounter problems, you can refer to FAQs or reach out to us from:

Next Steps

You have successfully connected an MXChip IoT DevKit to your IoT hub, and you have sent the captured sensor data to your IoT hub. Check our Projects Catalog for more samples you can build with the IoT DevKit and Azure multiple services.