Connect IoT DevKit AZ3166 to Azure IoT Hub

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 rich sample gallery.

What you learn

  • How to create an IoT hub and register a device for the MXChip IoT DevKit.
  • How to connect the IoT DevKit to Wi-Fi and configure the IoT Hub connection string.
  • How to send the DevKit sensor telemetry data to your IoT hub.
  • How to prepare the development environment and develop application for the IoT DevKit.

Don't have a DevKit yet? Try the DevKit simulator or purchase a DevKit.

You can find the source code for all DevKit tutorials from code samples gallery.

What you need

  • Use Azure Cloud Shell using the bash environment.

    Embed launch

  • If you prefer, install the Azure CLI to run CLI reference commands.

    • If you're using a local install, sign in with Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. See Sign in with Azure CLI for additional sign-in options.
    • When you're prompted, install Azure CLI extensions on first use. For more information about extensions, see Use extensions with Azure CLI.
    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Prepare your hardware

Hook up the following hardware to your computer:

  • DevKit board
  • Micro-USB cable

Required hardware

To connect the DevKit to your computer, follow these steps:

  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

Quickstart: Send telemetry from DevKit to an IoT Hub

The quickstart uses pre-compiled DevKit firmware to send the telemetry to the IoT Hub. Before you run it, you create an IoT hub and register a device with the hub.

Create an IoT hub

This section describes how to create an IoT hub using the Azure portal.

  1. Sign in to the Azure portal.

  2. From the Azure homepage, select the + Create a resource button, and then enter IoT Hub in the Search the Marketplace field.

  3. Select IoT Hub from the search results, and then select Create.

  4. On the Basics tab, complete the fields as follows:

    • Subscription: Select the subscription to use for your hub.

    • Resource Group: Select a resource group or create a new one. To create a new one, select Create new and fill in the name you want to use. To use an existing resource group, select that resource group. For more information, see Manage Azure Resource Manager resource groups.

    • Region: Select the region in which you want your hub to be located. Select the location closest to you. Some features, such as IoT Hub device streams, are only available in specific regions. For these limited features, you must select one of the supported regions.

    • IoT Hub Name: Enter a name for your hub. This name must be globally unique. If the name you enter is available, a green check mark appears.


    Because the IoT hub will be publicly discoverable as a DNS endpoint, be sure to avoid entering any sensitive or personally identifiable information when you name it.

    Create a hub in the Azure portal

  5. Select Next: Size and scale to continue creating your hub.

    Set the size and scale for a new hub using the Azure portal

    You can accept the default settings here. If desired, you can modify any of the following fields:

    • Pricing and scale tier: Your selected tier. You can choose from several tiers, depending on how many features you want and how many messages you send through your solution per day. The free tier is intended for testing and evaluation. It allows 500 devices to be connected to the hub and up to 8,000 messages per day. Each Azure subscription can create one IoT hub in the free tier.

      If you are working through a Quickstart for IoT Hub device streams, select the free tier.

    • IoT Hub units: The number of messages allowed per unit per day depends on your hub's pricing tier. For example, if you want the hub to support ingress of 700,000 messages, you choose two S1 tier units. For details about the other tier options, see Choosing the right IoT Hub tier.

    • Azure Security Center: Turn this on to add an extra layer of threat protection to IoT and your devices. This option is not available for hubs in the free tier. For more information about this feature, see Azure Security Center for IoT.

    • Advanced Settings > Device-to-cloud partitions: This property relates the device-to-cloud messages to the number of simultaneous readers of the messages. Most hubs need only four partitions.

  6. Select Next: Tags to continue to the next screen.

    Tags are name/value pairs. You can assign the same tag to multiple resources and resource groups to categorize resources and consolidate billing. For more information, see Use tags to organize your Azure resources.

    Assign tags for the hub using the Azure portal

  7. Select Next: Review + create to review your choices. You see something similar to this screen, but with the values you selected when creating the hub.

    Review information for creating the new hub

  8. Select Create to create your new hub. Creating the hub takes a few minutes.

Register a device

A device must be registered with your IoT hub before it can connect. In this quickstart, you use the Azure Cloud Shell to register a simulated device.

  1. Run the following command in Azure Cloud Shell to create the device identity.

    YourIoTHubName: Replace this placeholder below with the name you choose for your IoT hub.

    MyNodeDevice: The name of the device you're registering. Use MyNodeDevice as shown. If you choose a different name for your device, you need to use that name throughout this article, and update the device name in the sample applications before you run them.

    az iot hub device-identity create --hub-name YourIoTHubName --device-id MyNodeDevice


    If you get an error running device-identity, install the Azure IoT Extension for Azure CLI. Run the following command to add the Microsoft Azure IoT Extension for Azure CLI to your Cloud Shell instance. The IoT Extension adds commands that are specific to IoT Hub, IoT Edge, and IoT Device Provisioning Service (DPS) to Azure CLI.

    az extension add --name azure-iot
  2. Run the following commands in Azure Cloud Shell to get the device connection string for the device you just registered:

    YourIoTHubName: Replace this placeholder below with the name you choose for your IoT hub.

    az iot hub device-identity show-connection-string --hub-name YourIoTHubName --device-id MyNodeDevice --output table

    Make a note of the device connection string, which looks like:


    You use this value later in the quickstart.

Send DevKit telemetry

The DevKit connects to a device-specific endpoint on your IoT hub and sends temperature and humidity telemetry.

  1. Download the latest version of GetStarted firmware for IoT DevKit.

  2. Make sure IoT DevKit connect to your computer via USB. Open File Explorer there is a USB mass storage device called AZ3166.

    Open Windows Explorer

  3. Drag and drop the firmware just downloaded into the mass storage device and it will flash automatically.

    Copy firmware

  4. On the DevKit, Hold down button B, push and release the Reset button, and then release button B. Your DevKit enters AP mode. To confirm, the screen displays the service set identifier (SSID) of the DevKit and the configuration portal IP address.

    Reset button, button B, and SSID

    Set AP Mode

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

    Connect SSID

  6. Open in the browser. Select the Wi-Fi that you want the IoT DevKit connect to, type the Wi-Fi password, then paste the device connection string you made note of previously. Then click Save.

    Configuration UI


    The IoT DevKit only supports 2.4GHz network. Check FAQ for more details.

  7. The WiFi information and device connection string will be stored into the IoT DevKit when you see the result page.

    Configuration result


    After Wi-Fi is configured, your credentials will persist on the device for that connection, even if the device is unplugged.

  8. The IoT DevKit reboots in a few seconds. On the DevKit screen, you see the IP address for the DevKit follows by the telemetry data including temperature and humidity value with message count send to Azure IoT Hub.

    WiFi IP

    Sending data

  9. To verify the telemetry data sent to Azure, run the following command in Azure Cloud Shell:

    az iot hub monitor-events --hub-name YourIoTHubName --output table

Prepare the development environment

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

Install Visual Studio Code with Azure IoT Tools extension package

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

    • Windows: Use Windows Installer version. Do not install from the App Store.
    • macOS: Drag and drop the extracted into /Applications folder.
    • Ubuntu: Unzip it into folder such as $HOME/Downloads/arduino-1.8.8
  2. Install Visual Studio Code, a cross platform source code editor with powerful intellisense, code completion and debugging support as well as rich extensions can be installed from marketplace.

  3. Launch VS Code, look for Arduino in the extension marketplace and install it. This extension provides enhanced experiences for developing on Arduino platform.

    Install Arduino

  4. Look for Azure IoT Tools in the extension marketplace and install it.

    Screenshot that shows Azure IoT Tools in the extension marketplace.

    Or copy and paste this URL into a browser window: vscode:extension/


    The Azure IoT Tools extension pack contains the Azure IoT Device Workbench which is used to develop and debug on various IoT devkit devices. The Azure IoT Hub extension, also included with the Azure IoT Tools extension pack, is used to manage and interact with Azure IoT Hubs.

  5. Configure VS Code with Arduino settings.

    In Visual Studio Code, click File > Preferences > Settings (on macOS, Code > Preferences > Settings). Then click the Open Settings (JSON) icon in the upper-right corner of the Settings page.

    Install Azure IoT Tools

    Add following lines to configure Arduino depending on your platform:

    • Windows:

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

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

      Replace the {username} placeholder below with your username.

      "arduino.path": "/home/{username}/Downloads/arduino-1.8.8",
      "arduino.additionalUrls": ""
  6. Click F1 to open the command palette, type and select Arduino: Board Manager. Search for AZ3166 and install the latest version.

    Install DevKit SDK

ST-Link/V2 is the USB interface that IoT DevKit uses to communicate with your development machine. You need to install it on Windows to flash the compiled device code to the DevKit. Follow the OS-specific steps to allow the machine access to your device.

  • Windows: Download and install USB driver from STMicroelectronics website.

  • macOS: No driver is required for macOS.

  • Ubuntu: Run the commands in terminal and sign out and sign in 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)

