Connect IoT DevKit AZ3166 to Azure IoT Hub in the cloud

You can use the MXChip IoT DevKit to develop and prototype Internet of Things (IoT) solutions that take advantage of Microsoft Azure services. It includes an Arduino-compatible board with rich peripherals and sensors, an open-source board package, and a growing projects catalog.

What you do

Connect the DevKit to an Azure IoT hub that you create, collect the temperature and humidity data from sensors, and send the data to the IoT hub.

Don't have a DevKit yet? Try DevKit simulator or get one.

What you learn

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

What you need

Prepare your hardware

Hook up the hardware to your computer.

You need this hardware:

  • DevKit board
  • Micro-USB cable

Required hardware

To connect the DevKit to your computer:

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

Hardware connections

Configure Wi-Fi

IoT projects rely on internet connectivity. Use the following instructions to configure the DevKit to connect to Wi-Fi.

Enter AP mode

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

Reset button, button B, and SSID

Connect to DevKit AP

Now, use another Wi-Fi enabled device (computer or mobile phone) to connect to the DevKit SSID (highlighted in the previous image). Leave the password empty.

Network info and Connect button

Configure Wi-Fi for the DevKit

Open the IP address shown on the DevKit screen on your computer or mobile phone browser, select the Wi-Fi network that you want the DevKit to connect to, and then type the password. Select Connect.

Password box and Connect button

When the connection succeeds, the DevKit reboots in a few seconds. You then see the Wi-Fi name and IP address on the screen:

Wi-Fi name and IP address

Note

The IP address displayed in the photo might not match the actual IP address assigned and displayed on the DevKit screen. This is normal, because Wi-Fi uses DHCP to dynamically assign IPs.

After Wi-Fi is configured, your credentials will persist on the device for that connection, even if the device is unplugged. For example, if you configure the DevKit for Wi-Fi in your home and then take the DevKit to the office, you will need to reconfigure AP mode (starting at the step in the "Enter AP Mode" section) to connect the DevKit to your office Wi-Fi.

Start using the DevKit

The default app running on the DevKit checks the latest version of the firmware and displays some sensor diagnosis data for you.

Upgrade to the latest firmware

Note

Since v1.1, DevKit enables ST-SAFE in bootloader. You need to upgrade firmware if you are running under v1.1 in order to make it work probably.

If you need a firmware upgrade, the screen will show the current and latest firmware versions. To upgrade, follow the Upgrade firmware guide.

Display of current and latest firmware versions

Note

This is a one-time effort. After you start developing on the DevKit and upload your app, the latest firmware will come with your app.

Test various sensors

Press button B to test sensors. Continue pressing and releasing the button B to cycle through each sensor.

Button B and sensor display

Prepare the development environment

Now it's time to set up the development environment: tools and packages for you to build stunning IoT applications. You can choose the Windows or macOS version according to your operating system.

Windows

We encourage you to use the installation package to prepare the development environment. If you encounter any problems, you can follow the manual steps to get it done.

Download the latest package

The .zip file that you download contains all the necessary tools and packages for DevKit development.

The .zip file contains the following tools and packages. If you already have some components installed, the script will 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: Tool that the extension for Arduino relies on.
  • DevKit Board Package: Tool chains, libraries, and projects for the DevKit.
  • ST-Link Utility: Essential tools and drivers.

Run the installation script

In Windows File Explorer, locate the .zip file and extract it. Find install.cmd, right-click it, and select Run as administrator.

File Explorer

During installation, you see the progress of each tool or package.

Installation progress

Note

Depending on your environment, sometimes you will get failure when installing Arduino IDE. In this case, you may try install Arduino IDE individually and run install.cmd again. Otherwise, please follow the manual steps to install all necessary tools and packages.

Install drivers

The VS Code for Arduino extension relies on the Arduino IDE. If this is the first time you are installing the Arduino IDE, you're prompted to install relevant drivers:

getting-started-driver

