Development in Windows

"Friends do not let friends code in Windows"

The Alpakka controller is better developed in GNU/Linux. So before going into the extra trouble of setting up Windows for development please, consider installing Linux in a partition of your computer, or just using a Linux live-USB.

But if you still want (or must) continue in Windows, we have you covered. Since most PC gamers are on Windows, we went the extra mile to be sure that Windows is also a viable development environment.

The trick is that even in Windows we will also be using Linux, thanks to WSL (Windows Subsystem for Linux) which allows us to virtualize a Linux distribution inside Windows, officially supported by Microsoft, and with a very nice integration. That way we will use the same tooling that we would be using in Linux, though it still requires a bit of extra work.

Setup WSL

For using WSL is required an updated version of Windows 10 or 11.

Open the new Windows Terminal app as an administrator, and do:

# In Windows terminal
wsl --install -d ubuntu

After everything is installed, an Ubuntu command line window will open, in which you will setup the username and password of the Linux image. Then close that window, and instead use Windows' terminal app directly to access Linux instances:

# In Windows terminal
wsl

Now you are in Linux (is easy to know if you are in Windows or Linux depending on the prompt colors).

Also at this point your Windows drives as C: or D: should be accessible in Linux as /mnt/c, /mnt/d, etc...

Ready for the basics

Now you are ready to start using the basic developer commands, as compiling the firmware and loading it into the controller. Which is an acceptable subset of the whole Linux development cycle.

This may be enough if you just want to tweak the built-in profiles.

But with this setup you will NOT be able to use the TTL/UART serial interface yet, so you won't have detailed logs if something fails.

If you want to be able to do make session, you have to continue tweaking WSL as follows.

Setup WSL for USB sharing

When connecting the USB-to-TTL cable, we have to share it with the Linux instance so it takes control of it, for that we need to install a couple of things, both in Windows and in Linux:

# In Windows terminal
winget install --interactive --exact dorssel.usbipd-win

# In Linux terminal
sudo apt install linux-tools-5.4.0-77-generic hwdata
sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/5.4.0-77-generic/usbip 20

Now you can manually share USB devices (the USB-to-TTL cable) with the Linux instance, replace busid with the actual id of the USB, eg: 1-4.

# In Windows terminal
usbipd wsl list
usbipd wsl attach --busid busid

Check that the USB device is available in the Linux instance:

# In Linux terminal
lsusb

Setup WSL for TTL serial

Because Linux instances for virtual (usually cloud) environments do not ship with much hardware support, we need to use a custom WSL core with Linux usbserial module enabled, and all the available USB-to-TTL drivers, so they are automatically assigned to /dev/ttyUSB0 on Linux.

You can get a pre-compiled WSL kernel from us, or compile it yourself.

Copy the kernel to your Windows user folder, eg: C:\Users\youruser\wsl_kernel_dev, then create a WSL config file:

# At C:\Users\youruser\.wslconfig
[wsl2]
kernel=C:\\Users\\youruser\\wsl_kernel_dev

Shutdown WSL:

# In Windows terminal
wsl --shutdown

Restart WSL and share the USB again (with usbipd as explained above). Linux now should have the USB serial device available at /dev/ttyUSB0.

Fix GNU Screen permissions

And finally before being able to use make session, we have to fix some permissions for GNU Screen to work properly:

# In Linux terminal
sudo mkdir /run/screen
sudo chmod 777 /run/screen
sudo chmod 777 /dev/ttyUSB0

Done with the boilerplate

Now you can develop following the same instructions than for Linux development