Flashing instructions (#269)

* fixes ppa error and starts flashing instructions

* images

* Add CubeProgrammer flashing instructions.

* Fix broken internal links

* Grammar

* Move flashing article to the tutorials section

* Adds emoji to title to look good on main tutorials page

* Fixes links

* Grammar fix

* Move flashing article back to firmware

* Moves links

* Add setup diagram

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.
-
-        1. Download and unzip the x86_64 Linux arm-none-eabi toolchain binaries.
+### Arm Toolchain
 
-                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
+Install the Arm GNU Toolchain (v13 or newer) from <https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads>.
 
-        2. Add the binaries to your profile PATH.
+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)__.
 
-            Open `~/.profile` in a text editor and add this to the end of the file.
+    > There are multiple downloads available in this section. Choose the installer: `.exe` on Windows, `.tar.xz` on Linux, `.pkg` on MacOS.
 
-                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
 

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/mkdocs.yml

@@ -125,6 +125,7 @@ nav:
     - firmware/architecture.md
     - firmware/project-structure/index.md
     - firmware/compile-project.md
+    - firmware/flashing/index.md
   - Glossary: glossary.md
 
 watch: