For first-time users of the MXChip IoT DevKit (a.k.a DevKit), follow these quick steps to prepare your development environment and begin building IoT applications.
Step 1. Before starting
A. What you need
- MXChip IoT DevKit. Get it now
- A computer running Windows 10 or macOS 10.10+
- Wi-Fi or hotspot on mobile phone that DevKit can connect to
Step 2. Prepare your hardware
Hook up the hardware to your computer.
A. Hardware you need
- DevKit board
- Micro-USB cable
B. Connect DevKit to your computer
- Connect Micro-USB end to the DevKit
- Connect USB end to your computer
- The green LED for power confirms the connection
Step 3. Configure Wi-Fi
IoT projects rely on internet connectivity. Use the following instructions to configure the DevKit to connect to Wi-Fi.
A. 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:
B. Connect to DevKit AP
Now, use another Wi-Fi enabled device (computer or mobile phone) to connect to the DevKit SSID (highlighted in the preview image). Leave the password empty.
C. 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:
When the connection succeeds, the DevKit reboots in a few seconds. You then see the Wi-Fi name and IP address on the screen:
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.
Step 4. 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.
A. Upgrade to the latest firmware
Notice: 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.
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.
B. Test various sensors
Press button B to test sensors. Continue pressing and releasing the button B to cycle through each sensor.
Step 5. 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.
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.
A. 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: 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.
B. Run the installation script
In Windows File Explorer, locate the .zip and extract it. Find
install.cmd, right-click it, and select Run as administrator:
During installation, you see the progress of each tool or package.
Notice: 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.
C. 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 are prompted to install relevant drivers:
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.
Notice: 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.
Follow these steps to prepare the development environment on macOS.
A. Install Azure CLI 2.0
Follow the official guide to install Azure CLI 2.0:
- Install Azure CLI 2.0 by using one
curl -L https://aka.ms/InstallAzureCli | bash
- Restart your command shell for changes to take effect:
exec -l $SHELL
B. Install Arduino IDE
The Visual Studio Code Arduino extension relies on the Arduino IDE. Download and install the Arduino IDE for macOS.
C. Install Visual Studio Code
Download and install Visual Studio Code for macOS. This is the primary development tool for building DevKit IoT applications.
D. Download the latest package
Download the .zip file that contains required task scripts for DevKit development in VS Code.
Locate the .zip file and extract it. Then start the Terminal app and run the following commands:
a. Move extracted folder to your macOS user folder:
mv [.zip extracted folder]/azure-board-cli ~/. ; cd ~/azure-board-cli
b. Install npm packages:
E. Install the VS Code extension for Arduino
You can install Azure Marketplace extensions directly in Visual Studio Code. Select the extensions icon in the left pane, search for Arduino, and then select Install:
After VS Code extension is installed, open
settings.json, add a new setting “arduino.path” and the value is the installation path of Arduino IDE.
F. Install the DevKit board package
Add the DevKit board by using Board Manager in Visual Studio Code.
Cmd+Shift+Pto open the command palette, type Arduino, and then find and select Arduino: Board Manager.
Select Additional URLs at the lower right.
- In the
settings.jsonfile, add a line at the bottom of the USER SETTINGS pane and save.
- In Board Manager, search for az3166 and install the latest version.
You now have all the necessary tools and packages installed for macOS.
Problems and feedback
Was this documentation helpful?
You’re all set! It’s time to build your first IoT application. For samples, start with our Projects Catalog.