Installation should take around 10 minutes, depending on your internet speed. After the installation is complete, you should see Visual Studio Code and Arduino IDE shortcuts on your desktop.

Note

Occasionally, when you start VS Code, you're prompted with an error that it cannot find the Arduino IDE or related board package. To solve it, close VS Code and restart the Arduino IDE. VS Code should then locate the Arduino IDE path correctly.

macOS

We encourage you to use one-click installation experience to prepare the development environment. If you encounter any problems, you can follow the manual steps to get it done.

Install Homebrew

Note

If you have installed Homebrew, you can skip this step.

Follow the Homebrew installation instructions to install it.

Download the latest package

The .zip file that you download contains all the necessary tools and packages for DevKit development.

The .zip file contains the following tools and packages. If you already have some components installed, the script will 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: Tool that the extension for Arduino relies on.
  • DevKit Board Package: Tool chains, libraries, and projects for the DevKit.
  • ST-Link Utility: Essential tools and drivers.

Run the installation script

In the Finder, locate the .zip and extract it:

macOS finder

Launch Terminal app, locate the folder you extract .zip file and run:

./install.sh

macOS install

Note

If you meet Homebrew permission error, run brew doctor to get it fixed. Check FAQ for more details.

You now have all the necessary tools and packages installed for macOS.

Open the project folder

Start VS Code

Make sure your DevKit is not connected. Start VS Code first and connect the DevKit to your computer. VS Code automatically finds the DevKit and opens an introduction page:

Introduction page

Note

Occasionally, when you start VS Code, you're prompted with an error that it cannot find the Arduino IDE or related board package. Close VS Code and restart the Arduino IDE. VS Code should then locate the Arduino IDE path correctly.

Open the Arduino Examples folder

On the Arduino Examples tab, browse to Examples for MXCHIP AZ3166 > AzureIoT, and select GetStarted.

Arduino Examples tab

If you happen to close the pane, you can reopen it. Use Ctrl+Shift+P (macOS: Cmd+Shift+P) to open the command palette, type Arduino, and then find and select Arduino: Examples.

Provision Azure services

In the solution window, run your task through Ctrl+P (macOS: Cmd+P) by entering task cloud-provision.

In the VS Code terminal, an interactive command line guides you through provisioning the required Azure services:

Interactive command line

Build and upload the Arduino sketch

Windows

  1. Use Ctrl+P to run task device-upload.
  2. The terminal prompts you to enter configuration mode. To do so, hold down button A, then push and release the reset button. The screen displays the DevKit id and 'Configuration'.

This is to set the connection string that retrieves from task cloud-provision step.

Then VS Code starts verifying and uploading the Arduino sketch:

Verification and upload of the Arduino sketch

The DevKit reboots and starts running the code.

Note

Occasionally, you get error "Error: AZ3166: Unknown package". This is due to the board package index is not refreshed. Check this FAQ steps to solve it.

macOS

  1. Put DevKit into configuration mode: Hold down button A, then push and release the reset button. The screen displays 'Configuration'.
  2. Use Cmd+P to run task device-upload.

This is to set the connection string that retrieves from task cloud-provision step.

Then VS Code starts verifying and uploading the Arduino sketch:

device-upload

The DevKit reboots and starts running the code.

Note

Occasionally, you get error "Error: AZ3166: Unknown package". This is due to the board package index is not refreshed. Check this FAQ steps to solve it.

Test the project

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

  1. Click the COM[X] word on the status bar to set the right COM port with STMicroelectronics: com-port

  2. Click power plug icon on the status bar to open the Serial Monitor: serial-monitor

  3. On the status bar, click the number that represents the Baud Rate and set to 115200: baud-rate

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

  • The Serial Monitor displays the same information as the content in the screenshot below.
  • The LED on MXChip IoT DevKit is blinking.

Final output in VS Code

Problems and feedback

If you encounter problems, you can find FAQs. You can also give us feedback by leaving a comment on this page.

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.

To continue getting started with Azure IoT Hub and to explore other IoT scenarios, see: