Connect an MXChip IoT DevKit device to your Microsoft IoT Central application

This article describes how, as a device developer, to connect a MXChip IoT DevKit (DevKit) device to your Microsoft IoT Central application.

Before you begin

To complete the steps in this article, you need the following:

  1. A Microsoft IoT Central application created from the Sample Devkits application template. For more information, see Create your Microsoft IoT Central Application.
  2. A DevKit device. To purchase a DevKit device, visit MXChip IoT DevKit.

An application created from the Sample Devkits application template includes a MXChip device template with the following characteristics:

Telemetry measurements

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

Settings

Numeric settings

Display name Field name Units Decimal places Minimum Maximum Initial
Voltage setVoltage Volts 0 0 240 0
Current setCurrent Amps 0 0 100 0
Fan Speed fanSpeed RPM 0 0 1000 0

Toggle settings

Display name Field name On text Off text Initial
IR activateIR ON OFF Off

Properties

Type Display name Field name Data type
Device property Die number dieNumber number
Text Location location N/A

Add a real device

In your Microsoft IoT Central application, add a real device from the MXChip device template and make a note of the device connection string. For more information, see Add a real device to your Microsoft IoT Central application.

Prepare the DevKit device

To prepare the DevKit device:

  1. Download the latest pre-built Microsoft IoT Central firmware for the MXChip from the releases page on GitHub. The download filename on the releases page looks like AZ3166-IoT-Central-X.X.X.bin.

  2. Connect the DevKit device to your development machine using a USB cable. In Windows, a file explorer window opens on a drive mapped to the storage on the DevKit device. For example, the drive might be called AZ3166 (D:).

  3. Drag the iotCentral.bin file onto the drive window. When the copying is complete, the device reboots with the new firmware.

  4. When the DevKit device restarts, the following screen displays:

    WiFi name:
    AZ3166_??????
    mac:????
    Ready to connect
    

    Note

    If the screen displays a MAC address consisting of only zeros, press the Reset button on the device.

  5. The device is now in access point (AP) mode. You can connect to this WiFi access point from your computer or mobile device.

  6. On your computer, phone, or tablet connect to the WiFi network name shown on the screen of the device. When you connect to this network, you do not have internet access. This state is expected, and you are only connected to this network for a short time while you configure the device.

  7. Open your web browser and navigate to http://192.168.0.1/start. The following web page displays:

    Device configuration page

    In the web page, add the name of your WiFi network, your WiFi network password, and the connection string of your device. Select all the available telemetry measurements.

    Note

    You made a note of the connection string in the "Before you begin" section in this article.

  8. After you choose Configure Device, you see this page:

    Device configured

  9. Press the Reset button on your device.

Note

To reconfigure the device to use a different WiFi network, connection string, or telemetry measurement, press both the A and B buttons on the board simultaneously.

View the telemetry

When the DevKit device restarts, the screen on the device shows:

  • The number of telemetry messages sent.
  • The number of failures.
  • The number of desired properties received and the number of reported properties sent.

Shake the device increment the number of reported properties sent. The device sends a random number as the Die number device property.

You can view the telemetry measurements and reported property values, and configure settings in Microsoft IoT Central:

  1. Make sure that Builder Mode is off.

  2. Use Device Explorer to navigate to the Measurements page for the real MXChip device you added:

    Navigate to real device

  3. On the Measurements page, you can see the telemetry coming from the MXChip device:

    View telemetry from real device

  4. On the Properties page, you can view the last die number reported by the device:

    View device properties

  5. On the Settings page, you can update the settings on the MXChip device:

    View device settings

Download the source code

If you want to explore and modify the device code, you can download it from GitHub. If you plan to modify the code, you should follow these instructions to prepare the development environment for your desktop operating system.

To download the source code, run the following command on your desktop machine:

git clone https://github.com/Azure/azure-iot-central-firmware.git

The previous command downloads the source code to a folder called azure-iot-central-firmware.

Note

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

Review the code

Use Visual Studio Code, which was installed when you prepared your development environment, to open the AZ3166 folder in the azure-iot-central-firmware folder:

Visual Studio Code

To see how the telemetry is sent to the Microsoft IoT Central application, open the main_telemetry.cpp file in the source folder.

The function buildTelemetryPayload creates the JSON telemetry payload using data from the sensors on the device.

The function sendTelemetryPayload calls sendTelemetry in the iotHubClient.cpp to send the JSON payload to the IoT Hub your Microsoft IoT Central application uses.

To see how property values are reported to the Microsoft IoT Central application, open the main_telemetry.cpp file in the source folder.

The function telemetryLoop sends the doubleTap reported property when the accelerometer detects a double tap. It uses the sendReportedProperty function in the iotHubClient.cpp source file.

The code in the iotHubClient.cpp source file uses functions from the Microsoft Azure IoT SDKs and libraries for C to interact with IoT Hub.

For information about how to modify, build, and upload the sample code to your device, see the readme.md file in the AZ3166 folder.

Next steps

Now that you have learned how to connect a DevKit device to your Microsoft IoT Central application, here are the suggested next steps: