I have found WSL2 to be a wonderful addition to Windows which simplifies building projects that originated on Linux or OSX. I have now started to rely on WSL2 as the primary build system for most of my projects so it makes sense to document getting a new machine set-up for building – in this case Espressif ESP32 projects – on WSL2.
While the instructions on the Espressif website for installing the ESP-IDF development toolchain is quite well written, for me currently it fails in two important regards:
- installing on Ubuntu 20.04 results in a problem with Python
- if a specific version of the IDF is to be targeted then it needs to be selected before the tools are installed (or tools need to be re-installed after any change).
Hence I felt it might be helpful to document the steps which result in a successful installation on WSL2 as I use that all the time now.
WSL2
The first step, if you haven’t already done so, is to install WSL2. There is a good tutorial on the Microsoft website which worked for me with no changes – although I did have to make sure that Windows 10 had fully updated – this took several repeats of going to the Updates page and requesting that Windows check for updates, install pending updates, or reboot.
https://docs.microsoft.com/en-us/windows/wsl/install-win10
Note that you need to follow all the steps, including downloading Ubuntu 20.04 from the Windows Store and installing it – then setting a username and password.
Pre-requisites
First step is to install pre-requisites:
sudo apt-get install python3 python3-pip python3-setuptoolssudo git wget flex bison gperf cmake ninja-build ccache libffi-dev libssl-dev dfu-utilSelecting the Right Python
The next step with a new Ubuntu 20.04 install is to ensure that Python 3 is the default python. Espressif’s way to do this is as follows:
update-alternatives --install /usr/bin/python python /usr/bin/python3 10Downloading the IDF
Next step is to download the IDF
mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.gitNow Select the Version of IDF
For instance to select V4.0.1 of the IDF:
cd ~/esp/esp-idf
git fetch
git checkout v4.0.1
git submodule update --init --recursiveInstall the IDF Tools
The final step in the installation is to install the IDF tools:
cd ~/esp/esp-idf
./install.shUsing ESP IDF to Build a Project
Assuming that you have a project cloned from GitHub or similar then you will need to change directory to the root folder of that project and then run the following:
cd YOUR-PROJECT-ROOT
. $HOME/esp/esp-idf/export.sh
idf.py buildThe export.sh script sets the environment variables so that the IDF tools can be found.
There are many other idf.py commands that can be used and these are documented:
In some of my projects I place a shell script in the root of the project to simplify the build process. This may require editing to work with the locations of your IDF but should work in standard cases. In many cases the script needs to be made executable before use:
chmod +x ./build-flash-monitor.shAnd also note that if you did the cloning from GitHub or editing in a Windows command prompt or VSCode local (as opposed to remote using WSL2) then the line-endings of files are most-probably going to be Windows style – CRLF and these will need changing (in VSCode this can be done by opening the file and clicking CRLF in the bottom bar of the editor window – then changing to LF and saving).
Resources
https://docs.espressif.com/projects/esp-idf/en/latest/esp32/versions.html