fly316/PX4-Autopilot
7
0
Fork 0
mirror of https://gitee.com/mirrors_PX4/PX4-Autopilot.git synced 2026-10-27 05:53:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

Move PX4 Guide source into /docs (#24490)

Browse Source 
* Add vitepress tree

* Update existing workflows so they dont trigger on changes in the docs path

* Add nojekyll, package.json, LICENCE etc

* Add crowdin docs upload/download scripts

* Add docs flaw checker workflows

* Used docs prefix for docs workflows

* Crowdin obvious fixes

* ci: docs move to self hosted runner

runs on a beefy server for faster builds

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: don't run build action for docs or ci changes

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: update runners

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* Add docs/en

* Add docs assets and scripts

* Fix up editlinks to point to PX4 sources

* Download just the translations that are supported

* Add translation sources for zh, uk, ko

* Update latest tranlsation and uorb graphs

* update vitepress to latest

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Hamish Willee
2025-03-13 16:08:27 +11:00
committed by GitHub
co-authored by Ramon Roche
parent 8e6d2ebe4a
commit 88d623bedb
5176 changed files with 558771 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/advanced_config/advanced_flight_controller_orientation_leveling.md
+37
View File
@@ -0,0 +1,37 @@
# Advanced Flight Controller Orientation Tuning
These instructions can be used to manually fine-tune the orientation and horizon level, for example to correct for small sensor board misalignments or minor calibration errors.
If there is a persistent drift bias (often seen in multirotors but not limited to them), it is a good strategy to trim it with the help of these fine-tuning offset angle parameters, instead of using the trimmers of your RC Transmitter.
This ensures the vehicle will maintain the trimming when in fully autonomous flight.
::: info
These instructions are "advanced", and not recommended for regular users (the broad tuning is generally sufficient).
:::
## Setting Orientation Parameters
The [SENS_BOARD_ROT](../advanced_config/parameter_reference.md#SENS_BOARD_ROT) parameter defines the rotation of the flight controller board relative to the vehicle frame, while the fine tuning offsets ([SENS_BOARD_X_OFF](../advanced_config/parameter_reference.md#SENS_BOARD_X_OFF), [SENS_BOARD_Y_OFF](../advanced_config/parameter_reference.md#SENS_BOARD_Y_OFF), [SENS_BOARD_Z_OFF](../advanced_config/parameter_reference.md#SENS_BOARD_Z_OFF)) set the rotation of the sensors relative to the board itself.
The fine tuning offsets are added to the `SENS_BOARD_ROT` angle in order to determine the total offset angles for the Yaw, Pitch and Roll orientation of the flight controller.
First perform the normal calibration for [Flight Controller Orientation](../config/flight_controller_orientation.md) and [Level Horizon Calibration](../config/level_horizon_calibration.md) to set the [SENS_BOARD_ROT](../advanced_config/parameter_reference.md#SENS_BOARD_ROT) parameter.
The other parameters can then be set in order to fine-tune the orientation of the IMU sensors relative to the board itself.
You can locate the parameters in QGroundControl as shown below:
1. Open QGroundControl menu: **Settings > Parameters > Sensor Calibration**.
1. The parameters as located in the section as shown below (or you can search for them):
![FC Orientation QGC v2](../../assets/qgc/setup/sensor/fc_orientation_qgc_v2.png)
## Parameter Summary
- [SENS_BOARD_ROT](../advanced_config/parameter_reference.md#SENS_BOARD_ROT): Rotation of the FMU board relative to the vehicle frame.
- [SENS_BOARD_X_OFF](../advanced_config/parameter_reference.md#SENS_BOARD_X_OFF): Rotation, in degrees, around PX4FMU's X axis or Roll axis.
Positive angles increase in CCW direction, negative angles increase in CW direction.
- [SENS_BOARD_Y_OFF](../advanced_config/parameter_reference.md#SENS_BOARD_Y_OFF): Rotation, in degrees, around PX4FMU's Y axis or Pitch axis.
Positive angles increase in CCW direction, negative angles increase in CW direction.
- [SENS_BOARD_Z_OFF](../advanced_config/parameter_reference.md#SENS_BOARD_Z_OFF): Rotation, in degrees, around PX4FMU's Z axis Yaw axis.
Positive angles increase in CCW direction, negative angles increase in CW direction.
docs/en/advanced_config/bootloader_update.md
+195
View File
@@ -0,0 +1,195 @@
# Bootloader Update
The _PX4 Bootloader_ is used to load firmware for [Pixhawk boards](../flight_controller/pixhawk_series.md) (PX4FMU, PX4IO).
Pixhawk controllers usually comes with an appropriate bootloader version pre-installed.
However in some cases it is not present, or an older version is present that needs to be updated, or the board has been bricked and needs to be erased and the bootloader reinstalled.
This topic explains how to build the PX4 bootloader, and several methods for flashing it to a board.
::: info
- Most boards will need to use the [Debug Probe](#debug-probe-bootloader-update) to update the bootloader.
- 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).
:::
## Building the PX4 Bootloader
### PX4 Bootloader FMUv6X and later
Boards starting with FMUv6X (STM32H7) use the in-tree PX4 bootloader.
This can be built from within the [PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) directory using the `make` command and the board-specific target with a `_bootloader` suffix.
For FMUv6X the command is:
```sh
make px4_fmu-v6x_bootloader
```
This will build the bootloader binary as `build/px4_fmu-v6x_bootloader/px4_fmu-v6x_bootloader.elf`, which can be flashed via SWD or DFU.
If you are building the bootloader you should be familiar with one of these options already.
If you need a HEX file instead of an ELF file, use objcopy:
```sh
arm-none-eabi-objcopy -O ihex build/px4_fmu-v6x_bootloader/px4_fmu-v6x_bootloader.elf px4_fmu-v6x_bootloader.hex
```
### PX4 Bootloader FMUv5X and earlier
PX4 boards up to FMUv5X (before STM32H7) used the [PX4 bootloader](https://github.com/PX4/Bootloader) repository.
The instructions in the repo README explain how to use it.
## Debug Probe Bootloader Update
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).
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:
- FMUv6X
```sh
arm-none-eabi-gdb px4_fmu-v6x_bootloader.elf
```
- FMUv6X-RT
```sh
arm-none-eabi-gdb px4_fmu-v6xrt_bootloader.elf
```
- FMUv5
```sh
arm-none-eabi-gdb px4fmuv5_bl.elf
```
::: info
H7 Bootloaders from [PX4/PX4-Autopilot](https://github.com/PX4/PX4-Autopilot) are named with pattern `*._bootloader.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:
```sh
GNU gdb (GNU Tools for Arm Embedded Processors 7-2017-q4-major) 8.0.50.20171128-git
Copyright (C) 2017 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-linux-gnu --target=arm-none-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
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.
1. Now connect to the debug probe with the following command:
```sh
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.
::: 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:
```sh
(gdb) mon swdp_scan
(gdb) attach 1
```
1. Load the binary into the Pixhawk:
```sh
(gdb) load
```
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
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.
::: 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.
The problem is fixed on newer boards, but you may need to update the factory-provided bootloader in order to install FMUv3 Firmware and access all 2MB available memory.
:::
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).
_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).
The bootloader update will only take a few seconds.
1. 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)
::: info
If the hardware has the [Silicon Errata](../flight_controller/silicon_errata.md#fmuv2-pixhawk-silicon-errata) it will still be detected as FMUv2 and you will see that FMUv2 was re-installed (in console).
In this case you will not be able to install FMUv3 hardware.
:::
## Other Boards (Non-Pixhawk)
Boards that are not part of the [Pixhawk Series](../flight_controller/pixhawk_series.md) will have their own mechanisms for bootloader update.
For boards that are preflashed with Betaflight, see [Bootloader Flashing onto Betaflight Systems](bootloader_update_from_betaflight.md).
docs/en/advanced_config/bootloader_update_from_betaflight.md
+132
View File
@@ -0,0 +1,132 @@
# PX4 Bootloader Flashing onto Betaflight Systems
This page documents how to flash the PX4 bootloader onto boards that are already flashed with Betaflight (e.g. [OmnibusF4 SD](../flight_controller/omnibus_f4_sd.md) or [Kakute F7](../flight_controller/kakutef7.md)).
There are three tools that can be used to flash the PX4 bootloader: _Betaflight Configurator_, [dfu-util](http://dfu-util.sourceforge.net/) command line tool, or the graphical [dfuse](https://www.st.com/en/development-tools/stsw-stm32080.html) (Windows only).
::: info
The _Betaflight Configurator_ is easiest, but newer versions may not support non-betaflight bootloader update.
You might try it first, but use the other methods if firmware update does not work.
:::
## Betaflight Configurator Bootloader Update
::: info
_Betaflight Configurator_ may not support PX4 Bootloader update, as of May 2023.
Older versions should work, though the precise versions are not known.
:::
To install the PX4 bootloader using the _Betaflight Configurator_:
1. Download or build [bootloader firmware](#bootloader-firmware) for the board you want to flash.
1. Download the [Betaflight Configurator](https://github.com/betaflight/betaflight-configurator/releases) for your platform.
:::tip
If using the _Chrome_ web browser, a simple cross-platform alternative is to install the configurator as an [extension from here](https://chrome.google.com/webstore/detail/betaflight-configurator/kdaghagfopacdngbohiknlhcocjccjao).
:::
1. Connect the board to your PC and start the Configurator.
1. Press the **Load Firmware [Local]** button
![Betaflight Configurator - Local Firmware](../../assets/flight_controller/omnibus_f4_sd/betaflight_configurator.jpg)
1. Select the bootloader binary from the file system and then flash the board.
You should now be able to install PX4 firmware on the board.
## DFU Bootloader Update
This section explains how to flash the PX4 bootloader using the [dfu-util](http://dfu-util.sourceforge.net/) or the graphical [dfuse](https://www.st.com/en/development-tools/stsw-stm32080.html) tool (Windows only).
You will first need to download or build [bootloader firmware](#bootloader-firmware) for the board you want to flash (below, this is referred to as `<target.bin>`).
::: info
All of the methods below are safe as the STM32 MCU cannot be bricked!
DFU cannot be overwritten by flashing and will always allow you to install a new firmware, even if flashing fails.
:::
### DFU mode
Both tools require the board to be in DFU mode.
To enter DFU mode, hold the boot button down while connecting the USB cable to your computer.
The button can be released after the board has powered up.
### dfu-util
::: info
The [Holybro Kakute H7 v2](../flight_controller/kakuteh7v2.md), [Holybro Kakute H7](../flight_controller/kakuteh7.md) and [mini](../flight_controller/kakuteh7mini.md) flight controllers may require that you first run an additional command to erase flash parameters (in order to fix problems with parameter saving):
```
dfu-util -a 0 --dfuse-address 0x08000000:force:mass-erase:leave -D build/<target>/<target>.bin
```
The command may generate an error which can be ignored.
Once completed, enter DFU mode again to complete the regular flashing.
:::
To flash the bootloader onto the flight controller:
```
dfu-util -a 0 --dfuse-address 0x08000000 -D build/<target>/<target>.bin
```
Reboot the flight controller and it let it boot without holding the boot button.
### dfuse
The dfuse manual can be found here: https://www.st.com/resource/en/user_manual/cd00155676.pdf
Use the tool to flash the `<target>.bin` file.
## Bootloader Firmware
The tools above flash pre-built bootloader firmware.
Bootloader firmware can be built for most targets using the normal PX4 source code, while other targets can only be build using source in the bootloader repository.
Flight controllers that have bootloader PX4-Autopilot `make` targets, can build the bootloader from the PX4-Autopilot source.
The list of controllers for which this applies can be obtained by running the following `make` command, and noting the `make` targets that end in `_bootloader`
```
$make list_config_targets
...
cuav_nora_bootloader
cuav_x7pro_bootloader
cubepilot_cubeorange_bootloader
holybro_durandal-v1_bootloader
holybro_kakuteh7_bootloader
holybro_kakuteh7v2_bootloader
holybro_kakuteh7mini_bootloader
matek_h743-mini_bootloader
matek_h743-slim_bootloader
modalai_fc-v2_bootloader
mro_ctrl-zero-classic_bootloader
mro_ctrl-zero-h7_bootloader
mro_ctrl-zero-h7-oem_bootloader
mro_pixracerpro_bootloader
px4_fmu-v6u_bootloader
px4_fmu-v6x_bootloader
```
To build for these flight controllers, download and build the [PX4-Autopilot source](https://github.com/PX4/PX4-Autopilot), and then make the target using the following commands:
```sh
git clone --recursive https://github.com/PX4/PX4-Autopilot.git
cd PX4-Autopilot
make <target> # For example: holybro_kakuteh7mini_bootloader
```
For other flight controllers download the [PX4/Bootloader](https://github.com/PX4/Bootloader) repository and build the source code using the appropriate targets:
```
git clone --recursive https://github.com/PX4/Bootloader.git
cd Bootloader
make <target> # For example: omnibusf4sd_bl or kakutef7_bl
```
## Reinstall Betaflight
In order to switch back to _Betaflight_:
1. Backup the PX4 parameters.
You can do this by [exporting](../advanced/parameters_and_configurations.md#exporting-and-loading-parameters) them to an SD card.
1. Keep the **bootloader** button pressed while attaching the USB cable
1. Flash _Betaflight_ as usual with the _Betaflight-configurator_
docs/en/advanced_config/bootloader_update_v6xrt.md
+108
View File
@@ -0,0 +1,108 @@
# Bootloader Update Pixhawk V6X-RT via USB
This topic explains explains to flash [Pixhawk FMUv6X-RT](../flight_controller/pixhawk6x-rt.md) bootloader via USB _without needing a debug probe_.
## Overview
The _PX4 Bootloader_ is used to load firmware for [Pixhawk boards](../flight_controller/pixhawk_series.md) (PX4FMU, PX4IO).
Pixhawk controllers usually comes with an appropriate bootloader version pre-installed.
However in some cases it may not be present, or an older version may be present that needs to be updated.
It is also possible that the device is bricked, so the device has to be erased and a new bootloader must be flashed.
Most flight controllers require a Debug probe in order to update the bootloader, as discussed in [Bootloader Update > Debug Probe Bootloader Update](../advanced_config/bootloader_update.md#debug-probe-bootloader-update).
You can use this approach for the Pixhawk FMUv6X-RT, but if you don't have a debug probe you can use the instructions outlined in this topic instead.
## Building the PX4 FMUv6X-RT Bootloader
This can be built from within the PX4-Autopilot folder using the `make` command and the board-specific target with a `_bootloader` suffix.
For FMUv6X-RT the command is:
```sh
make px4_fmu-v6xrt_bootloader
```
This will build the bootloader binary as `build/px4_fmu-v6xrt_bootloader/px4_fmu-v6xrt_bootloader.bin`, which can be flashed via SWD or ISP.
If you are building the bootloader you should be familiar with one of these options already.
If you need a HEX file instead of an ELF file, use objcopy:
```sh
arm-none-eabi-objcopy -O ihex build/px4_fmu-v6xrt_bootloader/px4_fmu-v6xrt_bootloader.elf px4_fmu-v6xrt_bootloader.hex
```
## Flashing the bootloader through USB
The Pixhawk V6X-RT comes with a build-in bootloader located on the ROM.
To flash a new bootloader through USB you've got to download the [NXP MCUXpresso Secure Provisioning tool](https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/mcuxpresso-secure-provisioning-tool:MCUXPRESSO-SECURE-PROVISIONING).
The tool is available for Windows, Linux and macOS.
1. Install the _MCUXpresso Secure Provisioning_ application and launch the application:
![Flash bootloader through Secure provisioning - Step 1](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step1.png)
1. On first start you have to create a "New Workspace".
Select `i.mX RT11xx` and then select `MIMXRT1176`
![Flash bootloader through Secure provisioning - Step 2](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step2.png)
1. After creating a "New Workspace" click on the **FlexSPI NOR - simplified** button
![Flash bootloader through Secure provisioning - Step 3](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step3.png)
1. On the _Boot Memory Configuration_ window change the "Device type" to `Macronix Octal DDR` and press **OK**.
![Flash bootloader through Secure provisioning - Step 4](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step4.png)
1. On the menu bar select **Tools > Flash Programmer**:
![Flash bootloader through Secure provisioning - Step 5](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step5.png)
1. You should get this pop-up indicating the Pixhawk V6X-RT is not in the "ISP bootloader mode".
![Flash bootloader through Secure provisioning - Step 6](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step6.png)
To get the Pixhawk V6X-RT into "ISP bootloader mode" there are 2 options:
1. Launch QGC connect the Pixhawk select **Analayze Tools** and then **MAVLINK Console**.
On the console type `reboot -i`.
This will put the Pixhawk V6X-RT into "ISP bootloader mode"
![ISP bootloader mode](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_enter_isp_qgc.png)
2. If the board is bricked and connecting to QGC is not possible you've open the FMUM module and press the BOOT button (circled in red in the picture below) while powering the board.
<img src="../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_enter_isp_button.jpg" style="zoom:67%;" />
Press **YES** to launch the _Flash Programmer Tool_.
1. When the Flash Programming has started you get a popup to configure the target memory press **Yes**
![Flash bootloader through Secure provisioning - Step 7](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step7.png)
1. When the Target Memory configuration is succesful you can press the the **Erase All** button
![Flash bootloader through Secure provisioning - Step 8](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step8.png)
1. After erasing the flash press the **Load ...** button and then press the **Browse** button
![Flash bootloader through Secure provisioning - Step 9](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step9.png)
1. Locate the `px4_fmu-v6xrt_bootloader.bin` file and press **Open** and then press on **Load**.
![Flash bootloader through Secure provisioning - Step 10](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step10.png)
1. If the load is successful you should see the "Success: load from file" at the bottom right
![Flash bootloader through Secure provisioning - Step 11](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step11.png)
1. Press the **Write** button to flash the PX4 bootloader
![Flash bootloader through Secure provisioning - Step 12](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step12.png)
1. On success it should show "Success: Write memory 0x30000000 - 0x3XXXXXXX" Note: values might differ due to bootloader changes.
![Flash bootloader through Secure provisioning - Step 13](../../assets/advanced_config/bootloader_6xrt/bootloader_update_v6xrt_step13.png)
Now unplug the Pixhawk V6X-RT and re-power the board.
After the bootloader has updated you can [Load PX4 Firmware](../config/firmware.md) using _QGroundControl_.
docs/en/advanced_config/compass_power_compensation.md
+76
View File
@@ -0,0 +1,76 @@
# Compass Power Compensation
Compasses (magnetometers) should be mounted as far as possible from cables that carry large currents, as these induce magnetic fields that may corrupt the compass readings.
This topic explains how to compensate for the induced magnetic fields in the cases where moving the compass is not realistic.
:::tip
Moving the compass away from power-carrying cables is the easiest and most effective way to fix this issue, because the strength of the magnetic fields decreases quadratically with the distance from the cable.
:::
::: info
The process is demonstrated for a multicopter, but is equally valid for other vehicle types.
:::
<a id="when"></a>
## When is Power Compensation Applicable?
Performing this power compensation is advisable only if all the following statements are true:
1. The compass cannot be moved away from the power-carrying cables.
1. There is a strong correlation between the compass readings and the thrust setpoint, and/or the battery current.
![Corrupted mag](../../assets/advanced_config/corrupted_mag.png)
1. The drone cables are all fixed in place/do not move (calculated compensation parameters will be invalid if the current-carrying cables can move).
<a id="how"></a>
## How to Compensate the Compass
1. Make sure your drone runs a Firmware version supporting power compensation (current master, or releases from v.1.11.0).
1. Perform the [standard compass calibration](../config/compass.md#compass-calibration).
1. Set the parameter [SDLOG_MODE](../advanced_config/parameter_reference.md#SDLOG_MODE) to 2 to enable logging of data from boot.
1. Set the parameter [SDLOG_PROFILE](../advanced_config/parameter_reference.md#SDLOG_PROFILE) checkbox for _Sensor comparison_ (bit 6) to get more data points.
1. Secure the drone so that it cannot move, and attach the propellers (so the motors can draw the same current as in flight).
This example secures the vehicle using straps.
![strap](../../assets/advanced_config/strap.png)
1. Power the vehicle and switch into [ACRO flight mode](../flight_modes_mc/acro.md) (using this mode ensures the vehicle won't attempt to compensate for movement resulting from the straps).
- Arm the vehicle and slowly raise the throttle to the maximum
- Slowly lower the throttle down to zero
- Disarm the vehicle
::: info
Perform the test carefully and closely monitor the vibrations.
:::
1. Retrieve the ulog and use the python script [mag_compensation.py](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/sensors/vehicle_magnetometer/mag_compensation/python/mag_compensation.py) to identify the compensation parameters.
```sh
python mag_compensation.py ~/path/to/log/logfile.ulg <type> [--instance <number>]
```
where:
- `<type>`: `current` or `thrust` (power signal used for compensation)
- `--instance <number>` (optional): The number is `0` (default) or `1`, the instance of the current or thrust signal to use.
::: info
If your log does not contain battery current measurements, you will need to comment out the respective lines in the Python script, such that it does the calculation for thrust only.
:::
1. The script will return the parameter identification for thrust as well as for current and print them to the console.
The figures that pop up from the script show the "goodness of fit" for each compass instance, and how the data would look if compensated with the suggested values.
If a current measurement is available, using the current-compensation usually yields the better results.
Here is an example of a log, where the current fit is good, but the thrust parameters are unusable as the relationship is not linear.
![line fit](../../assets/advanced_config/line_fit.png)
1. Once the parameters are identified, the power compensation must be enabled by setting [CAL_MAG_COMP_TYP](../advanced_config/parameter_reference.md#CAL_MAG_COMP_TYP) to 1 (when using thrust parameters) or 2 (when using current parameters).
Additionally, the compensation parameters for each axis of each compass must be set.
![comp params](../../assets/advanced_config/comp_params.png)
docs/en/advanced_config/esc_calibration.md
+140
View File
@@ -0,0 +1,140 @@
# ESC Calibration
::: info
These instructions are only relevant to [PWM ESCs](../peripherals/pwm_escs_and_servo.md) and [OneShot ESCs](../peripherals/oneshot.md).
[DShot](../peripherals/dshot.md) and [CAN](../can/index.md) ESCs ([DroneCAN](../dronecan/escs.md)/Cyphal) do not require this kind of calibration.
:::
Electronic Speed Controllers (ESCs) regulate motor speed (and direction) based on their input command from the flight controller (FC).
The range of input commands to which an ESC will respond is often configurable, and the default range can differ even between ESCs of the same model.
This calibration updates all the ESCs with a fixed maximum (2000us) and minimum (1000us) PWM input from the flight controller.
Subsequently all the ESCs/motors on the vehicle will respond to flight controller input in the same way, across the whole input range.
Calibration using this tool is recommended for all PWM/OneShot ESCs that support it.
::: info
Calibration is particularly important for low-cost ESC, as they commonly vary a lot in their response to input.
However it is also recommended for high-quality controllers.
Even though these are factory calibrated and should all respond the same way, in practice the input range can differ.
For example if a controller has been manually calibrated after leaving the factory it may no longer behave in the same way.
:::
:::warning
If you want to use an ESC that does not support this calibration, then it must be factory calibrated and respond consistently out of the box.
This should be verified using [Actuator Testing](../config/actuators.md#actuator-testing).
Jump to the [actuator configuration step (7)](#actuatorconfig_step) (which is still important).
:::
OneShot ESCs should be [configured to use OneShot](../peripherals/oneshot.md#px4-configuration) before calibration. You should calibrate the ESCs after switching, even if you have previously calibrated.
## Preconditions
The calibration sequence requires that you are able keep the flight controller powered while manually power-cyling the ESCs.
If using a Pixhawk flight controller, the recommended way to do this is to separately power the flight controller via USB, and connect/disconnect the battery to power the ESCs when needed.
Flight control systems that can't power the autopilot via USB will need a [different approach](#problem_power_module).
If the battery is connected via a power module the calibration procedure can detect the battery connection and use it to drive the calibration sequence.
If battery power can't be detected the calibration sequence is performed based on timeouts.
## Steps
To calibrate the ESCs:
1. Remove the propellers.
:::warning
Never attempt ESC calibration with propellers on!
The motors _should_ not spin during ESC calibration.
However if calibration starts when the ESC is already powered, or if the ESC doesn't properly support/detect the calibration sequence, then it will respond to the PWM input by running the motor at maximum speed.
:::
1. Map the ESCs you're calibrating as motors in the vehicle's [Actuator Configuration](../config/actuators.md).
Only mapped actuators get an output and only ESCs mapped as motors will be calibrated.
1. Unpower the ESCs by unplugging the battery.
The flight controller must stay powered, for example, by keeping the USB connected to the ground station.
1. Open the _QGroundControl_ **Settings > Power**, then press the **Calibrate** button.
![ESC Calibration step 1](../../assets/qgc/setup/esc/qgc_esc_calibration.png)
1. After starting the calibration sequence without error, directly power the ESCs (you should be prompted):
![ESC Calibration step 2](../../assets/qgc/setup/esc/esc_calibration_step_2.png)
The calibration will begin automatically:
![ESC Calibration step 3](../../assets/qgc/setup/esc/esc_calibration_step_3.png)
1. During the calibration you should hear model-specific beeping from the ESC, which indicates the individual steps of the calibration.
You will be prompted when the calibration completes.
<a id="actuatorconfig_step"></a>
![ESC Calibration step 4](../../assets/qgc/setup/esc/esc_calibration_step_4.png)
1. Go back to the [Actuator Configuration](../config/actuators.md) section.
Following ESC calibration all motors with the same (re)calibrated ESCs should behave in the same way for the same inputs. The default PWM settings for motor outputs in the actuator configuration should now work out of the box.
You need to confirm that the motors do indeed work correctly.
Since the default configuration values have been set conservatively, you may also wish to tune them for your particular ESCs.
::: info
The steps below are similar to those described in [Actuator Configuration > Motor Configuration](../config/actuators.md#motor-configuration).
:::
Verify the following values:
- The minimum value for a motor (default: `1100us`) should make the motor spin slowly but reliably, and also spin up reliably after it was stopped.
You can confirm that a motor spins at minimum (still without propellers) in [Actuator Testing](../config/actuators.md#actuator-testing), by enabling the sliders, and then moving the test output slider for the motor to the first snap position from the bottom.
The correct value should make the motor spin immediately and reliably as you move the slider from disarmed to minimum.
To find the "optimal" minimum value, move the slider to the bottom (disarmed).
Then increase the PWM output's `disarmed` setting in small increments (e.g. 1025us, 1050us, etc), until the motor starts to spin reliably (it is better to be a little too high than a little too low).
Enter this value into the `minimum` setting for all the motor PWM outputs, and restore the `disarmed` output to `1100us`.
- The maximum value for a motor (default: `1900us`) should be chosen such that increasing the value doesn't make the motor spin any faster.
You can confirm that the motor spins quickly at the maximum setting in [Actuator Testing](../config/actuators.md#actuator-testing), by moving the associated test output slider to the top position.
To find the "optimal" maximum value, first move the slider to the bottom (disarmed).
Then increase the PWM output's `disarmed` setting to near the default maximum (`1900`) - the motors should spin up.
Listen to the tone of the motor as you increase the PWM maximum value for the output in increments (e.g. 1925us, 1950us, etc).
The optimal value is found at the point when the sound of the motors does not change as you increase the value of the output.
Enter this value into the `maximum` setting for all the motor PWM outputs, and restore the `disarmed` output to `1100us`.
- The disarmed value for a motor (default: `1000us`) should make the motor stop and stay stopped.
You can confirm this in [Actuator Testing](../config/actuators.md#actuator-testing) by moving the test output slider to the snap position at the bottom of the slider and observing that the motor does not spin.
If the ESC spins with the default value of 1000us then the ESC is not properly calibrated.
If using an ESC that can't be calibrated, you should reduce the PWM output value for the output to below where the motor does not spin anymore (such as 950us or 900us).
::: info
VTOL and fixed-wing motors do not need any special PWM configuration.
With the default PWM configuration they will automatically stop during flight when commanded by the autopilot.
:::
## Troubleshooting
1. Calibration can state that it has succeeded even when it has failed.
This happens if you do not power the ESC at the right time, or the ESCs don't support calibration.
This occurs because PX4 has no feedback from the ESC to know whether or not calibration was successful.
You have to rely on interpreting the beeps during the calibration and subsequent motor tests to know for sure that the calibration worked.
<a id="problem_power_module"></a>
1. Calibration cannot be started if you have a power module configured and connected (for safety reasons).
Unplug power to the ESCs first.
If you're blocked because a power module is necessary to keep your flight controller alive, but you can (un)power the ESCs separately, you can temporarily disable the detection of the power module just for the ESC calibration using the parameters [BATn_SOURCE](../advanced_config/parameter_reference.md#BAT1_SOURCE). Once the power module that's powering the autopilot is not detected as battery anymore a timing based calibration is possible.
1. PX4 will abort calibration (for safety reasons) if the system detects an increase in current consumption immediately after initiating calibration.
This requires a power module.
docs/en/advanced_config/ethernet_setup.md
+267
View File
@@ -0,0 +1,267 @@
# PX4 Ethernet Setup
Ethernet connectivity provides a fast, reliable, and flexible communication alternative to using USB or other serial connections.
It can be used to connect to ground stations, companion computers, and other MAVLink systems.
It is particularly recommended when connecting to systems that "natively" use Ethernet - for example IP radios.
This topic covers:
- [PX4 Ethernet Setup](#px4-ethernet-setup)
- [Supported Flight Controllers](#supported-flight-controllers)
- [Setting up the Ethernet Network](#setting-up-the-ethernet-network)
- [PX4 Ethernet Network Setup](#px4-ethernet-network-setup)
- [Ubuntu Ethernet Network Setup](#ubuntu-ethernet-network-setup)
- [Companion Computer Ethernet Network Setup](#companion-computer-ethernet-network-setup)
- [PX4 MAVLink Serial Port Configuration](#px4-mavlink-serial-port-configuration)
- [QGroundControl Setup Example](#qgroundcontrol-setup-example)
- [MAVSDK-Python Setup Example](#mavsdk-python-setup-example)
- [ROS 2 Setup Example](#ros-2-setup-example)
## Supported Flight Controllers
PX4 supports Ethernet connectivity on [Pixhawk 5X-standard](https://github.com/pixhawk/Pixhawk-Standards/blob/master/DS-011%20Pixhawk%20Autopilot%20v5X%20Standard.pdf) flight controllers (and later) that have an Ethernet port.
It may also be supported on other boards.
Supported flight controllers include:
- [CUAV Pixhawk V6X](../flight_controller/cuav_pixhawk_v6x.md)
- [Holybro Pixhawk 5X](../flight_controller/pixhawk5x.md)
- [Holybro Pixhawk 6X](../flight_controller/pixhawk6x.md)
- [RaccoonLab FMUv6X Autopilot](../flight_controller/raccoonlab_fmu6x.md)
## Setting up the Ethernet Network
To connect systems over Ethernet you need to configure them to run on the same IP network, so that each system has a unique IP address and can find the other systems.
This might be done using a DHCP server to allocate addresses, or by manually configuring the addresses of each system on the network.
There is no single "out of the box configuration" that we can provide that will necessarily work in your local network.
Therefore as an example of the kind of configuration you might do, below we show how to set up the systems on an IP network with static addresses in the range `10.41.10.Xxx`, where PX4 has a statically allocated address `10.41.10.2` (PX4-default) and the computer has address `10.41.10.1`.
If you wanted to connect a companion computer or other system to the network you could use a similar approach to allocate a static address.
::: info
There is nothing "special" about the network configuration (other than perhaps the tools used to modify the network settings); it works much the same as any home or business network.
Which is to say that a knowledge of how IP networks work is highly desirable!
:::
### PX4 Ethernet Network Setup
<!-- Information about NuttX network manager: https://github.com/PX4/PX4-Autopilot/pull/16330 -->
PX4 uses the [netman](../modules/modules_system.md#netman) module to apply and update network settings.
The default configuration first requests an IP address from DHCP, and if that fails will fallback to the default static address `10.41.10.2`.
You can explicitly set any static IP address (including the default address), to bypass the initial DHCP check and make the connection a little faster.
::: info
If you want to use the default static IP address for PX4 you can skip forward to the next section.
:::
Network settings are defined in the configuration file `/fs/microsd/net.cfg` on the SD card.
This is a text file, that defines each setting on a new line as a `name=value` pair.
A configuration file might look like this:
```ini
DEVICE=eth0
BOOTPROTO=fallback
IPADDR=10.41.10.2
NETMASK=255.255.255.0
ROUTER=10.41.10.254
DNS=10.41.10.254
```
Where the values are:
- `DEVICE`: Interface name. Default is `eth0`.
- `BOOTPROTO`: Protocol for getting PX4 IP address. Valid values for proto are: `dhcp`, `static`, `fallback` (use DHCP but fall back to static address after time, if that fails)
- `IPADDR`: Static IP address (used if BOOTPROTO is `static` or `fallback`)
- `NETMASK`: Network mask
- `ROUTER`: The address of the default route.
- `DNS`: The address of the DNS server.
To set the above "example" configuration using the _QGroundControl_:
1. Connect the flight controller to the computer with the USB cable.
1. Open **QGroundcontrol > Analyze Tools > MAVLink Console**
1. Enter commands "like" the ones below into the _MAVLink Console_ (to write the values to the configuration file):
```sh
echo DEVICE=eth0 > /fs/microsd/net.cfg
echo BOOTPROTO=fallback >> /fs/microsd/net.cfg
echo IPADDR=10.41.10.2 >> /fs/microsd/net.cfg
echo NETMASK=255.255.255.0 >>/fs/microsd/net.cfg
echo ROUTER=10.41.10.254 >>/fs/microsd/net.cfg
echo DNS=10.41.10.254 >>/fs/microsd/net.cfg
```
1. Once the network configuration has been set you can disconnect the USB cable.
1. Reboot the flight controller to apply the settings.
Note that the above setup gives the flight controller an address on the Ethernet network.
You also need to [configure the Ethernet port](#px4-mavlink-serial-port-configuration) to use MAVLink.
### Ubuntu Ethernet Network Setup
If you're using Ubuntu for your ground station (or companion computer) then you can use [netplan](https://netplan.io/) to configure the network.
Below we show how you write a setup to the netplan configuration file "`/etc/netplan/01-network-manager-all.yaml`", which would run on the same network as used by the PX4 setup above.
Note that there are many more [examples](https://netplan.io/examples/) and instructions in the [netplan](https://netplan.io/) documentation.
To setup the Ubuntu Computer:
1. In a terminal, create and open a `netplan` configuration file: `/etc/netplan/01-network-manager-all.yaml`
Below we do this using the _nano_ text editor.
```
sudo nano /etc/netplan/01-network-manager-all.yaml
```
1. Copy and paste the following configuration information into the file (note: the indentations are important!):
```
network:
version: 2
renderer: NetworkManager
ethernets:
enp2s0:
addresses:
- 10.41.10.1/24
nameservers:
addresses: [10.41.10.1]
routes:
- to: 10.41.10.1
via: 10.41.10.1
```
Save and exit the editor.
1. Apply the _netplan_ configuration by entering the following command into the Ubuntu terminal.
```
sudo netplan apply
```
### Companion Computer Ethernet Network Setup
The setup for a companion computer will depend on the companion computer's operating system.
A Linux operating system may support `netplan`, in which case the instructions would be the same as above, but using a unique IP address.
## PX4 MAVLink Serial Port Configuration
The Ethernet port configuration sets the properties of the _serial link_ (which is how PX4 views the Ethernet connection).
This includes the set of MAVLink messages that are streamed, the data rate, the UDP ports that a remote system can connect listen to, etc.
::: info
You must separately configure the PX4 IP address and other _network settings_ ([as shown previously](#px4-ethernet-network-setup)).
:::
PX4 configures the serial port to connect to a GCS via MAVLink, using the parameters shown below:
| Parameter | Value | Description |
| ------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------ |
| [MAV_2_CONFIG](../advanced_config/parameter_reference.md#MAV_2_CONFIG) | 1000 | Configure Ethernet port |
| [MAV_2_BROADCAST](../advanced_config/parameter_reference.md#MAV_2_BROADCAST) | 1 | Broadcast `HEARTBEAT` messages |
| [MAV_2_MODE](../advanced_config/parameter_reference.md#MAV_2_MODE) | 0 | Send the "normal" set of MAVLink messages (i.e. the GCS set) |
| [MAV_2_RADIO_CTL](../advanced_config/parameter_reference.md#MAV_2_RADIO_CTL) | 0 | Disable software throttling of MAVLink traffic |
| [MAV_2_RATE](../advanced_config/parameter_reference.md#MAV_2_RATE) | 100000 | Maximum sending rate |
| [MAV_2_REMOTE_PRT](../advanced_config/parameter_reference.md#MAV_2_REMOTE_PRT) | 14550 | MAVLink Remote Port of 14550 (GCS) |
| [MAV_2_UDP_PRT](../advanced_config/parameter_reference.md#MAV_2_UDP_PRT) | 14550 | MAVLink Network Port of 14550 (GCS) |
Normally a companion computer would use port `14540` (rather than `14550`) and stream the set of MAVLink messages specified in the `Onboard` profile.
You can configure this setup by changing [MAV_2_REMOTE_PRT](../advanced_config/parameter_reference.md#MAV_2_REMOTE_PRT) and [MAV_2_UDP_PRT](../advanced_config/parameter_reference.md#MAV_2_UDP_PRT) to `14540` and [MAV_2_MODE](../advanced_config/parameter_reference.md#MAV_2_MODE) to `2` (Onboard).
Note however that this will still work using the GCS profile.
For more information on MAVLink serial port configuration see [MAVLink Peripherals (GCS/OSD/Companion)](../peripherals/mavlink_peripherals.md)
## QGroundControl Setup Example
Assuming you have already [Set up the Ethernet Network](#setting-up-the-ethernet-network) so your ground station computer and PX4 run on the same network, and
To connect QGroundControl to PX4 over Ethernet:
1. [Set up the Ethernet Network](#setting-up-the-ethernet-network) so your ground station computer and PX4 run on the same network.
1. Connect the ground station computer and PX4 using an Ethernet cable.
1. Start QGroundControl and [define a comm link](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/settings_view/settings_view.html) (**Application Settings > Comm Links**) specifying the _server address_ and port as the IP address and port assigned in PX4, respectively.
Assuming that the values are set as described in the rest of this topic the setup will look like this:
![QGC comm link for ethernet setup](../../assets/qgc/settings/comm_link/px4_ethernet_link_config.png)
1. QGroundControl should then connect if you select this link.
::: info
[PX4 Ethernet Port Configuration](#px4-ethernet-network-setup) should not be needed (the default are appropriate for a GCS).
:::
## MAVSDK-Python Setup Example
To setup MAVSDK-Python running on a companion computer:
1. [Set up the Ethernet Network](#setting-up-the-ethernet-network) so your companion computer and PX4 run on the same network.
1. Modify the [PX4 Ethernet Port Configuration](#px4-ethernet-network-setup) to connect to a companion computer.
You might change the parameters [MAV_2_REMOTE_PRT](../advanced_config/parameter_reference.md#MAV_2_REMOTE_PRT) and [MAV_2_UDP_PRT](../advanced_config/parameter_reference.md#MAV_2_UDP_PRT) to `14540`, and [MAV_2_MODE](../advanced_config/parameter_reference.md#MAV_2_MODE) to `2` (Onboard).
1. Follow the instructions in [MAVSDK-python](https://github.com/mavlink/MAVSDK-Python) to install and use MAVSDK.
For example, your code will connect to the PX4 using:
```python
await drone.connect(system_address="udp://10.41.10.2:14540")
```
::: info
MAVSDK can connect to the PX4 on port `14550` if you don't modify the PX4 Ethernet port configuration.
However this is not recommended because the default configuration is optimised for communicating with a GCS (not a companion computer).
:::
## ROS 2 Setup Example
::: info Prerequisites:
- You have a supported autopilot hardware running PX4 firmware that includes [uXRCE-DDS](../middleware/uxrce_dds.md) middleware.
Note that PX4 v1.14 and later include the required [uxrce_dds_client](../modules/modules_system.md#uxrce-dds-client) module by default.
- [ROS 2](../ros2/user_guide.md) has been set up correctly on the companion computer.
- You have followed the Ethernet network and port setup as discussed at the top of this page.
:::
To set up ROS 2:
1. Connect your flight controller and companion computer via Ethernet.
2. [Start the uXRCE-DDS client on PX4](../middleware/uxrce_dds.md#starting-the-client), either manually or by customizing the system startup script.
Note that you must use the IP address of the companion computer and the UDP port on which the agent is listening (the example configuration above sets the companion IP address to `10.41.10.1`, and the agent UDP port is set to `8888` in the next step).
3. [Start the micro XRCE-DDS agent on the companion computer](../middleware/uxrce_dds.md#starting-the-agent).
For example, enter the following command in a terminal to start the agent listening on UDP port `8888`.
```sh
MicroXRCEAgent udp4 -p 8888
```
4. Run a [listener node](../ros2/user_guide.md#running-the-example) in a new terminal to confirm the connection is established:
```sh
source ~/ws_sensor_combined/install/setup.bash
ros2 launch px4_ros_com sensor_combined_listener.launch.py
```
If everything is setup correctly, the following output should be displayed in the terminal:
```sh
RECEIVED SENSOR COMBINED DATA
=============================
ts: 855801598
gyro_rad[0]: -0.00339938
gyro_rad[1]: 0.00440091
gyro_rad[2]: 0.00513893
gyro_integral_dt: 4997
accelerometer_timestamp_relative: 0
accelerometer_m_s2[0]: -0.0324082
accelerometer_m_s2[1]: 0.0392213
accelerometer_m_s2[2]: -9.77914
accelerometer_integral_dt: 4997
```
## See Also
- [Get The Pixhawk Raspberry Pi CM4 Baseboard By Holybro Talking With PX4](https://px4.io/get-the-pixhawk-raspberry-pi-cm4-baseboard-by-holybro-talking-with-px4/) (px4.io blog):
- Tutorial showing how to connect Pixhawk 6X + Raspberry Pi on CM4 baseboard via wired Ethernet.
- Blog dupliciates a lot of material from this topic.
docs/en/advanced_config/flight_termination.md
+76
View File
@@ -0,0 +1,76 @@
# Flight Termination Configuration
The _Flight termination_ [failsafe action](../config/safety.md#failsafe-actions) may be triggered by a [safety check](../config/safety.md) (e.g. RC Loss, geofence violation, etc. on any vehicle type or in any flight mode), or by the [Failure Detector](../config/safety.md#failure-detector).
::: info
Flight termination may also be triggered from a ground station or companion computer using the MAVLink [MAV_CMD_DO_FLIGHTTERMINATION](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_FLIGHTTERMINATION) command.
This is sent, for example, when you call the [MAVSDK Action plugin](https://mavsdk.mavlink.io/main/en/cpp/api_reference/classmavsdk_1_1_action.html#classmavsdk_1_1_action_1a47536c4a4bc8367ccd30a92eb09781c5) `terminate()` or `terminate_async()` methods.
:::
When _Flight termination_ is activated, PX4 simultaneously turns off all controllers and sets all PWM outputs to their failsafe values.
Depending on what devices are connected, the PWM failsafe outputs can be used to:
- Deploy a [parachute](../peripherals/parachute.md).
- Extend retractable landing gear.
- Move a PWM-connected gimbal to a safe orientation (or retract it) in order to protect the camera.
- Trigger an inflatable device like an airbag.
- Trigger an alarm.
There is no way to recover from flight termination.
After triggering you should unplug the battery as soon as possible.
You will need to reboot/power cycle the vehicle before it can be used again.
:::tip
PX4 does not know what safety devices are attached - it just applies a predefined set of PWM values to its outputs.
:::
:::tip
Failsafe values are applied to all outputs on termination.
There is no way to configure independent time-based (or other) triggering of the motors or specific safety devices.
:::
::: info
This is _not_ an independent _Flight Termination System_.
If power is lost or if the autopilot crashes completely, the failsafe devices will not be triggered.
:::
## Hardware Configuration
Any _safety device(s)_ (e.g. a [parachute](../peripherals/parachute.md)) that can be triggered by changing a PWM value can be used, and may be connected to any free PWM port (both MAIN and AUX).
::: info
If you're using Pixhawk-series board you will have to separately power the servo rail (i.e. from a 5V BEC, which is often also available from your ESC).
:::
## Software Configuration
The [Safety](../config/safety.md) topic explains how to set the _flight termination_ as the [failsafe action](../config/safety.md#failsafe-actions) to be performed for particular failsafe check.
The [Failure Detector](../config/safety.md#failure-detector) can also (optionally) be configured to trigger flight termination if the vehicle flips (exceeds a certain attitude) or if failure is detected by an external automatic trigger system (ATS):
- Enable the failure detector during flight by setting [CBRK_FLIGHTTERM=0](../advanced_config/parameter_reference.md#CBRK_FLIGHTTERM).
- [Safety > Failure Detector > Attitude Trigger](../config/safety.md#attitude-trigger) explains how to configure the attitude limits that trigger _Flight termination_.
::: info
During _takeoff_ excessive attitutes will trigger _lockdown_ (kill motors, but not launch parachute) rather than flight termination.
This is always enabled, irrespective of the value of `CBRK_FLIGHTTERM`.
:::
- [Safety > External Automatic Trigger System (ATS)](../config/safety.md#external-automatic-trigger-system-ats) explains how to configure an external trigger system.
For each MAIN output to which a safety device is attached, where "n" is the PWM port number, set:
- [PWM_MAIN_DISn](../advanced_config/parameter_reference.md#PWM_MAIN_DIS1) to the device's "OFF" PWM value.
- [PWM_MAIN_FAILn](../advanced_config/parameter_reference.md#PWM_MAIN_FAIL1) to the device's "ON" PWM value.
For each AUX output to which a safety device is attached, where "n" is the PWM port number, set:
- [PWM_AUX_DIS1](../advanced_config/parameter_reference.md#PWM_AUX_DIS1) to the device's "OFF" PWM value.
- [PWM_AUX_FAILn](../advanced_config/parameter_reference.md#PWM_AUX_FAIL1) to the device's "ON" PWM value.
Finally, set the `PWM_AUX_FAILn` and `PWM_MAIN_FAILn` PWM values for any motors.
## Logic Diagram
The diagram below shows the logical flow around flight termination.
![Logic diagram](../../assets/config/flight_termination_logic_diagram.png)
docs/en/advanced_config/imu_factory_calibration.md
+34
View File
@@ -0,0 +1,34 @@
# IMU/Compass Factory Calibration
PX4 OEM manufacturers can perform an IMU and compass factory calibration in order to store values for the accelerometer, gyroscope and magnetometer calibration into persistent storage (usually EEPROM).
This ensures that end users can always reset vehicle configurations and tuning to a safe state for flying.
This procedure will write the following parameters to `/fs/mtd_caldata`: [CAL_ACC\*](../advanced_config/parameter_reference.md#CAL_ACC0_ID), [CAL_GYRO\*](../advanced_config/parameter_reference.md#CAL_GYRO0_ID), [CAL_MAG\*](../advanced_config/parameter_reference.md#CAL_MAG0_ID).
This data will then be used when the parameters are set (or reset) to their default values.
:::warning
This feature relies on the FMU having a dedicated EEPROM chip or an accompanying IMU PCBA that has sufficient space for the data.
PX4 will store the data to `/fs/mtd_caldata`, creating the file if necessary.
:::
::: info
These values cannot be stored in the [frame configuration](../dev_airframes/adding_a_new_frame.md) because they vary from device to device (the frame configuration defines the set of parameters that are applicable across all vehicles of the same type, such as the enabled sensors, [autopilot rotation](../config/flight_controller_orientation.md) and PID tuning).
:::
## Performing the Factory Calibration
1. Set the parameter [SYS_FAC_CAL_MODE](../advanced_config/parameter_reference.md#SYS_FAC_CAL_MODE) to 1.
1. Perform all IMU calibrations: [accelerometer](../config/accelerometer.md#performing-the-calibration), [gyroscope](../config/gyroscope.md#performing-the-calibration) and [magnetometer](../config/compass.md#performing-the-calibration).
1. Reboot the vehicle.
This will write all `CAL_ACC*`, `CAL_GYRO*` and `CAL_MAG*` parameters into `/fs/mtd_caldata`.
1. Set the parameter `SYS_FAC_CAL_MODE` back to 0 (default).
::: info
If you only want to factory calibrate the accelerometer and the gyroscope you can set [SYS_FAC_CAL_MODE](../advanced_config/parameter_reference.md#SYS_FAC_CAL_MODE) to 2, in which case the magnetometer is omitted.
:::
Subsequent user calibrations will then take effect as usual (factory calibration data is only used for the parameter default values).
## Further Information
- [QGroundControl User Guide > Sensors](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/sensors_px4.html)
docs/en/advanced_config/index.md
+44
View File
@@ -0,0 +1,44 @@
# Advanced Configuration
This topic lists configuration topics that are not particularly vehicle specific, for features that are more rarely modified, or that are specific only to manufacturers/OEMs.
## Parameters
- [Finding/Updating Parameters](../advanced_config/parameters.md)
- [Full Parameter Reference](../advanced_config/parameter_reference.md)
## Feature configuration
- [Using PX4's Navigation Filter (EKF2)](../advanced_config/tuning_the_ecl_ekf.md)
- [Flight Termination Configuration](../advanced_config/flight_termination.md)
- [Land Detector Configuration](../advanced_config/land_detector.md)
- [Prearm/Arm/Disarm Configuration](../advanced_config/prearm_arm_disarm.md)
## OEM/Factory Calibration
- [IMU Factory Calibration](../advanced_config/imu_factory_calibration.md)
- [Sensor Thermal Compensation](../advanced_config/sensor_thermal_calibration.md)
- [Compass Power Compensation](../advanced_config/compass_power_compensation.md)
- [Advanced Controller Orientation](../advanced_config/advanced_flight_controller_orientation_leveling.md)
- [Static Pressure Buildup](../advanced_config/static_pressure_buildup.md)
## Serial port/Ethernet configuration
- [Serial Port Configuration](../peripherals/serial_configuration.md)
- [MAVLink Telemetry (OSD/GCS)](../peripherals/mavlink_peripherals.md)
- [PX4 Ethernet Setup](../advanced_config/ethernet_setup.md)
## Miscellaneous
- [Bootloader Update](../advanced_config/bootloader_update.md)
- [Bootloader Update FMUv6X-RT via USB](../advanced_config/bootloader_update_v6xrt.md)
## See Also
- [Standard Configuration](../config/index.md) - Setup essential sensors/features needed for most PX4 vehicles.
- [Flight Controller Peripherals](../peripherals/index.md) - Setup specific sensors, optional sensors, actuators, and so on.
- Vehicle Config/Tuning:
- [Multicopter Config/Tuning](../config_mc/index.md)
- [Helicopter Config/Tuning](../config_heli/index.md)
- [Fixed-wing Config/Tuning](../config_fw/index.md)
- [VTOL Config/Tuning](../config_vtol/index.md)
docs/en/advanced_config/land_detector.md
+98
View File
@@ -0,0 +1,98 @@
# Land Detector Configuration
The land detector is a dynamic vehicle model representing key vehicle states from ground contact through to landed.
This topic explains the main parameters you may wish to tune in order to improve landing behaviour.
## Auto-Disarming
The land-detector automatically disarms the vehicle on landing.
You can set [COM_DISARM_LAND](../advanced_config/parameter_reference.md#COM_DISARM_LAND) to specify the number of seconds after landing that the system should disarm (or turn off auto-disarming by setting the parameter to -1).
## Multicopter Configuration
The complete set of relevant landing detector parameters are listed in the parameter reference with the prefix [LNDMC](../advanced_config/parameter_reference.md#land-detector) (these can be edited in QGroundControl via the [parameter editor](../advanced_config/parameters.md)).
:::tip
Information about how the parameters affect landing can be found below in [Land Detector States](#mc-land-detector-states).
:::
Other key parameters that you may need to tune in order to improve landing behaviour on particular airframes are:
- [MPC_THR_HOVER](../advanced_config/parameter_reference.md#MPC_THR_HOVER) - the hover throttle of the system (default is 50%).
It is important to set this correctly as it makes altitude control more accurate and ensures correct land detection.
A racer or a big camera drone without payload mounted might need a much lower setting (e.g. 35%).
::: info
Incorrectly setting `MPC_THR_HOVER` may result in ground-contact or maybe-landed detection while still in air (in particular, while descending in [Position mode](../flight_modes_mc/position.md) or [Altitude mode](../flight_modes_mc/altitude.md)).
This causes the vehicle to "twitch" (turn down the motors, and then immediately turn them back up).
:::
- [MPC_THR_MIN](../advanced_config/parameter_reference.md#MPC_THR_MIN) - the overall minimum throttle of the system.
This should be set to enable a controlled descent.
- [MPC_LAND_CRWL](../advanced_config/parameter_reference.md#MPC_LAND_CRWL) - the vertical speed applied in the last stage of autonomous landing if the system has a distance sensor and it is present and working. Has to be set larger than LNDMC_Z_VEL_MAX.
### MC Land Detector States
In order to detect landing, the multicopter first has to go through three different states, where each state contains the conditions from the previous states plus tighter constraints.
If a condition cannot be reached because of missing sensors, then the condition is true by default.
For instance, in [Acro mode](../flight_modes_mc/acro.md) and no sensor is active except for the gyro sensor, then the detection solely relies on thrust output and time.
In order to proceed to the next state, each condition has to be true for a third of the configured total land detector trigger time [LNDMC_TRIG_TIME](../advanced_config/parameter_reference.md#LNDMC_TRIG_TIME).
If the vehicle is equipped with a distance sensor, but the distance to ground is currently not measurable (usually because it is too large), the trigger time is increased by a factor of 3.
If one condition fails, the land detector drops out of the current state immediately.
#### Ground Contact
Conditions for this state:
- no vertical movement ([LNDMC_Z_VEL_MAX](../advanced_config/parameter_reference.md#LNDMC_Z_VEL_MAX))
- no horizontal movement ([LNDMC_XY_VEL_MAX](../advanced_config/parameter_reference.md#LNDMC_XY_VEL_MAX))
- lower thrust than [MPC_THR_MIN](../advanced_config/parameter_reference.md#MPC_THR_MIN) + (hover throttle - [MPC_THR_MIN](../advanced_config/parameter_reference.md#MPC_THR_MIN)) \* (0.3, unless a hover thrust estimate is available, then 0.6),
- additional check if vehicle is currently in a height-rate controlled flight mode: the vehicle has to have the intent to descend (vertical velocity setpoint above LNDMC_Z_VEL_MAX).
- additional check for vehicles with a distance sensor: current distance to ground is below 1m.
If the vehicle is in position- or velocity-control and ground contact was detected,
the position controller will set the thrust vector along the body x-y-axis to zero.
#### Maybe Landed
Conditions for this state:
- all conditions of the [ground contact](#ground-contact) state are true
- is not rotating ([LNDMC_ROT_MAX](../advanced_config/parameter_reference.md#LNDMC_ROT_MAX))
- has low thrust `MPC_THR_MIN + (MPC_THR_HOVER - MPC_THR_MIN) * 0.1`
- no freefall detected
If the vehicle only has knowledge of thrust and angular rate,
in order to proceed to the next state the vehicle has to have low thrust and no rotation for 8.0 seconds.
If the vehicle is in position or velocity control and maybe landed was detected,
the position controller will set the thrust vector to zero.
#### Landed
Conditions for this state:
- all conditions of the [maybe landed](#maybe-landed) state are true
## Fixed-wing Configuration
Tuning parameters for fixed-wing land detection:
- [LNDFW_AIRSPD_MAX](../advanced_config/parameter_reference.md#LNDFW_AIRSPD_MAX) - the maximum airspeed allowed for the system still to be considered landed.
Has to be a tradeoff between airspeed sensing accuracy and triggering fast enough.
Better airspeed sensors should allow lower values of this parameter.
- [LNDFW_VEL_XY_MAX ](../advanced_config/parameter_reference.md#LNDFW_VEL_XY_MAX) - the maximum horizontal velocity for the system to be still be considered landed.
- [LNDFW_VEL_Z_MAX](../advanced_config/parameter_reference.md#LNDFW_VEL_XY_MAX) - the maximum vertical velocity for the system to be still be considered landed.
- [LNDFW_XYACC_MAX](../advanced_config/parameter_reference.md#LNDFW_XYACC_MAX) - the maximal horizontal acceleration for the system to still be considered landed.
- [LNDFW_TRIG_TIME](../advanced_config/parameter_reference.md#LNDFW_TRIG_TIME) - Trigger time during which the conditions above have to be fulfilled to declare a landing.
::: info
When FW launch detection is enabled ([FW_LAUN_DETCN_ON](../advanced_config/parameter_reference.md#FW_LAUN_DETCN_ON)), the vehicle will stay in "landed" state until takeoff is detected (which is purely based on acceleration and not velocity).
:::
## VTOL Land Detector
The VTOL land detector is 1:1 the same as the MC land detector if the system is in hover mode. In FW mode, land detection is disabled.
docs/en/advanced_config/parameter_reference.md
+38021
View File
File diff suppressed because it is too large Load Diff
docs/en/advanced_config/parameters.md
+111
View File
@@ -0,0 +1,111 @@
# Finding/Updating Parameters
PX4 behaviour can be configured/tuned using [parameters](../advanced_config/parameter_reference.md) (e.g. [Multicopter PID gains](../config_mc/pid_tuning_guide_multicopter.md), calibration information, etc.).
The _QGroundControl Parameters_ screen allows you to find and modify **any** of the parameters associated with the vehicle.
The screen is accessed by clicking the **Q** application icon > **Vehicle Setup**, and then _Parameters_ in the sidebar.
::: info
Most of the more commonly used parameters are more conveniently set using the dedicated setup screens, as described in the [Standard Configuration](../config/index.md) section.
The _Parameters_ screen is needed when modifying less commonly modified parameters - for example while tuning a new vehicle.
:::
:::warning
While some parameters can be changed in flight, this is not recommended (except where explicitly stated in the guide).
:::
<a id="finding"></a>
## Finding a Parameter
You can search for a parameter by entering a term in the _Search_ field.
This will show you a list of all parameter names and descriptions that contain the entered substring (press **Clear** to reset the search, and use the **Show modified only** checkbox to filter out unchanged parameters).
![Parameters Search](../../assets/qgc/setup/parameters/parameters_search.png)
You can also browse the parameters by type and group by clicking on the buttons to the left (in the image below the _DShot_ group in the _Standard_ parameters is selected).
![Parameters Screen](../../assets/qgc/setup/parameters/parameters_px4.png)
You can expand/collapse the "type" groupings as shown.
Note that the groups at the bottom named _Component X_ are attached [DroneCAN peripherals](../dronecan/index.md#qgc-cannode-parameter-configuration) ("X" is the node id).
[QGC can set the parameters](../dronecan/index.md#qgc-cannode-parameter-configuration) of these peripherals if they are attached to the Flight Controller when QGC is started.
![Parameters Types - collapsed](../../assets/qgc/setup/parameters/parameters_types.png)
:::tip
If you can't find an expected parameter, see the [next section](#missing).
:::
<a id="missing"></a>
## Missing Parameters
Parameters are usually not visible because either they are conditional on other parameters, or they are not present in the firmware (see below).
### Conditional Parameters
A parameter may not be displayed if it is conditional on another parameter that is not enabled.
You can usually find out what parameters are conditional by searching the [full parameter reference](../advanced_config/parameter_reference.md) and other documentation.
In particular [serial port configuration parameters](../peripherals/serial_configuration.md) depend on what service is assigned to a serial port.
### Parameter Not In Firmware
A parameter may not be present in the firmware because you're using a different version of PX4 or because you're using a build in which the associated module is not included.
New parameters are added in each PX4 version, and existing parameters are sometimes removed or renamed.
You can check whether a parameter _should_ be present by reviewing the [full parameter reference](../advanced_config/parameter_reference.md) for the version you're targeting.
You can also search for the parameter in the source tree and in the release notes.
The other reason that a parameter might not be in firmware is if its associated module has not been included.
This is a problem (in particular) for _FMUv2 firmware_, which omits many modules so that PX4 can fit into the 1MB of available flash.
There are two options to solve this problem:
- Check if you can update your board to run FMUv3 firmware, which includes all modules: [Firmware > FMUv2 Bootloader Update](../config/firmware.md#bootloader)
- If your board can only run FMUv2 firmware you will need to [rebuild PX4](../dev_setup/building_px4.md) with the missing modules enabled.
You need reconfigure the PX4 firmware itself through make px4_fmuv2_default boardconfig where you can enabled/disable modules.
::: info
You may also need to disable other modules in order to fit the rebuilt firmware into 1MB flash.
Finding modules to remove requires some trial/error and depends on what use cases you need the vehicle to meet.
:::
<a id="changing"></a>
## Changing a Parameter
To change the value of a parameter click on the parameter row in a group or search list.
This will open a side dialog in which you can update the value (this dialog also provides additional detailed information about the parameter - including whether a reboot is required for the change to take effect).
![Changing a parameter value](../../assets/qgc/setup/parameters/parameters_changing.png)
::: info
When you click **Save** the parameter is automatically and silently uploaded to the connected vehicle.
Depending on the parameter, you may then need to reboot the flight controller for the change to take effect.
:::
## Tools
You can select additional options from the **Tools** menu on the top right hand side of the screen.
![Tools menu](../../assets/qgc/setup/parameters/parameters_tools_menu.png)
**Refresh**
<br>Refresh the parameter values by re-requesting all of them from the vehicle.
**Reset all to firmware defaults**
<br>Reset all parameters to their original default values in the firmware.
**Reset to vehicle's configuration defaults**
<br>Reset all parameters to their original default values for the particular selected airfame configuration.
**Load from file / Save to file**
<br>Load parameters from an existing file or save your current parameter settings to a file.
**Clear all RC to Param**
<br>This clears all associations between RC transmitter controls and parameters.
For more information see: [Radio Setup > Param Tuning Channels](../config/radio.md#param-tuning-channels).
**Reboot Vehicle**
<br>Reboot the vehicle (required after changing some parameters).
docs/en/advanced_config/prearm_arm_disarm.md
+235
View File
@@ -0,0 +1,235 @@
# Arm, Disarm, Prearm Configuration
Vehicles may have moving parts, some of which are potentially dangerous when powered (in particular motors and propellers)!
To reduce the chance of accidents, PX4 has explicit state(s) for powering the vehicle components:
- **Disarmed:** There is no power to motors or actuators.
- **Pre-armed:** Motors/propellers are locked but actuators for non-dangerous electronics are powered (e.g. ailerons, flaps etc.).
- **Armed:** Vehicle is fully powered. Motors/propellers may be turning (dangerous!)
::: info
Ground stations may display _disarmed_ for pre-armed vehicles.
While not technically correct for pre-armed vehicles, it is "safe".
:::
Users can control progression though these states using a [safety switch](../getting_started/px4_basic_concepts.md#safety-switch) on the vehicle (optional) _and_ an [arming switch/button](#arm_disarm_switch), [arming gesture](#arm_disarm_gestures), or _MAVLink command_ on the ground controller:
- A _safety switch_ is a control _on the vehicle_ that must be engaged before the vehicle can be armed, and which may also prevent prearming (depending on the configuration).
Commonly the safety switch is integrated into a GPS unit, but it may also be a separate physical component.
:::warning
A vehicle that is armed is potentially dangerous.
The safety switch is an additional mechanism that prevents arming from happening by accident.
:::
- An _arming switch_ is a switch or button _on an RC controller_ that can be used to arm the vehicle and start motors (provided arming is not prevented by a safety switch).
- An _arming gesture_ is a stick movement _on an RC controller_ that can be used as an alternative to an arming switch.
- MAVLink commands can also be sent by a ground control station to arm/disarm a vehicle.
PX4 will also automatically disarm the vehicle if it does not takeoff within a certain amount of time after arming, and if it is not manually disarmed after landing.
This reduces the amount of time where an armed (and therefore dangerous) vehicle is on the ground.
PX4 allows you to configure how pre-arming, arming and disarming work using parameters (which can be edited in _QGroundControl_ via the [parameter editor](../advanced_config/parameters.md)), as described in the following sections.
:::tip
Arming/disarming parameters can be found in [Parameter Reference > Commander](../advanced_config/parameter_reference.md#commander) (search for `COM_ARM_*` and `COM_DISARM_*`).
:::
## Arming/Disarming Gestures {#arm_disarm_gestures}
By default, the vehicle is armed and disarmed by moving RC throttle/yaw sticks to particular extremes and holding them for 1 second.
- **Arming:** Throttle minimum, yaw maximum
- **Disarming:** Throttle minimum, yaw minimum
RC controllers will use different sticks for throttle and yaw [based on their mode](../getting_started/rc_transmitter_receiver.md#types-of-remote-controllers), and hence different gestures:
- **Mode 2**:
- _Arm:_ Left stick to bottom right.
- _Disarm:_ Left stick to the bottom left.
- **Mode 1**:
- _Arm:_ Left-stick to right, right-stick to bottom.
- _Disarm:_ Left-stick to left, right-stick to the bottom.
The required hold time can be configured using [COM_RC_ARM_HYST](#COM_RC_ARM_HYST).
Note that by default ([COM_DISARM_MAN](#COM_DISARM_MAN)) you can also disarm in flight using gestures/buttons: you may choose to disable this to avoid accidental disarming.
| Parameter | Description |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| <a id="MAN_ARM_GESTURE"></a>[MAN_ARM_GESTURE](../advanced_config/parameter_reference.md#MAN_ARM_GESTURE) | Enable arm/disarm stick guesture. `0`: Disabled, `1`: Enabled (default). |
| <a id="COM_DISARM_MAN"></a>[COM_DISARM_MAN](../advanced_config/parameter_reference.md#COM_DISARM_MAN) | Enable disarming in flight via switch/stick/button in MC manual thrust modes. `0`: Disabled, `1`: Enabled (default). |
| <a id="COM_RC_ARM_HYST"></a>[COM_RC_ARM_HYST](../advanced_config/parameter_reference.md#COM_RC_ARM_HYST) | Time that RC stick must be held in arm/disarm position before arming/disarming occurs (default: `1` second). |
## Arming Button/Switch {#arm_disarm_switch}
An _arming button_ or "momentary switch" can be configured to trigger arm/disarm _instead_ of [gesture-based arming](#arm_disarm_gestures) (setting an arming switch disables arming gestures).
The button should be held down for ([nominally](#COM_RC_ARM_HYST)) one second to arm (when disarmed) or disarm (when armed).
A two-position switch can also be used for arming/disarming, where the respective arm/disarm commands are sent on switch _transitions_.
:::tip
Two-position arming switches are primarily used in/recommended for racing drones.
:::
The switch or button is assigned (and enabled) using [RC_MAP_ARM_SW](#RC_MAP_ARM_SW), and the switch "type" is configured using [COM_ARM_SWISBTN](#COM_ARM_SWISBTN).
| Parameter | Description |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="RC_MAP_ARM_SW"></a>[RC_MAP_ARM_SW](../advanced_config/parameter_reference.md#RC_MAP_ARM_SW) | RC arm switch channel (default: 0 - unassigned). If defined, the specified RC channel (button/switch) is used for arming instead of a stick gesture. <br>**Note:**<br>- This setting _disables the stick gesture_!<br>- This setting applies to RC controllers. It does not apply to Joystick controllers that are connected via _QGroundControl_. |
| <a id="COM_ARM_SWISBTN"></a>[COM_ARM_SWISBTN](../advanced_config/parameter_reference.md#COM_ARM_SWISBTN) | Arm switch is a momentary button. <br>- `0`: Arm switch is a 2-position switch where arm/disarm commands are sent on switch transitions.<br>-`1`: Arm switch is a button or momentary button where the arm/disarm command ae sent after holding down button for set time ([COM_RC_ARM_HYST](#COM_RC_ARM_HYST)). |
::: info
The switch can also be set as part of _QGroundControl_ [Flight Mode](../config/flight_mode.md) configuration.
:::
## Auto-Disarming
By default vehicles will automatically disarm on landing, or if you take too long to take off after arming.
The feature is configured using the following timeouts.
| Parameter | Description |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| <a id="COM_DISARM_LAND"></a>[COM_DISARM_LAND](../advanced_config/parameter_reference.md#COM_DISARM_LAND) | Time-out for auto disarm after landing. Default: 2s (-1 to disable). |
| <a id="COM_DISARM_PRFLT"></a>[COM_DISARM_PRFLT](../advanced_config/parameter_reference.md#COM_DISARM_PRFLT) | Time-out for auto disarm if too slow to takeoff. Default: 10s (<=0 to disable). |
## Pre-Arm Checks
To reduce accidents, vehicles are only allowed to arm certain conditions are met (some of which are configurable).
Arming is prevented if:
- The vehicle is not in a "healthy" state.
For example it is not calibrated, or is reporting sensor errors.
- The vehicle has a [safety switch](../getting_started/px4_basic_concepts.md#safety-switch) that has not been engaged.
- The vehicle has a [remote ID](../peripherals/remote_id.md) that is unhealthy or otherwise not ready
- A VTOL vehicle is in fixed-wing mode ([by default](../advanced_config/parameter_reference.md#CBRK_VTOLARMING)).
- The current mode requires an adequate global position estimate but the vehicle does not have GPS lock.
- Many more (see [arming/disarming safety settings](../config/safety.md#arming-disarming-settings) for more information).
The current failed checks can be viewed in QGroundControl (v4.2.0 and later) [Arming Check Report](../flying/pre_flight_checks.md#qgc-arming-check-report) (see also [Fly View > Arming and Preflight Checks](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/fly_view/fly_view.md#arm)).
Note that internally PX4 runs arming checks at 10Hz.
A list of the failed checks is kept, and if the list changes PX4 emits the current list using the [Events interface](../concept/events_interface.md).
The list is also sent out when the GCS connects.
Effectively the GCS knows the status of prearm checks immediately, both when disarmed and armed.
:::details Implementation notes for developers
The client implementation is in [libevents](https://github.com/mavlink/libevents):
- [libevents > Event groups](https://github.com/mavlink/libevents#event-groups)
- [health_and_arming_checks.h](https://github.com/mavlink/libevents/blob/main/libs/cpp/parse/health_and_arming_checks.h)
QGC implementation: [HealthAndArmingCheckReport.cc](https://github.com/mavlink/qgroundcontrol/blob/master/src/MAVLink/LibEvents/HealthAndArmingCheckReport.cc).
:::
PX4 also emits a subset of the arming check information in the [SYS_STATUS](https://mavlink.io/en/messages/common.html#SYS_STATUS) message (see [MAV_SYS_STATUS_SENSOR](https://mavlink.io/en/messages/common.html#MAV_SYS_STATUS_SENSOR)).
## Arming Sequence: Pre Arm Mode & Safety Button
The arming sequence depends on whether or not there is a _safety switch_, and is controlled by the parameters [COM_PREARM_MODE](#COM_PREARM_MODE) (Prearm mode) and [CBRK_IO_SAFETY](#CBRK_IO_SAFETY) (I/O safety circuit breaker).
The [COM_PREARM_MODE](#COM_PREARM_MODE) parameter defines when/if pre-arm mode is enabled ("safe"/non-throttling actuators are able to move):
- _Disabled_: Pre-arm mode disabled (there is no stage where only "safe"/non-throttling actuators are enabled).
- _Safety Switch_ (Default): The pre-arm mode is enabled by the safety switch.
If there is no safety switch then pre-arm mode will not be enabled.
- _Always_: Prearm mode is enabled from power up.
If there is a safety switch then this will be a precondition for arming.
If there is no safety switch the I/O safety circuit breaker must be engaged ([CBRK_IO_SAFETY](#CBRK_IO_SAFETY)), and arming will depend only on the arm command.
The sections below detail the startup sequences for the different configurations
### Default: COM_PREARM_MODE=Safety and Safety Switch
The default configuration uses safety switch to prearm.
From prearm you can then arm to engage all motors/actuators.
It corresponds to: [COM_PREARM_MODE=1](#COM_PREARM_MODE) (safety switch) and [CBRK_IO_SAFETY=0](#CBRK_IO_SAFETY) (I/O safety circuit breaker disabled).
The default startup sequence is:
1. Power-up.
- All actuators locked into disarmed position
- Not possible to arm.
1. Safety switch is pressed.
- System now prearmed: non-throttling actuators can move (e.g. ailerons).
- System safety is off: Arming possible.
1. Arm command is issued.
- The system is armed.
- All motors and actuators can move.
### COM_PREARM_MODE=Disabled and Safety Switch
When prearm mode is _Disabled_, engaging the safety switch does not unlock the "safe" actuators, though it does allow you to then arm the vehicle.
This corresponds to [COM_PREARM_MODE=0](#COM_PREARM_MODE) (Disabled) and [CBRK_IO_SAFETY=0](#CBRK_IO_SAFETY) (I/O safety circuit breaker disabled).
The startup sequence is:
1. Power-up.
- All actuators locked into disarmed position
- Not possible to arm.
1. Safety switch is pressed.
- _All actuators stay locked into disarmed position (same as disarmed)._
- System safety is off: Arming possible.
1. Arm command is issued.
- The system is armed.
- All motors and actuators can move.
### COM_PREARM_MODE=Always and Safety Switch
When prearm mode is _Always_, prearm mode is enabled from power up.
To arm, you still need the safety switch.
This corresponds to [COM_PREARM_MODE=2](#COM_PREARM_MODE) (Always) and [CBRK_IO_SAFETY=0](#CBRK_IO_SAFETY) (I/O safety circuit breaker disabled).
The startup sequence is:
1. Power-up.
- System now prearmed: non-throttling actuators can move (e.g. ailerons).
- Not possible to arm.
1. Safety switch is pressed.
- System safety is off: Arming possible.
1. Arm command is issued.
- The system is armed.
- All motors and actuators can move.
### COM_PREARM_MODE=Safety or Disabled and No Safety Switch
With no safety switch, when `COM_PREARM_MODE` is set to _Safety_ or _Disabled_ prearm mode cannot be enabled (same as disarmed).
This corresponds to [COM_PREARM_MODE=0 or 1](#COM_PREARM_MODE) (Disabled/Safety Switch) and [CBRK_IO_SAFETY=22027](#CBRK_IO_SAFETY) (I/O safety circuit breaker engaged).
The startup sequence is:
1. Power-up.
- All actuators locked into disarmed position
- System safety is off: Arming possible.
1. Arm command is issued.
- The system is armed.
- All motors and actuators can move.
### COM_PREARM_MODE=Always and No Safety Switch
When prearm mode is _Always_, prearm mode is enabled from power up.
This corresponds to [COM_PREARM_MODE=2](#COM_PREARM_MODE) (Always) and [CBRK_IO_SAFETY=22027](#CBRK_IO_SAFETY) (I/O safety circuit breaker engaged).
The startup sequence is:
1. Power-up.
- System now prearmed: non-throttling actuators can move (e.g. ailerons).
- System safety is off: Arming possible.
1. Arm command is issued.
- The system is armed.
- All motors and actuators can move.
### Parameters
| Parameter | Description |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="COM_PREARM_MODE"></a>[COM_PREARM_MODE](../advanced_config/parameter_reference.md#COM_PREARM_MODE) | Condition to enter prearmed mode. `0`: Disabled, `1`: Safety switch (prearm mode enabled by safety switch; if no switch present cannot be enabled), `2`: Always (prearm mode enabled from power up). Default: `1` (safety button). |
| <a id="CBRK_IO_SAFETY"></a>[CBRK_IO_SAFETY](../advanced_config/parameter_reference.md#CBRK_IO_SAFETY) | Circuit breaker for IO safety. |
<!-- Discussion:
https://github.com/PX4/PX4-Autopilot/pull/12806#discussion_r318337567
https://github.com/PX4/PX4-user_guide/issues/567#issue-486653048
-->
docs/en/advanced_config/sensor_thermal_calibration.md
+197
View File
@@ -0,0 +1,197 @@
# Thermal Calibration and Compensation
PX4 contains functionality to calibrate and compensate accelerometer, gyro, magnetometer, and barometric pressure sensors for the effect of changing sensor temperature on sensor bias.
This topic details the [test environment](#test_setup) and [calibration procedures](#calibration_procedures).
At the end there is a description of the [implementation](#implementation).
::: info
After thermal calibration, the thermal calibration parameters (`TC_*`) are used for _all_ calibration/compensation of the respective sensors.
Any subsequent standard calibration will therefore update `TC_*` parameters and not the "normal" `SYS_CAL_*` calibration parameters (and in some cases these parameters may be reset).
:::
::: info
Releases up to PX4 v1.14, do not support thermal calibration of the magnetometer.
:::
<a id="test_setup"></a>
## Test Setup/Best Practice
The [calibration procedures](#calibration_procedures) described in the following sections are ideally run in an _environmental chamber_ (a temperature and humidity controlled environment) as the board is heated from the lowest to the highest operating/calibration temperature.
Before starting the calibration, the board is first _cold soaked_ (cooled to the minimum temperature and allowed to reach equilibrium).
::: info
Active electric heating elements will affect the magnetometer calibration values.
Ensure that heating elements are either inactive or sufficiently far from the sensor to avoid injecting noise into the magnetometer calibration.
:::
For the cold soak you can use a regular home freezer to achieve -20C, and commercial freezers can achieve of the order of -40C.
The board should be placed in a ziplock/anti-static bag containing a silica packet, with a power lead coming out through a sealed hole.
After the cold soak the bag can be moved to the test environment and the test continued in the same bag.
::: info
The bag/silica is to prevent condensation from forming on the board.
:::
It possible to perform the calibration without a commercial-grade environment chamber.
A simple environment container can be created using a styrofoam box with a very small internal volume of air.
This allows the autopilot to self-heat the air relatively quickly (be sure that the box has a small hole to equalize to ambient room pressure, but still be able to heat up inside).
Using this sort of setup it is possible to heat a board to ~70C.
Anecdotal evidence suggests that many common boards can be heated to this temperature without adverse side effects.
If in doubt, check the safe operating range with your manufacturer.
:::tip
To check the status of the onboard thermal calibration use the MAVlink console (or NuttX console) to check the reported internal temp from the sensor.
:::
<a id="calibration_procedures"></a>
## Calibration Procedures
PX4 supports two calibration procedures:
- [onboard](#onboard_calibration) - calibration is run on the board itself. This method requires knowledge of the amount of temperature rise that is achievable with the test setup.
- [offboard](#offboard_calibration) - compensation parameters are calculated on a development computer based on log information collected during the calibration procedure. This method allows users to visually check the quality of the data and curve-fit.
The offboard approach is more complex and slower, but requires less knowledge of the test setup and is easier to validate.
<a id="onboard_calibration"></a>
### Onboard Calibration Procedure
Onboard calibration is run entirely on the device. It require knowledge of the amount of temperature rise that is achievable with the test setup.
To perform and onboard calibration:
1. Ensure the frame type is set before calibration, otherwise calibration parameters will be lost when the board is setup.
2. Power the board and set the `SYS_CAL_*` parameters to 1 to enable calibration of the required sensors at the next startup. [^1]
3. Set the [SYS_CAL_TDEL](../advanced_config/parameter_reference.md#SYS_CAL_TDEL) parameter to the number of degrees of temperature rise required for the onboard calibrator to complete. If this parameter is too small, then the calibration will complete early and the temperature range for the calibration will not be sufficient to compensate when the board is fully warmed up. If this parameter is set too large, then the onboard calibrator will never complete. allowance should be made for the rise in temperature due to the boards self heating when setting this parameter. If the amount of temperature rise at the sensors is unknown, then the off-board method should be used.
4. Set the [SYS_CAL_TMIN](../advanced_config/parameter_reference.md#SYS_CAL_TMIN) parameter to the lowest temperature data that you want the calibrator to use. This enables a lower cold soak ambient temperature to be used to reduce the cold soak time whilst maintaining control over the calibration minimum temperature. The data for a sensor will not be used by the calibrator if it is below the value set by this parameter.
5. Set the [SYS_CAL_TMAX](../advanced_config/parameter_reference.md#SYS_CAL_TMAX) parameter to the highest starting sensor temperature that should be accepted by the calibrator. If the starting temperature is higher than the value set by this parameter, the calibration will exit with an error. Note that if the variation in measured temperature between different sensors exceeds the gap between `SYS_CAL_TMAX` and `SYS_CAL_TMIN`, then it will be impossible for the calibration to start.
6. Remove power and cold soak the board to below the starting temperature specified by the `SYS_CAL_TMIN` parameter. Note that there is a 10 second delay on startup before calibration starts to allow any sensors to stabilise and the sensors will warm internally during this period.
7. Keeping the board stationary[^2], apply power and warm to a temperature high enough to achieve the temperature rise specified by the `SYS_CAL_TDEL` parameter. The completion percentage is printed to the system console during calibration. [^3]
8. When the calibration completes, remove power, allow the board to cool to a temperature that is within the calibration range before performing the next step.
9. Perform a 6-point accel calibration via the system console using `commander calibrate accel` or via _QGroundControl_. If the board is being set-up for the first time, the gyro and magnetometer calibration will also need to be performed.
10. The board should always be re-powered before flying after any sensor calibration, because sudden offset changes from calibration can upset the navigation estimator and some parameters are not loaded by the algorithms that use them until the next startup.
<a id="offboard_calibration"></a>
### Offboard Calibration Procedure
Offboard calibration is run on a development computer using data collected during the calibration test. This method provides a way to visually check the quality of data and curve fit.
To perform an offboard calibration:
1. Ensure the frame type is set before calibration, otherwise calibration parameters will be lost when the board is setup.
1. Power up the board and set the [TC_A_ENABLE](../advanced_config/parameter_reference.md#TC_A_ENABLE), [TC_B_ENABLE](../advanced_config/parameter_reference.md#TC_B_ENABLE), [TC_G_ENABLE](../advanced_config/parameter_reference.md#TC_G_ENABLE), and [TC_M_ENABLE](../advanced_config/parameter_reference.md#TC_M_ENABLE) parameters to `1`.
1. Set all [CAL_ACC\*](../advanced_config/parameter_reference.md#CAL_ACC0_ID), [CAL_GYRO\*](../advanced_config/parameter_reference.md#CAL_GYRO0_ID), [CAL_MAG\*](../advanced_config/parameter_reference.md#CAL_MAG0_ID), and [CAL_BARO\*](../advanced_config/parameter_reference.md#CAL_BARO0_ID) parameters to defaults.
1. Set the [SDLOG_MODE](../advanced_config/parameter_reference.md#SDLOG_MODE) parameter to 2 to enable logging of data from boot.
1. Set the [SDLOG_PROFILE](../advanced_config/parameter_reference.md#SDLOG_PROFILE) checkbox for _thermal calibration_ (bit 2) to log the raw sensor data required for calibration.
1. Cold soak the board to the minimum temperature it will be required to operate in.
1. Apply power and keeping the board still [^2], warm it slowly to the maximum required operating temperature. [^3]
1. Remove power and extract the .ulog file.
1. Open a terminal window in the **Firmware/Tools** directory and run the python calibration script:
```sh
python process_sensor_caldata.py <full path name to .ulog file>
```
This will generate a **.pdf** file showing the measured data and curve fits for each sensor, and a **.params** file containing the calibration parameters.
1. Power the board, connect _QGroundControl_ and load the parameter from the generated **.params** file onto the board using _QGroundControl_. Due to the number of parameters, loading them may take some time.
1. After parameters have finished loading, set `SDLOG_MODE` to 1 to re-enable normal logging and remove power.
1. Power the board and perform a normal accelerometer sensor calibration using _QGroundControl_. It is important that this step is performed when board is within the calibration temperature range. The board must be repowered after this step before flying as the sudden offset changes can upset the navigation estimator and some parameters are not loaded by the algorithms that use them until the next startup.
<a id="implementation"></a>
## Implementation Detail
Calibration refers to the process of measuring the change in sensor value across a range of internal temperatures, and performing a polynomial fit on the data to calculate a set of coefficients (stored as parameters) that can be used to correct the sensor data. Compensation refers to the process of using the internal temperature to calculate an offset that is subtracted from the sensor reading to correct for changing offset with temperature
The accelerometer, gyro, and magnetometer sensor offsets are calculated using a 3rd order polynomial, whereas the barometric pressure sensor offset is calculated using a 5th order polynomial. Example fits are show below:
![Thermal calibration accel](../../assets/calibration/thermal_calibration_accel.png)
![Thermal calibration gyro](../../assets/calibration/thermal_calibration_gyro.png)
![Thermal calibration mag](../../assets/calibration/thermal_calibration_mag.png)
![Thermal calibration barometer](../../assets/calibration/thermal_calibration_baro.png)
### Calibration Parameter Storage
With the existing parameter system implementation we are limited to storing each value in the struct as a separate entry. To work around this limitation the following logical naming convention is used for the [thermal compensation parameters](../advanced_config/parameter_reference.md#thermal-compensation):
```sh
TC_[type][instance]_[cal_name]_[axis]
```
Where:
- `type`: is a single character indicating the type of sensor where `A` = accelerometer, `G` = rate gyroscope, `M` = magnetometer, and `B` = barometer.
- `instance`: is an integer 0,1 or 2 allowing for calibration of up to three sensors of the same `type`.
- `cal_name`: is a string identifying the calibration value. It has the following possible values:
- `Xn`: Polynomial coefficient where n is the order of the coefficient, e.g. `X3 * (temperature - reference temperature)**3`.
- `SCL`: scale factor.
- `TREF`: reference temperature (deg C).
- `TMIN`: minimum valid temperature (deg C).
- `TMAX`: maximum valid temperature (deg C).
- `axis`: is an integer 0,1 or 2 indicating that the calibration data is for X,Y or Z axis in the board frame of reference. For the barometric pressure sensor, the `axis` suffix is omitted.
Examples:
- [TC_A1_TREF](../advanced_config/parameter_reference.md#TC_A1_TREF) is the reference temperature for the second accelerometer.
- [TC_G0_X3_0](../advanced_config/parameter_reference.md#TC_G0_X3_0) is the `^3` coefficient for the first gyro x-axis.
### Calibration Parameter Usage
The correction for thermal offsets (using the calibration parameters) is performed in the [sensors module](../modules/modules_system.md#sensors).
The reference temperature is subtracted from the measured temperature to obtain a delta temperature where:
```
delta = measured_temperature - reference_temperature
```
The delta temperature is then used to calculate a offset, where:
```
offset = X0 + X1*delta + X2*delta**2 + ... + Xn*delta**n
```
The offset and temperature scale factor are then used to correct the sensor measurement where:
```
corrected_measurement = (raw_measurement - offset) * scale_factor
```
If the temperature is above the test range set by the `*_TMIN` and `*_TMAX` parameters, then the measured temperature will be clipped to remain within the limits.
Correction of the accelerometer, gyroscope, magnetometer, or barometer data is enabled by setting [TC_A_ENABLE](../advanced_config/parameter_reference.md#TC_A_ENABLE), [TC_G_ENABLE](../advanced_config/parameter_reference.md#TC_G_ENABLE), [TC_M_ENABLE](../advanced_config/parameter_reference.md#TC_M_ENABLE), or [TC_B_ENABLE](../advanced_config/parameter_reference.md#TC_B_ENABLE) parameters to 1 respectively.
### Compatibility with legacy `CAL_*` parameters and commander controlled calibration
The legacy temperature-agnostic PX4 rate gyro and accelerometer sensor calibration is performed by the commander module and involves adjusting offset, and in the case of accelerometer calibration, scale factor calibration parameters. The offset and scale factor parameters are applied within the driver for each sensor. These parameters are found in the [CAL parameter group](../advanced_config/parameter_reference.md#sensor-calibration).
Onboard temperature calibration is controlled by the events module and the corrections are applied within the sensors module before the sensor combined uORB topic is published. This means that if thermal compensation is being used, all of the corresponding legacy offset and scale factor parameters must be set to defaults of zero and unity before a thermal calibration is performed. If an on-board temperature calibration is performed, this will be done automatically, however if an offboard calibration is being performed it is important that the legacy `CAL*OFF` and `CAL*SCALE` parameters be reset before calibration data is logged.
If accel thermal compensation has been enabled by setting the `TC_A_ENABLE` parameter to 1, then the commander controlled 6-point accel calibration can still be performed.
However, instead of adjusting the `*OFF` and `*SCALE` parameters in the `CAL` parameter group, these parameters are set to defaults and the thermal compensation `X0` and `SCL` parameters are adjusted instead.
If gyro thermal compensation has been enabled by setting the `TC_G_ENABLE` parameter to 1, then the commander controlled gyro calibration can still be performed, however it will be used to shift the compensation curve up or down by the amount required to zero the angular rate offset. It achieves this by adjusting the X0 coefficients.
If magnetometer thermal compensation has been enabled by setting the `TC_M_ENABLE` parameter to 1, then the commander controlled 6-point accel calibration can still be performed.
However, instead of adjusting the `*OFF` and `*SCALE` parameters in the `CAL` parameter group, these parameters are set to defaults and the thermal compensation `X0` and `SCL` parameters are adjusted instead.
### Limitations
Scale factors are assumed to be temperature invariant due to the difficulty associated with measuring these at different temperatures. This limits the usefulness of the accelerometer calibration to those sensor models with stable scale factors. In theory with a thermal chamber or IMU heater capable of controlling IMU internal temperature to within a degree, it would be possible to perform a series of 6 sided accelerometer calibrations and correct the accelerometers for both offset and scale factor. Due to the complexity of integrating the required board movement with the calibration algorithm, this capability has not been included.
---
[^1]: The [SYS_CAL_ACCEL](../advanced_config/parameter_reference.md#SYS_CAL_ACCEL), [SYS_CAL_BARO](../advanced_config/parameter_reference.md#SYS_CAL_BARO) and [SYS_CAL_GYRO](../advanced_config/parameter_reference.md#SYS_CAL_GYRO) parameters are reset to 0 when the calibration is started.
[^2]: Calibration of the barometric pressure sensor offsets requires a stable air pressure environment. The air pressure will change slowly due to weather and inside buildings can change rapidly due to external wind fluctuations and HVAC system operation.
[^3]: Care must be taken when warming a cold soaked board to avoid formation of condensation on the board that can cause board damage under some circumstances.
docs/en/advanced_config/static_pressure_buildup.md
+42
View File
@@ -0,0 +1,42 @@
# Static Pressure Buildup
Air flowing over an enclosed vehicle can cause the _static pressure_ to change within the canopy/hull.
Depending on the location of holes/leaks in the hull, you can end up with under or overpressure (similar to a wing).
The change in pressure can affect barometer measurements, leading to an inaccurate altitude estimate.
This might manifest as the vehicle losing altitude when it stops moving in [Altitude](../flight_modes_mc/altitude.md), [Position](../flight_modes_mc/position.md) or [Mission](../flight_modes_mc/mission.md) modes (when the vehicle stops moving the static pressure drops, the sensor reports a higher altitude, and the vehicle compensates by descending).
The problem is particularly visible on multicopters because fixed wing vehicles move with a more constant airspeed (and it is the airspeed deltas that are noticeable).
One solution is to use foam-filled venting holes to reduce the buildup (as much as possible) and then attempt dynamic calibration to remove any remaining effects.
:::tip
Before "fixing" the problem you should first check that the Z setpoint tracks the estimated altitude (to verify that there are no controller issues).
:::
::: info
While it is possible to remove the barometer from the altitude estimate (i.e. only use altitude from the GPS), this is not recommended.
GPS is inaccurate in many environments, and particularly in urban environments where you have signal reflections off buildings.
:::
## Airflow Analysis
You can modify the hull by drilling holes or filling them with foam.
One way to analyse the effects of these changes is to mount the drone on a car and drive around (on a relatively level surface) with the hull exposed to air/wind.
By looking at the ground station you can review the effects of movement-induced static pressure changes on the measured altitude (using the road as "ground truth).
This process allows rapid iteration without draining batteries: modify drone, drive/review, repeat!
:::tip
Aim for a barometer altitude drop of less than 2 metres at maximum horizontal speed before attempting software-based calibration below.
:::
## Dynamic Calibration
After modifying the hardware, you can then use the [EKF2_PCOEF\_\*](../advanced_config/parameter_reference.md#EKF2_PCOEF_XN) parameters to tune for expected barometer variation based on relative air velocity.
For more information see [Using PX4's Navigation Filter (EKF2) > Correction for Static Pressure Position Error](../advanced_config/tuning_the_ecl_ekf.md#correction-for-static-pressure-position-error).
::: info
The approach works well if the relationship between the error due to static pressure and the velocity varies linearly.
If the vehicle has a more complex aerodynamic model it will be less effective.
:::
docs/en/advanced_config/tuning_the_ecl_ekf.md
+843
View File
@@ -0,0 +1,843 @@
# Using PX4's Navigation Filter (EKF2)
This tutorial answers common questions about use of the EKF algorithm used for navigation.
:::tip
The [PX4 State Estimation Overview](https://youtu.be/HkYRJJoyBwQ) video from the _PX4 Developer Summit 2019_ (Dr. Paul Riseborough) provides an overview of the estimator, and additionally describes both the major changes from 2018/2019, major changes and improvements were added since then.
:::
## Overview
PX4's Navigation filter uses an Extended Kalman Filter (EKF) algorithm to process sensor measurements and provide an estimate of the following states:
- Quaternion defining the rotation from North, East, Down local navigation frame to X, Y, Z body frame
- Velocity at the IMU - North, East, Down (m/s)
- Position at the IMU - Latitude (rad), Longitude (rad), Altitude (m)
- IMU gyro bias estimates - X, Y, Z (rad/s)
- IMU accelerometer bias estimates - X, Y, Z (m/s<sup>2</sup>)
- Earth Magnetic field components - North, East, Down \(gauss\)
- Vehicle body frame magnetic field bias - X, Y, Z \(gauss\)
- Wind velocity - North, East \(m/s\)
- Terrain altitude (m)
To improve stability, an "error-state" formulation is implemented
This is especially relevant when estimating the uncertainty of a rotation which is a 3D vector (tangent space of SO(3)).
The EKF runs on a delayed 'fusion time horizon' to allow for different time delays on each measurement relative to the IMU.
Data for each sensor is FIFO buffered and retrieved from the buffer by the EKF to be used at the correct time.
The delay compensation for each sensor is controlled by the [EKF2\_\*\_DELAY](../advanced_config/parameter_reference.md#ekf2) parameters.
A complementary filter is used to propagate the states forward from the 'fusion time horizon' to current time using the buffered IMU data.
The time constant for this filter is controlled by the [EKF2_TAU_VEL](../advanced_config/parameter_reference.md#EKF2_TAU_VEL) and [EKF2_TAU_POS](../advanced_config/parameter_reference.md#EKF2_TAU_POS) parameters.
::: info
The 'fusion time horizon' delay and length of the buffers is determined by [EKF2_DELAY_MAX](../advanced_config/parameter_reference.md#EKF2_DELAY_MAX).
This value should be at least as large as the longest delay `EKF2\_\*\_DELAY`.
Reducing the 'fusion time horizon' delay reduces errors in the complementary filter used to propagate states forward to current time.
:::
The EKF uses the IMU data for state prediction only.
IMU data is not used as an observation in the EKF derivation.
The algebraic equations for the covariance prediction and measurement jacobians are derived using [SymForce](https://symforce.org/) and can be found here: [Symbolic Derivation](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/ekf2/EKF/python/ekf_derivation/derivation.py).
Covariance update is done using the [Joseph Stabilized form](https://en.wikipedia.org/wiki/Kalman_filter#Deriving_the_posteriori_estimate_covariance_matrix) to improve numerical stability and allow conditional update of independent states.
### Precisions about the position output
The position is estimated as latitude, longitude and altitude and the INS integration is performed using the WGS84 ellipsoid mode.
However, the position uncertainty is defined in the local navigation frame at the current position (i.e.: NED error in meters).
The position and velocity states are adjusted to account for the offset between the IMU and the body frame before they are output to the control loops.
The position of the IMU relative to the body frame is set by the `EKF2_IMU_POS_X,Y,Z` parameters.
In addition to the global position estimate in latitude/longitude/altitude, the filter also provides a local position estimate (NED in meters) by projecting the global position estimate using an [azimuthal_equidistant_projection](https://en.wikipedia.org/wiki/Azimuthal_equidistant_projection) centred on an arbitrary origin.
This origin is automatically set when global position measurements are fused but can also be specified manually.
If no global position information is provided, only the local position is available and the INS integration is performed on a spherical Earth.
## Running a Single EKF Instance
The _default behaviour_ is to run a single instance of the EKF.
In this case sensor selection and failover is performed before data is received by the EKF.
This provides protection against a limited number of sensor faults, such as loss of data, but does not protect against the sensor providing inaccurate data that exceeds the ability of the EKF and control loops to compensate.
The parameter settings for running a single EKF instance are:
- [EKF2_MULTI_IMU](../advanced_config/parameter_reference.md#EKF2_MULTI_IMU) = 0
- [EKF2_MULTI_MAG](../advanced_config/parameter_reference.md#EKF2_MULTI_MAG) = 0
- [SENS_IMU_MODE](../advanced_config/parameter_reference.md#SENS_IMU_MODE) = 1
- [SENS_MAG_MODE](../advanced_config/parameter_reference.md#SENS_MAG_MODE) = 1
## Running Multiple EKF Instances
Depending on the number of IMUs and magnetometers and the autopilot's CPU capacity, multiple instances of the EKF can be run.
This provides protection against a wider range of sensor errors and is achieved by each EKF instance using a different sensor combination.
By comparing the internal consistency of each EKF instance, the EKF selector is able to determine the EKF and sensor combination with the best data consistency.
This enables faults such as sudden changes in IMU bias, saturation or stuck data to be detected and isolated.
The total number of EKF instances is the product of the number of IMU's and number of magnetometers selected by [EKF2_MULTI_IMU](../advanced_config/parameter_reference.md#EKF2_MULTI_IMU) and [EKF2_MULTI_MAG](../advanced_config/parameter_reference.md#EKF2_MULTI_MAG) and is given by the following formula:
> N_instances = MAX([EKF2_MULTI_IMU](../advanced_config/parameter_reference.md#EKF2_MULTI_IMU) , 1) x MAX([EKF2_MULTI_MAG](../advanced_config/parameter_reference.md#EKF2_MULTI_MAG) , 1)
For example an autopilot with 2 IMUs and 2 magnetometers could run with EKF2_MULTI_IMU = 2 and EKF2_MULTI_MAG = 2 for a total of 4 EKF instances where each instance uses the following combination of sensors:
- EKF instance 1 : IMU 1, magnetometer 1
- EKF instance 2 : IMU 1, magnetometer 2
- EKF instance 3 : IMU 2, magnetometer 1
- EKF instance 4 : IMU 2, magnetometer 2
The maximum number of IMU or magnetometer sensors that can be handled is 4 of each for a theoretical maximum of 4 x 4 = 16 EKF instances.
In practice this is limited by available computing resources.
During development of this feature, testing with STM32F7 CPU based HW demonstrated 4 EKF instances with acceptable processing load and memory utilisation margin.
:::warning
Ground based testing to check CPU and memory utilisation should be performed before flying.
:::
If [EKF2_MULTI_IMU](../advanced_config/parameter_reference.md#EKF2_MULTI_IMU) >= 3, then the failover time for large rate gyro errors is further reduced because the EKF selector is able to apply a median select strategy for faster isolation of the faulty IMU.
The setup for multiple EKF instances is controlled by the following parameters:
- [SENS_IMU_MODE](../advanced_config/parameter_reference.md#SENS_IMU_MODE):
Set to 0 if running multiple EKF instances with IMU sensor diversity, ie [EKF2_MULTI_IMU](../advanced_config/parameter_reference.md#EKF2_MULTI_IMU) > 1.
When set to 1 (default for single EKF operation) the sensor module selects IMU data used by the EKF.
This provides protection against loss of data from the sensor but does not protect against bad sensor data.
When set to 0, the sensor module does not make a selection.
- [SENS_MAG_MODE](../advanced_config/parameter_reference.md#SENS_MAG_MODE):
Set to 0 if running multiple EKF instances with magnetometer sensor diversity, ie [EKF2_MULTI_MAG](../advanced_config/parameter_reference.md#EKF2_MULTI_MAG) > 1.
When set to 1 (default for single EKF operation) the sensor module selects Magnetometer data used by the EKF.
This provides protection against loss of data from the sensor but does not protect against bad sensor data.
When set to 0, the sensor module does not make a selection.
- [EKF2_MULTI_IMU](../advanced_config/parameter_reference.md#EKF2_MULTI_IMU):
This parameter specifies the number of IMU sensors used by the multiple EKF's.
If `EKF2_MULTI_IMU` <= 1, then only the first IMU sensor will be used.
When [SENS_IMU_MODE](../advanced_config/parameter_reference.md#SENS_IMU_MODE) = 1, this will be the sensor selected by the sensor module.
If `EKF2_MULTI_IMU` >= 2, then a separate EKF instance will run for the specified number of IMU sensors up to the lesser of 4 or the number of IMU's present.
- [EKF2_MULTI_MAG](../advanced_config/parameter_reference.md#EKF2_MULTI_MAG):
This parameter specifies the number of magnetometer sensors used by the multiple EKF's
If `EKF2_MULTI_MAG` <= 1, then only the first magnetometer sensor will be used.
When [SENS_MAG_MODE](../advanced_config/parameter_reference.md#SENS_MAG_MODE) = 1, this will be the sensor selected by the sensor module.
If `EKF2_MULTI_MAG` >= 2, then a separate EKF instance will run for the specified number of magnetometer sensors up to the lesser of 4 or the number of magnetometers present.
::: info
The recording and [EKF2 replay](../debug/system_wide_replay.md#ekf2-replay) of flight logs with multiple EKF instances is not supported.
To enable recording for EKF replay you must set the parameters to enable a [single EKF instance](#running-a-single-ekf-instance).
:::
## What sensor measurements does it use?
The EKF has different modes of operation that allow for different combinations of sensor measurements.
On start-up the filter checks for a minimum viable combination of sensors and after initial tilt, yaw and height alignment is completed, enters a mode that provides rotation, vertical velocity, vertical position, IMU delta angle bias and IMU delta velocity bias estimates.
This mode requires IMU data, a source of yaw (magnetometer or external vision) and a source of height data.
This minimum data set is required for all EKF modes of operation.
Other sensor data can then be used to estimate additional states.
### IMU
- Three axis body fixed Inertial Measurement unit delta angle and delta velocity data at a minimum rate of 100Hz.
Note: Coning corrections should be applied to the IMU delta angle data before it is used by the EKF.
### Magnetometer
Three axis body fixed magnetometer data at a minimum rate of 5Hz is required to be considered by the estimator.
::: info
- The magnetometer **biases** are only observable while the drone is rotating
- The true heading is observable when the vehicle is accelerating (linear acceleration) while absolute position or velocity measurements are fused (e.g. GPS).
This means that magnetometer heading measurements are optional after initialization if those conditions are met often enough to constrain the heading drift (caused by gyro bias).
:::
Magnetometer data fusion can be configured using [EKF2_MAG_TYPE](../advanced_config/parameter_reference.md#EKF2_MAG_TYPE):
0. Automatic:
- The magnetometer readings only affect the heading estimate before arming, and the whole attitude after arming.
- Heading and tilt errors are compensated when using this method.
- Incorrect magnetic field measurements can degrade the tilt estimate.
- The magnetometer biases are estimated whenever observable.
1. Magnetic heading:
- Only the heading is corrected.
The tilt estimate is never affected by incorrect magnetic field measurements.
- Tilt errors that could arise when flying without velocity/position aiding are not corrected when using this method.
- The magnetometer biases are estimated whenever observable.
2. Deprecated
3. Deprecated
4. Deprecated
5. None:
- Magnetometer data is never used.
This is useful when the data can never be trusted (e.g.: high current close to the sensor, external anomalies).
- The estimator will use other sources of heading: [GPS heading](#yaw-measurements) or external vision.
- When using GPS measurements without another source of heading, the heading can only be initialized after sufficient horizontal acceleration.
See [Estimate yaw from vehicle movement](#yaw-from-gps-velocity) below.
6. Init only:
- Magnetometer data is only used to initialize the heading estimate.
This is useful when the data can be used before arming but not afterwards (e.g.: high current after the vehicle is armed).
- After initialization, the heading is constrained using other observations.
- Unlike mag type `None`, when combined with GPS measurements, this method allows position controlled modes to run directly during takeoff.
The following selection tree can be used to select the right option:
![EKF mag type selection tree](../../assets/config/ekf/ekf_mag_type_selection_tree.png)
### Height
A source of height data - GPS, barometric pressure, range finder, external vision or a combination of those at a minimum rate of 5Hz is required.
If none of the selected measurements are present, the EKF will not start.
When these measurements have been detected, the EKF will initialise the states and complete the tilt and yaw alignment.
When tilt and yaw alignment is complete, the EKF can then transition to other modes of operation enabling use of additional sensor data:
Each height source can be enabled/disabled using its dedicated control parameter:
- [GNSS/GPS](#gnss-gps): [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL)
- [Barometer](#barometer): [EKF2_BARO_CTRL](../advanced_config/parameter_reference.md#EKF2_BARO_CTRL)
- [Range finder](#range-finder): [EKF2_RNG_CTRL](../advanced_config/parameter_reference.md#EKF2_RNG_CTRL)
- [External vision](#external-vision-system): Enabled when [EKF2_HGT_REF](../advanced_config/parameter_reference.md#EKF2_HGT_REF) is set to "Vision"
Over the long term the height estimate follows the "reference source" of height data.
This reference is defined by the [EKF2_HGT_REF](../advanced_config/parameter_reference.md#EKF2_HGT_REF) parameter.
#### Typical configurations
| | [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) | [EKF2_BARO_CTRL](../advanced_config/parameter_reference.md#EKF2_BARO_CTRL) | [EKF2_RNG_CTRL](../advanced_config/parameter_reference.md#EKF2_RNG_CTRL) | [EKF2_HGT_REF](../advanced_config/parameter_reference.md#EKF2_HGT_REF) |
| ------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| Outdoor (default) | 7 (Lon/lat/alt/vel) | 1 (enabled) | 1 ([conditional](#conditional-range-aiding)) | 1 (GNSS) |
| Indoor (non-flat terrain) | 0 (disabled) | 1 (enabled) | 1 ([conditional](#conditional-range-aiding)) | 2 (range) |
| Indoor (flat terrain) | 0 (disabled) | 1 (enabled) | 2 ([always enabled](#range-height-fusion)) | 2 (range) |
| External vision | As required | As required | As required | 3 (vision) |
### Barometer
Enable/disable using [EKF2_BARO_CTRL](../advanced_config/parameter_reference.md#EKF2_BARO_CTRL) as a source for [Height](#height) data.
Note that data from only one barometer is fused, even if multiple barometers are available.
The barometer with the highest [CAL_BAROx_PRIO](../advanced_config/parameter_reference.md#CAL_BARO0_PRIO) priority value is selected first, falling back to the next highest priority barometer if a sensor fault is detected.
If barometers have equal-highest priorities, the first detected is used.
A barometer can be completely disabled as a possible source by setting its `CAL_BAROx_PRIO` value to `0` (disabled).
See [Height](#height) more details about the configuration of height sources.
#### Correction for Static Pressure Position Error
Barometric pressure altitude is subject to errors generated by aerodynamic disturbances caused by vehicle wind relative velocity and orientation.
This is known in aeronautics as _static pressure position error_.
The EKF2 module that uses the ECL/EKF2 estimator library provides a method of compensating for these errors, provided wind speed state estimation is active.
For vehicles operating in a fixed-wing mode, wind speed state estimation requires either [Airspeed](#airspeed) and/or [Synthetic Sideslip](#synthetic-sideslip) fusion to be enabled.
For multi-rotors, fusion of [Drag Specific Forces](#mc_wind_estimation_using_drag) can be enabled and tuned to provide the required wind velocity state estimates.
The EKF2 module models the error as a body fixed ellipsoid that specifies the fraction of dynamic pressure that is added to/subtracted from the barometric pressure - before it is converted to a height estimate.
A good tuning is obtained as follows:
1. Fly once in [Position mode](../flight_modes_mc/position.md) repeatedly forwards/backwards/left/right/up/down between rest and maximum speed (best results are obtained when this testing is conducted in still conditions).
2. Extract the `.ulg` log file using, for example, [QGroundControl: Analyze > Log Download](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/analyze_view/log_download.html)
::: info
The same log file can be used to tune the [multirotor wind estimator](#mc_wind_estimation_using_drag).
:::
3. Use the log with the [baro_static_pressure_compensation_tuning.py](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/ekf2/EKF/python/tuning_tools/baro_static_pressure_compensation) Python script to obtain the optimal set of parameters.
Tuning parameters:
- [EKF2_PCOEF_XP](../advanced_config/parameter_reference.md#EKF2_PCOEF_XP)
- [EKF2_PCOEF_XN](../advanced_config/parameter_reference.md#EKF2_PCOEF_XN)
- [EKF2_PCOEF_YP](../advanced_config/parameter_reference.md#EKF2_PCOEF_YP)
- [EKF2_PCOEF_YN](../advanced_config/parameter_reference.md#EKF2_PCOEF_YN)
- [EKF2_PCOEF_Z](../advanced_config/parameter_reference.md#EKF2_PCOEF_Z)
#### Barometer bias compensation
A barometer at a constant altitude is subject to drift in its measurements due to changes in the ambient pressure environment or variations of the sensor temperature.
To compensate for this measurement error, EKF2 estimates the bias using GNSS height (if available) a "non drifting" reference.
No tuning is required.
### GNSS/GPS
#### Position and Velocity Measurements
GPS measurements will be used for position and velocity if the following conditions are met:
- GPS use is enabled via setting of the [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) parameter.
- GPS quality checks have passed.
These checks are controlled by the [EKF2_GPS_CHECK](../advanced_config/parameter_reference.md#EKF2_GPS_CHECK) and `EKF2_REQ_*` parameters.
For more details about the configuration of height sources, [click here](#height).
#### Yaw Measurements
Some GPS receivers such as the [Trimble MB-Two RTK GPS receiver](https://www.trimble.com/Precision-GNSS/MB-Two-Board.aspx) can be used to provide a heading measurement that replaces the use of magnetometer data.
This can be a significant advantage when operating in an environment where large magnetic anomalies are present, or at latitudes here the earth's magnetic field has a high inclination.
Use of GPS yaw measurements is enabled by setting bit position 3 to 1 (adding 8) in the [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) parameter.
#### Yaw From GPS Velocity
The EKF runs an additional multi-hypothesis filter internally that uses multiple 3-state Extended Kalman Filters (EKF's) whose states are NE velocity and yaw angle.
These individual yaw angle estimates are then combined using a Gaussian Sum Filter (GSF).
The individual 3-state EKF's use IMU and GPS horizontal velocity data (plus optional airspeed data) and do not rely on any prior knowledge of the yaw angle or magnetometer measurements.
This provides a backup to the yaw from the main filter and is used to reset the yaw for the main 24-state EKF when a post-takeoff loss of navigation indicates that the yaw estimate from the magnetometer is bad.
This will result in an `Emergency yaw reset - magnetometer use stopped` message information message at the GCS.
Data from this estimator is logged when ekf2 replay logging is enabled and can be viewed in the `yaw_estimator_status` message.
The individual yaw estimates from the individual 3-state EKF yaw estimators are in the `yaw` fields.
The GSF combined yaw estimate is in the `yaw_composite` field.
The variance for the GSF yaw estimate is in the `yaw_variance` field.
All angles are in radians.
Weightings applied by the GSF to the individual 3-state EKF outputs are in the`weight` fields.
This also makes it possible to operate without any magnetometer data or dual antenna GPS receiver for yaw provided some horizontal movement after takeoff can be performed to enable the yaw to become observable.
To use this feature, set [EKF2_MAG_TYPE](../advanced_config/parameter_reference.md#EKF2_MAG_TYPE) to `none` (5) to disable magnetometer use.
Once the vehicle has performed sufficient horizontal movement to make the yaw observable, the main 24-state EKF will align it's yaw to the GSF estimate and commence use of GPS.
#### Dual Receivers
Data from GPS receivers can be blended using an algorithm that weights data based on reported accuracy (this works best if both receivers output data at the same rate and use the same accuracy).
The mechanism also provides automatic failover if data from a receiver is lost (it allows, for example, a standard GPS to be used as a backup to a more accurate RTK receiver).
This is controlled by the [SENS_GPS_MASK](../advanced_config/parameter_reference.md#SENS_GPS_MASK) parameter.
The [SENS_GPS_MASK](../advanced_config/parameter_reference.md#SENS_GPS_MASK) parameter is set by default to disable blending and always use the first receiver, so it will have to be set to select which receiver accuracy metrics are used to decide how much each receiver output contributes to the blended solution.
Where different receiver models are used, it is important that the [SENS_GPS_MASK](../advanced_config/parameter_reference.md#SENS_GPS_MASK) parameter is set to a value that uses accuracy metrics that are supported by both receivers.
For example do not set bit position 0 to `true` unless the drivers for both receivers publish values in the `s_variance_m_s` field of the `vehicle_gps_position` message that are comparable.
This can be difficult with receivers from different manufacturers due to the different way that accuracy is defined, e.g. CEP vs 1-sigma, etc.
The following items should be checked during setup:
- Verify that data for the second receiver is present.
This will be logged as `vehicle_gps_position_1` and can also be checked when connected via the _nsh console_ using the command `listener vehicle_gps_position -i 1`.
The [GPS_2_CONFIG](../advanced_config/parameter_reference.md#GPS_2_CONFIG) parameter will need to be set correctly.
- Check the `s_variance_m_s`, `eph` and `epv` data from each receiver and decide which accuracy metrics can be used.
If both receivers output sensible `s_variance_m_s` and `eph` data, and GPS vertical position is not being used directly for navigation, then setting [SENS_GPS_MASK](../advanced_config/parameter_reference.md#SENS_GPS_MASK) to 3 is recommended.
Where only `eph` data is available and both receivers do not output `s_variance_m_s` data, set [SENS_GPS_MASK](../advanced_config/parameter_reference.md#SENS_GPS_MASK) to 2.
Bit position 2 would only be set if the GPS had been selected as the reference height source with the [EKF2_HGT_REF](../advanced_config/parameter_reference.md#EKF2_HGT_REF) parameter and both receivers output sensible `epv` data.
- The output from the blended receiver data is logged as `ekf_gps_position`, and can be checked whilst connect via the nsh terminal using the command `listener ekf_gps_position`.
- Where receivers output at different rates, the blended output will be at the rate of slower receiver.
Where possible receivers should be configured to output at the same rate.
#### GNSS Performance Requirements
For the ECL to accept GNSS data for navigation, certain minimum requirements need to be satisfied over a period of time, defined by [EKF2_REQ_GPS_H](../advanced_config/parameter_reference.md#EKF2_REQ_GPS_H) (10 seconds by default).
Minima are defined in the [EKF2*REQ*\*](../advanced_config/parameter_reference.md#EKF2_REQ_EPH) parameters and each check can be enabled/disabled using the [EKF2_GPS_CHECK](../advanced_config/parameter_reference.md#EKF2_GPS_CHECK) parameter.
The table below shows the different metrics directly reported or calculated from the GNSS data, and the minimum required values for the data to be used by ECL.
In addition, the _Average Value_ column shows typical values that might reasonably be obtained from a standard GNSS module (e.g. u-blox M8 series) - i.e. values that are considered good/acceptable.
| Metric | Minimum required | Average Value | Units | Notes |
| -------------------- | ----------------------------------------------------------------------------------------- | ------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| eph | <&nbsp;3 ([EKF2_REQ_EPH](../advanced_config/parameter_reference.md#EKF2_REQ_EPH)) | 0.8 | m | Standard deviation of horizontal position error |
| epv | <&nbsp;5 ([EKF2_REQ_EPV](../advanced_config/parameter_reference.md#EKF2_REQ_EPV)) | 1.5 | m | Standard deviation of vertical position error |
| Number of satellites | ≥6&nbsp;([EKF2_REQ_NSATS](../advanced_config/parameter_reference.md#EKF2_REQ_NSATS)) | 14 | - |
| sacc | <&nbsp;0.5 ([EKF2_REQ_SACC](../advanced_config/parameter_reference.md#EKF2_REQ_SACC)) | 0.2 | m/s | Standard deviation of horizontal speed error |
| fix type | ≥&nbsp;3 | 4 | - | 0-1: no fix, 2: 2D fix, 3: 3D fix, 4: RTCM code differential, 5: Real-Time Kinematic, float, 6: Real-Time Kinematic, fixed, 8: Extrapolated |
| PDOP | <&nbsp;2.5 ([EKF2_REQ_PDOP](../advanced_config/parameter_reference.md#EKF2_REQ_PDOP)) | 1.0 | - | Position dilution of precision |
| hpos drift rate | <&nbsp;0.1 ([EKF2_REQ_HDRIFT](../advanced_config/parameter_reference.md#EKF2_REQ_HDRIFT)) | 0.01 | m/s | Drift rate calculated from reported GNSS position (when stationary). |
| vpos drift rate | <&nbsp;0.2 ([EKF2_REQ_VDRIFT](../advanced_config/parameter_reference.md#EKF2_REQ_VDRIFT)) | 0.02 | m/s | Drift rate calculated from reported GNSS altitude (when stationary). |
| hspd | <&nbsp;0.1 ([EKF2_REQ_HDRIFT](../advanced_config/parameter_reference.md#EKF2_REQ_HDRIFT)) | 0.01 | m/s | Filtered magnitude of reported GNSS horizontal velocity. |
| vspd | <&nbsp;0.2 ([EKF2_REQ_VDRIFT](../advanced_config/parameter_reference.md#EKF2_REQ_VDRIFT)) | 0.02 | m/s | Filtered magnitude of reported GNSS vertical velocity. |
::: info
The `hpos_drift_rate`, `vpos_drift_rate` and `hspd` are calculated over a period of 10 seconds and published in the `ekf2_gps_drift` topic.
Note that `ekf2_gps_drift` is not logged!
:::
### Range Finder
[Range finder](../sensor/rangefinders.md) distance to ground is used by a single state filter to estimate the vertical position of the terrain relative to the height datum.
The fusion modes of operation are controlled by [EKF2_RNG_CTRL](../advanced_config/parameter_reference.md#EKF2_RNG_CTRL):
1. [Conditional range aiding](#conditional-range-aiding)
1. [Range height fusion](#range-height-fusion)
For more details about the configuration of height sources, [click here](#height).
#### Conditional range aiding
Conditional range finder fusion (a.k.a. _Conditional range aid_) activates the range finder fusion for height estimation during low speed/low altitude operation (in addition to the other active height sources).
If the range finder is set as the reference height source (using [EKF2_HGT_REF](../advanced_config/parameter_reference.md#EKF2_HGT_REF)), the other active height sources such as baro and GNSS altitude will adjust their measurement to match the readings of the range finder over time.
When the conditions are not met to start range aiding, a secondary reference is automatically selected.
::: info
Switching between height references causes the absolute altitude estimate to drift over time.
This isn't an issue when flying in position mode but can be problematic if the drone is supposed to fly a mission at a specific GNSS altitude.
If the absolute altitude drift is unwanted, it is recommended to set the GNSS altitude as the height reference, even when using conditional range aid.
:::
It is primarily intended for _takeoff and landing_, in cases where the barometer setup is such that interference from rotor wash is excessive and can corrupt EKF state estimates.
Range aid may also be used to improve altitude hold when the vehicle is stationary.
:::tip
[Terrain Hold](../flying/terrain_following_holding.md#terrain_hold) is recommended over _Range Aid_ for terrain holding.
This is because terrain hold uses the normal ECL/EKF estimator for determining height, and this is generally more reliable than a distance sensor in most conditions.
:::
_Conditional range aid_ is enabled by setting [EKF2_RNG_CTRL](../advanced_config/parameter_reference.md#EKF2_RNG_CTRL) = "Enabled (conditional mode)" (1).
It is further configured using the `EKF2_RNG_A_` parameters:
- [EKF2_RNG_A_VMAX](../advanced_config/parameter_reference.md#EKF2_RNG_A_VMAX): Maximum horizontal speed, above which range aid is disabled.
- [EKF2_RNG_A_HMAX](../advanced_config/parameter_reference.md#EKF2_RNG_A_HMAX): Maximum height, above which range aid is disabled.
- [EKF2_RNG_A_IGATE](../advanced_config/parameter_reference.md#EKF2_RNG_A_IGATE): Range aid consistency checks "gate" (a measure of the error before range aid is disabled).
#### Range height fusion
PX4 allows you to continuously fuse the range finder as a source of height (in any flight mode/vehicle type).
This may be useful for applications when the vehicle is _guaranteed_ to only fly over a near-flat surface (e.g. indoors).
When using a distance sensor as a height source, fliers should be aware:
- Flying over obstacles can lead to the estimator rejecting rangefinder data (due to internal data consistency checks), which can result in poor altitude holding while the estimator is relying purely on accelerometer estimates.
::: info
This scenario might occur when a vehicle ascends a slope at a near-constant height above ground, because the rangefinder altitude does not change while that estimated from the accelerometer does.
The EKF performs innovation consistency checks that take into account the error between measurement and current state as well as the estimated variance of the state and the variance of the measurement itself.
If the checks fail the rangefinder data will be rejected, and the altitude will be estimated from the accelerometer and the other selected height sources (GNSS, baro, vision), if enabled and available
After 5 seconds of inconsistent data if the distance sensor is the active source oh height data, the estimator resets the height state to match the current distance sensor data.
If one or more other sources of height are active, the range finder is declared faulty and the estimator continues to estimate its height using the other sensors.
The measurements might also become consistent again, for example, if the vehicle descends, or if the estimated height drifts to match the measured rangefinder height.
:::
- The local NED origin will move up and down with ground level.
- Rangefinder performance over uneven surfaces (e.g. trees) can be very poor, resulting in noisy and inconsistent data.
This again leads to poor altitude hold.
The feature is enabled by setting [EKF2_RNG_CTRL](../advanced_config/parameter_reference.md#EKF2_RNG_CTRL) to "Enabled" (2).
To make the range finder the height reference when active, set: [EKF2_HGT_REF](../advanced_config/parameter_reference.md#EKF2_HGT_REF) to "Range sensor".
:::tip
To enable the range finder fusion only when the drone is stationary (in order to benefit from a better altitude estimate during takeoff and landing) but not fuse the range finder the rest of the time, use the [conditional mode](#conditional-range-aiding) (1) of [EKF2_RNG_CTRL](../advanced_config/parameter_reference.md#EKF2_RNG_CTRL).
:::
#### Range Finder Obstruction Detection
The EKF can detect whether the rangefinder path-to-ground is obstructed (perhaps by a payload) using a kinematic consistency check between the vertical velocity estimate and the numerical derivative of the range finder data.
If the range finder is statistically inconsistent with EKF2, the sensor is rejected for the rest of the flight unless the statistical test passes again for at least 1 second at a vertical speed of 0.5m/s or more.
The check is only enabled when the rangefinder is not used as the primary height source, and is only active while the vehicle is not moving horizontally (as it assumes a static ground height).
For effective obstruction detection, the range finder noise parameter needs to be tightly tuned using flight data.
The kinematic consistency gate parameter can then be adjusted to obtain the desired fault detection sensitivity.
Tuning parameters:
- [EKF2_RNG_NOISE](../advanced_config/parameter_reference.md#EKF2_RNG_NOISE)
- [EKF2_RNG_K_GATE](../advanced_config/parameter_reference.md#EKF2_RNG_K_GATE)
### Airspeed
Equivalent Airspeed (EAS) data can be used to estimate wind velocity and reduce drift when GPS is lost by setting [EKF2_ARSP_THR](../advanced_config/parameter_reference.md#EKF2_ARSP_THR) to a positive value.
Airspeed data will be used when it exceeds the threshold set by a positive value for [EKF2_ARSP_THR](../advanced_config/parameter_reference.md#EKF2_ARSP_THR) and the vehicle type is not rotary wing.
### Synthetic Sideslip
Fixed-wing platforms can take advantage of an assumed sideslip observation of zero to improve wind speed estimation and also enable wind speed estimation without an airspeed sensor.
This is enabled by setting the [EKF2_FUSE_BETA](../advanced_config/parameter_reference.md#EKF2_FUSE_BETA) parameter to 1.
<a id="mc_wind_estimation_using_drag"></a>
### Multicopter Wind Estimation using Drag Specific Forces
Multi-rotor platforms can take advantage of the relationship between airspeed and drag force along the X and Y body axes to estimate North/East components of wind velocity.
This can be enabled using [EKF2_DRAG_CTRL](../advanced_config/parameter_reference.md#EKF2_DRAG_CTRL).
The relationship between airspeed and specific force (IMU accelerometer measurements) along the X and Y body axes is controlled by the [EKF2_BCOEF_X](../advanced_config/parameter_reference.md#EKF2_BCOEF_X), [EKF2_BCOEF_Y](../advanced_config/parameter_reference.md#EKF2_BCOEF_Y) and [EKF2_MCOEF](../advanced_config/parameter_reference.md#EKF2_MCOEF) parameters which set the ballistic coefficients for flight in the X and Y directions, and the momentum drag produced by the propellers, respectively.
The amount of specific force observation noise is set by the [EKF2_DRAG_NOISE](../advanced_config/parameter_reference.md#EKF2_DRAG_NOISE) parameter.
A good tuning is obtained as follows:
1. Fly once in [Position mode](../flight_modes_mc/position.md) repeatedly forwards/backwards/left/right/up/down between rest and maximum speed (best results are obtained when this testing is conducted in still conditions).
2. Extract the **.ulg** log file using, for example, [QGroundControl: Analyze > Log Download](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/analyze_view/log_download.html)
::: info
The same **.ulg** log file can also be used to tune the [static pressure position error coefficients](#correction-for-static-pressure-position-error).
:::
3. Use the log with the [mc_wind_estimator_tuning.py](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/ekf2/EKF/python/tuning_tools/mc_wind_estimator) Python script to obtain the optimal set of parameters.
### Optical Flow
[Optical flow](../sensor/optical_flow.md) data will be used if the following conditions are met:
- Valid range finder data is available.
- [EKF2_OF_CTRL](../advanced_config/parameter_reference.md#EKF2_OF_CTRL) is set.
- The quality metric returned by the flow sensor is greater than the minimum requirement set by the [EKF2_OF_QMIN](../advanced_config/parameter_reference.md#EKF2_OF_QMIN) parameter.
For better performance, set the location of the optical flow sensor as described [here](../sensor/optical_flow.md#ekf2).
If a stable hover can be achieved at low altitude above ground (< 10m) but slow oscillations occur at higher altitude, consider adjusting the [optical flow scale factor](../sensor/optical_flow.md#scale-factor).
### External Vision System
Position, velocity or orientation measurements from an external vision system, e.g. Vicon, can be used.
The measurements that are fused are configured by setting the appropriate bits of [EKF2_EV_CTRL](../advanced_config/parameter_reference.md#EKF2_EV_CTRL) to `true`:
- `0`: Horizontal position data
- `1`: Vertical position data.
Height sources may additionally be configured using [EKF2_HGT_REF](../advanced_config/parameter_reference.md#EKF2_HGT_REF) (see section [Height](#height)).
- `2`: Velocity data
- `3`: Yaw data
Note that if yaw data is used (bit 3) the heading is with respect to the external vision frame; otherwise the heading is relative to North.
The EKF considers uncertainty in the visual pose estimate.
This uncertainty information can be sent via the covariance fields in the MAVLink [ODOMETRY](https://mavlink.io/en/messages/common.html#ODOMETRY) message or it can be set through the parameters [EKF2_EVP_NOISE](../advanced_config/parameter_reference.md#EKF2_EVP_NOISE), [EKF2_EVV_NOISE](../advanced_config/parameter_reference.md#EKF2_EVV_NOISE) and [EKF2_EVA_NOISE](../advanced_config/parameter_reference.md#EKF2_EVA_NOISE).
You can choose the source of the uncertainty with [EKF2_EV_NOISE_MD](../advanced_config/parameter_reference.md#EKF2_EV_NOISE_MD).
## How do I use the 'ecl' library EKF?
EKF2 is enabled by default (for more information see [Switching State Estimators](../advanced/switching_state_estimators.md) and [EKF2_EN](../advanced_config/parameter_reference.md#EKF2_EN)).
## What are the advantages and disadvantages of the ecl EKF over other estimators?
Like all estimators, much of the performance comes from the tuning to match sensor characteristics.
Tuning is a compromise between accuracy and robustness and although we have attempted to provide a tune that meets the needs of most users, there will be applications where tuning changes are required.
For this reason, no claims for accuracy relative to the legacy combination of `attitude_estimator_q` + `local_position_estimator` have been made and the best choice of estimator will depend on the application and tuning.
### Disadvantages
- The ecl EKF is a complex algorithm that requires a good understanding of extended Kalman filter theory and its application to navigation problems to tune successfully.
It is therefore more difficult for users that are not achieving good results to know what to change.
- The ecl EKF uses more RAM and flash space.
- The ecl EKF uses more logging space.
### Advantages
- The ecl EKF is able to fuse data from sensors with different time delays and data rates in a mathematically consistent way which improves accuracy during dynamic maneuvers once time delay parameters are set correctly.
- The ecl EKF is capable of fusing a large range of different sensor types.
- The ecl EKF detects and reports statistically significant inconsistencies in sensor data, assisting with diagnosis of sensor errors.
- For fixed-wing operation, the ecl EKF estimates wind speed with or without an airspeed sensor and is able to use the estimated wind in combination with airspeed measurements and sideslip assumptions to extend the dead-reckoning time available if GPS is lost in flight.
- The ecl EKF estimates 3-axis accelerometer bias which improves accuracy for tailsitters and other vehicles that experience large attitude changes between flight phases.
- The federated architecture (combined attitude and position/velocity estimation) means that attitude estimation benefits from all sensor measurements.
This should provide the potential for improved attitude estimation if tuned correctly.
## How do I check the EKF performance?
EKF outputs, states and status data are published to a number of uORB topics which are logged to the SD card during flight.
The following guide assumes that data has been logged using the _.ulog file format_.
The **.ulog** format data can be parsed in python by using the [PX4 pyulog library](https://github.com/PX4/pyulog).
Most of the EKF data is found in the [EstimatorInnovations](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorInnovations.msg) and [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg) uORB messages that are logged to the .ulog file.
A python script that automatically generates analysis plots and metadata can be found [here](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/ecl_ekf/process_logdata_ekf.py).
To use this script file, cd to the `Tools/ecl_ekf` directory and enter `python process_logdata_ekf.py <log_file.ulg>`.
This saves performance metadata in a csv file named **<log_file>.mdat.csv** and plots in a pdf file named `<log_file>.pdf`.
Multiple log files in a directory can be analysed using the [batch_process_logdata_ekf.py](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/ecl_ekf/batch_process_logdata_ekf.py) script.
When this has been done, the performance metadata files can be processed to provide a statistical assessment of the estimator performance across the population of logs using the [batch_process_metadata_ekf.py](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/ecl_ekf/batch_process_metadata_ekf.py) script.
### Output Data
- Attitude output data is found in the [VehicleAttitude](https://github.com/PX4/PX4-Autopilot/blob/main/msg/VehicleAttitude.msg) message.
- Local position output data is found in the [VehicleLocalPosition](https://github.com/PX4/PX4-Autopilot/blob/main/msg/VehicleLocalPosition.msg) message.
- Global \(WGS-84\) output data is found in the [VehicleGlobalPosition](https://github.com/PX4/PX4-Autopilot/blob/main/msg/VehicleGlobalPosition.msg) message.
- Wind velocity output data is found in the [Wind.msg](https://github.com/PX4/PX4-Autopilot/blob/main/msg/Wind.msg) message.
### States
Refer to states\[24\] in [EstimatorStates](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStates.msg).
The index map for states\[24\] is as follows:
- \[0 ... 3\] Quaternions
- \[4 ... 6\] Velocity NED \(m/s\)
- \[7 ... 9\] Position NED \(m\)
- \[10 ... 12\] IMU delta angle bias XYZ \(rad\)
- \[13 ... 15\] IMU delta velocity bias XYZ \(m/s\)
- \[16 ... 18\] Earth magnetic field NED \(gauss\)
- \[19 ... 21\] Body magnetic field XYZ \(gauss\)
- \[22 ... 23\] Wind velocity NE \(m/s\)
### State Variances
Refer to covariances\[24\] in [EstimatorStates](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStates.msg).
The index map for covariances\[24\] is as follows:
- \[0 ... 3\] Quaternions
- \[4 ... 6\] Velocity NED \(m/s\)^2
- \[7 ... 9\] Position NED \(m^2\)
- \[10 ... 12\] IMU delta angle bias XYZ \(rad^2\)
- \[13 ... 15\] IMU delta velocity bias XYZ \(m/s\)^2
- \[16 ... 18\] Earth magnetic field NED \(gauss^2\)
- \[19 ... 21\] Body magnetic field XYZ \(gauss^2\)
- \[22 ... 23\] Wind velocity NE \(m/s\)^2
### Observation Innovations & Innovation Variances
The observation `estimator_innovations`, `estimator_innovation_variances`, and `estimator_innovation_test_ratios` message fields are defined in [EstimatorInnovations.msg](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorInnovations.msg).
The messages all have the same field names/types (but different units).
::: info
The messages have the same fields because they are generated from the same field definition.
The `# TOPICS` line (at the end of [the file](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorInnovations.msg)) lists the names of the set of messages to be created):
```
# TOPICS estimator_innovations estimator_innovation_variances estimator_innovation_test_ratios
```
:::
Some of the observations are:
- Magnetometer XYZ (gauss, gauss^2) : `mag_field[3]`
- Yaw angle (rad, rad^2) : `heading`
- True Airspeed (m/s, (m/s)^2) : `airspeed`
- Synthetic sideslip (rad, rad^2) : `beta`
- Optical flow XY (rad/sec, (rad/s)^2) : `flow`
- Height above ground (m, m^2) : `hagl`
- Drag specific force ((m/s)^2): `drag`
- Velocity and position innovations : per sensor
In addition, each sensor has its own fields for horizontal and vertical position and/or velocity values (where appropriate).
These are largely self documenting, and are reproduced below:
```
# GPS
float32[2] gps_hvel # horizontal GPS velocity innovation (m/sec) and innovation variance ((m/sec)**2)
float32 gps_vvel # vertical GPS velocity innovation (m/sec) and innovation variance ((m/sec)**2)
float32[2] gps_hpos # horizontal GPS position innovation (m) and innovation variance (m**2)
float32 gps_vpos # vertical GPS position innovation (m) and innovation variance (m**2)
# External Vision
float32[2] ev_hvel # horizontal external vision velocity innovation (m/sec) and innovation variance ((m/sec)**2)
float32 ev_vvel # vertical external vision velocity innovation (m/sec) and innovation variance ((m/sec)**2)
float32[2] ev_hpos # horizontal external vision position innovation (m) and innovation variance (m**2)
float32 ev_vpos # vertical external vision position innovation (m) and innovation variance (m**2)
# Fake Position and Velocity
float32[2] fake_hvel # fake horizontal velocity innovation (m/s) and innovation variance ((m/s)**2)
float32 fake_vvel # fake vertical velocity innovation (m/s) and innovation variance ((m/s)**2)
float32[2] fake_hpos # fake horizontal position innovation (m) and innovation variance (m**2)
float32 fake_vpos # fake vertical position innovation (m) and innovation variance (m**2)
# Height sensors
float32 rng_vpos # range sensor height innovation (m) and innovation variance (m**2)
float32 baro_vpos # barometer height innovation (m) and innovation variance (m**2)
# Auxiliary velocity
float32[2] aux_hvel # horizontal auxiliary velocity innovation from landing target measurement (m/sec) and innovation variance ((m/sec)**2)
float32 aux_vvel # vertical auxiliary velocity innovation from landing target measurement (m/sec) and innovation variance ((m/sec)**2)
```
### Output Complementary Filter
The output complementary filter is used to propagate states forward from the fusion time horizon to current time.
To check the magnitude of the angular, velocity and position tracking errors measured at the fusion time horizon, refer to `output_tracking_error[3]` in the `ekf2_innovations` message.
The index map is as follows:
- [0] Angular tracking error magnitude (rad)
- [1] Velocity tracking error magnitude (m/s).
The velocity tracking time constant can be adjusted using the [EKF2_TAU_VEL](../advanced_config/parameter_reference.md#EKF2_TAU_VEL) parameter.
Reducing this parameter reduces steady state errors but increases the amount of observation noise on the NED velocity outputs.
- [2] Position tracking error magnitude \(m\).
The position tracking time constant can be adjusted using the [EKF2_TAU_POS](../advanced_config/parameter_reference.md#EKF2_TAU_POS) parameter.
Reducing this parameter reduces steady state errors but increases the amount of observation noise on the NED position outputs.
### EKF Errors
The EKF contains internal error checking for badly conditioned state and covariance updates.
Refer to the `filter_fault_flags` in [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).
### Observation Errors
There are two categories of observation faults:
- Loss of data.
An example of this is a range finder failing to provide a return.
- The innovation, which is the difference between the state prediction and sensor observation is excessive.
An example of this is excessive vibration causing a large vertical position error, resulting in the barometer height measurement being rejected.
Both of these can result in observation data being rejected for long enough to cause the EKF to attempt a reset of the states using the sensor observations.
All observations have a statistical confidence checks applied to the innovations.
The number of standard deviations for the check are controlled by the `EKF2_*_GATE` parameter for each observation type.
Test levels are available in [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg) as follows:
- `mag_test_ratio`: ratio of the largest magnetometer innovation component to the innovation test limit
- `vel_test_ratio`: ratio of the largest velocity innovation component to the innovation test limit
- `pos_test_ratio`: ratio of the largest horizontal position innovation component to the innovation test limit
- `hgt_test_ratio`: ratio of the vertical position innovation to the innovation test limit
- `tas_test_ratio`: ratio of the true airspeed innovation to the innovation test limit
- `hagl_test_ratio`: ratio of the height above ground innovation to the innovation test limit
For a binary pass/fail summary for each sensor, refer to innovation_check_flags in [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).
### GPS Quality Checks
The EKF applies a number of GPS quality checks before commencing GPS aiding.
These checks are controlled by the [EKF2_GPS_CHECK](../advanced_config/parameter_reference.md#EKF2_GPS_CHECK) and `EKF2_REQ_*` parameters.
The pass/fail status for these checks is logged in the [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).gps_check_fail_flags message.
This integer will be zero when all required GPS checks have passed.
If the EKF is not commencing GPS alignment, check the value of the integer against the bitmask definition `gps_check_fail_flags` in [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).
### EKF Numerical Errors
The EKF uses single precision floating point operations for all of its computations and first order approximations for derivation of the covariance prediction and update equations in order to reduce processing requirements.
This means that it is possible when re-tuning the EKF to encounter conditions where the covariance matrix operations become badly conditioned enough to cause divergence or significant errors in the state estimates.
To prevent this, every covariance and state update step contains the following error detection and correction steps:
- If the innovation variance is less than the observation variance (this requires a negative state variance which is impossible) or the covariance update will produce a negative variance for any of the states, then:
- The state and covariance update is skipped
- The corresponding rows and columns in the covariance matrix are reset
- The failure is recorded in the [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg) `filter_fault_flags` message
- State variances (diagonals in the covariance matrix) are constrained to be non-negative.
- An upper limit is applied to state variances.
- Symmetry is forced on the covariance matrix.
After re-tuning the filter, particularly re-tuning that involve reducing the noise variables, the value of `estimator_status.gps_check_fail_flags` should be checked to ensure that it remains zero.
## What should I do if the height estimate is diverging?
The most common cause of EKF height diverging away from GPS and altimeter measurements during flight is clipping and/or aliasing of the IMU measurements caused by vibration.
If this is occurring, then the following signs should be evident in the data
- [EstimatorInnovations](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorInnovations.msg).vel_pos_innov\[2\] and [EstimatorInnovations](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorInnovations.msg).vel_pos_innov\[5\] will both have the same sign.
- [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).hgt_test_ratio will be greater than 1.0
The recommended first step is to ensure that the autopilot is isolated from the airframe using an effective isolation mounting system.
An isolation mount has 6 degrees of freedom, and therefore 6 resonant frequencies.
As a general rule, the 6 resonant frequencies of the autopilot on the isolation mount should be above 25Hz to avoid interaction with the autopilot dynamics and below the frequency of the motors.
An isolation mount can make vibration worse if the resonant frequencies coincide with motor or propeller blade passage frequencies.
The EKF can be made more resistant to vibration induced height divergence by making the following parameter changes:
- Double the value of the innovation gate for the primary height sensor.
If using barometric height this is [EKF2_BARO_GATE](../advanced_config/parameter_reference.md#EKF2_BARO_GATE).
- Increase the value of [EKF2_ACC_NOISE](../advanced_config/parameter_reference.md#EKF2_ACC_NOISE) to 0.5 initially.
If divergence is still occurring, increase in further increments of 0.1 but do not go above 1.0
Note that the effect of these changes will make the EKF more sensitive to errors in GPS vertical velocity and barometric pressure.
## What should I do if the position estimate is diverging?
The most common causes of position divergence are:
- High vibration levels.
- Fix by improving mechanical isolation of the autopilot.
- Increasing the value of [EKF2_ACC_NOISE](../advanced_config/parameter_reference.md#EKF2_ACC_NOISE) and [EKF2_GYR_NOISE](../advanced_config/parameter_reference.md#EKF2_GYR_NOISE) can help, but does make the EKF more vulnerable to GPS glitches.
- Large gyro bias offsets.
- Fix by re-calibrating the gyro.
Check for excessive temperature sensitivity (&gt; 3 deg/sec bias change during warm-up from a cold start and replace the sensor if affected of insulate to slow the rate of temperature change.
- Bad yaw alignment
- Check the magnetometer calibration and alignment.
- Check the heading shown QGC is within 15 deg truth
- Poor GPS accuracy
- Check for interference
- Improve separation and shielding
- Check flying location for GPS signal obstructions and reflectors \(nearby tall buildings\)
- Loss of GPS
Determining which of these is the primary cause requires a methodical approach to analysis of the EKF log data:
- Plot the velocity innovation test ratio - [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).vel_test_ratio
- Plot the horizontal position innovation test ratio - [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).pos_test_ratio
- Plot the height innovation test ratio - [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).hgt_test_ratio
- Plot the magnetometer innovation test ratio - [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).mag_test_ratio
- Plot the GPS receiver reported speed accuracy - [SensorGps.msg](https://github.com/PX4/PX4-Autopilot/blob/main/msg/SensorGps.msg).s_variance_m_s
- Plot the IMU delta angle state estimates - [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).states\[10\], states\[11\] and states\[12\]
- Plot the EKF internal high frequency vibration metrics:
- Delta angle coning vibration - [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).vibe\[0\]
- High frequency delta angle vibration - [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).vibe\[1\]
- High frequency delta velocity vibration - [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).vibe\[2\]
During normal operation, all the test ratios should remain below 0.5 with only occasional spikes above this as shown in the example below from a successful flight:
![Position, Velocity, Height and Magnetometer Test Ratios](../../assets/ecl/test_ratios_-_successful.png)
The following plot shows the EKF vibration metrics for a multirotor with good isolation.
The landing shock and the increased vibration during takeoff and landing can be seen.
Insufficient data has been gathered with these metrics to provide specific advice on maximum thresholds.
![Vibration metrics - successful](../../assets/ecl/vibration_metrics_-_successful.png)
The above vibration metrics are of limited value as the presence of vibration at a frequency close to the IMU sampling frequency (1 kHz for most boards) will cause offsets to appear in the data that do not show up in the high frequency vibration metrics.
The only way to detect aliasing errors is in their effect on inertial navigation accuracy and the rise in innovation levels.
In addition to generating large position and velocity test ratios of &gt; 1.0, the different error mechanisms affect the other test ratios in different ways:
### Determination of Excessive Vibration
High vibration levels normally affect vertical position and velocity innovations as well as the horizontal components.
Magnetometer test levels are only affected to a small extent.
\(insert example plots showing bad vibration here\)
### Determination of Excessive Gyro Bias
Large gyro bias offsets are normally characterised by a change in the value of delta angle bias greater than 5E-4 during flight (equivalent to ~3 deg/sec) and can also cause a large increase in the magnetometer test ratio if the yaw axis is affected.
Height is normally unaffected other than extreme cases.
Switch on bias value of up to 5 deg/sec can be tolerated provided the filter is given time settle before flying.
Pre-flight checks performed by the commander should prevent arming if the position is diverging.
\(insert example plots showing bad gyro bias here\)
### Determination of Poor Yaw Accuracy
Bad yaw alignment causes a velocity test ratio that increases rapidly when the vehicle starts moving due inconsistency in the direction of velocity calculated by the inertial nav and the GPS measurement.
Magnetometer innovations are slightly affected.
Height is normally unaffected.
\(insert example plots showing bad yaw alignment here\)
### Determination of Poor GPS Accuracy
Poor GPS accuracy is normally accompanied by a rise in the reported velocity error of the receiver in conjunction with a rise in innovations.
Transient errors due to multipath, obscuration and interference are more common causes.
Here is an example of a temporary loss of GPS accuracy where the multi-rotor started drifting away from its loiter location and had to be corrected using the sticks.
The rise in [EstimatorStatus](https://github.com/PX4/PX4-Autopilot/blob/main/msg/EstimatorStatus.msg).vel_test_ratio to greater than 1 indicates the GPs velocity was inconsistent with other measurements and has been rejected.
![GPS glitch - test ratios](../../assets/ecl/gps_glitch_-_test_ratios.png)
This is accompanied with rise in the GPS receivers reported velocity accuracy which indicates that it was likely a GPS error.
![GPS Glitch - reported receiver accuracy](../../assets/ecl/gps_glitch_-_reported_receiver_accuracy.png)
If we also look at the GPS horizontal velocity innovations and innovation variances, we can see the large spike in North velocity innovation that accompanies this GPS 'glitch' event.
![GPS Glitch - velocity innovations](../../assets/ecl/gps_glitch_-_velocity_innovations.png)
### Determination of GPS Data Loss
Loss of GPS data will be shown by the velocity and position innovation test ratios 'flat-lining'.
If this occurs, check the other GPS status data in `vehicle_gps_position` for further information.
The following plot shows the NED GPS velocity innovations `ekf2_innovations_0.vel_pos_innov[0 ... 2]`, the GPS NE position innovations `ekf2_innovations_0.vel_pos_innov[3 ... 4]` and the Baro vertical position innovation `ekf2_innovations_0.vel_pos_innov[5]` generated from a simulated VTOL flight using SITL Gazebo.
The simulated GPS was made to lose lock at 73 seconds.
Note the NED velocity innovations and NE position innovations 'flat-line' after GPS is lost.
Note that after 10 seconds without GPS data, the EKF reverts back to a static position mode using the last known position and the NE position innovations start to change again.
![GPS Data Loss - in SITL](../../assets/ecl/gps_data_loss_-_velocity_innovations.png)
### Barometer Ground Effect Compensation
If the vehicle has the tendency during landing to climb back into the air when close to the ground, the most likely cause is barometer ground effect.
This is caused when air pushed down by the propellers hits the ground and creates a high pressure zone below the drone.
The result is a lower reading of pressure altitude, leading to an unwanted climb being commanded.
The figure below shows a typical situation where the ground effect is present.
Note how the barometer signal dips at the beginning and end of the flight.
![Barometer ground effect](../../assets/ecl/gnd_effect.png)
You can enable _ground effect compensation_ to fix this problem:
- From the plot estimate the magnitude of the barometer dip during takeoff or landing. In the plot above one can read a barometer dip of about 6 meters during landing.
- Then set the parameter [EKF2_GND_EFF_DZ](../advanced_config/parameter_reference.md#EKF2_GND_EFF_DZ) to that value and add a 10 percent margin. Therefore, in this case a value of 6.6 meters would be a good starting point.
If a terrain estimate is available (e.g. the vehicle is equipped with a range finder) then you can additionally specify [EKF2_GND_MAX_HGT](../advanced_config/parameter_reference.md#EKF2_GND_MAX_HGT), the above ground-level altitude below which ground effect compensation should be activated.
If no terrain estimate is available this parameter will have no effect and the system will use heuristics to determine if ground effect compensation should be activated.
## Further Information
- [PX4 State Estimation Overview](https://youtu.be/HkYRJJoyBwQ), _PX4 Developer Summit 2019_, Dr. Paul Riseborough): Overview of the estimator, and major changes from 2018/19, and the expected improvements through 2019/20.