Files
PX4-Autopilot/docs/en/config_fw/position_tuning_guide_fixedwing.md
T
Silvan Fuhrer b4134d75f2 feat(tecs): don't trade altitude for speed above trim airspeed (#29009)
* fix(tecs): don't trade altitude for speed above trim airspeed

With an airspeed setpoint above trim and the throttle at `FW_THR_MAX`, TECS pitches down to
keep chasing the setpoint and settles below the altitude setpoint.
Accelerating above trim should be the throttle's job; losing altitude at high speed is not wanted.

The pitch loop now sees the airspeed setpoint capped at max(trim, current airspeed);
the throttle loop still tracks the full setpoint. Below trim, pitch still trades height for speed, up to trim.
Overspeed above the setpoint is still corrected with pitch.
The cap fades out as the effective `FW_T_SPDWEIGHT` goes from 1 to 2, so gliders (weight 2),
fast descend and underspeed recovery keep using pitch to reach their airspeed.
The behaviour is documented in the TECS docs and the `FW_T_SPDWEIGHT` description.

Signed-off-by: Silvan <silvan@auterion.com>

* fix(tecs): use tas and not tas_sp for the pitch loop

Signed-off-by: Silvan <silvan@auterion.com>

* fix(tecs): don't counter throttle acceleration with pitch above trim

Capping the pitch loop's airspeed setpoint at max(trim, airspeed) keeps
pitch from diving to gain speed, but between trim and the setpoint the
throttle's acceleration still shows up in the kinetic energy rate
estimate. Against a kinetic energy rate setpoint of zero, the pitch loop
then pitches up and turns the throttle's energy into height. At a speed
weight of 1 this halves the acceleration and lifts the vehicle above the
altitude setpoint while accelerating.

Remove the kinetic term, setpoint and estimate, from the pitch loop
between trim and the setpoint, so pitch controls height only there. As
for the cap, this fades out with speed priority.

Point-mass simulation with the TECS defaults, speed step from 15 m/s:
- to 20 m/s: 95% of the step in 21 s instead of 37 s, 1.2 m instead of
  2.4 m above the altitude setpoint
- to 28 m/s, above the 24.7 m/s the vehicle can reach: 2.2 m instead of
  5.2 m above the altitude setpoint, still no altitude loss
- deceleration, climbs, a speed weight of 2 and cruise at trim are
  unchanged; in turbulent cruise above trim the pitch rate RMS is 6%
  higher, as the kinetic term switches when the airspeed crosses the
  setpoint

The remaining rise comes from the lift gained with speed at constant
pitch, which only altitude feedback corrects.

Assisted-by: Claude:claude-opus-5-5

* fix(tecs): fade the pitch loop's kinetic setpoint only once

Between trim airspeed and the airspeed setpoint, the capped pitch loop
setpoint already fades the kinetic energy rate setpoint in with the
speed weight between 1 and 2. Scaling it by the same fade factor again
faded the setpoint quadratically but the estimate only linearly, so at a
speed weight of 1.5 the pitch loop countered acceleration it should only
half ignore. Scale only the estimate.

Speed weights up to 1 and of 2 are unaffected. In a point-mass
simulation at a speed weight of 1.5, a step from 15 to 20 m/s now takes
30 s instead of 37 s and rises 1.6 m instead of 2.4 m, between the
results at weights 1 and 2 instead of worse than both.

Assisted-by: Claude:claude-opus-5-5

* docs(tecs): show the pitch and throttle speed roles in a diagram

The paragraph on how pitch and throttle share speed control above trim
was hard to follow. Show the three regions of measured airspeed (below
trim, between trim and the setpoint, above the setpoint) with what the
pitch and throttle loops do in each, and describe each region in its own
bullet. Also state that there is no middle region with a setpoint at or
below trim.

Assisted-by: Claude:claude-opus-5-5

---------

Signed-off-by: Silvan <silvan@auterion.com>
2026-10-15 08:33:02 +02:00

6.2 KiB

Fixed-wing Altitude/Position Controller Tuning

This guide offers some help in tuning the high-level fixed-wing controllers needed for flying missions and in altitude/position control mode. PX4 uses TECS for altitude and airspeed control, and NPFG for horizontal heading/position control.

::: info An incorrectly set gain during tuning can make altitude or heading control unstable. A pilot tuning the TECS gains should therefore be able to fly and land the plane in stabilized control mode. :::

