AZ3166

page_type	description	languages	products
sample	Connecting an MXChip AZ3166 device to Azure IoT using Azure RTOS	c	azure-iot azure-iot-hub azure-iot-pnp azure-rtos

Getting started with the MXChip AZ3166 IoT DevKit

Total completion time: 45 minutes

In this tutorial you use Azure RTOS to connect the MXChip AZ3166 IoT DevKit (hereafter, the MXChip DevKit) to Azure IoT. The article is part of the series Getting started with Azure RTOS. The series introduces device developers to Azure RTOS, and shows how to connect several device evaluation kits to Azure IoT.

You will complete the following tasks:

• Install a set of embedded development tools for programming the MXChip DevKit in C
• Build an image and flash it onto the MXChip DevKit
• Use Azure CLI to create and manage an Azure IoT hub that the MXChip DevKit will securely connect to
• Use Azure IoT Explorer to view device telemetry, view properties, and call cloud-to-device (c2d) methods
• Use VS Code, OpenOCD and GDB to debug the firmware

Prerequisites

• A PC running Microsoft Windows (Windows 10 recommended)

• If you don't have an Azure subscription, create one for free before you begin.

• Hardware

  • The MXChip AZ3166 IoT DevKit (MXChip DevKit)
  • Wi-Fi 2.4 GHz
  • USB 2.0 A male to Micro USB male cable

Prepare the development environment

To set up your development environment, first you clone a GitHub repo that contains all the assets you need for the tutorial. Then you install a set of programming tools.

Clone the repo for the tutorial

Clone the following repo to download all sample device code, setup scripts, and offline versions of the documentation. If you previously cloned this repo in another tutorial, you don't need to do it again.

To clone the repo, run the following command in Ubuntu bash command line:

git clone --recursive https://github.com/VSChina/devkit-rtos-getting-started.git

Install the tools

The cloned repo contains a setup script that installs and configures the required tools. If you installed these tools in another tutorial in the getting started guide, you don't need to do it again.

Note: The setup script installs the following tools:

• GCC: Compile
• CMake: Build
• Termite: Monitor COM port output for connected devices
• Azure IoT Explorer: Cross-platform utility to monitor and manage Azure IoT resources

To run the setup script:

1. From File Explorer, navigate to the following path in the repo and run the setup script named get-toolchain.bat:

   devkit-rtos-getting-started\tools\get-toolchain.bat

   After the installation completes, the Azure IoT Explorer opens automatically. Keep the IoT Explorer open, you'll use it in later steps.

2. After the installation, open a new console window to recognize the configuration changes made by the setup script. Use this console to complete the remaining programming tasks in the tutorial. You can use Windows CMD, PowerShell, or Git Bash for Windows.

3. Run the following code to confirm that CMake version 3.14 or later is installed.

   cmake --version

Prepare Azure resources

To prepare Azure cloud resources and connect a device to Azure, you can use Azure CLI. There are two ways to access the Azure CLI: by using the Azure Cloud Shell, or by installing Azure CLI locally. Azure Cloud Shell lets you run the CLI in a browser so you don't have to install anything.

Use one of the following options to run Azure CLI.

If you prefer to run Azure CLI locally:

1. If you already have Azure CLI installed locally, run az --version to check the version. This tutorial requires Azure CLI 2.10.1 or later.
2. To install or upgrade, see Install Azure CLI. If you install Azure CLI locally, you can run CLI commands in the GCC Command Prompt, Git Bash for Windows, or PowerShell.

If you prefer to run Azure CLI in the browser-based Azure Cloud Shell:

1. Use your Azure account credentials to sign into the Azure Cloud shell at https://shell.azure.com/.

   Note: If this is the first time you've used the Cloud Shell, it prompts you to create storage, which is required to use the Cloud Shell. Select a subscription to create a storage account and Microsoft Azure Files share.

2. Select Bash or PowerShell as your preferred CLI environment in the Select environment dropdown. If you plan to use Azure Cloud Shell, keep your browser open to run the Azure CLI commands in this tutorial.

   

Create an IoT hub

You can use Azure CLI to create an IoT hub that handles events and messaging for your device.

To create an IoT hub:

1. In your CLI console, run the az extension add command to add the Microsoft Azure IoT Extension for Azure CLI to your CLI shell. The IOT Extension adds IoT Hub, IoT Edge, and IoT Device Provisioning Service (DPS) specific commands to Azure CLI.

   az extension add --name azure-iot

2. Run the az group create command to create a resource group. The following command creates a resource group named MyResourceGroup in the centralus region.

   Note: You can optionally set an alternate location. To see available locations, run az account list-locations. For this tutorial we recommend using centralus as in the example CLI command. The IoT Plug and Play feature that you use later in the tutorial, is currently only available in three regions, including centralus.

   az group create --name MyResourceGroup --location centralus

3. Run the az iot hub create command to create an IoT hub. It might take a few minutes to create an IoT hub.

   YourIotHubName. Replace this placeholder below with the name you chose for your IoT hub. An IoT hub name must be globally unique in Azure. This placeholder is used in the rest of this tutorial to represent your unique IoT hub name.

   az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName}

