diff --git a/docs/docs/firmware/compile-project.md b/docs/docs/firmware/compile-project.md index 8acd244e5..308533aec 100644 --- a/docs/docs/firmware/compile-project.md +++ b/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). diff --git a/docs/docs/firmware/dev-setup.md b/docs/docs/firmware/dev-setup.md index 745a55b69..f18347f71 100644 --- a/docs/docs/firmware/dev-setup.md +++ b/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 . - - 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 . @@ -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 . - 2. Add the binaries to your profile PATH. +1. Find the __ 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 diff --git a/docs/docs/firmware/flashing/img/.gitignore b/docs/docs/firmware/flashing/img/.gitignore new file mode 100644 index 000000000..87118d95b --- /dev/null +++ b/docs/docs/firmware/flashing/img/.gitignore @@ -0,0 +1,2 @@ +# draw.io backups +*.bkp \ No newline at end of file diff --git a/docs/docs/firmware/flashing/img/blue_chest.jpg b/docs/docs/firmware/flashing/img/blue_chest.jpg new file mode 100644 index 000000000..a6aa9c12b Binary files /dev/null and b/docs/docs/firmware/flashing/img/blue_chest.jpg differ diff --git a/docs/docs/firmware/flashing/img/chest-bags.png b/docs/docs/firmware/flashing/img/chest-bags.png new file mode 100644 index 000000000..4cad2965d Binary files /dev/null and b/docs/docs/firmware/flashing/img/chest-bags.png differ diff --git a/docs/docs/firmware/flashing/img/cubeprog.png b/docs/docs/firmware/flashing/img/cubeprog.png new file mode 100644 index 000000000..6021bb593 Binary files /dev/null and b/docs/docs/firmware/flashing/img/cubeprog.png differ diff --git a/docs/docs/firmware/flashing/img/cubeprog_diagram-Download.png b/docs/docs/firmware/flashing/img/cubeprog_diagram-Download.png new file mode 100644 index 000000000..af9e01150 Binary files /dev/null and b/docs/docs/firmware/flashing/img/cubeprog_diagram-Download.png differ diff --git a/docs/docs/firmware/flashing/img/cubeprog_diagram-STLink.png b/docs/docs/firmware/flashing/img/cubeprog_diagram-STLink.png new file mode 100644 index 000000000..5d88c69c7 Binary files /dev/null and b/docs/docs/firmware/flashing/img/cubeprog_diagram-STLink.png differ diff --git a/docs/docs/firmware/flashing/img/cubeprog_diagram.drawio b/docs/docs/firmware/flashing/img/cubeprog_diagram.drawio new file mode 100644 index 000000000..60a865767 --- /dev/null +++ b/docs/docs/firmware/flashing/img/cubeprog_diagram.drawio @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/docs/firmware/flashing/img/cubeprog_firstscreen.png b/docs/docs/firmware/flashing/img/cubeprog_firstscreen.png new file mode 100644 index 000000000..3bafa42a1 Binary files /dev/null and b/docs/docs/firmware/flashing/img/cubeprog_firstscreen.png differ diff --git a/docs/docs/firmware/flashing/img/etape.jpg b/docs/docs/firmware/flashing/img/etape.jpg new file mode 100644 index 000000000..8716ba642 Binary files /dev/null and b/docs/docs/firmware/flashing/img/etape.jpg differ diff --git a/docs/docs/firmware/flashing/img/notch-2.jpg b/docs/docs/firmware/flashing/img/notch-2.jpg new file mode 100644 index 000000000..e19450c2d Binary files /dev/null and b/docs/docs/firmware/flashing/img/notch-2.jpg differ diff --git a/docs/docs/firmware/flashing/img/nucleo144-f767zi.png b/docs/docs/firmware/flashing/img/nucleo144-f767zi.png new file mode 100644 index 000000000..997fd10eb Binary files /dev/null and b/docs/docs/firmware/flashing/img/nucleo144-f767zi.png differ diff --git a/docs/docs/firmware/flashing/img/setup_labelled.jpg b/docs/docs/firmware/flashing/img/setup_labelled.jpg new file mode 100644 index 000000000..3c0ff947e Binary files /dev/null and b/docs/docs/firmware/flashing/img/setup_labelled.jpg differ diff --git a/docs/docs/firmware/flashing/img/st-bag.jpg b/docs/docs/firmware/flashing/img/st-bag.jpg new file mode 100644 index 000000000..4432f5e04 Binary files /dev/null and b/docs/docs/firmware/flashing/img/st-bag.jpg differ diff --git a/docs/docs/firmware/flashing/img/tms-jtag.jpg b/docs/docs/firmware/flashing/img/tms-jtag.jpg new file mode 100644 index 000000000..0d5ee872e Binary files /dev/null and b/docs/docs/firmware/flashing/img/tms-jtag.jpg differ diff --git a/docs/docs/firmware/flashing/index.md b/docs/docs/firmware/flashing/index.md new file mode 100644 index 000000000..bf56e6ea8 --- /dev/null +++ b/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. + +
+ ![nucleo stlink](img/nucleo144-f767zi.png){ width="100%" } +
ST-Link on Nucleo-144 F767ZI
+
+ +### 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. + +
+![](img/chest-bags.png){ width="80%" } +
ST-Link and cables are kept in bags in this drawer. Return them when finished!
+
+ +Please wrap the ST-Link in electrical tape since it has exposed conductors and is very easy to fry. + +
+![](img/etape.jpg){ width="80%" } +
E-Tape would have prevented the Great ST-Link Massacre of Comp '24.
+
+ +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. + +
+ ![](img/notch-2.jpg){ width="80%" } +
Connector tab and notch
+
+ +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: + +
+![](img/cubeprog_firstscreen.png){ width="100%" } +
+ +### Connect to the STM32 with ST Link + +
+![](img/cubeprog_diagram-STLink.png){ width="60%" } +
+ +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 + +
+![](img/cubeprog_diagram-Download.png){ width="80%" } +
+ +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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e01b35c63..44c654160 100644 --- a/docs/mkdocs.yml +++ b/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: