Using WSL in Windows

  • In this tutorial will show you how to develop your projects based on Visual Studio Code + ESP-IDF Extension + Remote - WSL to implement all features of this extension in WSL.

  • Install the following tools before starting the project:

  1. Windows WSL (steps to install below).

  2. Visual Studio Code

  3. usbipd-win

Installing Ubuntu on Windows (WSL)

  • If you don’t have WSL installed run:

wsl --install

  • Update the WSL kernel with

wsl --update

  • Check the WSL available distributions list with the Powershell command prompt, as below:

wsl -l -o
../_images/wsl-l-o.png

  • So to install a ubuntu distribution in WSL on Windows, please type in the following command:

wsl --install --distribution Ubuntu

usbipd-win in WSL

  • To access the USB, serial and JTAG devices which are from the local Windows, usbipd-win must be installed, else it is impossible to download,monitor and debug on IDF docker image side. the way to install it, it is also same as Windows applications, so it will not be described in detail here.

  • You still need to do a bit configurations after installing the four tools above:

Check Ubuntu on Windows (WSL)

  1. Check the current WSL version is 2

wsl -l -v
../_images/wsl-l-v.png

  1. Please upgrade to version 2, if not

wsl --set-version Ubuntu 2

  1. Set the Ubuntu distribution as default:

wsl -s Ubuntu

  1. At last, to check if the commands have taken effect with wsl --status command.

../_images/wsl-status.png

Adding the Required Linux Packages in WSL

Install ESP-IDF requirements for Linux.

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

  1. Install usbipd in Powershell command prompt:

winget install usbipd

  1. Now configure the USB serial device to be able to connect to the WSL with usbipd:

  2. Open PowerShell command prompt with administrator rights and then type in the command

usbipd list

for a list of USB serial devices.

  1. To access the specified device from Windows on WSL locally, the device must be bound with usbipd. Open PowerShell command prompt with administrator rights and then type in the command:

usbipd bind --busid <BUSID>

Note

this command needs to be used only one time,unless the computer has restarted. 1-1 is the device’s bus id <BUSID> I would like to bind.

  1. After binding, please attach the specified device to WSL with this command in the Powershell command prompt.

usbipd attach --wsl --busid <BUSID>

  1. At last, let us check if it works well on both side and type this command on WSL side.

dmesg | tail
../_images/wsl_demsg_tail.png

  • As we can see above, 1-1 device has been attached to ttyACM0, that means WSL can access the 1-1 USB device now.

Install Remote WSL extension in Visual Studio Code

Install the Remote - WSL, Remote Development and ESP-IDF extensions, as below:

../_images/remote_wsl.png ../_images/remote_development.png ../_images/esp-idf.png

Open Project in WSL

  • Start your development by clicking the >< green button at the left bottom of Visual Studio Code and select Open Folder in WSL to start configuring the WSL and open the Blink example project.

  • Configure the ESP-IDF extension inside the WSL as described in the Install ESP-IDF and Tools documentation.

Note

  • Running the setup from WSL could override the Windows host machine configuration settings since it is using the User Settings by default. Consider saving settings to a workspace or workspace folder.

  • At this moment, you can start to use the Blink example project for building, flashing, monitoring, debugging, etc.

Building the Project

  • Here taking the esp32-c3 as an example, users only need to change the target device from esp32 to esp32-c3, as below:

../_images/device_target_esp32_c3.png

  • Next, start to build the example project, as below:

../_images/container_build.gif

Flashing to your Device

After building, we can use the following ways to download the firmware.

External USB-Serial

  • Based on the description above, users can follow the usbipd instructions section mentioned. here Silicon Labs CP210x USB to UART Bridge is taken as an example, it has been attached to docker image:

../_images/wsl_demsg_tail_usb_serial.png

  • As you can see, this device has attached to ttyUSB0, so idf.port also need to change accordingly.

../_images/ttyUSB0.png

  • But, the container doesn’t know the configuration has changed yet at this moment.

../_images/unkown_ttyUSB0.png

  • So users need to reopen the container, that is Reopen Folder Locally and then the new configuration wil be reloaded as well.

../_images/container_reopen.gif

  • At last, click the Flash button and start to download the firmware.

../_images/container_flash_uart.gif

Internal USB-serial

Just as the External USB-Serial, the only difference is the number attached. where the external usb-serial is ttyUSBx, while the internal usb-serial is ttyACMx.

../_images/container_flash_uart_internal.gif

USB-JTAG

Same as External USB-Serial and Internal USB-serial, but it needs to configure the following extra parameters:

../_images/extra_parameters.png

the interface is the same as Internal USB-serial, that is ttyACMx:

../_images/container_flash_jtag.gif

Additional steps for debugging

Make sure to copy the OpenOCD udev rules files into the /etc/udev/rules.d directory before running OpenOCD and starting a debug session.

Debugging

After following USB-JTAG, press F5 to start to debug:

../_images/container_debug.gif

Precautions

  1. If you want to debug on Windows, you need to unplug the USB cable and re-plug in it again, otherwise the corresponding USB port cannot be found in the Windows device manager.

  2. Docker Desktop For Windows needs to be opened and cannot be closed during container development.