This tutorial guides you to enable USB communication in WSL 2 for Cahute and fxlink, which is not supported natively by WSL as of this writing (updated 2024-12-13).

Pre-requisites
As the title suggests, this guide is intended for developers using WSL 2. This is because usbipd-win and WSLg do not support WSL 1 distros. It is also not applicable to Windows on ARM computers as the author of usbipd-win has no plans to support ARM64. Although there is a non-production solution for ARM64 PCs, this article only covers usbipd-win for now as the writer does not have any ARM64 device for verifying.

For Windows 10 users, you must be running version 21H2 or higher, which is the minimum requirement for WSLg to work.

Setting up WSL 2
If you are new to WSL, open PowerShell as administrator and execute the following commands to enable it:


Restart your PC to apply these changes.

The latest release of WSL 2 (v2.3.26) does not come with USB mass storage modules. Only pre-releases v2.3.11-2.3.14 provide them for now.

Set the default install version for new distros to WSL 2:


You can type wsl --list --online and select your preferred distro from the list by wsl --install <distro> --web-download, or install other third-party WSL distros like ArchWSL. The guide will be using Ubuntu 24.04 LTS for demonstration.

Installing Cahute and fxlink
Make sure to sudo apt update && sudo apt upgrade to have the latest libraries before going through all these instructions.

Go to the README of GiteaPC and install it. Since we will be using the full version of fxlink, install the following dependencies:


Then continue with the remaining instructions as usual.

Lastly, follow these instructions to install Cahute.

Instructions for using usbipd-win
On the Windows host, go to the release page for the usbipd-win project and download the latest .msi installer.

After installing usbipd-win, connect your calculator with USB. Then open PowerShell as administrator and run usbipd list. The list should include one of the following information:


Copy its bus ID and execute the following commands while the WSL instance is running:


Note that for calculators that support USB Flash mode, you have to repeat the bind command for each connection mode as they have different PID as shown above.

To let your calculator always connect to WSL instance instead of the host, add -a flag after usbipd attach. This will start endless attach loop for the calculator connection.

For calculators that use CESG502, type p7 info in WSL terminal to confirm that Cahute can detect the calculator connection. If your calculator is in USB Flash mode, enter lsblk to see if its storage appears under sdx directory.

Possible issues and workarounds
1. If you have installed USBPcap in Windows (which is used for debugging with Cahute), usbipd will prompt you:


If you prefer not to force bind your calculator to WSL instance, do not use both components simultaneously.

2. If usbipd-win cannot automatically load vhci_hcd module, edit the module config file:


Add vhci_hcd module at a new line, save the config file and restart your WSL session.

3. Since fxlink is installed in your home directory, fxsdk build-cg -s may not work properly as it requires sudo privileges. In this case, execute the following workaround in WSL terminal:


Copy its path and enter the following command at your fxSDK project directory as sudo:


Another way (but not recommended) is to use root account and install fxSDK there instead.

4. If p7screen prompts you:


You probably encounter the bug that has been upstreamed to libsdl's bug tracker (thanks Cakeisalie5 for the report). For now to work around it, create a WSLg config file:


Save the config file with the following content and restart your WSL session: