Tutorial: Running Klipper on a Windows PC (Using WSL)

If you happened upon this article or series of articles from some point in the future you may wonder why I and many others invested so much time into finding ‘things’ that could run Klipper. Well remember that COVID thing? At this point in time most of the world is past the national lock down stages and trying to get back on with life. Unfortunately the manufacturing industries haven’t fully recovered and getting hold of a Raspberry Pi has been challenging for quite some time now. Many people have resorted to back alley scalpers and AI stock finding algorithms, but demand is not being met. To satiate the desire to print faster and to Klipperise everything there is a need to know what other devices can be used instead.

Unfortunately this tutorial is unlikely to solve the RPi crisis and I should really have sat down to consider if I should do this rather than could I do this. Anyway I have managed to get a working Klipper installation on a Windows PC using the windows subsystem for Linux (WSL) tool. I see this as a useful tool for connecting up a board to test and mess around with it rather than a permanent solution for running your printers (Although I would love someone to prove me wrong here). Waffle aside lets get stuck into the tutorial.

Warning this method will required you to have WSL and your Windows PC running the entire time you are printing. You may or may not get USB disconnects when WSL window is closed, I haven’t tested the reliability or actual prints with this method yet!

BOM

• Patience
• USB cable to connect control board to PC

Installing WSL

Quickly before we do actually get started I should answer the question of what is WSL? The Windows Subsystem for Linux lets developers run a Linux environment — including most command-line tools, utilities, and applications — directly on Windows, unmodified, without the overhead of a traditional virtual machine or dualboot setup.

For most people that probably meant nothing but I felt like I should include it. Installing WSL is very straight forward. Documentation is provided in full here but read on for the basic steps to get started.

Open command prompt as administrator and run the command below

wsl --install

WSL will start to install. Wait for it complete, this can take quite a while as it will automatically download and install Ubuntu at the same time. Other Linux OS are available on the Microsoft store.

Once complete you will be notified that changes won’t be applied until a reboot has occurred. Please go ahead and reboot your PC. When it starts back up the installation should automatically continue and an Ubuntu window will open. Enter a username and password.

You should be greeted with the welcoming sight of an Ubuntu command line interface.

Open the command prompt back up and lets update WSL before we get any further. Shut WSL down then launch it again (Ubuntu should appear like any other program in your menu now) for the changes to take effect.

wsl --update
wsl --shutdown

Preparing Windows

Unfortunately WSL does not automatically have access to USB devices or serial communication ports. Thankfully someone clever has added a tool to make that possible.

In the command prompt enter the command below to install usbipd (run as administrator again)

winget install usbipd

Plug in a printer control board to your PC. Check that you can see the COM port in the device manager. It is COM8 for me.

Run the following command and take a note down of the BUSID for your control board. Mine is ‘1-12’

Depending on your setup and whether or not you have used WSL previously and/or docker you may need to set Ubuntu as your default. run the command below to check. If it is not the default use the second line to set it to be the default. You can run the first command again to check it worked.

wsl --list
wsl --setdefault Ubuntu
wsl --list

sudo apt install linux-tools-virtual hwdata
sudo update-alternatives --install /usr/local/bin/usbip usbip `ls /usr/lib/linux-tools/*/usbip | tail -n1` 20

Now you need to attach the USB device to WSL. Run the command below in CMD prompt. The device should have disappeared from your device list now.

usbipd wsl attach --busid=1-12

Check that it is not visible in WSL. Run the command below in Ubuntu. You can see the results of running this command before and after attaching the USB device below. An STM32 device has appeared which is perfect as I know that is the processor on my control board.

lsusb

Inside Ubuntu run the following two commands. You will be prompted for the sudo password. Enter the one you set when you created your user at the start. Press y when prompted to continue the installations.

Configuring Ubuntu

Quickly install net-tools as we will use them later to get the IP address.

sudo apt install net-tools

Now the biggest issue with trying to run Klipper on WSL is that it the OS does not support systemd which is used by most services (klipper, moonraker etc.) in the background. Thankfully again someone far cleverer has found a hack to enable this to work!

Start off by installing the dependencies in Ubuntu. Again use Y to accept the installations.

sudo apt update
sudo apt install dbus policykit-1 daemonize

Create an interceptor that catches the systemd calls and sends them to the right place. (I’ve changed the text editor to nano because I find it easier to use than the one advised by the Github readme.)

sudo touch /usr/local/bin/wsl2hack
sudo chmod +x /usr/local/bin/wsl2hack
sudo nano /usr/local/bin/wsl2hack

The commands above will end by launching a text editor (nano). Paste the following code in but make sure to update your username. in the 3rd line with the one you set when installing Ubuntu. when done hit ctrl + X and then y and finally enter to save the changes.

#!/bin/bash
# your WSL2 username
UNAME="<YOURUSER>"

UUID=$(id -u "${UNAME}")
UGID=$(id -g "${UNAME}")
UHOME=$(getent passwd "${UNAME}" | cut -d: -f6)
USHELL=$(getent passwd "${UNAME}" | cut -d: -f7)

if [[ -p /dev/stdin || "${BASH_ARGC}" > 0 && "${BASH_ARGV[1]}" != "-c" ]]; then
    USHELL=/bin/bash
fi

if [[ "${PWD}" = "/root" ]]; then
    cd "${UHOME}"
fi

# get pid of systemd
SYSTEMD_PID=$(pgrep -xo systemd)

# if we're already in the systemd environment
if [[ "${SYSTEMD_PID}" -eq "1" ]]; then
    exec "${USHELL}" "$@"
fi

if [[ -z ${SYSTEMD_PID} ]]; then
    # start systemd
    /usr/bin/daemonize -l "${HOME}/.systemd.lock" /usr/bin/unshare -fp --mount-proc /lib/systemd/systemd --system-unit=basic.target

    # wait for systemd to start
    retries=50
    while [[ -z ${SYSTEMD_PID} && $retries -ge 0 ]]; do
        (( retries-- ))
            sleep .1
            SYSTEMD_PID=$(pgrep -xo systemd)
    done

    if [[ $retries -lt 0 ]]; then
        >&2 echo "Systemd timed out; aborting."
        exit 1
    fi
fi

# export WSL variables
export WINPATH="$(echo "$PATH"|grep -o ':/mnt/c.*$'|sed 's!^:!!')"
RUNOPTS=""
RUNOPTS="$RUNOPTS -l"
RUNOPTS="$RUNOPTS -w WINPATH"
RUNOPTS="$RUNOPTS -w WSL_INTEROP"
RUNOPTS="$RUNOPTS -w WSL_DISTRO_NAME"

# enter systemd namespace
exec /usr/bin/nsenter -t "${SYSTEMD_PID}" -m -p --wd="${PWD}" /sbin/runuser $RUNOPTS -s "${USHELL}" "${UNAME}" -- "${@}"

Run the follow command. Choose 1 (nano) and then add rootwsl:x:0:0:root:/root:/usr/local/bin/wsl2hack as the first line in the file. DO NOT change or delete anything else. ctrl + X, y and enter to save changes.

sudo vipw

Now repeat the last steps but using the command below.

sudo vipw -s

Close Ubuntu. Use the CMD prompt to shut it down.

Next we need to set the default user to root for the script to work and simulate systemd on startup. Again in CMD prompt run

wsl --shutdown
ubuntu config --default-user root

Launch Ubuntu and check that everything is working by running the command below. You should get the response active and be logged into the user you set up rather than the root user.

systemctl is-active dbus

Installing Klipper

Now is the easy bit. It’s time to install Klipper using KIAUH like we are accustomed to. Also a big thank you to th33xitus for firstly developing and maintaining KIAUH and secondly for giving me a pointer on the systemd side of things to get this to work!

Run the following commands in Ubuntu

cd ~
git clone https://github.com/th33xitus/kiauh.git

Next start up KIAUH and install the components in the following order Klipper -> Moonraker -> Mainsail (or Fluidd if you prefer).

Get the ip address of the device by running the command below. Look for the inet line under eth0.

/sbin/ifconfig

Enter this into your web browser and boom you should have klipper!

As per usual the MCU can’t be found because we need to configure the printer.cfg. However first make sure your usb device is mounted. in CMD prompt run the following command (modified based on the code you wrote down near for the bus id earlier)

usbipd wsl attach --busid=1-12 

In Ubuntu run the command below to get the id of the device. Paste this ID into your printer.cfg file (using the mainsail UI) and that’s it your ready to Klipper!

ls /dev/serial/by-id/*