4. After the IoT hub is created, view the JSON output in the console, and copy the hostName value to a safe place. You use this value in a later step. The hostName value looks like the following example:

   {Your IoT hub name}.azure-devices.net

Register a device

In this section, you create a new device instance and register it with the IoT hub you created. You will use the connection information for the newly registered device to securely connect your physical device in a later section.

To register a device:

1. In your console, run the az iot hub device-identity create command. This creates the simulated device identity.

   YourIotHubName. Replace this placeholder below with the name you chose for your IoT hub.

   MyMXChipDevice. You can use this name directly for the device in CLI commands in this tutorial. Optionally, use a different name.

   az iot hub device-identity create --device-id MyMXChipDevice --hub-name {YourIoTHubName}

2. After the device is created, view the JSON output in the console, and copy the deviceId and primaryKey values to use in a later step.

Confirm that you have the copied the following values from the JSON output to use in the next section:

• hostName
• deviceId
• primaryKey

Prepare the device

To connect the MXChip DevKit to Azure, you'll modify a configuration file for Wi-Fi and Azure IoT settings, rebuild the image, and flash the image to the device.

Add configuration

1. In VSCode or any other text editor, edit the file devkit-rtos-getting-started/MXChip/AZ3166/app/azure_config.h to set the Wi-Fi constants to the following values from your local environment.

   Constant name	Value
   WIFI_SSID	{Your Wi-Fi ssid}
   WIFI_PASSWORD	{Your Wi-Fi password}
   WIFI_MODE	{Your Wi-Fi security type}

2. Edit the same file to set the Azure IoT device information constants to the values that you saved after you created Azure resources.

   Constant name	Value
   IOT_HUB_HOSTNAME	{Your Iot hub hostName value}
   IOT_DEVICE_ID	{Your deviceID value}
   IOT_PRIMARY_KEY	{Your primaryKey value}

Build the image

In your console or in File Explorer, run the script rebuild.bat at the following path to build the image:

devkit-rtos-getting-started\MXChip\AZ3166\tools\rebuild.bat

After the build completes, confirm that the binary files were created in the following path:

devkit-rtos-getting-started/MXChip/AZ3166/build/app/mxchip_azure_iot.bin

Flash the image

1. On the MXChip DevKit, locate the Reset button, and the Micro USB port. You use these components in the following steps. Both are highlighted in the following picture:

   

2. Connect the Micro USB cable to the Micro USB port on the MXChip DevKit, and then connect it to your computer.

3. In File Explorer, find the MXChip DevKit device connected to your computer. It is a driver labeled as AZ3166.

4. Copy the image file mxchip_azure_iot.bin that you created in the previous section, and paste it into the root folder of the MXChip DevKit. The flashing process starts automatically.

   Note: During the flashing process, the RED LED toggled on MXChip DevKit. The process completes in a few seconds without further notification.

Confirm device connection details

You can use the Termite utility to monitor communication and confirm that your device is set up correctly.

Note: If you have issues getting your device to initialize or connect after flashing, see Troubleshooting.

1. Open Device Manager and find the COM port for the MXChip IoT DevKit.

   

2. Start Termite.

3. Select Settings.

4. In the Serial port settings dialog, check the following settings and update if needed:

   • Baud rate: 115,200
   • Data bits: 8
   • Stop bits: 1

   

5. Select OK.

   Now you can view the terminal output. The MXChip DevKit provides initialization messages about your connection and key protocols, and then publishes telemetry from the sensors on the device.

   

Interact with the device using Azure IoT Explorer

You can use the Azure IoT Explorer to view and manage the properties of your devices. In the following steps, you'll add a connection to your IoT hub in IoT Explorer. With the connection, you can view properties for devices associated with the IoT hub. Optionally, you can perform the same task using Azure CLI.

To add a connection to your IoT hub:

1. In your CLI console, run the az iot hub show-connection-string command to get the connection string for your IoT hub.

   az iot hub show-connection-string --name {YourIoTHubName}

2. Copy the connection string without the surrounding quotation characters.

3. In Azure IoT Explorer, select IoT hubs > Add connection.

4. Paste the connection string into the Connection string box.

5. Select Save.

   

If the connection succeeds, the Azure IoT Explorer switches to a Devices view and lists your device.

Azure IoT explorer needs a local copy of the model file that matches the Model ID your device sends. The model file lets Azure IoT explorer display the telemetry, properties, and commands that your device implements.Configure a local folder from Home->IoT Plug and Play Settings->Add Local Folder where you stored the RTOSGetStarted.json.

Once the device is successfully connected to IoT Hub, you should be able to see the Model ID in the IoT Plug and Play tab of IoT Explorer as shown in the screenshot below:

With the information available in the model, IoT Explorer can create a custom UI to interact with the device, below you can see how the telemetry is displayed and the UI to invoke the commands.

