Merge branch 'main' into manush/can-traffic

.gitignore

@@ -1,2 +1,8 @@
 .DS_STORE
-.vscode
+.vscode
+
+env/
+venv/
+.env/
+.venv/
+__pycache__/

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# Minimum version of pre-commit
+minimum_pre_commit_version: "2.9.0"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      # Prevent committing directly to the main branch
+      - id: no-commit-to-branch
+        args: [--branch, main]
+        stages: [commit]
+
+  - repo: local
+    hooks:
+      - id: clang-format
+        name: Run git-clang-format
+        entry: git clang-format --style=file --staged
+        language: python
+        stages: [commit]
+        additional_dependencies:
+          - clang-format~=19.0

docs/docs/firmware/compile-project.md

@@ -1,8 +1,10 @@
 # Compiling a Project
 
-We have a CMake build system and Makefile front end.
+We have a CMake build system and Makefile front end. The Makefile expects 2 variables from the command line.
 
-The Makefile expects 2 variables from the command line
+!!! note "Virtual Environment"
+
+    These instructions assume that your [`cangen` virtual environment is active](dev-setup.md/#install-cangen).
 
 ## Makefile Variables
 
@@ -42,3 +44,8 @@ This command only applies when `#!bash PLATFORM=stm32f767`. It deletes all "giti
 ### `st-flash`
 
 Calls `build` then downloads the firmware to a connected stm device.
+
+!!! tip
+    You should use the [STM32CubeProgrammer](dev-setup.md/#stm32cubeprogrammer) software instead of `st-flash`.
+
+    See [Flashing Firmware](flashing/index.md).

docs/docs/firmware/dev-setup.md

@@ -45,12 +45,6 @@ Follow these steps to begin developing in `racecar/firmware`.
         C:\path-to-msys2\mingw64\lib
         ```
 
-    5. Install the Arm GNU Toolchain from <https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads>.
-
-        1. Download the `.exe` installer under "Windows hosted cross toolchains -> AArch32 bare-metal target (arm-none-eabi)".
-        2. Run the installer.
-        3. After the installer finishes, check `Add path to environment variable.`
-
 === "Linux"
 
     1. Set up the Kitware APT repository <https://apt.kitware.com/>.
@@ -61,25 +55,21 @@ Follow these steps to begin developing in `racecar/firmware`.
 
         ```bash
         sudo apt-get update
-        sudo apt-get install software-properties-common
+        sudo apt-get install software-properties-common python3-launchpadlib
         sudo add-apt-repository ppa:deadsnakes/ppa
         sudo apt-get update
         sudo apt-get install git-all build-essential cmake python3.12 wget gcc-13
         ```
 
-    3. Install the Arm GNU Toolchain.
+### Arm Toolchain
 
-        1. Download and unzip the x86_64 Linux arm-none-eabi toolchain binaries.
+Install the Arm GNU Toolchain (v13 or newer) from <https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads>.
 
-                wget https://developer.arm.com/-/media/Files/downloads/gnu/13.3.rel1/binrel/arm-gnu-toolchain-13.3.rel1-x86_64-arm-none-eabi.tar.xz
-                sudo tar xf arm-gnu-toolchain-13.3.rel1-x86_64-arm-none-eabi.tar.xz -C /usr/share
-                rm arm-gnu-toolchain-13.3.rel1-x86_64-arm-none-eabi.tar.xz
+1. Find the __<ARCHITECTURE\> hosted cross toolchains__ section for your computer's architecture then download and install the __AArch32 bare-metal target (arm-none-eabi)__.
 
-        2. Add the binaries to your profile PATH.
+    > There are multiple downloads available in this section. Choose the installer: `.exe` on Windows, `.tar.xz` on Linux, `.pkg` on MacOS.
 
-            Open `~/.profile` in a text editor and add this to the end of the file.
-
-                PATH="/usr/share/arm-gnu-toolchain-13.3.rel1-x86_64-arm-none-eabi/bin:$PATH"
+2. Add the folder containing the binaries to your path.
 
 ### Verify Installation
 
@@ -150,7 +140,7 @@ Navigate to a directory where you would like to hold the `racecar` repo (I used
 
     git clone --recurse-submodules https://github.com/macformula/racecar.git
 
-## Install CANgen dependencies
+## Install CANgen
 
 Create a Python virtual environment for CANgen. Navigate into `racecar/firmware` and run.
 
@@ -168,14 +158,16 @@ Create a Python virtual environment for CANgen. Navigate into `racecar/firmware`
     source .env/bin/activate
     ```
 
-The second command "activates" the virtual environment. You will see `(.env)` beside your terminal prompt when it is activated, and it must be activated before building any project.
+The second command "activates" the virtual environment. You will see `(.env)` beside your terminal prompt when it is activated. __It must be activated before building any project.__
 
-Finally, with the environment activated, install the CANgen requirements.
+With the environment activated, change into `racecar/` and install CANgen:
 
 ```bash
-pip install -r ../scripts/cangen/requirements.txt
+pip install -e scripts/cangen
 ```
 
+> The `-e` flag is _very_ important. It installs CANgen as an editable package which means you won't have to reinstall when the package is changed.
+
 You can now start developing in `racecar`! However, I recommend you configure your IDE with `clangd`, so continue to the next section.
 
 ## IDE Integration
@@ -234,3 +226,23 @@ __Important:__ Create an empty file named `.clangd` in the `firmware/` directory
 You will need a Unix development environment (Unix machine, WSL, or remote into the Raspberry Pi).
 
 Go through the [gRPC C++ Quickstart Guide](https://grpc.io/docs/languages/cpp/quickstart/). Build the example project.
+
+## Pre-Commit Setup
+
+We use `pre-commit` hooks to run formatting and code checks before the code is pushed.
+
+### Installing Pre-Commit
+
+1. Install `pre-commit` via pip:
+
+    ```bash
+    pip install pre-commit
+    ```
+
+2. Install the git hooks by running this command in the `racecar` directory:
+
+    ```bash
+    pre-commit install
+    ```
+
+    This will install the hooks so they run automatically when you use `git commit`.

docs/docs/firmware/flashing/img/.gitignore

@@ -0,0 +1,2 @@
+# draw.io backups
+*.bkp

docs/docs/firmware/flashing/index.md

@@ -0,0 +1,111 @@
+# :material-download: Flashing Firmware
+
+After [compiling a project](../compile-project.md) for the `stm32f767` platform, you need to flash the firmware to the board. This article describes how to connect to a board and flash using [STM32CubeProgrammer](../dev-setup.md/#stm32cubeprogrammer).
+
+## Connect to the Board
+
+We flash using ST-Link which is an interface to STM microcontrollers.
+
+### Development Boards + Dashboard
+
+Most development boards (such as the [Nucleo-144](https://www.st.com/en/evaluation-tools/nucleo-f767zi.html) and [dashboard kit](https://www.st.com/en/evaluation-tools/stm32f7508-dk.html)) have built-in ST-Link hardware and a USB interface.
+
+Simply connect the board to your laptop with a USB cable.
+
+<figure markdown="span">
+  ![nucleo stlink](img/nucleo144-f767zi.png){ width="100%" }
+  <figcaption>ST-Link on Nucleo-144 F767ZI</figcaption>
+</figure>
+
+### Vehicle ECUs
+
+The vehicle ECUs are not development boards. They are bare STM32F7 processors soldered to a circuit board. These boards do not have a built-in ST-Link or USB interface so we must use a different connector.
+
+You will need and external ST-Link and a USB cable from the blue tool chest in the Hatch bay. Some of the ST-Links are Micro-USB and others are USB-C. We should have cables for both.
+
+<figure markdown="span">
+![](img/chest-bags.png){ width="80%" }
+<figcaption>ST-Link and cables are kept in bags in this drawer. Return them when finished!</figcaption>
+</figure>
+
+Please wrap the ST-Link in electrical tape since it has exposed conductors and is very easy to fry.
+
+<figure markdown="span">
+![](img/etape.jpg){ width="80%" }
+<figcaption>E-Tape would have prevented the Great ST-Link Massacre of Comp '24.</figcaption>
+</figure>
+
+1. Ensure the ECU is off (not receiving power) and the USB is not connected to your laptop.
+2. Carefully connect the grey ribbon cable to the ST-Link and the JTAG connector on the ECU board.
+
+    Both ends of the ribbon cable have a tab which must align with the notch on the connector.
+
+    <figure markdown="span">
+    ![](img/notch-2.jpg){ width="80%" }
+    <figcaption>Connector tab and notch</figcaption>
+    </figure>
+
+3. Power on the ECU. Talk to an upper year SW or Electrical member for help.
+4. Connect your laptop to the ST-Link using the USB cable.
+
+Full setup:
+
+![](img/setup_labelled.jpg)
+
+## Open CubeProgrammer
+
+You installed Cube Programmer when [Setting up your Development Environment](../dev-setup.md). Run the program. It will open to a screen like this:
+
+<figure markdown="span">
+![](img/cubeprog_firstscreen.png){ width="100%" }
+</figure>
+
+### Connect to the STM32 with ST Link
+
+<figure markdown="span">
+![](img/cubeprog_diagram-STLink.png){ width="60%" }
+</figure>
+
+1. Select __ST-LINK__ as the programming interface.
+2. Select the ST-Link device serial number. There should only be one option if you are plugged into a single device.
+3. Verify the ST-Link configuration.
+4. Click __Connect__.
+
+### Flash your program
+
+<figure markdown="span">
+![](img/cubeprog_diagram-Download.png){ width="80%" }
+</figure>
+
+1. Switch to the __Download__ window.
+2. Select the binary file to flash. This is the `.bin` file located in
+
+    ```text
+    racecar/firmware/build/PROJECT/PLATFORM/
+    ```
+
+3. Verify the flash configuration.
+4. Click __Start Programming__.
+
+## Troubleshooting
+
+### First flash succeeds, second fails
+
+Disconnect from the ST-Link then reconnect. Wait a few seconds and click __Start Programming__ again.
+
+### Cannot flash at all
+
+You are connected to ST-Link but unable to flash.
+
+* Is the ECU powered? The ST-Link is powered by your laptop but the ECU needs external power.
+
+### Cannot connect to ST-Link
+
+The ST-Link serial appears but I cannot connect:
+
+1. Verify the ST-Link configuration.
+
+The ST-Link serial number does NOT appear:
+
+1. Check your USB connections.
+2. Verify the ST-Link is receiving power by looking for LED lights.

docs/docs/firmware/hw-debug.md

@@ -0,0 +1,113 @@
+# :material-bug: Hardware Debugging
+
+## Background
+
+For debugging our boards, we use OpenOCD and GDB.
+
+[OpenOCD (Open On-Chip Debugger)](https://openocd.org/) is a tool that enables on-chip debugging, flash programming, and testing for microcontrollers. It will start a server that listens for commands from various sources such as GDB.
+
+[GDB (GNU Debugger)](https://www.sourceware.org/gdb/) is a debugging tool that enables inspection, modification, and control of program execution on microcontrollers.
+
+## Installation
+
+=== "Windows"
+    ```text
+    choco install openocd
+    ```
+
+=== "Linux"
+    ```text
+    sudo apt-get install openocd
+    ```
+
+=== "Mac"
+    ```text
+    brew install openocd
+    ```
+
+The ARM GNU Toolchain containing GDB is already installed if you followed the [Firmware Development Setup](../firmware/dev-setup.md) guide. Refer to that if it is not installed.
+
+### Verify Installation
+
+Check that both programs are installed and have an acceptable version.
+
+Do not copy the `# version comments`.
+
+```text
+openocd --version               # >= 0.12.0
+arm-none-eabi-gdb --version     # >= 13.0
+```
+
+## Usage
+
+To debug a program, the OpenOCD server must be started and GDB connected to it.
+
+1. Build your project for the `stm32f767` platform. See [Compiling a Project](../firmware/compile-project.md) for more details:
+
+    ```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 build
+    ```
+
+2. Plug your board into your computer and ensure it is powered on.
+
+3. Start the OpenOCD server:
+
+    ```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 debug-openocd
+    ```
+
+4. In a separate terminal, start GDB:
+
+    ```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 debug-gdb
+    ```
+
+5. Start debugging in the GDB terminal. See the list of common commands and an example below.
+
+### GDB Commands
+
+These commands are executed directly in the GDB terminal.
+
+`help`: Displays a list of available commands and their syntax/descriptions.
+
+`load`: Loads the program into the target device's memory. The `debug-gdb` command has been configured to do this automatically on startup.
+
+`continue`: Resumes program execution until the next breakpoint or end.
+
+`finish`: Continues execution until the current function finishes, then stops.
+
+`next`: Executes the next line of code, stepping over any function calls.
+
+`step`: Executes the next line of code, stepping into any function calls.
+
+`break`: Sets a breakpoint at a specified line or function to pause execution.
+
+`info breakpoints`: Lists all active breakpoints and their details.
+
+`where`: Displays the current call stack, showing the active function and its caller hierarchy.
+
+Refer to [VisualGDB](https://visualgdb.com/gdbreference/commands/) and [GDB Cheat Sheet](https://darkdust.net/files/GDB%20Cheat%20Sheet.pdf) for more commands and details.
+
+### Example
+
+The following commands show an example debugging session with the Blink project.
+
+```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 debug-openocd
+```
+
+```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 debug-gdb
+```
+
+```text
+    (gdb) break main        # Set a breakpoint at the main function
+    (gdb) continue          # Continue the execution of the program
+    (gdb) where             # Display the current call stack
+    (gdb) next              # Execute the next line of code
+    (gdb) quit              # Exit GDB
+```
+
+## Resources
+
+Refer to additional documentation for more information on debugging with [OpenOCD](https://openocd.org/doc/html/index.html) and [GDB](https://sourceware.org/gdb/current/onlinedocs/gdb/).

docs/docs/firmware/project-structure/index.md

@@ -94,7 +94,7 @@ We now add 3 elements to our contract.
     --8<-- "inc/bindings.h"
     ```
 
-This completes the bindings contract. We can now write the application code, knowing that the platforms will all stasify this contract.
+This completes the bindings contract. We can now write the application code, knowing that the platforms will all satisfy this contract.
 
 ## Application code