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

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.