ESP32 Development on Windows Subsystem for Linux

Introduction: ESP32 Development on Windows Subsystem for Linux

ESP32 is a low-cost, low-power microcontroller board from Espressif. It is popular among makers because of its low cost and its built-in peripherals, which include WiFi and Bluetooth. However, the development tools for ESP32 require a Unix-like environment, which can be difficult to setup and maintain on a Windows system.

Thanks to the recent addition of serial communication, we can use the Microsoft Windows Subsystem for Linux to run the entire Linux based toolchain natively on Windows 10, without the need to recompile or use virtual machines or containers.

Windows Subsystem for Linux (WSL) enables native execution of Linux (or ELF64 to give them their more formal name) binaries to run as a special class of process, called a pico process. Windows intercepts Linux system calls and automatically translates them into the appropriate Windows executive call. The result is that most well-behaved Linux applications will run on Windows.

Step 1: Enable the Feature in Windows

In order to make use of WSL, we first need to enable the feature in the operating system. Right-click the Start button and choose Run. Type OptionalFeatures.exe and press Enter. Ensure the Windows Subsystem for Linux is checked then click OK. You may need to reboot in order for the feature to install.

Step 2: Install Linux Distribution

Next open the Windows Store and search for Ubuntu. This is the Linux distribution we shall be using for our development environment. Once you have installed and launched the Ubuntu app you will be prompted to pick a username and password. (This doesn't have to be the same as your Windows username and password, but it should be something logical that you will remember).

Step 3: Install ESP32 Toolchain

First we need to install the prerequisites for the toolchain. This is done using Ubuntu's package manager. Launch Ubuntu and type the following:

sudo apt-get update
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-serial

To install the toolchain we need to download and extract it:

cd ~
mkdir esp
cd esp
tar -xzf ~/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz

Step 4: Install the ESP IoT Development Framework

Creating a git clone of the Espressif IDF repository is the first step to installing the development framework:

cd ~/esp
git clone --recursive

ESP-IDF needs some environment variables to run properly. We will set these in our command line shell's profile, so they are available every time we start Bash.

Type nano ~/.profile to begin editing. Add the following lines to the end:

export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"
export IDF_PATH=”$HOME/esp/esp-idf”

Save and exit with Ctrl+X.

Step 5: Install and Configure USB Serial Drivers

Most ESP32 development boards incorporate a USB to serial bridge, so you can program them and monitor the output from your computer . However, they don't use the FTDI chip that most Arduino boards do. Instead, most use the CP210x chip from Silicon Labs. You will need to download and install the drivers before plugging the device in.

Once you have done that, open Device Manager and confirm the device has been recognized. You need to know which COM port Windows has assigned to your device. In my case it is COM4, but yours may will be different.

In Ubuntu, we don't refer to the device by Windows COM port, instead we use the filename /dev/ttySX - where X is the Windows COM port number. So COM4 would be /dev/ttyS4.

In order to be able to write to the serial port, we need to set the permissions. To do this, type:

sudo chmod 0666 /dev/ttyS4

NB In my case, I'm using /dev/ttyS4. You should substitute your device name instead.

Step 6: Build and Flash a Program

Let's test our ESP32 by building and flashing the ubiquitous Hello World program.

You may have noticed that up until now we have been working inside a Unix-like filesystem with directories such as /dev, /bin and /home. We'll copy the project files to our main C drive so that we can edit them using any Windows text editor if needed. All our drives are available in WSL through the /mnt directory.

mkdir /mnt/c/esp
cp -r $IDF_PATH/examples/get-started/hello_world /mnt/c/esp
cd /mnt/c/esp/hello_world
make menuconfig

NB This creates a folder on the root of the C: drive called esp. If you would rather work in another location, simple substitute in the path.

We need to change the default serial port based on the device we identified earlier. In my case that means changing the default serial port to /dev/ttyS4. Don't forget to save when you exit menuconfig.

make -j16 all
make flash

The -j16 option isn't necessary but it helps speed up the build process in multi processor computers. As I have a 16 thread machine, I pass -j16. If you have a four thread processor you should use -j4.

My board has a push button labelled IOO which you must press to enable the flash process. Just a short press during the Connecting...... phase was enough.

Step 7: Connecting to the ESP32 and Viewing Output

To view the output from the ESP32 simply type

make monitor

This will display the output from our hello_world application. Congratulations, you have successfully programmed your ESP32 device using Windows Subsystem for Linux!

Be the First to Share


    • Make it Glow Contest

      Make it Glow Contest
    • First Time Author Contest

      First Time Author Contest
    • PCB Challenge

      PCB Challenge

    9 Discussions


    Question 5 months ago on Step 5

    I get "input output error" when trying to read or write to /dev/tty(number).
    I searched about it and saw people who says wsl don't support it.
    How did you seucceed to operate it?


    8 months ago

    Very helpful tips,
    I will use the same to solve issues of my company Indiaaccess Servers and Hostasp Servers
    Thanks for your info


    1 year ago

    First of all thank you for this easy to set up process !
    I've a laptop without com port ( only usb ), any idea how to set the step 5 ?




    Reply 1 year ago

    If you plug the device into your laptop and install the correct device driver it will appear as a COM port in device manager. If it is not showing, you may need a different device driver depending on your specific board. Common chips are CP2102 as in this guide and CH340G.


    Question 2 years ago on Step 3

    Am incorrect in thinking you have an errant space between ~/ and the file name? I had to remove this to get past the step.


    Answer 2 years ago

    Nice catch Jon. I've fixed the typo in the article.


    2 years ago on Step 7

    When running the monitor use Ctrl+] to exit

    I'm new to the ESP32, but have found that this setup under WSL is far cleaner than using MSYS2 as is usually prescribed for Windows users.


    2 years ago

    Very nice instructable! Thanks for sharing.