:::tip All parameters are documented in the Parameter Reference FW Performance and FW NPFG Control sections. The most important parameters are covered in this guide. :::

TECS Tuning (Altitude and Airspeed)

TECS (Total Energy Control System) is a guidance algorithm for fixed-wing aircraft that coordinates throttle and pitch angle setpoints to control the aircraft's altitude and airspeed. For a detailed description of the TECS algorithm and the control diagram, see Controller Diagrams.

A well-tuned attitude controller is required before tuning TECS: PID Tuning Guide.

Tuning TECS is mainly about setting the airframe limitations correctly. Those limitations can be specified in terms of parameters that can be determined from a sequence of flight maneuvers, which are described below. Most of the maneuvers required the plane to be flown by a pilot in Stabilized flight mode.

:::tip It is highly beneficial to have a person available who can read and take note of telemetry data while the pilot is flying the maneuvers. To improve accuracy we also recommended that you verify the data obtained during flight with the data recorded in the flight logs. :::

1st: Trim Conditions

Fly in stabilized mode and find trim values for both throttle and pitch angle for level flight at trim airspeed. Use throttle to adjust airspeed and pitch to keep level flight.

Set the following parameters:

  • FW_AIRSPD_TRIM - set to the desired trim airspeed flown during the maneuver.
  • FW_THR_TRIM - set to the throttle required to fly at trim airspeed.
  • FW_PSP_OFF - set to the pitch angle required to maintain level flight.

2nd: Airspeed & Throttle Limits

Fly in stabilized mode and increase throttle while maintaining level flight using pitch control - until the vehicle reaches the maximum allowed airspeed.

Set the following parameters:

  • FW_THR_MAX - set to the throttle you applied to reach maximum airspeed during level flight.
  • FW_THR_MIN - set to the minimum throttle the plane should fly at.
  • FW_AIRSPD_MAX - set to the maximum airspeed you achieved during level flight at FW_THR_MAX.

TECS accelerates above trim airspeed with throttle only, rather than by descending (see Speed and Altitude Weighting). If FW_AIRSPD_MAX is set higher than the vehicle can reach in level flight at FW_THR_MAX, it will hold altitude and fly slower than commanded.

3rd: Pitch & Climb Rate Limits

:::warning Do not use FW_T_CLMB_MAX, FW_T_SINK_MAX or FW_T_SINK_MIN to specify the desired climb or sink performance you would like to get from the vehicle! The parameters define the operating limitations and they should be set during the tuning phase, as described below. :::

Fly in stabilized mode, apply full throttle (FW_THR_MAX) and slowly increase the pitch angle of the vehicle until the airspeed reaches FW_AIRSPD_TRIM.

  • FW_P_LIM_MAX - set to the pitch angle required to climb at trim airspeed when applying FW_THR_MAX.
  • FW_T_CLMB_MAX - set to the climb rate achieved during the climb at FW_AIRSPD_TRIM.

Fly in stabilized mode, reduce the throttle to FW_THR_MIN and slowly decrease the pitch angle until the vehicle reaches FW_AIRSPD_MAX.

  • FW_P_LIM_MIN - set to the pitch angle required to reach FW_AIRSPD_MAX at FW_THR_MIN.
  • FW_T_SINK_MAX - set to the sink rate achieved during the descent.

Fly in stabilized mode, reduce throttle to FW_THR_MIN and adjust the pitch angle such that the plane maintains FW_AIRSPD_TRIM.

  • FW_T_SINK_MIN - set to the sink rate achieved while maintaining FW_AIRSPD_TRIM.

Specify the target climb and sink rate for autonomous missions by adjusting FW_T_CLMB_R_SP and FW_T_SINK_R_SP. These specify the height rates at which the vehicle will climb or descend in order to change altitude. Furthermore, these two values define the height rate limits commanded by the user in Altitude mode and Cruise mode.

FW Path Control Tuning (Position)

All path control parameters are described in FW NPFG Control (Parameter Reference).

  • NPFG_PERIOD - This is the previously called L1 distance and defines the tracking point ahead of the aircraft it's following. A value of 10-20 meters works for most aircraft. Shorten slowly during tuning until response is sharp without oscillation. Vehicles with a slow roll dynamic should have this value increased.