Now you are all set with preparing and configuring your development environment. Let us build the GetStarted sample you just ran.

Build your first project

The IoT DevKit contains a rich gallery of samples that you can use to learn connect the DevKit to various Azure services.

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

  2. Click F1 to open the command palette, type and select Azure IoT Device Workbench: Open Examples.... Then select IoT DevKit as board.

  3. In the IoT Workbench Examples page, find Get Started and click Open Sample. Then selects the default path to download the sample code.

    Open sample

Provision Azure IoT Hub and device

Instead of provisioning Azure IoT Hub and device from the Azure portal, you can do it in the VS Code without leaving the development environment.

  1. In the new opened project window, click F1 to open the command palette, type and select Azure IoT Device Workbench: Provision Azure Services.... Follow the step by step guide to finish provisioning your Azure IoT Hub and creating the IoT Hub device.

    Provision command


    If you have not signed in Azure. Follow the pop-up notification for signing in.

  2. Select the subscription you want to use.

    Select sub

  3. Then select or create a new resource group.

    Select resource group

  4. In the resource group you specified, follow the guide to select or create a new Azure IoT Hub.

    Select IoT Hub steps

    Select IoT Hub

    Selected IoT Hub

  5. In the output window, you will see the Azure IoT Hub provisioned.

    IoT Hub Provisioned

  6. Select or create a new device in Azure IoT Hub you provisioned.

    Select IoT Device steps

    Select IoT Device Provisioned

  7. Now you have Azure IoT Hub provisioned and device created in it. Also the device connection string will be saved in VS Code for configuring the IoT DevKit later.

    Provision done

Configure and compile device code

  1. 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 COM

  2. Click F1 to open the command palette, type and select Azure IoT Device Workbench: Configure Device Settings..., then select Config Device Connection String > Select IoT Hub Device Connection String.

  3. On DevKit, 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.

    Connection string

  4. Click F1 again, type and select Azure IoT Device Workbench: Upload Device Code. It starts compile and upload the code to DevKit.

    Arduino upload

The DevKit reboots and starts running the code.


If there is any errors or interruptions, you can always recover by running the command again.

Test the project

View the telemetry sent to Azure IoT Hub

Click the power plug icon on the status bar to open the Serial Monitor:

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.

Serial monitor output


You might encounter an error during testing in which the LED isn't blinking, the Azure portal doesn't show incoming data from the device, but the device OLED screen shows as Running.... To resolve the issue, in the Azure portal, go to the device in the IoT hub and send a message to the device. If you see the following response in the serial monitor in VS Code, it's possible that direct communication from the device is blocked at the router level. Check firewall and router rules that are configured for the connecting devices. Also, ensure that outbound port 1833 is open.

ERROR: mqtt_client.c (ln 454): Error: failure opening connection to endpoint
INFO: >>>Connection status: disconnected
ERROR: tlsio_mbedtls.c (ln 604): Underlying IO open failed
ERROR: mqtt_client.c (ln 1042): Error: io_open failed
ERROR: iothubtransport_mqtt_common.c (ln 2283): failure connecting to address
INFO: >>>Re-connect.
INFO: IoThub Version: 1.3.6

View the telemetry received by Azure IoT Hub

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

  1. Sign in Azure portal, find the IoT Hub you created.

    Azure portal

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

    Azure IoT Hub connection string

  3. In VS Code, click F1, type and select Azure IoT Hub: Set IoT Hub Connection String. Copy the connection string into it.

    Set Azure IoT Hub connection string

  4. Expand the AZURE IOT HUB DEVICES pane on the left, right click on the device name you created and select Start Monitoring Built-in Event Endpoint.

    Monitor D2C Message

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

    Screenshot that shows the incoming D2C messages to the IoT Hub.

Review the code

The GetStarted.ino is the main Arduino sketch file.

D2C message

To see how device telemetry is sent to the Azure IoT Hub, open the utility.cpp file in the same folder. View API Reference to learn how to use sensors and peripherals on IoT DevKit.

The DevKitMQTTClient used is a wrapper of the iothub_client from the Microsoft Azure IoT SDKs and libraries for C to interact with Azure IoT Hub.

Problems and feedback

If you encounter problems, you can check for a solution in the IoT DevKit FAQ or reach out to us from Gitter. 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 to get started with Azure IoT Hub and to explore other IoT scenarios using IoT DevKit, see the following: