From c1b4bc6fa331b4fbc2f5363857859ca8208276ab Mon Sep 17 00:00:00 2001 From: Claegtun Date: Sun, 26 Oct 2025 14:20:24 +1100 Subject: [PATCH 01/10] Began. --- .../05-flashing-firmware-to-NUSense.mdx | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense.mdx diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense.mdx new file mode 100644 index 00000000..856a0b3d --- /dev/null +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense.mdx @@ -0,0 +1,23 @@ +--- +section: Guides +chapter: Hardware +title: Flashing Firmware to NUSense +description: How to install code to the NUSense subcontroller board +slug: /guides/hardware/flashing-firmware-to-NUSense +authors: + - Clayton Carlon (@Claegtun) +--- + +## Flashing Firmware to NUSense + +NUSense is a subcontroller board custom-made by NUbots that communicates with the servo-motors through RS485. This guide shall take the reader through the process of installing or *flashing* firmware unto the microcontroller. + +### Prerequisites + +The reader needs +- a NUSense board with the appropriate components soldered, +- a tool to flash firmware to the board -- this guide will use the ST-Link dongle --, +- a computer with the latest STM32CubeIDE installed. + + + From 72b848a20e70752da4e8e6632c9f4b041d92637f Mon Sep 17 00:00:00 2001 From: Claegtun Date: Sun, 7 Dec 2025 12:22:37 +1100 Subject: [PATCH 02/10] Renamed the file; added more detail. --- ...flashing-firmware-to-NUSense-and-NUFSR.mdx | 123 ++++++++++++++++++ .../05-flashing-firmware-to-NUSense.mdx | 23 ---- 2 files changed, 123 insertions(+), 23 deletions(-) create mode 100644 src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx delete mode 100644 src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense.mdx diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx new file mode 100644 index 00000000..74f151e4 --- /dev/null +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx @@ -0,0 +1,123 @@ +--- +section: Guides +chapter: Hardware +title: Flashing Firmware to NUSense and NUFSR +description: How to install code to the NUSense subcontroller board +slug: /guides/hardware/flashing-firmware-to-NUSense-and-NFSR +authors: + - Clayton Carlon (@Claegtun) +--- + +## Flashing Firmware to NUSense and NUFSR + +NUSense is a subcontroller board custom-made together by Elby Designs and NUbots that communicates with the servo-motors through RS485. This guide shall take the reader through the process of installing or *flashing* firmware unto the microcontroller. It also applies to NUFSR. + +### Prerequisites + +The reader needs +- a NUSense/NUFSR board with the appropriate components soldered, e.g. in the case of NUSense U101, JP101, etc., +- a tool to flash firmware to the board -- this guide will use the ST-Link dongle --, +- and a computer with the latest STM32CubeIDE installed -- Linux versions can be found [here](https://www.st.com/en/development-tools/stm32cubeide.html#get-software). + +### Set-up + +1. Clone the NUbots/NUcontroller repository. + + ```bash + git clone https://github.com/NUbots/NUcontroller.git + ``` + +2. Start STM32CubeIDE up. + +3. It will ask to choose a workspace. Choose the local NUcontroller directory as the workspace and launch. + +4. Once the IDE has been launched, go to _File > Import... > Existing Projects into Workspace_. + +5. + +### Connecting to the ST-Link + +1. Plug the ST-Link into the computer that is running STM32CubeIDE. + + + +It is most convenient to use a short USB extension cable so that the ST-Link can be near to the NUSense board. + + + +2. Plug the other end of the ST-Link into the NUSense board with a custom ribbon-cable. + + + +The ST-Link must connect to the NUSense board through a custom ribbon-cable, not just an ordinary one. It should have a few wires rearranged for the different pin-mapping of the ST-Link. Otherwise, one can connect the ST-Link through a few jumper wires as according to the pin-mapping printed on the ST-Link itself and the NUSense schematic. Along with 3.3 V and ground/0 V, SWDIO maps to TMS, and SWCLK maps to TCK. + + + +3. In \[STM32\]CubeIDE, go to _Run > Debug Configurations_. Click on _NUSense Debug_ on the left-hand pane; if it is not there, then double-click on _STM32 C/C++ Application_. After that, go to the _Debugger_ tab. The default settings should be left as they are, but make sure that SWD is chosen under the _Interface_ section and check _ST-LINK S/N_. Then click _Scan_. This finds the serial number of the connected ST-Link; make sure that it is chosen in the dropdown. Click _Apply_ and _Close_. + + + +CubeIDE sometimes stores the serial numbers of past ST-Link devices. So, if you have used multiple ST-Links, then you may need to make sure that the right serial number is chosen. CubeIDE should keep this one set between sessions. Thus, it is best to stick with the same physical ST-Link as much as possible so that you need not to go to the configuration each time. + + + +### Compiling and Flashing + +1. Before flashing, it is a good idea to see the optimiser flags. Go to _Project > Properties > C/C++ Build > Settings_. Depending on your local setup, the dropdown at the top would likely be set as _Debug \[Active\]_ as the _Configuration_; this would do for now. Under the _Tool Settings_ tab, go to _MCU G++ Compiler > Optimization_ and choose the dropdown to whichever optimisation-level that you wish. Here is a quick summary: + + - None (`-O0`) -- runs without any optimisation, that is with the highest fidelity to the source; + - Optimise for Debug (`-Og`) -- runs with as little optimisation as not to get in the way of stepping line by line and accessing variables, watch-expressions, memory, etc. within the debug session -- from the perspective of the debugging, should more or less behave like -O0; + - Optimise (`-O1`), Optimise more (`-O2`), Optimise most (`-O3`) -- runs with general optimisation in increasing degrees; + - Optimise for size (`-Os`) -- optimises with a focus on shrinking the amount of memory used; + - Optimise for speed (`-Ofast`) -- optimises with a focus on computation-time and was experimentally found to be the quickest for the NUSense firmware. + +The optimisation under _MCU GCC Compiler_ should always be set to `-Ofast` unless you wish to debug the generated C firmware in the Hardware Abstraction Library (HAL). + + + +It is recommended to only ever use `-Og` or `-Ofast`, the former only for debugging, and the latter for all else, especially deployment. **Always** make sure that `-Ofast` is set for deployed firmware; `-Og` may seriously hamper the robot's performance. + + + +2. There are three actions for compiling and flashing firmware. + + - _Build_ which only compiles the firmware and is found as the hammer symbol or under _Project_, + - _Run_ which compiles the firmware and flashes the binary and is found as the green play symbol or under _Run_, + - and _Debug_ which compiles the firmware, flashes the binary, and opens a debug session with the microcontroller; it is found as the green bug symbol or under _Run_. + + + +You may take notice that _Run_ and _Debug_ always attempts to compile the firmware as a first step even if it has been compiled before. Therefore, there is no need to _Build_ everytime before flashing. Often, _Run_ and _Debug_ will not actually recompile it but rather see whether a change in the firmware warrants a recompile. As a result, _Build_ is typically only used for checking for compiler-errors, etc. + +Furthermore, running _Debug_ and then exiting the debug session has more of less the same effect as running _Run_. + + + + + +There are two things for which to watch out when flashing firmware for the first time. Firstly, depending on the physical ST-Link, it may ask to update the ST-Link's _firmware_ -- not to be confused with the NUSense _firmware_. To update the ST-Link, + +1. Click _Open in update mode_. + +2. If it says "ST-Link is not in DFU mode. Please restart it.", then + + a. unplug and replug the ST-Link from and to the computer, + + b. click _Refresh device list_, + + c. and click _Open in update mode_ again. + +3. Lastly, click _Upgrade_. + + + + + +Sometimes albeit rare, especially if it is the first ever time flashing to a particular chip, the microcontroller needs to be put into _boot_ mode. This is done when the _BOOT0_ pin of the microcontroller is pulled high when it is powered on. On some revisions of the NUSense board, there is a push-button labelled S101; on NUFSR and other revisions of NUSense, there is instead a two-pin header. In order to put the microcontroller into boot mode, either the push-button needs to be held or a jumper wire is connected across the two pins when power is supplied, more specifically 3.3 V. + +Keep in mind that the ST-Link itself supplies 3.3 V, just enough to power the microcontroller and the IMU. So, if flashing with no other power supplied to the board, then unplugging and replugging the ST-Link counts as if power was cycled. + + + +6. Cleaning the project is often useful for troubleshooting cached errors, etc. It clears the build cache. Go to _Project > Clean ..._ or right-click on the NUSense project under the _Project Explorer_ tab and click _Clean Project_. + diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense.mdx deleted file mode 100644 index 856a0b3d..00000000 --- a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -section: Guides -chapter: Hardware -title: Flashing Firmware to NUSense -description: How to install code to the NUSense subcontroller board -slug: /guides/hardware/flashing-firmware-to-NUSense -authors: - - Clayton Carlon (@Claegtun) ---- - -## Flashing Firmware to NUSense - -NUSense is a subcontroller board custom-made by NUbots that communicates with the servo-motors through RS485. This guide shall take the reader through the process of installing or *flashing* firmware unto the microcontroller. - -### Prerequisites - -The reader needs -- a NUSense board with the appropriate components soldered, -- a tool to flash firmware to the board -- this guide will use the ST-Link dongle --, -- a computer with the latest STM32CubeIDE installed. - - - From 1afc00916852f8b700594785e4f1880908a3f518 Mon Sep 17 00:00:00 2001 From: Claegtun Date: Sun, 7 Dec 2025 12:25:40 +1100 Subject: [PATCH 03/10] Formatted. --- ...flashing-firmware-to-NUSense-and-NUFSR.mdx | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx index 74f151e4..3c6fda88 100644 --- a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx @@ -10,11 +10,12 @@ authors: ## Flashing Firmware to NUSense and NUFSR -NUSense is a subcontroller board custom-made together by Elby Designs and NUbots that communicates with the servo-motors through RS485. This guide shall take the reader through the process of installing or *flashing* firmware unto the microcontroller. It also applies to NUFSR. +NUSense is a subcontroller board custom-made together by Elby Designs and NUbots that communicates with the servo-motors through RS485. This guide shall take the reader through the process of installing or _flashing_ firmware unto the microcontroller. It also applies to NUFSR. ### Prerequisites The reader needs + - a NUSense/NUFSR board with the appropriate components soldered, e.g. in the case of NUSense U101, JP101, etc., - a tool to flash firmware to the board -- this guide will use the ST-Link dongle --, - and a computer with the latest STM32CubeIDE installed -- Linux versions can be found [here](https://www.st.com/en/development-tools/stm32cubeide.html#get-software). @@ -23,7 +24,7 @@ The reader needs 1. Clone the NUbots/NUcontroller repository. - ```bash + ```bash git clone https://github.com/NUbots/NUcontroller.git ``` @@ -33,7 +34,7 @@ The reader needs 4. Once the IDE has been launched, go to _File > Import... > Existing Projects into Workspace_. -5. +5. ### Connecting to the ST-Link @@ -65,11 +66,11 @@ CubeIDE sometimes stores the serial numbers of past ST-Link devices. So, if you 1. Before flashing, it is a good idea to see the optimiser flags. Go to _Project > Properties > C/C++ Build > Settings_. Depending on your local setup, the dropdown at the top would likely be set as _Debug \[Active\]_ as the _Configuration_; this would do for now. Under the _Tool Settings_ tab, go to _MCU G++ Compiler > Optimization_ and choose the dropdown to whichever optimisation-level that you wish. Here is a quick summary: - - None (`-O0`) -- runs without any optimisation, that is with the highest fidelity to the source; - - Optimise for Debug (`-Og`) -- runs with as little optimisation as not to get in the way of stepping line by line and accessing variables, watch-expressions, memory, etc. within the debug session -- from the perspective of the debugging, should more or less behave like -O0; - - Optimise (`-O1`), Optimise more (`-O2`), Optimise most (`-O3`) -- runs with general optimisation in increasing degrees; - - Optimise for size (`-Os`) -- optimises with a focus on shrinking the amount of memory used; - - Optimise for speed (`-Ofast`) -- optimises with a focus on computation-time and was experimentally found to be the quickest for the NUSense firmware. + - None (`-O0`) -- runs without any optimisation, that is with the highest fidelity to the source; + - Optimise for Debug (`-Og`) -- runs with as little optimisation as not to get in the way of stepping line by line and accessing variables, watch-expressions, memory, etc. within the debug session -- from the perspective of the debugging, should more or less behave like -O0; + - Optimise (`-O1`), Optimise more (`-O2`), Optimise most (`-O3`) -- runs with general optimisation in increasing degrees; + - Optimise for size (`-Os`) -- optimises with a focus on shrinking the amount of memory used; + - Optimise for speed (`-Ofast`) -- optimises with a focus on computation-time and was experimentally found to be the quickest for the NUSense firmware. The optimisation under _MCU GCC Compiler_ should always be set to `-Ofast` unless you wish to debug the generated C firmware in the Hardware Abstraction Library (HAL). @@ -81,15 +82,15 @@ It is recommended to only ever use `-Og` or `-Ofast`, the former only for debugg 2. There are three actions for compiling and flashing firmware. - - _Build_ which only compiles the firmware and is found as the hammer symbol or under _Project_, - - _Run_ which compiles the firmware and flashes the binary and is found as the green play symbol or under _Run_, - - and _Debug_ which compiles the firmware, flashes the binary, and opens a debug session with the microcontroller; it is found as the green bug symbol or under _Run_. + - _Build_ which only compiles the firmware and is found as the hammer symbol or under _Project_, + - _Run_ which compiles the firmware and flashes the binary and is found as the green play symbol or under _Run_, + - and _Debug_ which compiles the firmware, flashes the binary, and opens a debug session with the microcontroller; it is found as the green bug symbol or under _Run_. -You may take notice that _Run_ and _Debug_ always attempts to compile the firmware as a first step even if it has been compiled before. Therefore, there is no need to _Build_ everytime before flashing. Often, _Run_ and _Debug_ will not actually recompile it but rather see whether a change in the firmware warrants a recompile. As a result, _Build_ is typically only used for checking for compiler-errors, etc. +You may take notice that _Run_ and _Debug_ always attempts to compile the firmware as a first step even if it has been compiled before. Therefore, there is no need to _Build_ everytime before flashing. Often, _Run_ and _Debug_ will not actually recompile it but rather see whether a change in the firmware warrants a recompile. As a result, _Build_ is typically only used for checking for compiler-errors, etc. -Furthermore, running _Debug_ and then exiting the debug session has more of less the same effect as running _Run_. +Furthermore, running _Debug_ and then exiting the debug session has more of less the same effect as running _Run_. @@ -101,11 +102,11 @@ There are two things for which to watch out when flashing firmware for the first 2. If it says "ST-Link is not in DFU mode. Please restart it.", then - a. unplug and replug the ST-Link from and to the computer, + a. unplug and replug the ST-Link from and to the computer, - b. click _Refresh device list_, + b. click _Refresh device list_, - c. and click _Open in update mode_ again. + c. and click _Open in update mode_ again. 3. Lastly, click _Upgrade_. @@ -113,11 +114,10 @@ There are two things for which to watch out when flashing firmware for the first -Sometimes albeit rare, especially if it is the first ever time flashing to a particular chip, the microcontroller needs to be put into _boot_ mode. This is done when the _BOOT0_ pin of the microcontroller is pulled high when it is powered on. On some revisions of the NUSense board, there is a push-button labelled S101; on NUFSR and other revisions of NUSense, there is instead a two-pin header. In order to put the microcontroller into boot mode, either the push-button needs to be held or a jumper wire is connected across the two pins when power is supplied, more specifically 3.3 V. +Sometimes albeit rare, especially if it is the first ever time flashing to a particular chip, the microcontroller needs to be put into _boot_ mode. This is done when the _BOOT0_ pin of the microcontroller is pulled high when it is powered on. On some revisions of the NUSense board, there is a push-button labelled S101; on NUFSR and other revisions of NUSense, there is instead a two-pin header. In order to put the microcontroller into boot mode, either the push-button needs to be held or a jumper wire is connected across the two pins when power is supplied, more specifically 3.3 V. Keep in mind that the ST-Link itself supplies 3.3 V, just enough to power the microcontroller and the IMU. So, if flashing with no other power supplied to the board, then unplugging and replugging the ST-Link counts as if power was cycled. 6. Cleaning the project is often useful for troubleshooting cached errors, etc. It clears the build cache. Go to _Project > Clean ..._ or right-click on the NUSense project under the _Project Explorer_ tab and click _Clean Project_. - From ea034c93c22e8aebd777bbb5d510a7451a4634b1 Mon Sep 17 00:00:00 2001 From: Claegtun Date: Sun, 7 Dec 2025 12:44:27 +1100 Subject: [PATCH 04/10] Fixed things in preview. --- ...flashing-firmware-to-NUSense-and-NUFSR.mdx | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx index 3c6fda88..86ce12a7 100644 --- a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx @@ -17,8 +17,8 @@ NUSense is a subcontroller board custom-made together by Elby Designs and NUbots The reader needs - a NUSense/NUFSR board with the appropriate components soldered, e.g. in the case of NUSense U101, JP101, etc., -- a tool to flash firmware to the board -- this guide will use the ST-Link dongle --, -- and a computer with the latest STM32CubeIDE installed -- Linux versions can be found [here](https://www.st.com/en/development-tools/stm32cubeide.html#get-software). +- a tool to flash firmware to the board — this guide will use the ST-Link dongle —, +- and a computer with the latest STM32CubeIDE installed — Linux versions can be found [here](https://www.st.com/en/development-tools/stm32cubeide.html#get-software). ### Set-up @@ -40,22 +40,22 @@ The reader needs 1. Plug the ST-Link into the computer that is running STM32CubeIDE. +2. Plug the other end of the ST-Link into the NUSense board with a custom ribbon-cable. + +3. In \[STM32\]CubeIDE, go to _Run > Debug Configurations_. Click on _NUSense Debug_ on the left-hand pane; if it is not there, then double-click on _STM32 C/C++ Application_. After that, go to the _Debugger_ tab. The default settings should be left as they are, but make sure that SWD is chosen under the _Interface_ section and check _ST-LINK S/N_. Then click _Scan_. This finds the serial number of the connected ST-Link; make sure that it is chosen in the dropdown. Click _Apply_ and _Close_. + It is most convenient to use a short USB extension cable so that the ST-Link can be near to the NUSense board. -2. Plug the other end of the ST-Link into the NUSense board with a custom ribbon-cable. - The ST-Link must connect to the NUSense board through a custom ribbon-cable, not just an ordinary one. It should have a few wires rearranged for the different pin-mapping of the ST-Link. Otherwise, one can connect the ST-Link through a few jumper wires as according to the pin-mapping printed on the ST-Link itself and the NUSense schematic. Along with 3.3 V and ground/0 V, SWDIO maps to TMS, and SWCLK maps to TCK. -3. In \[STM32\]CubeIDE, go to _Run > Debug Configurations_. Click on _NUSense Debug_ on the left-hand pane; if it is not there, then double-click on _STM32 C/C++ Application_. After that, go to the _Debugger_ tab. The default settings should be left as they are, but make sure that SWD is chosen under the _Interface_ section and check _ST-LINK S/N_. Then click _Scan_. This finds the serial number of the connected ST-Link; make sure that it is chosen in the dropdown. Click _Apply_ and _Close_. - CubeIDE sometimes stores the serial numbers of past ST-Link devices. So, if you have used multiple ST-Links, then you may need to make sure that the right serial number is chosen. CubeIDE should keep this one set between sessions. Thus, it is best to stick with the same physical ST-Link as much as possible so that you need not to go to the configuration each time. @@ -66,37 +66,39 @@ CubeIDE sometimes stores the serial numbers of past ST-Link devices. So, if you 1. Before flashing, it is a good idea to see the optimiser flags. Go to _Project > Properties > C/C++ Build > Settings_. Depending on your local setup, the dropdown at the top would likely be set as _Debug \[Active\]_ as the _Configuration_; this would do for now. Under the _Tool Settings_ tab, go to _MCU G++ Compiler > Optimization_ and choose the dropdown to whichever optimisation-level that you wish. Here is a quick summary: - - None (`-O0`) -- runs without any optimisation, that is with the highest fidelity to the source; - - Optimise for Debug (`-Og`) -- runs with as little optimisation as not to get in the way of stepping line by line and accessing variables, watch-expressions, memory, etc. within the debug session -- from the perspective of the debugging, should more or less behave like -O0; - - Optimise (`-O1`), Optimise more (`-O2`), Optimise most (`-O3`) -- runs with general optimisation in increasing degrees; - - Optimise for size (`-Os`) -- optimises with a focus on shrinking the amount of memory used; - - Optimise for speed (`-Ofast`) -- optimises with a focus on computation-time and was experimentally found to be the quickest for the NUSense firmware. + - None (`-O0`) — runs without any optimisation, that is with the highest fidelity to the source; + - Optimise for Debug (`-Og`) — runs with as little optimisation as not to get in the way of stepping line by line and accessing variables, watch-expressions, memory, etc. within the debug session — from the perspective of the debugging, should more or less behave like `-O0`; + - Optimise (`-O1`), Optimise more (`-O2`), Optimise most (`-O3`) — runs with general optimisation in increasing degrees; + - Optimise for size (`-Os`) — optimises with a focus on shrinking the amount of memory used; + - Optimise for speed (`-Ofast`) — optimises with a focus on computation-time and was experimentally found to be the quickest for the NUSense firmware. The optimisation under _MCU GCC Compiler_ should always be set to `-Ofast` unless you wish to debug the generated C firmware in the Hardware Abstraction Library (HAL). - - -It is recommended to only ever use `-Og` or `-Ofast`, the former only for debugging, and the latter for all else, especially deployment. **Always** make sure that `-Ofast` is set for deployed firmware; `-Og` may seriously hamper the robot's performance. - - - 2. There are three actions for compiling and flashing firmware. - _Build_ which only compiles the firmware and is found as the hammer symbol or under _Project_, - _Run_ which compiles the firmware and flashes the binary and is found as the green play symbol or under _Run_, - and _Debug_ which compiles the firmware, flashes the binary, and opens a debug session with the microcontroller; it is found as the green bug symbol or under _Run_. +3. Cleaning the project is often useful for troubleshooting cached errors, etc. It clears the build cache. Go to _Project > Clean ..._ or right-click on the NUSense project under the _Project Explorer_ tab and click _Clean Project_. + + + +It is recommended to only ever use `-Og` or `-Ofast`, the former only for debugging, and the latter for all else, especially deployment. **Always** make sure that `-Ofast` is set for deployed firmware; `-Og` may seriously hamper the robot's performance. + + + You may take notice that _Run_ and _Debug_ always attempts to compile the firmware as a first step even if it has been compiled before. Therefore, there is no need to _Build_ everytime before flashing. Often, _Run_ and _Debug_ will not actually recompile it but rather see whether a change in the firmware warrants a recompile. As a result, _Build_ is typically only used for checking for compiler-errors, etc. -Furthermore, running _Debug_ and then exiting the debug session has more of less the same effect as running _Run_. +Furthermore, running _Debug_ and then exiting the debug session has more or less the same effect as running _Run_. -There are two things for which to watch out when flashing firmware for the first time. Firstly, depending on the physical ST-Link, it may ask to update the ST-Link's _firmware_ -- not to be confused with the NUSense _firmware_. To update the ST-Link, +There are two things for which to watch out when flashing firmware for the first time. Firstly, depending on the physical ST-Link, it may ask to update the ST-Link's _firmware_ — not to be confused with the NUSense _firmware_. To update the ST-Link, 1. Click _Open in update mode_. @@ -114,10 +116,8 @@ There are two things for which to watch out when flashing firmware for the first -Sometimes albeit rare, especially if it is the first ever time flashing to a particular chip, the microcontroller needs to be put into _boot_ mode. This is done when the _BOOT0_ pin of the microcontroller is pulled high when it is powered on. On some revisions of the NUSense board, there is a push-button labelled S101; on NUFSR and other revisions of NUSense, there is instead a two-pin header. In order to put the microcontroller into boot mode, either the push-button needs to be held or a jumper wire is connected across the two pins when power is supplied, more specifically 3.3 V. +Sometimes albeit rare, especially if it is the first ever time flashing to a particular chip, the microcontroller needs to be put into _boot_ mode. This is done when the _BOOT0_ pin of the microcontroller is pulled high when it is powered on. On some revisions of the NUSense board, there is a push-button labelled S101; on NUFSR and other revisions of NUSense, there is instead a two-pin header. In order to put the microcontroller into boot mode, either the push-button needs to be held or a jumper wire is connected across the two pins when power is supplied, more specifically 3.3 V. Keep in mind that the ST-Link itself supplies 3.3 V, just enough to power the microcontroller and the IMU. So, if flashing with no other power supplied to the board, then unplugging and replugging the ST-Link counts as if power was cycled. - - -6. Cleaning the project is often useful for troubleshooting cached errors, etc. It clears the build cache. Go to _Project > Clean ..._ or right-click on the NUSense project under the _Project Explorer_ tab and click _Clean Project_. + \ No newline at end of file From 79aac83a0a052b508016757253ac2df39486d041 Mon Sep 17 00:00:00 2001 From: Claegtun Date: Sun, 7 Dec 2025 12:44:49 +1100 Subject: [PATCH 05/10] Formatted. --- .../03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx index 86ce12a7..101fa5b5 100644 --- a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx @@ -120,4 +120,4 @@ Sometimes albeit rare, especially if it is the first ever time flashing to a par Keep in mind that the ST-Link itself supplies 3.3 V, just enough to power the microcontroller and the IMU. So, if flashing with no other power supplied to the board, then unplugging and replugging the ST-Link counts as if power was cycled. - \ No newline at end of file + From 15eab338332ed489d45907684e2584f0aa52d217 Mon Sep 17 00:00:00 2001 From: Claegtun Date: Sun, 7 Dec 2025 12:49:28 +1100 Subject: [PATCH 06/10] Made a test. --- .../05-flashing-firmware-to-NUSense-and-NUFSR.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx index 101fa5b5..f6665d3c 100644 --- a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx @@ -72,7 +72,13 @@ CubeIDE sometimes stores the serial numbers of past ST-Link devices. So, if you - Optimise for size (`-Os`) — optimises with a focus on shrinking the amount of memory used; - Optimise for speed (`-Ofast`) — optimises with a focus on computation-time and was experimentally found to be the quickest for the NUSense firmware. -The optimisation under _MCU GCC Compiler_ should always be set to `-Ofast` unless you wish to debug the generated C firmware in the Hardware Abstraction Library (HAL). + The optimisation under _MCU GCC Compiler_ should always be set to `-Ofast` unless you wish to debug the generated C firmware in the Hardware Abstraction Library (HAL). + + + + It is recommended to only ever use `-Og` or `-Ofast`, the former only for debugging, and the latter for all else, especially deployment. **Always** make sure that `-Ofast` is set for deployed firmware; `-Og` may seriously hamper the robot's performance. + + 2. There are three actions for compiling and flashing firmware. @@ -82,12 +88,6 @@ The optimisation under _MCU GCC Compiler_ should always be set to `-Ofast` unles 3. Cleaning the project is often useful for troubleshooting cached errors, etc. It clears the build cache. Go to _Project > Clean ..._ or right-click on the NUSense project under the _Project Explorer_ tab and click _Clean Project_. - - -It is recommended to only ever use `-Og` or `-Ofast`, the former only for debugging, and the latter for all else, especially deployment. **Always** make sure that `-Ofast` is set for deployed firmware; `-Og` may seriously hamper the robot's performance. - - - You may take notice that _Run_ and _Debug_ always attempts to compile the firmware as a first step even if it has been compiled before. Therefore, there is no need to _Build_ everytime before flashing. Often, _Run_ and _Debug_ will not actually recompile it but rather see whether a change in the firmware warrants a recompile. As a result, _Build_ is typically only used for checking for compiler-errors, etc. From da4f28ca671da269798aebf93ce46f58041acdc2 Mon Sep 17 00:00:00 2001 From: Claegtun Date: Sun, 7 Dec 2025 12:54:43 +1100 Subject: [PATCH 07/10] Moved alerts under lists. --- ...flashing-firmware-to-NUSense-and-NUFSR.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx index f6665d3c..1fdaad72 100644 --- a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx @@ -40,27 +40,27 @@ The reader needs 1. Plug the ST-Link into the computer that is running STM32CubeIDE. -2. Plug the other end of the ST-Link into the NUSense board with a custom ribbon-cable. + -3. In \[STM32\]CubeIDE, go to _Run > Debug Configurations_. Click on _NUSense Debug_ on the left-hand pane; if it is not there, then double-click on _STM32 C/C++ Application_. After that, go to the _Debugger_ tab. The default settings should be left as they are, but make sure that SWD is chosen under the _Interface_ section and check _ST-LINK S/N_. Then click _Scan_. This finds the serial number of the connected ST-Link; make sure that it is chosen in the dropdown. Click _Apply_ and _Close_. + It is most convenient to use a short USB extension cable so that the ST-Link can be near to the NUSense board. - + -It is most convenient to use a short USB extension cable so that the ST-Link can be near to the NUSense board. +2. Plug the other end of the ST-Link into the NUSense board with a custom ribbon-cable. - + - + The ST-Link must connect to the NUSense board through a custom ribbon-cable, not just an ordinary one. It should have a few wires rearranged for the different pin-mapping of the ST-Link. Otherwise, one can connect the ST-Link through a few jumper wires as according to the pin-mapping printed on the ST-Link itself and the NUSense schematic. Along with 3.3 V and ground/0 V, SWDIO maps to TMS, and SWCLK maps to TCK. -The ST-Link must connect to the NUSense board through a custom ribbon-cable, not just an ordinary one. It should have a few wires rearranged for the different pin-mapping of the ST-Link. Otherwise, one can connect the ST-Link through a few jumper wires as according to the pin-mapping printed on the ST-Link itself and the NUSense schematic. Along with 3.3 V and ground/0 V, SWDIO maps to TMS, and SWCLK maps to TCK. + - +3. In \[STM32\]CubeIDE, go to _Run > Debug Configurations_. Click on _NUSense Debug_ on the left-hand pane; if it is not there, then double-click on _STM32 C/C++ Application_. After that, go to the _Debugger_ tab. The default settings should be left as they are, but make sure that SWD is chosen under the _Interface_ section and check _ST-LINK S/N_. Then click _Scan_. This finds the serial number of the connected ST-Link; make sure that it is chosen in the dropdown. Click _Apply_ and _Close_. - + -CubeIDE sometimes stores the serial numbers of past ST-Link devices. So, if you have used multiple ST-Links, then you may need to make sure that the right serial number is chosen. CubeIDE should keep this one set between sessions. Thus, it is best to stick with the same physical ST-Link as much as possible so that you need not to go to the configuration each time. + CubeIDE sometimes stores the serial numbers of past ST-Link devices. So, if you have used multiple ST-Links, then you may need to make sure that the right serial number is chosen. CubeIDE should keep this one set between sessions. Thus, it is best to stick with the same physical ST-Link as much as possible so that you need not to go to the configuration each time. - + ### Compiling and Flashing @@ -86,15 +86,15 @@ CubeIDE sometimes stores the serial numbers of past ST-Link devices. So, if you - _Run_ which compiles the firmware and flashes the binary and is found as the green play symbol or under _Run_, - and _Debug_ which compiles the firmware, flashes the binary, and opens a debug session with the microcontroller; it is found as the green bug symbol or under _Run_. -3. Cleaning the project is often useful for troubleshooting cached errors, etc. It clears the build cache. Go to _Project > Clean ..._ or right-click on the NUSense project under the _Project Explorer_ tab and click _Clean Project_. + - + You may take notice that _Run_ and _Debug_ always attempts to compile the firmware as a first step even if it has been compiled before. Therefore, there is no need to _Build_ everytime before flashing. Often, _Run_ and _Debug_ will not actually recompile it but rather see whether a change in the firmware warrants a recompile. As a result, _Build_ is typically only used for checking for compiler-errors, etc. -You may take notice that _Run_ and _Debug_ always attempts to compile the firmware as a first step even if it has been compiled before. Therefore, there is no need to _Build_ everytime before flashing. Often, _Run_ and _Debug_ will not actually recompile it but rather see whether a change in the firmware warrants a recompile. As a result, _Build_ is typically only used for checking for compiler-errors, etc. + Furthermore, running _Debug_ and then exiting the debug session has more or less the same effect as running _Run_. -Furthermore, running _Debug_ and then exiting the debug session has more or less the same effect as running _Run_. + - +3. Cleaning the project is often useful for troubleshooting cached errors, etc. It clears the build cache. Go to _Project > Clean ..._ or right-click on the NUSense project under the _Project Explorer_ tab and click _Clean Project_. From d8b44f4661ca39dbd592c6147036e6c6767b4ace Mon Sep 17 00:00:00 2001 From: Claegtun Date: Fri, 19 Dec 2025 16:43:51 +1100 Subject: [PATCH 08/10] Elaborated on importing the project; added non-breaking spaces. --- ...-flashing-firmware-to-NUSense-and-NUFSR.mdx | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx index 1fdaad72..d212719d 100644 --- a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx @@ -30,11 +30,19 @@ The reader needs 2. Start STM32CubeIDE up. -3. It will ask to choose a workspace. Choose the local NUcontroller directory as the workspace and launch. +3. It will ask to choose a workspace. Choose the local _NUcontroller_ directory as the workspace and launch. 4. Once the IDE has been launched, go to _File > Import... > Existing Projects into Workspace_. -5. +5. Select "root directory" and browse for the local _NUcontroller/NUSense_ directory. Make sure that NUSense is selected under _Projects_ and then click _Finish_. + +6. The NUSense CubeIDE project should now be imported. If successful, a project called _NUSense_ should show up on the left pane under the _Project Explorer_ with a blue square icon next to it. Expand it in order to browse the source files. + + + + Most of the meaningful code is under the _Core_ folder which is further split up into _Inc_ for header files and _Src_ for source files. Nearly all NUbots-written firmware are found in the C++ files; all C files are auto-generated by CubeMX. + + ### Connecting to the ST-Link @@ -50,7 +58,7 @@ The reader needs - The ST-Link must connect to the NUSense board through a custom ribbon-cable, not just an ordinary one. It should have a few wires rearranged for the different pin-mapping of the ST-Link. Otherwise, one can connect the ST-Link through a few jumper wires as according to the pin-mapping printed on the ST-Link itself and the NUSense schematic. Along with 3.3 V and ground/0 V, SWDIO maps to TMS, and SWCLK maps to TCK. + The ST-Link must connect to the NUSense board through a custom ribbon-cable, not just an ordinary one. It should have a few wires rearranged for the different pin-mapping of the ST-Link. Otherwise, one can connect the ST-Link through a few jumper wires as according to the pin-mapping printed on the ST-Link itself and the NUSense schematic. Along with 3.3 V and ground/0V , `SWDIO` maps to `TMS`, and `SWCLK` maps to `TCK`. @@ -116,8 +124,8 @@ There are two things for which to watch out when flashing firmware for the first -Sometimes albeit rare, especially if it is the first ever time flashing to a particular chip, the microcontroller needs to be put into _boot_ mode. This is done when the _BOOT0_ pin of the microcontroller is pulled high when it is powered on. On some revisions of the NUSense board, there is a push-button labelled S101; on NUFSR and other revisions of NUSense, there is instead a two-pin header. In order to put the microcontroller into boot mode, either the push-button needs to be held or a jumper wire is connected across the two pins when power is supplied, more specifically 3.3 V. +Sometimes albeit rare, especially if it is the first ever time flashing to a particular chip, the microcontroller needs to be put into _boot_ mode. This is done when the `BOOT0` pin of the microcontroller is pulled high when it is powered on. On some revisions of the NUSense board, there is a push-button labelled `S101`; on NUFSR and other revisions of NUSense, there is instead a two-pin header. In order to put the microcontroller into boot mode, either the push-button needs to be held or a jumper wire is connected across the two pins when power is supplied, more specifically 3.3 V. -Keep in mind that the ST-Link itself supplies 3.3 V, just enough to power the microcontroller and the IMU. So, if flashing with no other power supplied to the board, then unplugging and replugging the ST-Link counts as if power was cycled. +Keep in mind that the ST-Link itself supplies 3.3 V, just enough to power the microcontroller and the IMU. So, if flashing with no other power supplied to the board, then unplugging and replugging the ST-Link counts as if power was cycled. From ea87a31ce55d4f2debe8c189a67b38291b1132dd Mon Sep 17 00:00:00 2001 From: Claegtun Date: Sun, 4 Jan 2026 14:35:33 +1100 Subject: [PATCH 09/10] Changed to the subjunctive mood. --- .../03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx index d212719d..7ea22cb4 100644 --- a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx @@ -126,6 +126,6 @@ There are two things for which to watch out when flashing firmware for the first Sometimes albeit rare, especially if it is the first ever time flashing to a particular chip, the microcontroller needs to be put into _boot_ mode. This is done when the `BOOT0` pin of the microcontroller is pulled high when it is powered on. On some revisions of the NUSense board, there is a push-button labelled `S101`; on NUFSR and other revisions of NUSense, there is instead a two-pin header. In order to put the microcontroller into boot mode, either the push-button needs to be held or a jumper wire is connected across the two pins when power is supplied, more specifically 3.3 V. -Keep in mind that the ST-Link itself supplies 3.3 V, just enough to power the microcontroller and the IMU. So, if flashing with no other power supplied to the board, then unplugging and replugging the ST-Link counts as if power was cycled. +Keep in mind that the ST-Link itself supplies 3.3 V, just enough to power the microcontroller and the IMU. So, if flashing with no other power supplied to the board, then unplugging and replugging the ST-Link counts as if power were cycled. From 371a1ed888d2a912d0862dfeb3b4bada27326c3c Mon Sep 17 00:00:00 2001 From: Claegtun Date: Sun, 4 Jan 2026 14:46:16 +1100 Subject: [PATCH 10/10] Small fixes. --- ...-flashing-firmware-to-NUSense-and-NUFSR.mdx | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx index 7ea22cb4..e3c7fac9 100644 --- a/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx +++ b/src/book/03-guides/03-hardware/05-flashing-firmware-to-NUSense-and-NUFSR.mdx @@ -40,12 +40,14 @@ The reader needs - Most of the meaningful code is under the _Core_ folder which is further split up into _Inc_ for header files and _Src_ for source files. Nearly all NUbots-written firmware are found in the C++ files; all C files are auto-generated by CubeMX. + Most of the meaningful code is under the _Core_ folder which is further split up into _Inc_ for header files and _Src_ for source files. Nearly all the NUbots-written firmware are found in the C++ files; all C files are auto-generated by CubeMX. ### Connecting to the ST-Link +The ST-Link is a physical tool provided by ST to flash the microcontroller. It is usually a USB device that plugs into the computer and connects to the microcontroller through a special protocol, either Serial Wire (SW) or JTAG. It also allows live debugging with breakpoints, etc. + 1. Plug the ST-Link into the computer that is running STM32CubeIDE. @@ -62,7 +64,9 @@ The reader needs -3. In \[STM32\]CubeIDE, go to _Run > Debug Configurations_. Click on _NUSense Debug_ on the left-hand pane; if it is not there, then double-click on _STM32 C/C++ Application_. After that, go to the _Debugger_ tab. The default settings should be left as they are, but make sure that SWD is chosen under the _Interface_ section and check _ST-LINK S/N_. Then click _Scan_. This finds the serial number of the connected ST-Link; make sure that it is chosen in the dropdown. Click _Apply_ and _Close_. +3. In \[STM32\]CubeIDE, go to _Run > Debug Configurations_. Click on _NUSense Debug_ on the left-hand pane; if it is not there, then double-click on _STM32 C/C++ Application_. + +4. After that, go to the _Debugger_ tab. The default settings should be left as they are, but make sure that SWD is chosen under the _Interface_ section and check _ST-LINK S/N_. Then click _Scan_. This finds the serial number of the connected ST-Link; make sure that it is chosen in the dropdown. Click _Apply_ and _Close_. @@ -74,11 +78,11 @@ The reader needs 1. Before flashing, it is a good idea to see the optimiser flags. Go to _Project > Properties > C/C++ Build > Settings_. Depending on your local setup, the dropdown at the top would likely be set as _Debug \[Active\]_ as the _Configuration_; this would do for now. Under the _Tool Settings_ tab, go to _MCU G++ Compiler > Optimization_ and choose the dropdown to whichever optimisation-level that you wish. Here is a quick summary: - - None (`-O0`) — runs without any optimisation, that is with the highest fidelity to the source; - - Optimise for Debug (`-Og`) — runs with as little optimisation as not to get in the way of stepping line by line and accessing variables, watch-expressions, memory, etc. within the debug session — from the perspective of the debugging, should more or less behave like `-O0`; - - Optimise (`-O1`), Optimise more (`-O2`), Optimise most (`-O3`) — runs with general optimisation in increasing degrees; - - Optimise for size (`-Os`) — optimises with a focus on shrinking the amount of memory used; - - Optimise for speed (`-Ofast`) — optimises with a focus on computation-time and was experimentally found to be the quickest for the NUSense firmware. + - _None_ (`-O0`) — runs without any optimisation, that is with the highest fidelity to the source; + - _Optimise_ for Debug (`-Og`) — runs with as little optimisation as not to get in the way of stepping line by line and accessing variables, watch-expressions, memory, etc. within the debug session — from the perspective of the debugging, should more or less behave like `-O0`; + - _Optimise_ (`-O1`), _Optimise more_ (`-O2`), _Optimise most_ (`-O3`) — runs with general optimisation in increasing degrees; + - _Optimise for size_ (`-Os`) — optimises with a focus on shrinking the amount of memory used; + - _Optimise for speed_ (`-Ofast`) — optimises with a focus on computation-time and was experimentally found to be the quickest for the NUSense firmware. The optimisation under _MCU GCC Compiler_ should always be set to `-Ofast` unless you wish to debug the generated C firmware in the Hardware Abstraction Library (HAL).