---

---

---

Debugging

You can debug the firmware application in VS Code using OpenOCD and GDB.

Install VS Code and extensions

1. Install Visual Studio Code.

2. In Extensions tab (Ctrl+Shift+X), search and install the following extensions.

   • C/C++
   • CMake
   • Cortex-Debug

Debugging using OpenOCD and GDB

1. Download and unzip OpenOCD for Windows to C:\Program Files(x86)\OpenOCD. Add openocd.exe path in Windows Path Environment Variables.

2. Install ST-Link driver within unzipped OpenOCD folder by running OpenOCD/drivers/ST-Link/stlink_winusb_install.bat.

3. Launch VS Code, open getting-started/MXChip/AZ3166/ folder.

4. In VSCode, press F5 or launch debug Run tab. Then select mxchip_azure_iot.

   

5. It will first flash the firmware onto the DevKit and start running it and stopped at main(). Press F5 again or select continue to run the app.

View Debug C++ in Visual Studio Code to learn debugging in VS Code.

Clean up resources

If you no longer need the Azure resources created in this tutorial, you can use the Azure CLI to delete the resource group and all the resources you created for this tutorial. Optionally, you can use Azure IoT Explorer to delete individual resources including devices and IoT hubs.

If you continue to another tutorial in this getting started guide, you can keep the resources you've already created and reuse them.

Important: Deleting a resource group is irreversible. The resource group and all the resources contained in it are permanently deleted. Make sure that you do not accidentally delete the wrong resource group or resources.

To delete a resource group by name:

1. Run the az group delete command. This removes the resource group, the IoT Hub, and the device registration you created.

   az group delete --name MyResourceGroup

2. Run the az group list command to confirm the resource group is deleted.

   az group list

Review the Code

• To download sample code, run the following command on your desktop machine.

  git clone https://github.com/VSChina/devkit-rtos-getting-started.git
  

  If git is not installed in your development environment, you can download it from https://git-scm.com/download.

• To learn how to define the interface by DTDL v2, open the core/model/RTOSGetStarted.json.

  • It defines the telemetry, property and command supported by this sample.

• To learn how the telemetry is sent to the Azure IoT, open the MXChip\AZ3166\app\nx_client.c file

  • The function azure_iot_nx_client_entry gets the sensor data and sends multiple telemetries.

• To learn how property values are reported to the Azure IoT, open the MXChip\AZ3166\app\nx_client.c file

  • The function azure_iot_nx_client_entry sends multiple read only properties.
  • The function device_twin_desired_property_cb handles the writeable property and then registered as callback in function azure_iot_nx_client_entry.

• To learn how the DevKit device responds to commands for LED actions and OLED display text action called from the IoT Central application, open the MXChip\AZ3166\app\nx_client.c file

  • The function direct_method_cb processes the commands, and then registered as callback in function azure_iot_nx_client_entry.

MXChip Device Details

The MXChip IoT DevKit device implemented by this sample has the following characteristics:

Telemetry

Field name	Units	Minimum	Maximum	Decimal places
humidity	%	0	100	0
temp	°C	-40	120	0
pressure	hPa	260	1260	0
magnetometerX	mgauss	-1000	1000	0
magnetometerY	mgauss	-1000	1000	0
magnetometerZ	mgauss	-1000	1000	0
accelerometerX	mg	-2000	2000	0
accelerometerY	mg	-2000	2000	0
accelerometerZ	mg	-2000	2000	0
gyroscopeX	mdps	-2000	2000	0
gyroscopeY	mdps	-2000	2000	0
gyroscopeZ	mdps	-2000	2000	0

Properties

Display name	Field name	Data type	Writable/Read only
Manufacturer	manufacturer	string	Read only
Device model	model	string	Read only
Software version	swVersion	string	Read only
Operating system name	osName	string	Read only
Processor architecture	processorArchitecture	string	Read only
Processor manufacturer	processorManufacturer	string	Read only
Total storage	totalStorage	long	Read only
Total memory	totalMemory	long	Read only
Telemetry Interval	telemetryInterval	integer	Writable

Commands

Field name	Input field name	Input field type
turnOnLed	/	/
turnOffLed	/	/
displayText	text	string

Next Steps

In this tutorial you built a custom image that contains Azure RTOS sample code, and then flashed the image to the MXChip AZ3166 IoT DevKit device. You also used the Azure CLI to create Azure resources, connect the MXChip DevKit securely to Azure, view telemetry, and send messages.

• For device developers, the suggested next step is to see the other tutorials in the series Getting started with Azure RTOS.
• If you have issues getting your device to initialize or connect after following the steps in this guide, see Troubleshooting.
• To learn more about how Azure RTOS components are used in the sample code for this tutorial, see Using Azure RTOS in the Getting Started Guides.

  Note: Azure RTOS provides OEMs with components to secure communication and to create code and data isolation using underlying MCU/MPU hardware protection mechanisms. However, each OEM is ultimately responsible for ensuring that their device meets evolving security requirements.