From 873aa890226385e1142bfb5bab40b782318147f6 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 19 Jun 2025 03:02:00 +1000 Subject: [PATCH] [Docs] Update QGC Bootloader instructions (#25072) * [Docs] Update QGC Bootloader instructions * Add release note --- docs/en/advanced_config/bootloader_update.md | 99 ++++++++++---------- docs/en/releases/main.md | 2 +- 2 files changed, 52 insertions(+), 49 deletions(-) diff --git a/docs/en/advanced_config/bootloader_update.md b/docs/en/advanced_config/bootloader_update.md index a41edfd6d8..ded1300b1b 100644 --- a/docs/en/advanced_config/bootloader_update.md +++ b/docs/en/advanced_config/bootloader_update.md @@ -9,11 +9,45 @@ This topic explains how to build the PX4 bootloader, and several methods for fla ::: info -- Most boards will need to use the [Debug Probe](#debug-probe-bootloader-update) to update the bootloader. +- You can use [QGC Bootloader Update](#qgc-bootloader-update-sys-bl-update) with firmware that includes the [`bl-update` module](../modules/modules_command.md#bl-update). + This is the easiest way to update the bootloader, provided the board is able to load firmware. +- You can also use the [Debug Probe](#debug-probe-bootloader-update) to update the bootloader. + This is useful for updating/fixing the bootloader when the board is bricked. - On [FMUv6X-RT](../flight_controller/pixhawk6x-rt.md) you can [install bootloader/unbrick boards via USB](bootloader_update_v6xrt.md). This is useful if you don't have a debug probe. -- On FMUv2 and some custom firmware (only) you can use [QGC Bootloader Update](#qgc-bootloader-update). - ::: + +::: + +## QGC Bootloader Update (`SYS_BL_UPDATE`) + +The easiest way to update the bootloader is to first use _QGroundControl_ to install firmware that contains the desired/latest bootloader. +You can then initiate bootloader update on next restart by setting the parameter: [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE). + +This approach can be used if the [`bl-update` module](../modules/modules_command.md#bl-update) is present in the firmware. +The easiest way to check this is just to see if the [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE) parameter is [found in QGroundControl](../advanced_config/parameters.md#finding-a-parameter). + +:::warning +Boards that include the module will have the line `CONFIG_SYSTEMCMDS_BL_UPDATE=y` in their `default.px4board` file (for examples [see this search](https://github.com/search?q=repo%3APX4%2FPX4-Autopilot+path%3A**%2Fdefault.px4board+CONFIG_SYSTEMCMDS_BL_UPDATE%3Dy&type=code)). +You can enable this key in your own custom firmware if needed. +::: + +The steps are: + +1. Insert an SD card (enables boot logging to debug any problems). +1. [Update the Firmware](../config/firmware.md#custom) with an image containing the new/desired bootloader. + + ::: info + The updated bootloader might be included the default firmware for your board or supplied in custom firmware. + ::: + +1. Wait for the vehicle to reboot. +1. [Find and enable](../advanced_config/parameters.md) the parameter [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE). +1. Reboot (disconnect/reconnect the board). + The bootloader update will only take a few seconds. + +Generally at this point you may then want to [update the firmware](../config/firmware.md) again using the correct/newly installed bootloader. + +An specific example of this process for updating the [FMUv2 bootloader](#fmuv2-bootloader-update) is given below. ## Building the PX4 Bootloader @@ -49,11 +83,9 @@ The instructions in the repo README explain how to use it. The following steps explain how you can "manually" update the bootloader using a [compatible Debug Probe](../debug/swd_debug.md#debug-probes-for-px4-hardware): 1. Get a binary containing the bootloader (either from dev team or [build it yourself](#building-the-px4-bootloader)). - -1. Get a [Debug Probe](../debug/swd_debug.md#debug-probes-for-px4-hardware). +2. Get a [Debug Probe](../debug/swd_debug.md#debug-probes-for-px4-hardware). Connect the probe your PC via USB and setup the `gdbserver`. - -1. Go into the directory containing the binary and run the command for your target bootloader in the terminal: +3. Go into the directory containing the binary and run the command for your target bootloader in the terminal: - FMUv6X @@ -78,7 +110,7 @@ The following steps explain how you can "manually" update the bootloader using a Bootloaders from [PX4/PX4-Bootloader](https://github.com/PX4/PX4-Bootloader) are named with the pattern `*_bl.elf`. ::: -1. The _gdb terminal_ appears and it should display the following output: +4. The _gdb terminal_ appears and it should display the following output: ```sh GNU gdb (GNU Tools for Arm Embedded Processors 7-2017-q4-major) 8.0.50.20171128-git @@ -98,28 +130,27 @@ The following steps explain how you can "manually" update the bootloader using a Reading symbols from px4fmuv5_bl.elf...done. ``` -1. Find your `` by running an `ls` command in the **/dev/serial/by-id** directory. - -1. Now connect to the debug probe with the following command: +5. Find your `` by running an `ls` command in the **/dev/serial/by-id** directory. +6. Now connect to the debug probe with the following command: ```sh tar ext /dev/serial/by-id/ ``` -1. Power on the Pixhawk with another USB cable and connect the probe to the `FMU-DEBUG` port. +7. Power on the Pixhawk with another USB cable and connect the probe to the `FMU-DEBUG` port. ::: info If using a Dronecode probe you may need to remove the case in order to connect to the `FMU-DEBUG` port (e.g. on Pixhawk 4 you would do this using a T6 Torx screwdriver). ::: -1. Use the following command to scan for the Pixhawk`s SWD and connect to it: +8. Use the following command to scan for the Pixhawk`s SWD and connect to it: ```sh (gdb) mon swdp_scan (gdb) attach 1 ``` -1. Load the binary into the Pixhawk: +9. Load the binary into the Pixhawk: ```sh (gdb) load @@ -127,38 +158,10 @@ The following steps explain how you can "manually" update the bootloader using a After the bootloader has updated you can [Load PX4 Firmware](../config/firmware.md) using _QGroundControl_. -## QGC Bootloader Update - -The easiest approach is to first use _QGroundControl_ to install firmware that contains the desired/latest bootloader. -You can then initiate bootloader update on next restart by setting the parameter: [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE). - -This approach can only be used if [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE) is present in firmware. - -:::warning -Currently only FMUv2 and some custom firmware includes the desired bootloader. -::: - -The steps are: - -1. Insert an SD card (enables boot logging to debug any problems). -1. [Update the Firmware](../config/firmware.md#custom) with an image containing the new/desired bootloader. - - ::: info - The updated bootloader might be supplied in custom firmware (i.e. from the dev team), or it or may be included in the latest main branch. - ::: - -1. Wait for the vehicle to reboot. -1. [Find and enable](../advanced_config/parameters.md) the parameter [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE). -1. Reboot (disconnect/reconnect the board). - The bootloader update will only take a few seconds. - -Generally at this point you may then want to [update the firmware](../config/firmware.md) again using the correct/newly installed bootloader. - -An specific example of this process for updating the FMUv2 bootloader is given below. - -### FMUv2 Bootloader Update +## FMUv2 Bootloader Update If _QGroundControl_ installs the FMUv2 target (see console during installation), and you have a newer board, you may need to update the bootloader in order to access all the memory on your flight controller. +This example explains how you can use [QGC Bootloader Update](qgc-bootloader-update-sys-bl-update) to update the bootloader. ::: info Early FMUv2 [Pixhawk-series](../flight_controller/pixhawk_series.md#fmu_versions) flight controllers had a [hardware issue](../flight_controller/silicon_errata.md#fmuv2-pixhawk-silicon-errata) that restricted them to using 1MB of flash memory. @@ -168,17 +171,17 @@ The problem is fixed on newer boards, but you may need to update the factory-pro To update the bootloader: 1. Insert an SD card (enables boot logging to debug any problems). -1. [Update the Firmware](../config/firmware.md) to PX4 _master_ version (when updating the firmware, check **Advanced settings** and then select **Developer Build (master)** from the dropdown list). +2. [Update the Firmware](../config/firmware.md) to PX4 _master_ version (when updating the firmware, check **Advanced settings** and then select **Developer Build (master)** from the dropdown list). _QGroundControl_ will automatically detect that the hardware supports FMUv2 and install the appropriate Firmware. ![FMUv2 update](../../assets/qgc/setup/firmware/bootloader_update.jpg) Wait for the vehicle to reboot. -1. [Find and enable](../advanced_config/parameters.md) the parameter [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE). -1. Reboot (disconnect/reconnect the board). +3. [Find and enable](../advanced_config/parameters.md) the parameter [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE). +4. Reboot (disconnect/reconnect the board). The bootloader update will only take a few seconds. -1. Then [Update the Firmware](../config/firmware.md) again. +5. Then [Update the Firmware](../config/firmware.md) again. This time _QGroundControl_ should autodetect the hardware as FMUv3 and update the Firmware appropriately. ![FMUv3 update](../../assets/qgc/setup/firmware/bootloader_fmu_v3_update.jpg) diff --git a/docs/en/releases/main.md b/docs/en/releases/main.md index 47e4c6a1bc..29f8b23043 100644 --- a/docs/en/releases/main.md +++ b/docs/en/releases/main.md @@ -40,7 +40,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide). ### Common -- TBD +- [QGroundControl Bootloader Update](../advanced_config/bootloader_update.md#qgc-bootloader-update-sys-bl-update) via the [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE) parameter has been re-enabled after being broken for a number of releases. ([PX4-Autopilot#25032: build: romf: fix generation of rc.board_bootloader_upgrade](https://github.com/PX4/PX4-Autopilot/pull/25032)). ### Control