diff --git a/docs/docs/tutorials/wsl-can/img/gui1.webp b/docs/docs/tutorials/wsl-can/img/gui1.webp new file mode 100644 index 000000000..4923a6e93 Binary files /dev/null and b/docs/docs/tutorials/wsl-can/img/gui1.webp differ diff --git a/docs/docs/tutorials/wsl-can/img/gui2.webp b/docs/docs/tutorials/wsl-can/img/gui2.webp new file mode 100644 index 000000000..08685661f Binary files /dev/null and b/docs/docs/tutorials/wsl-can/img/gui2.webp differ diff --git a/docs/docs/tutorials/wsl-can/img/gui3.webp b/docs/docs/tutorials/wsl-can/img/gui3.webp new file mode 100644 index 000000000..ba7bf50e8 Binary files /dev/null and b/docs/docs/tutorials/wsl-can/img/gui3.webp differ diff --git a/docs/docs/tutorials/wsl-can/img/gui4.webp b/docs/docs/tutorials/wsl-can/img/gui4.webp new file mode 100644 index 000000000..f60d5c85e Binary files /dev/null and b/docs/docs/tutorials/wsl-can/img/gui4.webp differ diff --git a/docs/docs/tutorials/wsl-can/index.md b/docs/docs/tutorials/wsl-can/index.md new file mode 100644 index 000000000..340417095 --- /dev/null +++ b/docs/docs/tutorials/wsl-can/index.md @@ -0,0 +1,127 @@ +# :material-linux: Virtual CAN on WSL2 + +By default, WSL2 does not support Virtual CAN, however it can be enabled by building a custom WSL2 kernel. + +!!! warning "This setup assumes you are running within WSL. If you do not have WSL installed, open up a Windows terminal and run:" + wsl --install + +## Step 1: Update the WSL Environment + +Run the following commands in your WSL terminal to update your environment and install the required dependencies. + + sudo apt-get update -y + +### Install dependencies: + + sudo apt install -y dwarves libelf-dev flex bison libssl-dev libncurses-dev bc build-essential make + sudo apt install -y --no-install-recommends wslu + +## Step 2: Download the WSL2 Linux Kernel + +To ensure compatibility, you need the specific kernel version of WSL2. + +1. **Check your kernel version:** + + uname -r + + - Example output: `5.15.153.1-microsoft-standard-WSL2` + - Note the version number, as it must match with `` in step 2, 3, and 4. + +2. **Download the kernel source**: + + - Go to the [WSL2 Linux Kernel repository](https://github.com/microsoft/WSL2-Linux-Kernel/tags). + - Find and copy the link for the `Source code (tar.gz)` file matching your kernel version. + - + +3. **Download and extract the file**: + + wget https://github.com/microsoft/WSL2-Linux-Kernel/archive/refs/tags/linux-msft-wsl-.tar.gz + tar -xf linux-msft-wsl-.tar.gz + +4. **Navigate to the extracted folder:** + + cd WSL2-Linux-Kernel- + +## Step 3: Configure Kernel Settings + +1. **Load current configuration**: + + cat /proc/config.gz | gunzip > .config + +2. **Prepare the kernel for modules**: + + make prepare modules_prepare -j $(expr $(nproc) - 1) + +3. **Open the configuration menu**: + + make menuconfig -j $(expr $(nproc) - 1) + + A menu interface should open. Use this to enable the necessary drivers for Virtual CAN. + +![Step 1](img/gui1.webp) + +### Enable CAN Drivers + +- Navigate to **Networking Support** and press `Enter`. +- Select **CAN BUS subsystem support** by pressing `M`, then press `Enter`. + +![Step 2](img/gui2.webp) +![Step 3](img/gui3.webp) +### Enable CAN Device Drivers + +- Navigate to **CAN Device Drivers**. +- For each driver shown in the screenshot, press `M` to enable as a module. +- Save and exit the configuration menu. + + +![Step 4](img/gui4.webp) + +## Step 4: Compile and Install Kernel Modules + +Run the following commands to compile and install the Virtual CAN modules: + + make modules -j $(expr $(nproc) - 1) + sudo make modules_install + +Then, compile the kernel: + + make -j $(expr $(nproc) - 1) + +## Step 5: Configure WSL to Use the Custom Kernel + +1. **Create a symbolic link** for the module directory, matching your kernel version: + + sudo ln -s /lib/modules/5.15.153.1-microsoft-standard-WSL2+ /lib/modules/5.15.153.1-microsoft-standard-WSL2 + +2. **Copy the vmlinux file**: + + Replace `` with your actual Windows username: + + cp vmlinux /mnt/c/Users// + + - In Windows File Explorer, you should now see a file named `vmlinux`. + +3. **Configure `.wslconfig`**: + + Create a file named `.wslconfig` in the same directory (i.e. in `/mnt/c/Users//`) and paste the following to the file: + + [wsl2] + kernel=C:\\Users\\\\vmlinux + +## Step 6: Restart WSL and Verify + +1. In a separate Windows terminal (not WSL), restart WSL: + + wsl --shutdown + +2. Wait ~10 seconds, then check that WSL has no active processes: + + wsl --list -v + +3. **Verify the setup** by running WSL again, then execute these commands: + + sudo modprobe can + sudo modprobe can-raw + sudo modprobe vcan + +If there is no other message, the installation was successful. \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 039a2765c..b34a3d35a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -117,6 +117,7 @@ nav: - tutorials/index.md - tutorials/git.md - tutorials/site-dev.md + - tutorials/wsl-can/index.md - Firmware: - firmware/index.md - firmware/dev-setup.md