Skip to main content

Developed on XIAO using Espressif ESP-IDF


This article is the first tutorial in the Seeed Studio XIAO ESP32 Development Matter series. If you want to start your Matter device development journey with the XIAO ESP32 Series, start here.

This tutorial applies to the XIAO ESP32C3, XIAO ESP32S3 and XIAO ESP32C6.

In the world of IoT development, the ESP-IDF (Espressif IoT Development Framework) has gained significant popularity due to its powerful features and extensive support for ESP32 series microcontrollers. With the emergence of the Matter protocol, which aims to provide a unified standard for smart home devices, developers are eager to explore this new frontier. However, Matter development currently does not support the Arduino framework, leaving ESP-IDF as the primary choice for development. In this tutorial, we will guide you through the process of installing ESP-IDF on an Ubuntu system, enabling you to kickstart your Matter development journey on XIAO ESP32 Series.

Base on Ubuntu 22.04

When it comes to Matter development, the choice of operating system is an important consideration. While Windows does not provide native support for Matter development, developers can still use Windows Subsystem for Linux (WSL) to create a compatible environment. WSL allows running a Linux distribution, such as Ubuntu, directly on Windows, providing access to the necessary tools and libraries for Matter development.

On the other hand, macOS is a popular choice among developers due to its Unix-based foundation and comprehensive development tools.

Ultimately, the choice of operating system depends on your personal preferences and the specific requirements of your Matter project. Ubuntu, being a Linux distribution, offers a native and streamlined experience for Matter development. However, if you are more comfortable with Windows or macOS, you can still set up a suitable development environment using tools like WSL on Windows or the built-in terminal on macOS.


We do not recommend developing ESP-Matter for Windows, even with WSL. Windows does not support exposing COM ports to WSL distros. You may need to switch terminals frequently or install usbipd-win for port issues, including the use of chip-tool is also a crushing point.

In summary, we will be using Ubuntu for the next development steps, and will be using the latest Ubuntu 22.04 currently supported by Matter. If you want to use an operating system other than this article for Matter development, you can refer to read the official documentation of Lexin. This article will not repeat.

Prepare the Software

Below I will list the system version and ESP-IDF version used in this article for reference. This is a stable version that has been tested to work properly.

Prepare the Hardware

In this section, we will detail how to configure the use of ESP-IDF in Ubuntu's environment and execute the lighting example provided by ESP-IDF. So for this article, you only need to prepare any of the following XIAO ESP32 series.


The XIAO ESP32C3 does not have an on-board LED, so if you are using the XIAO ESP32C3, you may need to have an additional LED.

Video Tutorials

Since the ESP-IDF development framework is aimed at more professional software developers, the threshold for using it is higher than that of Arduino. The related documents and information will be less than Arduino. In order to let XIAO users start using ESP-IDF as soon as possible, and reduce the possibility of encountering problems in the configuration of the development environment, we will present the configuration of the environment in the form of video and graphics. This section is the video part, if you want to follow along with the video, you can refer to this video to install and configure the ESP-IDF environment and finally light up the on-board LEDs of the XIAO ESP32C6.

Installation ESP-IDF Step by Step

This section is the graphical tutorial portion of the ESP-IDF environment configuration.

Step 1. Install Prerequisites

Begin by updating and upgrading your Ubuntu system to ensure you have the latest packages and dependencies. Open a terminal and run the following commands:

sudo apt update
sudo apt upgrade

Install the necessary prerequisites for ESP-IDF by running the following command, if you are sure that the following packages have already been installed, you can skip this step, but we still recommend that you run this command to check it again.

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

CMake version 3.16 or newer is required for use with ESP-IDF. Run "tools/ install cmake" to install a suitable version if your OS versions does not have one.

Step 2. Installing Python3

Typically, the full version of Ubuntu 22.04 LTS installs Python 3.12 by default. If you're not sure, you can check as follows. If it is not installed or ever you uninstalled it, you can also reinstall it as below. If you're pretty sure you have Python 3 installed, you can skip this step.

Check what Python you currently have:

python --version

If the output is like Python 2.7.17, your default interpreter is Python 2.7. If so, also check if Python 3 is not already installed on your computer:

python3 --version

If the above command returns an error, it means Python 3 is not installed.

Below is an overview of the steps to install Python 3.

  • Installing with HomeBrew can be done as follows:

    brew install python3
  • If you have MacPorts, you can run:

    sudo port install python38

Step 3. Get ESP-IDF

To get ESP-IDF, navigate to your installation directory and clone the repository with git clone, following instructions below specific to your operating system. Open Terminal, and run the following commands:

mkdir -p ~/esp
cd ~/esp
git clone -b v5.2.1 --recursive

By executing the above command, ESP-IDF will be downloaded to ~/esp/esp-idf.

Step 4. Set up the Tools

Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such as the compiler, debugger, Python packages, etc, for projects supporting ESP32.

cd esp-idf/

Step 5. Set up Environment Variables

The installed tools are not yet added to the PATH environment variable. To make the tools usable from the command line, some environment variables must be set. ESP-IDF provides another script which does that.

In the terminal where you are going to use ESP-IDF, run:

source ./
cd ..

At this point, the entire ESP-IDF environment is actually configured. To verify that ESP-IDF is installed correctly, run the following command: --version

If the installation is successful, you should see the version information of ESP-IDF.

Step 6 (Optional). Quick access to the ESP-IDF development environment

As described in the above steps, every time we start the terminal or reboot the computer, we need to import the environment variables of ESP-IDF in the new terminal, which brings us a great inconvenience, especially if we need to develop ESP32 frequently. We can modify the configuration file of Shell by the following steps to start the environment of ESP-IDF by the command of get_idf.

