Build RIOT on WSL (Windows Subsystem for Linux)

WSL provide a way to run native linux binaries on windows (not ports as cygwin or mingw). It also permit to run windows binaries transparently within linux which is a unique feature regarding to alternatives.

There are two versions of wsl, each having its drawbacks:

• WSL 1 only support 64bits linux binaries (but qemu do the trike) and tap driver is not working so "native" RIOT board can not work with network.
• WSL 2 use some hardware virtualisation and do not map windows COM ports to /dev/ttyS* but it is OK for "native" RIOT board.

This page is mainly about WSL 1 because I needed a solution without virtualization.

Enable WSL

Windows Features -> Windows Subsystem for Linux

or using powershell:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all

Set WSL version

To avoid having to perform a conversion, you must set the default version before installing the distribution.

To do so, run cmd.exe as administrator then issue the command:

C:\Windows\system32>wsl --set-default-version 1

Install a "Distro" from the windows store

The procedure described below works with Debian (lightweight), Ubuntu, Ubuntu-20.04, but not with Ubuntu-18.04.

Language

The distro language is english whatever that of windows, you can change it with:

sudo dpkg-reconfigure locales

Debian

As debian distro is very minimal you can install vim and bash-completion : sudo apt install vim bash-completion

then uncomment the relevent lines in /etc/bash.bashrc to enable bash completion:

# enable bash completion in interactive shells
if ! shopt -oq posix; then
  if [ -f /usr/share/bash-completion/bash_completion ]; then
    . /usr/share/bash-completion/bash_completion
  elif [ -f /etc/bash_completion ]; then
    . /etc/bash_completion
  fi
fi

to enable it immediately you can do:

source /etc/bash_completion

Setup script

sudo dpkg --add-architecture i386
sudo apt update
sudo apt -y dist-upgrade
sudo apt -y install libc6-dev-i386 libc6-dbg:i386 build-essential \
pkg-config uml-utilities bridge-utils git unzip gcc-arm-none-eabi \
python3-serial wget p7zip
wget https://sysprogs.com/getfile/1180/openocd-20200729.7z
p7zip -d openocd-20200729.7z 
sudo mv OpenOCD-20200729-0.10.0 /opt/openocd_pe32
sudo chmod +x /opt/openocd_pe32/bin/openocd.exe 
sudo chmod 777 /dev/ttyS*
echo "export OPENOCD=/opt/openocd_pe32/bin/openocd.exe" >> .bashrc
echo "export PORT_LINUX=/dev/ttyS3" >> .bashrc
echo "export DISPLAY=:0" >> .bashrc
source .bashrc
ln -s /mnt/c`cmd.exe /c "echo %homepath%" 2>/dev/null | tr -d "\r\n" | tr '\\\\' '/'`/Desktop

It install windows openocd build because of the lake of USB support in WSL.

For st-link programmer you must also install windows proprietary driver from: https://www.st.com/en/development-tools/stsw-link009.htm

You must replace PORT_LINUX=/dev/ttyS3 in .bashrc according to the windows COM port of you serial adapter that you can identify in the windows device manager, ttyS3 is for COM3.

The last line make a symlink to your windows Desktop directory, do not use it for source tree, git, etc.

In windows, distro's filesystems are accessible as network shares at \\wsl$

Native (32bit elf) support within WSL 1

sudo apt install qemu-user-static
sudo update-binfmts --install i386 /usr/bin/qemu-i386-static --magic '\x7fELF\x01\x01\x01\x03\x00\x00\x00\x00\x00\x00\x00\x00\x03\x00\x03\x00\x01\x00\x00\x00' --mask '\xff\xff\xff\xff\xff\xff\xff\xfc\xff\xff\xff\xff\xff\xff\xff\xff\xf8\xff\xff\xff\xff\xff\xff\xff'

GUI apps

To be able to use GUI apps from WSL you must install an X11 server in windows as vcxsrv or xming.

https://sourceforge.net/projects/vcxsrv/files/latest/download

Install it and run XLaunch, clic [Next] two times, then in the "Extra settings" dialog check "Disable access control".

Auto-start VcXsrv with WSL

Save configuration from XLaunch to \\wsl$\Ubuntu-20.04\home\<username>\.config.xlaunch

Add the following lines to your .bashrc:

if ! xset q &>/dev/null; then
    /mnt/c/Program\ Files/VcXsrv/xlaunch.exe -run .config.xlaunch
fi

Visual Studio Code support

Another option is to use Visual Studio Code. This has native support for opening projects in WSL on windows.

Install Visual Studio Code. And use the command code in your WSL terminal.

WSL 2

The previous setup should also work within WSL 2 except for pyterm which I am unable to get working with python for windows.

socat

Alternatively to pyterm you can use socat which is also supported as RIOT_TERMINAL and easyly extractable from cygwin:

git clone https://github.com/hugueslarrive/socat_pe32.git
sudo mv socat_pe32/ /opt/
sudo ln -s /opt/socat_pe32/socat.exe /usr/local/bin/socat
echo "export RIOT_TERMINAL=socat" >> .bashrc

My serial adapter COM3 is mapped to /dev/ttyS2 in cygwin so ttyS number seems to be COM number -1. So you should also adjust PORT_LINUX in ~/.bashrc according to this rule.