Get started

For first-time users of the MXChip IoT DevKit (a.k.a. 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 DevKit to a wireless access point.
  • How to install the development environment.
  • How to create an IoT Hub and register a device for the DevKit.
  • How to collect sensor data by running a sample application on the DevKit.
  • How to send the DevKit sensor data to your IoT hub.

What you need

Required hardware

Prepare your hardware

To connect the DevKit to your computer:

  1. Connect the Micro-USB end to the 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 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 DevKit SSID displayed in the previous step. If it asks for a password, leave it empty. Network info and Connect button

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

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

Note: After asuccessful Wi-Fi connection, the currently-installed and latest available version of the DevKit’s firmware is displayed on the DevKit screen. If the DevKit is not running on the latest available version, follow the firmware upgrading guide to install the latest version.

Install development environment

We encourage you to use the following one-click installation process to prepare the development environment. If you encounter any problems, you can always follow the manual steps to complete the process.

Windows

  1. Download the .zip file that contains all the tools and packages for DevKit development. Download

    The .zip file installs the following tools and packages. (If you already have some of them installed, the script can detect and skip them.)

    • Node.js and Yarn: Runtime for the setup script and automated tasks.
    • Azure CLI 2.0 MSI - Cross-platform command-line experience for managing Azure resources. The MSI contains dependent Python and pip.
    • Visual Studio Code (VS Code): Lightweight code editor for DevKit development.
    • Visual Studio Code extension for Arduino: Extension that enables Arduino development in Visual Studio Code.
    • Arduino IDE: The extension for Arduino relies upon this tool.
    • DevKit Board Package: Tool chains, libraries, and projects for the DevKit.
    • ST-Link Utility: Essential tools and drivers.
  2. Extract the downloaded file. Find install.cmd, right-click on it, and select Run as administrator: File Explorer

  3. Click Next to confirm install utilities like ST-Link drivers. getting-started-driver

Notice: Do not unzip the downloaded .zip file into a network folder and attempt to install from it from there. If you, the doArduino IDE can fail to find correct file locations.

The installation should take around 5 to 10 minutes, depending upon your internet speed. After it is complete, you should see Visual Studio Code and Arduino IDE shortcuts on your desktop.

macOS

Homebrew is the easiest way to manage your CLI install. It provides convenient ways to install, update, and uninstall. If you don’t have homebrew available on your system, install homebrew before continuing.

  1. Download the .zip file that contains all the tools and packages for DevKit development. Download

    The .zip file installs the following tools and packages. (If you already have some of them installed, the script can detect and skip them.)

    • Node.js and Yarn: Runtime for the setup script and automated tasks.
    • Azure CLI 2.0 - Cross-platform command-line experience for managing Azure resources.
    • Visual Studio Code (VS Code): Lightweight code editor for DevKit development.
    • Visual Studio Code extension for Arduino: Extension that enables Arduino development in Visual Studio Code.
    • Arduino IDE: The extension for Arduino relies on this tool.
    • DevKit Board Package: Tool chains, libraries, and projects for the DevKit.
    • ST-Link Utility: Essential tools and drivers.
  2. Extract the downloaded file. macOS finder

  3. Launch Terminal app, locate the folder into which you extracted the .zip file, and run:
      ./install.sh
    

    macOS install

Notice: If you encounter a Homebrew permission error, run brew doctor to fix it. Check FAQ for more details.

Notice: Do not unzip the downloaded .zip file into a network folder and attempt to install from it from there. If you, the doArduino IDE can fail to find correct file locations.

Open sample projects folder

  1. Make sure your DevKit is not connected to your computer. Start VS Code first, and then connect the DevKit to your computer.

  2. Expand left side ARDUINO EXAMPLES section, browse to Examples for MXCHIP AZ3166 > AzureIoT, and select GetStarted. Arduino Examples tab

A new VS Code window opens with GetStarted project files.

Note: If you happen to close the pane, you can reopen it. Click F1 to open the command palette, type Arduino, and then find and select Arduino: Examples.

Provision Azure services

  1. Provision Azure services by typing Ctrl+P (macOS: Cmd+P), then typing task and selecting task cloud-provision. An interactive terminal window opens and guides you to provision the required Azure services. Interactive command line

  2. Follow the guide to log in to Azure and finish the provisioning process. Provision Azure IoT Hub done

    The task automates Azure services provisioning. Here are the required items for getting the provision done.

    • Azure subscription: It is tied to your Azure account.
    • Azure Resource Group: It provides a way to monitor, control access, provision and manage billing for collections of assets that are required to run an application, or used by a client or company department.
    • Azure IoT Hub: A fully managed service that enables reliable and secure bidirectional communications between millions of IoT devices and a solution back end.
    • Device ID: Before a device can connect to an IoT hub, there must be an entry for that device in the IoT hub’s identity registry.
  3. After completing the provisioning process, press any key to close the terminal window.

Configure device connection string

  1. Configure the device’s connection string by typing Ctrl+P (macOS: Cmd+P), then typing task and selecting task config-device-connection. Configure connection string

  2. Click Enter to configure the connection string that retrieves from the cloud provisioning step.

  3. Hold down button A, push and release the reset button, and then release button A. Your DevKit enters configuration mode and saves the connection string.

  4. When done, press any key to close the terminal window.

Build and upload Arduino sketch

  1. Click F1, then type Arduino and select Arduino: Upload. Verification and upload of the Arduino sketch

The DevKit reboots and starts running the code.

Test the project

In VS Code, following these steps to open and set up the Serial Monitor:

  1. Click the COM[X] on the status bar to set the right COM port with STMicroelectronics: Set COM Port

  2. Click the power plug icon on the status bar to open the Serial Monitor: 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

Check data in Azure IoT Hub

In VS Code, you can use Azure IoT Toolkit to monitor device-to-cloud (D2C) messages in IoT Hub.

  1. Log in Azure portal, find the IoT Hub you created. azure-portal-iot-hub

  2. In the Shared access policies pane, click the iothubowner policy, and write down the Connection string of your IoT hub. azure-portal-iot-hub-conn-string

  3. In VS Code, click the Extensions icon in the Activity Bar: vscode-extensions-icon

  4. Search for Azure IoT Toolkit and install it. azure-iot-toolkit-installing

  5. Expand IoT Hub Devices on the bottom left corner. azure-iot-toolkit-iot-hub-devices

  6. Click Set IoT Hub Connection String in context menu. azure-iot-toolkit-iot-hub-conn-string

  7. Click IoT: Start monitoring D2C message in context menu.

  8. In OUTPUT pane, you can see the incoming D2C messages to the IoT Hub. azure-iot-toolkit-output-console

Problems and feedback

If you encounter problems, you can refer to FAQs or reach out to us from Gitter channel.

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 DevKit and Azure multiple services.