Table of Contents
This page describes the mtecs library which implements a total energy control system (tecs). The mtecs library is used by the app fw_pos_control_l1
The tecs controls the airspeed and altitude of the airplane. Given an altitude or flightpath angle setpoint and an airspeed setpoint the tecs calculates the necessary throttle and pitch setpoints. Hence the output of a tecs library call (= control signals) are the throttle and pitch setpoint.
mTECS can operate in the following modes (developers: see value of
enum tecs_mode). Depending on the mode different parameters are active:
- NORMAL: all standard parameters apply
- UNDERSPEED: triggered if airspeed falls below FW_AIRSPD_MIN: all MT_USP_* parameters apply and override the corresponding parameters of the normal mode
- TAKEOFF: active if flying towards a takeoff waypoint: all MT_TKF_* parameters apply and override the corresponding parameters of the normal mode.
- MT_TKF_PIT_MIN: this is the minimal pitch during takeoff. The value can be overridden by the corresponding field in the qgc waypoint UI
- LAND: activated through a landing waypoint and when the flare altitude (FW_LND_FLALT) is passed. All MT_LND_PIT_* parameters apply and override the corresponding parameters of the normal mode.
- LAND_THROTTLELIM: activated through a landing waypoint, when the throttle limit altitude (FW_LND_TLALT) is passed. All MT_LND_THR_* parameters apply and override the corresponding parameters of the normal mode.
The tecs consists of an inner control loop and an outer control loop. Also have a look at the diagram at the bottom of this page as a reference while reading this page.
Outer Control Loop
The airspeed control block is a PD controller with the airspeed derivative setpoint as output. The altitude control block is a PD controller with the flight path angle (angle between horizontal and vertical velocity) as setpoint.
The airspeed and altitude setpoints are provided to the mTECS library by the fw_pos_control_l1 app. The altitude setpoint is typically set with a waypoint or the navigator app sets it to be the current altitude when loiter is activated on the remote control. The airspeed setpoint is set to FW_AIRSPD_TRIM. During landing 1.3 * FW_AIRSPD_MIN is used.
Inner Control Loop
The input to the inner control loop (large grey shaed box in the diagram) are the outputs of the outer loop and the airspeed derivative. The inner loop controls the 'total energy rate' nad the 'energy distribution rate' and hence the input values are first converted to energy rates. The total energy rate control block and the energy distribution rate control block are both PI controllers with a feedforward gain.
Reading the logs/plots
The TECS field contains most of the information needed for tuning mTECS. See sdlog2 for more information on how to generate plots.
The relevant fields are:
- ASp: altitude setpoint
- A: altitude
- AF: altitude filtered
- FSp: flight path angle setpoint
- F: flight path angle
- FF: flight path angle filtered
- AsSP: airspeed setpoint
- As: airspeed
- AsF: airspeed filtered (with cutoff frequency set by the param MT_A_LP)
- AsDSP: airspeed derivative setpoint
- AsD: airspeed derivative
- M: mode (corresponding to value of
The relevant fields are:
- TERSP: total energy rate setpoint
- TER: total energy rate
- EDRSP: energy distribution rate setpoint
- EDR: energy distribution rate
Types of parameters
You can refer to the diagram at the bottom of this page to understand which parameter has an effect on which control block. In general:
- FF: Feed Forward gain: maps setpoint to control signal directly
- P: Proportional gain: maps the error to the control signal
- I: Integral part: maps the error integral to the control signal, increase to remove steady state error
- D: derivative gain: maps the error derivative to the control signal, a higher value increases damping (reduces oscillations)
- LP: lowpass cutoff frequency in Hz (a lower value filters more)
- MIN and MAX: lower and upper limits of the control signal (output of the block)
- OFF: Offset in the control signal, a constant value that is added to the control signal
- Throttle offset: set MT_THR_OFF to the typical throttle you need for cruise flight when flyin in seatbelt (typically between 0.5 and 0.8)
- Check all MIN and MAX parameters. Make sure that none of the limits interfere with your tuning.
- MT_FPA_MIN/MT_FPA_MAX: these params limit flight path angle (in degrees) which the TECS wants to fly to correct altitude. The values depend on your airframe. For a larger and relatively less powerful aircraft you have to choose smaller values than for a small overpowered plane.
- MT_ACC_MIN/MT_ACC_MAX: set to large values or don't change default
- MT_PIT_MIN/MT_PIT_MIN: pitch limits: set to sane values but make sure that you don't limit too much. Typically +-30 to 45 deg.
- MT_THR_MIN/MT_THR_MAX: set to 0 and 1 unless your aircraft is really overpowered.
- Set cruise airspeed FW_AIRSPD_TRIM (m/s)
- Set a simple waypoint course, for example a square around your position. First at constant altitude, later for fine tuning at different altitudes.
- Make sure that you can observe altitude and airspeed in the ground control station
- Also be ready to takeover in seatbelt/manual at any time.
- Switch to manual and observe airspeed and altitude. If one of them is quickly diverging (eg. quickly diving or stalling) first try to correct that issue before further tuning.
- Airspeed: Increase MT_ACC_P (outer loop) slowly to large values. Stop when oscillations start or when you are at a really large number. (E.g. 5)
- Altitude:Increase MT_FPA_P (outer loop) slowly to large values. Stop when oscillations start or when you are at a really large number. (E.g. 5)
- If increasing the outer loop params does not help (eg. no reaction on large errors) increase MT_THR_FF and MT_THR_P. Initially you can leave MT_THR_P at zero and only play around with MT_THR_FF. MT_THR_P should be kept significantly smaller than MT_THR_FF
- If you see the aircraft correcting only with throttle for altitude and speed errors increase MT_PIT_FF and MT_PIT_P. Initially you can leave MT_PIT_P at zero and only play around with MT_PIT_FF. MT_PIT_P should be kept significantly smaller than MT_PIT_FF
Short pitch down and full throttle movements
This could be the underspeed protection triggering. You can clearly see this in the plot if you look at airspeed and the tecs mode field. Lower FW_AIRSPD_MIN and refly. Maybe you need to increase airspeed filtering by lowering MT_A_LP.
Pulsing / Oscillating Throttle
If the throttle is oscillating quickly (1 to 2 hz or faster) this is probably because of the very noisy airspeed signal.
- So your first step should be to increase filtering by lowering one of these params: MT_A_LP, MT_AD_LP, MT_ACC_D_LP
- If that does not help you can go on to make airspeed control less aggressive: lower MT_ACC_P, higher MT_ACC_D (you can get it to the point where it should not control airspeed anymore).
- the flight path angle estimate could be the source of the problem as well (check the logs): so try to filter it more by lowering MT_FPA_LP
- If throttle is still pulsing (and especially if you lowered the gains in step 2 until no airspeed control is observable) try adjusting the 'total energy rate controller' to be less agressive: lower MT_THR_FF, MT_THR_P, MT_THR_I
- If it is still pulsing it can also be because your altitude control gains are too high. (The altitude estimate comes from the estimator and therefore this signal is much smoother.) Try to set the altitude controller less aggressive: lower MT_FPA_P, higher MT_FPA_D, lower MT_FPA_D_LP
Direct link to the above diagram.