Open the .bashrc file by typing the following command in the terminal.

nano ~/.bashrc

Add the following to the end of the .bashrc file.

alias get_idf='. ~/esp/esp-idf/'

Refresh the configuration by restarting the terminal session or by running source [path to profile], for example, source ~/.bashrc.

Now you can run get_idf to set up or refresh the esp-idf environment in any terminal session.


Technically, you can add to your shell's profile directly; however, it is not recommended. Doing so activates IDF virtual environment in every terminal session (including those where IDF is not needed), defeating the purpose of the virtual environment and likely affecting other software.

Running the LED Example Program

To ensure that your ESP-IDF environment is set up correctly, let's run a simple LED example program.

Step 1. Connect XIAO ESP32C6 to PC

Now connect your XIAO ESP32 Series board to the computer and check under which serial port the board is visible. We will use the XIAO ESP32C6 as an example.

Serial ports have the following naming patterns: /dev/tty. In general, your computer may have many ports that begin with tty.

Determining the ports is also easy, you can use the query command to see which ports are present by default when you are not connected to XIAO.

ls /dev/tty*

Then, after connecting the XIAO to the computer and querying it again, the extra serial port name is the port number of the XIAO.

Keep the port name handy as it is needed in the next steps.

As you can see above, my XIAO port number on my computer should be ttyACM0.

Step 2. Start a Project

Navigate to the examples directory

cd ~/esp/esp-idf/examples/get-started/blink

Set the target device. set-target esp32c6
  • If you are using XIAO ESP32C3, then the command you need to use is set-target esp32c3.
  • If you are using XIAO ESP32S3, then the command you need to use is set-target esp32s3.

Since the main effect of this sample project is to make the on-board LEDs blink, we need to configure the GPIO where the LEDs are located and the blinking time and other parameters. ESP-IDF provides the menuconfig command to set some adjustable parameters of the project. menuconfig

This command opens a configuration menu where you can modify various settings.

Taking the blink project as an example, there are three parameters that can be adjusted.

  1. Blink LED type: Set the type of LED to use, in this case we set it to GPIO.

  2. Blink GPIO number: The GPIO pin number where the LED is located is set to 15 here. The LED of XIAO ESP32C6 is connected to GPIO15.

  3. Blink period in ms: The time interval between light flashes. The default is 1000 milliseconds, or 1 second.

Once the setting is complete, press q to exit the setup menu and then y to confirm the changes.

Step 3. Build and Flash the Example

Build the project by running: build

This command compiles the application and all ESP-IDF components, then it generates the bootloader, partition table, and application binaries. If there are no errors, the build finishes by generating the firmware binary .bin files.

To flash the binaries that you just built for the ESP32 in the previous step, you need to run the following command: -p PORT flash

Replace PORT with your XIAO ESP32 board's USB port name. If the PORT is not defined, the will try to connect automatically using the available USB ports. According to the device port number we queried in the first step, for me, I should enter the following command to flash the programme. -p /dev/ttyACM0 flash

If there are no issues by the end of the flash process, the XIAO will reboot and start up the "blink" application.

To view the output of the LED example program, run the following command monitor

You should see the LED on your XIAO blinking, indicating that the example program is running successfully.

If you wish to exit the serial monitor, you can use the shortcut Ctrl+].


Here are some commonly used commands in the ESP-IDF environment:

  • menuconfig: Opens the project configuration menu.
  • build: Builds the project.
  • flash: Flashes the built firmware to the connected device.
  • monitor: Starts the serial monitor to view the output from the device.
  • clean: Cleans the build directory.
  • fullclean: Performs a full clean, including the downloaded dependencies.
  • set-target: Sets the target chip for the project.
  • size: Displays the size information of the built firmware.
  • app: Manages applications in the project.
  • component: Manages components in the project.

Congratulations! You have successfully installed ESP-IDF on your Ubuntu system, laying the foundation for your Matter development journey. Seeed Studio will continue to enhance and expand the development documentation for the XIAO ESP32 series in the context of Matter. With the completion of the ESP-IDF setup and configuration, you are now ready to proceed with the Matter development part of your journey.

Seeed Studio is committed to providing comprehensive resources and support to facilitate your Matter development experience. Keep an eye out for the upcoming Matter-specific documentation and tutorials tailored to the XIAO ESP32 series. These resources will guide you through the process of utilizing the ESP-IDF framework to build cutting-edge smart home devices that adhere to the Matter protocol.

As you delve deeper into Matter development, make sure to refer to the official ESP-IDF documentation for in-depth information on the framework's capabilities and best practices. Engage with the vibrant community of developers and enthusiasts to exchange knowledge, seek guidance, and collaborate on innovative projects.

With the power of ESP-IDF and the upcoming Matter development resources from Seeed Studio, you are well-equipped to create remarkable smart home solutions that push the boundaries of interoperability and user experience. Embrace the exciting possibilities that lie ahead and embark on your Matter development journey with confidence. Happy coding!


Why do I get all kinds of errors during the installation of the environment?

ESP-IDF's environment is a bit more demanding, and if you are using an Ubuntu host that is often used for development, it is likely that errors will occur due to different versions of some Python dependencies. Since the Matter framework is not developed by Seeed, there is probably nothing we can do about this part of the problem, so we recommend that you submit an issue to the official ESP-IDF repository for help if you encounter problems with the installation.


Tech Support & Product Discussion

Thank you for choosing our products! We are here to provide you with different support to ensure that your experience with our products is as smooth as possible. We offer several communication channels to cater to different preferences and needs.

Loading Comments...