UAV-develop/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-07-26 16:28:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

[Docs] Update QGC Bootloader instructions (#25072)

Browse Source 
* [Docs] Update QGC Bootloader instructions

* Add release note
This commit is contained in:
Hamish Willee
2025-06-19 03:02:00 +10:00
committed by GitHub
parent 1b3c6f7fd2
commit 873aa89022
2 changed files with 52 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
docs/en/advanced_config/bootloader_update.md
View File

@@ -9,11 +9,45 @@ This topic explains how to build the PX4 bootloader, and several methods for fla
::: info ::: 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). - 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. 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 ## 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): 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 binary containing the bootloader (either from dev team or [build it yourself](#building-the-px4-bootloader)).
2. Get a [Debug Probe](../debug/swd_debug.md#debug-probes-for-px4-hardware).
1. Get a [Debug Probe](../debug/swd_debug.md#debug-probes-for-px4-hardware).
Connect the probe your PC via USB and setup the `gdbserver`. Connect the probe your PC via USB and setup the `gdbserver`.
3. Go into the directory containing the binary and run the command for your target bootloader in the terminal:
1. Go into the directory containing the binary and run the command for your target bootloader in the terminal:
- FMUv6X - 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`. 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 ```sh
GNU gdb (GNU Tools for Arm Embedded Processors 7-2017-q4-major) 8.0.50.20171128-git 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. Reading symbols from px4fmuv5_bl.elf...done.
``` ```
1. Find your `<dronecode-probe-id>` by running an `ls` command in the **/dev/serial/by-id** directory. 5. Find your `<dronecode-probe-id>` by running an `ls` command in the **/dev/serial/by-id** directory.
6. Now connect to the debug probe with the following command:
1. Now connect to the debug probe with the following command:
```sh ```sh
tar ext /dev/serial/by-id/<dronecode-probe-id> tar ext /dev/serial/by-id/<dronecode-probe-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 ::: 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). 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 ```sh
(gdb) mon swdp_scan (gdb) mon swdp_scan
(gdb) attach 1 (gdb) attach 1
``` ```
1. Load the binary into the Pixhawk: 9. Load the binary into the Pixhawk:
```sh ```sh
(gdb) load (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_. After the bootloader has updated you can [Load PX4 Firmware](../config/firmware.md) using _QGroundControl_.
## QGC Bootloader Update ## FMUv2 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
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. 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 ::: 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. 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: To update the bootloader:
1. Insert an SD card (enables boot logging to debug any problems). 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. _QGroundControl_ will automatically detect that the hardware supports FMUv2 and install the appropriate Firmware.
![FMUv2 update](../../assets/qgc/setup/firmware/bootloader_update.jpg) ![FMUv2 update](../../assets/qgc/setup/firmware/bootloader_update.jpg)
Wait for the vehicle to reboot. 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). 3. [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). 4. Reboot (disconnect/reconnect the board).
The bootloader update will only take a few seconds. 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. 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) ![FMUv3 update](../../assets/qgc/setup/firmware/bootloader_fmu_v3_update.jpg)

2
docs/en/releases/main.md
View File

@@ -40,7 +40,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
### Common ### 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 ### Control