|
2 | 2 |
|
3 | 3 | ## Table of Contents |
4 | 4 |
|
5 | | -* [Table Of Contents](#table-of-contents) |
6 | | -* [Introduction](#introduction) |
7 | | -* [WSLg Setup (Windows 11 - Recommended)](#wslg-setup-(windows-11---recommended)) |
8 | | -* [WSL2 Setup (windows 10)](#wsl2-setup-(windows-10)) |
9 | | - * [X Server Setup](#x-server-setup) |
| 5 | +<!--TOC--> |
10 | 6 |
|
| 7 | +- [Table of Contents](#table-of-contents) |
| 8 | +- [Introduction](#introduction) |
| 9 | +- [WSLg Setup (Windows 11/10 - Recommended)](#wslg-setup-windows-1110---recommended) |
| 10 | +- [WSL2 Setup (Windows 10)](#wsl2-setup-windows-10) |
| 11 | + - [X Server Setup](#x-server-setup) |
| 12 | +- [Networking Issues](#networking-issues) |
| 13 | +- [USB Issues](#usb-issues) |
| 14 | + |
| 15 | +<!--TOC--> |
11 | 16 |
|
12 | 17 | ## Introduction |
13 | 18 |
|
14 | 19 | Windows has a Windows Subsystem for Linux component that can be used to develop and run code for Linux on Windows. WSL1 was a Windows component that implemented Linux kernel interfaces, and didn't work great with Thunderbots software. WSL2 runs a full-fledged Linux kernel in a VM, and works great with Thunderbots software with the exception that we need to use software rendering instead of GPU-accelerated rendering for our AI. WSLg is WSL2 but with built-in support for running GUI applications (e.g. Thunderscope). |
15 | 20 |
|
16 | | -**Support for WSL is experimental. Because we use software rendering, the experience will also be degraded on computers with weak or old CPUs.** |
17 | | - |
18 | | -**Note that this will not work with legacy robots. Due to the lack of USB support in WSL2, we are unable to use the USB dongle used to communicate with them.** |
| 21 | +> [!WARNING] |
| 22 | +> **Support for WSL is experimental. Performance will be degraded, features may not work properly, and the developer experience will be worse overall.** |
19 | 23 |
|
20 | | -## WSLg Setup (Windows 11 - Recommended) |
21 | | -1. Installing WSLg is more straight forward than WSL2. For up to date documentation, please follow the [official documentation for setting up WSLg](https://github.com/microsoft/wslg#installing-wslg). |
| 24 | +## WSLg Setup (Windows 11/10 - Recommended) |
| 25 | +1. Installing WSLg is more straight forward than WSL2 and is the recommended way to run Linux GUI applications in Windows. For up to date documentation, please follow the [official documentation for setting up WSLg](https://github.com/microsoft/wslg#installing-wslg). |
22 | 26 | 2. Once you have completed all of the above, complete the [Software Setup](./getting-started.md). |
23 | 27 |
|
24 | 28 |
|
25 | 29 | ## WSL2 Setup (Windows 10) |
26 | | -If you are not using Windows 11 and would prefer not to upgrade, you can follow the following steps. Note that this setup is more complex than the [WSLg](#wslg-setup-(windows-11---recommended)) setup as it does not support GUI applications out of the box. |
| 30 | +If you are not using Windows 11 or the latest version of Windows 10 and would prefer not to upgrade, you can follow the following steps. Note that this setup is more complex than the [WSLg](#wslg-setup-(windows-11---recommended)) setup as it does not support GUI applications out of the box. |
27 | 31 | 1. You'll need to be on build 19041 or later to use WSL2. If you have updated to Windows 10 version 2004 or newer, you will be able to use WSL2. |
28 | 32 | 2. When you have ensured that your Windows version supports WSL2, do the following to enable it. |
29 | 33 | - Enable WSL by opening an Administrator PowerShell window and running command |
30 | | - ``` |
31 | | - dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart |
32 | | - ``` |
| 34 | + ``` |
| 35 | + dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart |
| 36 | + ``` |
33 | 37 | - Enable the 'Virtual Machine Platform' component by Administrator PowerShell window and running command |
34 | | - ``` |
35 | | - dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart |
36 | | -
|
37 | | - ``` |
| 38 | + ``` |
| 39 | + dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart |
| 40 | + ``` |
38 | 41 | - Reboot your machine. |
39 | 42 | 3. Now, let's install Ubuntu. |
40 | 43 | - Download the WSL2 kernel from [here](https://docs.microsoft.com/en-us/windows/wsl/wsl2-kernel). |
@@ -62,3 +65,26 @@ If you are not using Windows 11 and would prefer not to upgrade, you can follow |
62 | 65 | 7. Verify that your system is configured correctly by running `glxgears -info` on the Linux command line. You should see a window pop up with spinning gears and the line `GL_RENDERER = llvmpipe (LLVM 9.0, 256 bits)` at the top of the output. |
63 | 66 |
|
64 | 67 | Once you have completed all of the above, complete the [Software Setup](./getting-started.md). |
| 68 | +
|
| 69 | +## Networking Issues |
| 70 | +
|
| 71 | +Networking compatibility with WSL is limited but it can be improved by enabling [mirrored mode](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking). There are still many unresolved issues with mirrored mode enabled (no vision, no robot status, etc.) but robot diagnostics should work and you should be able to control robots on the network. |
| 72 | +
|
| 73 | +Create a `.wslconfig` file in your `%UserProfile%` directory (typically your home directory, `cd ~`) and copy the following into the config file: |
| 74 | +
|
| 75 | +``` |
| 76 | +[wsl2] |
| 77 | +networkingMode = mirrored |
| 78 | +``` |
| 79 | +
|
| 80 | +This will enable [mirrored mode networking for WSL](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking). This mode “mirrors” the networking interfaces you have on Windows onto Linux, which improves networking capabilities and compatibility. |
| 81 | +
|
| 82 | +When selecting a network interface to use, choose `eth...`/`en...` or similar. There probably won’t be a `wlan` interface since WSL only sees the virtual network interface `eth...`. |
| 83 | +
|
| 84 | +## USB Issues |
| 85 | +
|
| 86 | +WSL does not natively support connecting USB devices, which is necessary for some tasks like flashing firmware onto our robots or using a physical e-stop. You will need to install a piece of open-source software called `usbipd-win` to support USB connectivity. |
| 87 | +
|
| 88 | +Please follow the [official documentation on installing `usbipd-win`](https://github.com/dorssel/usbipd-win?tab=readme-ov-file#how-to-install). |
| 89 | +
|
| 90 | +Note that connected devices are not automatically shared with `usbipd`, so you will have to manually share the device with `usbipd` and attach/detach the device to a `usbipd` client whenever you plug/unplug it (or between reboots). See the [official documentation for details on usage](https://github.com/dorssel/usbipd-win?tab=readme-ov-file#how-to-install). |
![pre-commit-ci-lite[bot]](https://avatars.githubusercontent.com/in/257897?v=4&size=40){kind=avatar}
0 commit comments