From 34921efa91a46acece7e53aa9bcfe6fcd097f25b Mon Sep 17 00:00:00 2001 From: Lidya Langana Date: Tue, 21 Jul 2026 17:35:16 -0600 Subject: [PATCH 1/2] Update the Readme file with windows instruction --- README.md | 109 ++++++++++++++++++++++++++++++++++---- images/gui_screenshot.png | Bin 0 -> 11079 bytes 2 files changed, 98 insertions(+), 11 deletions(-) create mode 100644 images/gui_screenshot.png diff --git a/README.md b/README.md index 19f8668..3006e50 100644 --- a/README.md +++ b/README.md @@ -10,31 +10,118 @@ Update the `TankController` code from C++ to Python and run on a Raspberry Pico. +# Getting Started + ## Requirements -To set up and run this project, the system must meet the following requirements: +Before running the project, install the following: -- **uv**: The python project package manager must be installed. Learn more at [https://docs.astral.sh/uv/](https://docs.astral.sh/uv/). - Format contributions with `uv run black .` -- **tkinter**: The Python GUI to test locally. Often installed separately as `python3-tk`. - Verify with `python -m tkinter`. A small GUI window should appear if Tkinter is installed correctly. +- **Python 3.14+** +- **uv** (Python package manager) + - Installation: https://docs.astral.sh/uv/ +- **Tkinter** (required for the local GUI) + - Verify the installation: -### Mac Requirements + ```bash + python -m tkinter + ``` -The GUI had trouble running on older version of python. + A small GUI window should appear if Tkinter is installed correctly. -```sh +### macOS + +Older Python versions may have issues running the GUI. Install Tkinter for Python 3.14: + +```bash brew install python-tk@3.14 ``` -## Run in Local Environment +### Windows -To run in a local environment with mocked devices (with the UI State Machine integrated) +Windows development requires **Windows Subsystem for Linux (WSL)**. -```sh +#### 1. Install WSL + +Open **PowerShell as Administrator** and run: + +```powershell +wsl --install +``` + +Restart your computer, open **Ubuntu**, and create your Linux username and password. + +Update Ubuntu: + +```bash +sudo apt update +sudo apt upgrade -y +``` + +#### 2. Install Development Tools + +```bash +sudo apt install git python3 python3-pip python3-venv build-essential +``` + +Install **uv**: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Reload your shell: + +```bash +source ~/.bashrc +``` + +## Clone the Repository + +From your Ubuntu terminal: + +```bash +cd ~ +git clone https://github.com/username/TankControllerPico.git +cd TankControllerPico +``` + +## Open in VS Code (Windows) + +1. Install the **Remote - WSL** extension. +2. Open the project from the Ubuntu terminal: + +```bash +code . +``` + +Install the **Python** and **Pylance** extensions in **WSL: Ubuntu**. + +## Set Up the Python Environment + +Create a virtual environment and install the project dependencies: + +```bash +uv venv +uv pip install -e ".[dev]" +``` + +## Run the Project + +Launch the local GUI with mocked devices: + +```bash ./run_gui.sh ``` +## picture + +Running the project should launch the TankController GUI. + +

+ TankController GUI +

+ + ## Features | View Commands | Set Commands | diff --git a/images/gui_screenshot.png b/images/gui_screenshot.png new file mode 100644 index 0000000000000000000000000000000000000000..c07d74298d3636fb18c887b185eff536e335adef GIT binary patch literal 11079 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 literal 0 HcmV?d00001 From 95d011ec0c08d24361262350b9eac13b0a69b62d Mon Sep 17 00:00:00 2001 From: Lidya Langana Date: Tue, 28 Jul 2026 11:39:52 -0700 Subject: [PATCH 2/2] Update README to include window instruction --- README.md | 110 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 75 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 3006e50..53793b1 100644 --- a/README.md +++ b/README.md @@ -6,41 +6,63 @@ -## Project Motivations +# TankControllerPico -Update the `TankController` code from C++ to Python and run on a Raspberry Pico. +## Project Motivation + +The goal of this project is to migrate the original **TankController** software from **C++** to **Python** and run it on a **Raspberry Pi Pico**. + +--- # Getting Started -## Requirements +Follow the steps below to set up your development environment. + +> [!NOTE] +> Windows development requires **Windows Subsystem for Linux (WSL)**. All project commands should be run inside your Linux terminal. + +--- -Before running the project, install the following: +## Step 1 — Install Prerequisites + +Before cloning the project, install the following: - **Python 3.14+** - **uv** (Python package manager) - - Installation: https://docs.astral.sh/uv/ + - https://docs.astral.sh/uv/ - **Tkinter** (required for the local GUI) - - Verify the installation: - ```bash - python -m tkinter - ``` +### Verify Tkinter + +Run: - A small GUI window should appear if Tkinter is installed correctly. +```bash +python -m tkinter +``` + +If Tkinter is installed correctly, a small GUI window will appear. + +--- + +## Step 2 — Complete Platform Setup + +Choose the instructions for your operating system. ### macOS -Older Python versions may have issues running the GUI. Install Tkinter for Python 3.14: +Older Python versions may have issues running the GUI. + +Install the Tkinter package for Python 3.14: ```bash brew install python-tk@3.14 ``` -### Windows +--- -Windows development requires **Windows Subsystem for Linux (WSL)**. +### Windows -#### 1. Install WSL +#### Install WSL Open **PowerShell as Administrator** and run: @@ -48,22 +70,26 @@ Open **PowerShell as Administrator** and run: wsl --install ``` -Restart your computer, open **Ubuntu**, and create your Linux username and password. +Restart your computer. -Update Ubuntu: +After restarting: + +1. Open **Ubuntu** from the Start menu. +2. Create your Linux username and password. +3. Update Ubuntu: ```bash sudo apt update sudo apt upgrade -y ``` -#### 2. Install Development Tools +#### Install Development Tools ```bash sudo apt install git python3 python3-pip python3-venv build-essential ``` -Install **uv**: +#### Install uv ```bash curl -LsSf https://astral.sh/uv/install.sh | sh @@ -75,37 +101,49 @@ Reload your shell: source ~/.bashrc ``` -## Clone the Repository +#### Configure VS Code + +Install the following VS Code extensions: -From your Ubuntu terminal: +- Remote - WSL +- Python +- Pylance + +Once the repository has been cloned, open it from your Ubuntu terminal: ```bash -cd ~ -git clone https://github.com/username/TankControllerPico.git -cd TankControllerPico +code . ``` -## Open in VS Code (Windows) +--- -1. Install the **Remote - WSL** extension. -2. Open the project from the Ubuntu terminal: +## Step 3 — Clone the Repository + +Clone the repository into your Linux environment. ```bash -code . +git clone https://github.com/username/TankControllerPico.git +cd TankControllerPico ``` -Install the **Python** and **Pylance** extensions in **WSL: Ubuntu**. +--- -## Set Up the Python Environment +## Step 4 — Set Up the Development Environment -Create a virtual environment and install the project dependencies: +Create a virtual environment: ```bash uv venv +``` + +Install the project dependencies: + +```bash uv pip install -e ".[dev]" ``` -## Run the Project +--- +## Step 5 — Run the Project Launch the local GUI with mocked devices: @@ -113,12 +151,14 @@ Launch the local GUI with mocked devices: ./run_gui.sh ``` -## picture - -Running the project should launch the TankController GUI. +If the setup was successful, the TankController GUI should open and look similar to the example below.

- TankController GUI + TankController GUI