Update "Getting Started" and software architecture docs

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,8 @@
 <!---
-This file outlines a list of common things that should be addressed when opening a PR. It's built from previous issues we've seen in a lot of pull requests. If you notice something that's being noted in a lot of PR's, it should probably be added here to help save people time in the future.
--->
+This file outlines a list of common things that should be addressed when opening a PR. It's built from previous issues we've seen in a lot of pull requests. If you notice something that's being noted in a lot of PRs, it should probably be added here to help save people time in the future.
 
-## Please fill out the following before requesting review on this PR
+Please fill out the following before requesting review on this PR!
+-->
 
 ### Description
 
@@ -19,13 +19,14 @@ This file outlines a list of common things that should be addressed when opening
 ### Resolved Issues
 
 <!--
-    Link any issues that this PR resolved. Ex. `resolves #1, #2, and #5` (note that they MUST be specified like this so Github can automatically close them then this PR merges)
+    Link any issues that this PR resolved. Ex. `resolves #1, closes #2, fixes #5` (note that they MUST be specified like this so Github can automatically close them then this PR merges)
 -->
 
 ### Length Justification and Key Files to Review
 
-<!-- If this pull request is longer then **500** lines (additions + deletions), please justify here why we *cannot* break this up into multiple pull requests
-and list the key files that contain the main idea of your PR -->
+<!-- 
+    If this pull request is longer then **500** lines (additions + deletions), please justify here why we *cannot* break this up into multiple pull requests and list the key files that contain the main content of your PR 
+-->
 
 ### Review Checklist
 

README.md

@@ -1,11 +1,19 @@
-# Software
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/tbots_logo_dark.png">
+  <img alt="Thunderbots Logo" src="docs/images/tbots_logo_light.png" width="300px">
+</picture>
+
+---
 
 [![Tbots CI](https://github.com/UBC-Thunderbots/Software/actions/workflows/main.yml/badge.svg)](https://github.com/UBC-Thunderbots/Software/actions?query=workflow%3A%22Tbots+CI%22+branch%3Amaster)
 
-Our main software and firmware repository. To get started, please see [Getting Started](docs/getting-started.md). Please thoroughly read this guide, along with our [style guide](docs/code-style-guide.md), before making *any* contributions.
+**Welcome to our main software and firmware repository!** 
+Our team is building software that controls our fleet of autonomous soccer-playing robots competing in the [RoboCup Small Size League](https://ssl.robocup.org/).
+
+- To get started with building and setting up our software, please see [Getting Started](docs/getting-started.md). Please thoroughly read this guide, along with our [style guide](docs/code-style-guide.md), before making *any* contributions.
 
-For an explanation of our software layout and architecture, check out [software architecture and design](docs/software-architecture-and-design.md).
+- Check out our [software architecture and design](docs/software-architecture-and-design.md) docs for an overview of how our software works and explanations of key systems and components.
 
-Want to learn more about the RoboCup Small Size League? (teams, rules, etc.) Check out the [Official RoboCup SSL Website](https://ssl.robocup.org/).
+- Want to learn more about the RoboCup Small Size League? (teams, rules, etc.) Check out the [Official RoboCup SSL Website](https://ssl.robocup.org/).
 
-Want to edit these docs? If you're planning on editing diagrams, read the guide on [editing the docs](docs/editing-the-docs.md).
+- Want to edit these docs? If you're planning on editing diagrams, read the guide on [editing the docs](docs/editing-the-docs.md).

docs/code-style-guide.md

@@ -1,19 +1,24 @@
 # Code Style Guide
 
-## Table of Contents
-* [Names and Variables](#names-and-variables)
-* [Comments](#comments)
-* [Headers](#headers)
-* [Includes](#includes)
-* [Namespaces](#namespaces)
-* [Exceptions](#exceptions)
-* [Tests](#tests)
-* [Getter And Setter Functions](#getter-and-setter-functions)
-* [Static Creators](#static-creators)
-* [Spelling](#spelling)
-* [Miscellaneous](#miscellaneous)
-* [Protobuf](#protobuf)
-
+### Table of Contents
+
+<!--TOC-->
+
+- [Table of Contents](#table-of-contents)
+- [Names and Variables](#names-and-variables)
+- [Comments](#comments)
+- [Headers](#headers)
+- [Includes](#includes)
+- [Namespaces](#namespaces)
+- [Exceptions](#exceptions)
+- [Tests](#tests)
+- [Getter And Setter Functions](#getter-and-setter-functions)
+- [Static Creators](#static-creators)
+- [Spelling](#spelling)
+- [Miscellaneous](#miscellaneous)
+- [Protobuf](#protobuf)
+
+<!--TOC-->
 
 Our C++ coding style is based off of [Google's C++ Style Guide](https://google.github.io/styleguide/cppguide.html). We use [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to enforce most of the nit-picky parts of the style, such as brackets and alignment, so this document highlights the important rules to follow that clang-format cannot enforce.
 

docs/getting-started-wsl.md

@@ -2,39 +2,42 @@
 
 ## Table of Contents
 
-* [Table Of Contents](#table-of-contents)
-* [Introduction](#introduction)
-* [WSLg Setup (Windows 11 - Recommended)](#wslg-setup-(windows-11---recommended))
-* [WSL2 Setup (windows 10)](#wsl2-setup-(windows-10))
-    * [X Server Setup](#x-server-setup)
+<!--TOC-->
 
+- [Table of Contents](#table-of-contents)
+- [Introduction](#introduction)
+- [WSLg Setup (Windows 11/10 - Recommended)](#wslg-setup-windows-1110---recommended)
+- [WSL2 Setup (Windows 10)](#wsl2-setup-windows-10)
+  - [X Server Setup](#x-server-setup)
+- [Networking Issues](#networking-issues)
+- [USB Issues](#usb-issues)
+
+<!--TOC-->
 
 ## Introduction
 
 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).
 
-**Support for WSL is experimental. Because we use software rendering, the experience will also be degraded on computers with weak or old CPUs.**
-
-**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.**
+> [!WARNING]  
+> **Support for WSL is experimental. Performance will be degraded, features may not work properly, and the developer experience will be worse overall.**
 
-## WSLg Setup (Windows 11 - Recommended)
-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). 
+## WSLg Setup (Windows 11/10 - Recommended)
+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). 
 2. Once you have completed all of the above, complete the [Software Setup](./getting-started.md).
 
 
 ## WSL2 Setup (Windows 10)
-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.
+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.
 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. 
 2. When you have ensured that your Windows version supports WSL2, do the following to enable it.
     - Enable WSL by opening an Administrator PowerShell window and running command 
-    ```
-    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
-    ```
+        ```
+        dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
+        ```
     - Enable the 'Virtual Machine Platform' component by Administrator PowerShell window and running command 
-    ```
-    dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
-
-    ``` 
+        ```
+        dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
+        ``` 
     - Reboot your machine.
 3. Now, let's install Ubuntu.
     - 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
 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.
 
 Once you have completed all of the above, complete the [Software Setup](./getting-started.md).
+
+## Networking Issues
+
+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.
+
+Create a `.wslconfig` file in your `%UserProfile%` directory (typically your home directory, `cd ~`) and copy the following into the config file:
+
+```
+[wsl2]
+networkingMode = mirrored
+```
+
+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.
+
+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...`. 
+
+## USB Issues
+
+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.
+
+Please follow the [official documentation on installing `usbipd-win`](https://github.com/dorssel/usbipd-win?tab=readme-ov-file#how-to-install).
+
+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).