Improve APA safety: pitot validation, reduced gains, safe defaults

[sensei-hacker]

User description

Summary

Improves safety of Airspeed-based PID Attenuation (APA) feature with automatic pitot sensor validation and more conservative gain limits.

Changes

Pitot Sensor Validation:

• Automatically detects blocked or failed pitot tubes by comparing against GPS+wind airspeed
• Displays "PITOT FAIL" OSD warning when pitot reading is implausible
• Automatically falls back to GPS-based airspeed when pitot fails
• Prevents dangerous high gains from invalid pitot data

Safer Gain Limits:

• Maximum gain reduced from 200% to 150% for more conservative operation
• I-term scaling reduced to prevent integral windup at low speeds
• Better control stability across the speed envelope

Safe Defaults:

• APA now defaults to disabled (apa_pow = 0)
• Pilots must explicitly enable after validating pitot sensor
• Existing configurations unchanged

Testing

• Hardware builds: ✅ Verified (MATEKF405SE, SITL)
• Runtime testing: Requires flight testing with pitot sensor

Related Issues

Closes #11208

[qodo-code-review]

PR Compliance Guide 🔍

All compliance sections have been disabled in the configurations.

[MrD-RC]

I have a couple of questions:

1. Does APA only work if GPS is enabled? In theory it shouldn't need to be. But the tests for the pitot blockage rely on the virtual airspeed sensor (wind + ground speed). So what happens if GPS is disabled?

2. Likewise, what happens if the virtual airspeed sensor is deemed unreliable? For example, you have been flying in a straight line for 10 minutes. So the wind estimation is stale.

3. Did any aircraft in the testing require gains between 150-200%? Or were some marginal at 150%? If so, the higher gains may still be necessary.

I agree with apa_pow defaulting to 0. To use this feature an airspeed sensor needs to be enabled. By default they are not. So long as there are sensible starting point examples in the documentation. I think this is all good.

[sensei-hacker]

Excellent questions, thank you!
I'm going to write out my thinking here so that hopefully you or someone can catch any mistakes I am making.

1. Does APA only work if GPS is enabled? In theory it shouldn't need to be. But the tests for the pitot blockage rely on the virtual airspeed sensor (wind + ground speed). So what happens if GPS is disabled?

This is what I'm seeing; please tell me if you see anywhere I am mistaken:

getVirtualAirspeedEstimate() returns 0 if GPS is not available
That's less than minValidationSpeed (minimum speed for the GPS-based reading to be used), so isPitotReadingPlausible() returns true

So the pitot reading is treated as plausible and the failure counter in pitotValidForAirspeed() does not increase -- APA is used.

I am also attaching a PDF with flowcharts and a decision table. That document is of course not authoritative - the code is.
APA_TPA_Decision_Logic.pdf

2. Likewise, what happens if the virtual airspeed sensor is deemed unreliable? For example, you have been flying in a straight line for 10 minutes. So the wind estimation is stale.

wind_estimator.c will virtually never deem the wind estimate unreliable while the aircraft is moving, so let's consider the case where the wind estimator calls itself reliable, but the data isn't great. Suppose the following actual speeds:

stale headwind estimate: 20 km/h
true current headwind  30 km/h
ground speed: 20 km/h

true airspeed (and pitot reading):: 50 km/h
estimated airspeed: 40 km/h

The pitot will be treated as plausible if reading is between 30-200% of the estimate.
That is, between (estimate * 0.3) and - (estimate * 2.0)
Here it is estimate * 1.25, WELL within the range of plausibility!

Let's try another:

stale headwind estimate: 40 km/h
true current headwind  20 km/h
ground speed: 40 km/h

true airspeed (and pitot reading): 60 km/h
estimated airspeed: 80 km/h

Still not even close to being treated as implausible.

What if we fly really slow, only 10 km/h actual airspeed, with a strong tailwind? (With the wind being stronger than our airspeed, which will mess up other things)

stale tailwind estimate: 40 km/h
true current tailwind  20 km/h
ground speed:  30 km/h

true airspeed (and pitot reading): 10  km/h
estimated airspeed: -10 km/h

NOW it wouldn't be trusted and would revert to the existing TPA behavior, if the stale wind estimate is four times higher than our airspeed.
So lesson learned - if the wind is much faster than your airspeed, you may get TPA. (also, your plane just got blown to the next town over since it's airspeed is much less than the wind speed).

3. Did any aircraft in the testing require gains between 150-200%? Or were some marginal at 150%? If so, the higher gains may still be necessary.

What gains (and therefore effective P-term and D-term) are "required" is of course a bit subjective and hard to measure - the PID loop will make things work with a range of PID/FF values. So this is an area it would be good to get feedback from testers - preferably with very clear observations of behavior, and blackbox logs would be wonderful. The earlier testing (RC4) improperly scaled the I-term changes, probably overdriving I and making the low-speed tests no longer applicable.

150 (50% increase) is conservative, IMHO. But 0% flew just fine for years before we had TPA.

[MrD-RC]

1. Does APA only work if GPS is enabled? In theory it shouldn't need to be. But the tests for the pitot blockage rely on the virtual airspeed sensor (wind + ground speed). So what happens if GPS is disabled?

This is what I'm seeing; please tell me if you see anywhere I am mistaken:

getVirtualAirspeedEstimate() returns 0 if GPS is not available That's less than minValidationSpeed (minimum speed for the GPS-based reading to be used), so isPitotReadingPlausible() returns true

Shouldn't this instead be false; as there is no way to validate the airspeed sensor? So we don't know if it's reading is plausible or not. Erring on the side of caution, but it is a safety feature. It does tie having an airspeed sensor to needing a GPS. But we could always make an explicit parameter, with a warning, to bypass that safety check if no GPS is found. Then it's the pilot's responsibility if they disable the safety feature and things go wrong.

2. Likewise, what happens if the virtual airspeed sensor is deemed unreliable? For example, you have been flying in a straight line for 10 minutes. So the wind estimation is stale.

wind_estimator.c will virtually never deem the wind estimate unreliable while the aircraft is moving.

I seem to recall that the wind estimate is marked as stale (unreliable) after 10 minutes of flying in the same direction. It will show an X in the OSD to warn that the wind speed reading is stale.

so let's consider the case where the wind estimator calls itself reliable, but the data isn't great. Suppose the following actual speeds:

stale headwind estimate: 40 km/h
true current headwind  20 km/h
ground speed: 40 km/h

true airspeed (and pitot reading): 60 km/h
estimated airspeed: 80 km/h

Still not even close to being treated as implausible.

Honestly, I'd have expected that to start being close to implausible. 200% seems like a big difference. If I'm seeing 20km/h difference at those sorts of speeds. I start not trusting the airspeed sensor. Usually calibration could be out. But not that the tube is blocked (unless it's reading wildly under). I'm visually looking at +/- ~30% difference at most for my known flying speed. Usually it is much closer, easily within 5-10%. Perhaps this could issue a calibration warning on the OSD. Then not fully trust the airspeed at higher values?

3. Did any aircraft in the testing require gains between 150-200%? Or were some marginal at 150%? If so, the higher gains may still be necessary.

What gains (and therefore effective P-term and D-term) are "required" is of course a bit subjective and hard to measure - the PID loop will make things work with a range of PID/FF values. So this is an area it would be good to get feedback from testers - preferably with very clear observations of behavior, and blackbox logs would be wonderful. The earlier testing (RC4) improperly scaled the I-term changes, probably overdriving I and making the low-speed tests no longer applicable.

150 (50% increase) is conservative, IMHO. But 0% flew just fine for years before we had TPA.
True. But I think I recall one of the testers requesting a higher value at one stage. Because the values at the time weren't enough for their aircraft. If this new feature calls for a slightly higher range. It would be nice if it's there from the get-go.

I'll trust the opinions of the @Jetrell and the guys who were testing this extensively with regard to this. I just wouldn't want to make this feature inapplicable in some applications. Especially when it's the result of one guy, who likely had his PIDs tuned too tightly.

[sensei-hacker]

I seem to recall that the wind estimate is marked as stale (unreliable) after 10 minutes of flying in the same direction. It will show an X in the OSD to warn that the wind speed reading is stale.

I'm showing 15 minutes without a combined change in pitch and yaw, 11.5 degrees. A bit higher than I was thinking.
There is a quite a bit of math involved to compute the threshold of 11.5 degrees.

#define WINDESTIMATOR_TIMEOUT 60*15 // 15min with out altitude change

Shouldn't this instead be false; as there is no way to validate the airspeed sensor? S

Let's consider what we do with other sensors. If the gyro is giving reasonable readings, maybe 30 degrees per second, and we have no other sensor to cross-validate, do we throw out the gyro reading, mark it as untrusted?

If the GPS is giving reasonable location and speed readings, and we have no other location sensor to cross-validate, do we throw out the GPS reading, mark it as untrusted?

Heck, if the RC commands from the receiver are reasonable values 1000us-2000us and we have no other source to cross-validate ...

If every source of input required two independent sources -- well we'd be Ardupilot. 😀
( Kidding, Ardupilot doesn't do that. Boeing doesn't. Airbus might.)

If I'm seeing 20km/h difference at those sorts of speeds.

Would you rather trust that the ground speed is the same as the airspeed? (Which will never be true for an airplane in flight). So long as the airspeed sensor isn't giving clearly questionable readings (-1, or INT16_MAX), I would treat it as the most reliable source of airspeed data, barring clear reason not to. Full scale pilots are trained that if your pitot says one thing and your eyes say another, trust your instruments more than your eyes. Given reasonable readings, I would certainly trust it more than the alternatives, which are guaranteed to be wrong.

I'll trust the opinions of the @Jetrell and the guys who were testing this extensively with regard to this.

Jetrell is amazing. And cross-validation is always good when can get it, so I'd also love to hear from anyone else who has some data. Especially with blackbox data. "Data is king."

[MrD-RC]

To be honest, with ground speed + wind speed available. I would use that as a pretty good indicator within reason. Certainly enough for a sanity check. If it's more than +/-50% off. Something is wrong.

I completely agree with not trusting your eyes. Anyone who's flown lowish over water knows how deceiving that is. But, I would also say there are big differences between full size pitots and the size most people are using. The hole is tiny on the hobby tubes. I've seen a couple of occurrences of them getting foreign matter in there. It doesn't always completely block the tube too. So you still get readings. They're just off. We actually moved to a larger pitot tube to get away from this issue. But people in the hobby wouldn't. Mainly because of thse size.

So would I 100% trust a pitot tube over everything else at the hobby scale? No.

[sensei-hacker]

I've seen a couple of occurrences of them getting foreign matter in there. It doesn't always completely block the tube too. So you still get readings.

I would love to see those blackbox logs and see if higher-frequency components of the reading fluctuate a lot more than a clear tube, or any other signs we could pay attention to. I suppose a sudden drop in reported airspeed that doesn't correlate with either accelerometer or GPS could be a clue. If the airspeed drops from 60 km/h to 20 km/h in just 20 milliseconds, something is wrong. That would be a deceleration of 30G.

I'm more comfortable looking at things like that. A bug strike or similar would be a sudden event, a sudden big change in reported speed. We pretty much know the aircraft didn't decelerate at 30G and remain in one piece, so that gives us a solid reason to say something is wrong with that pitot data.

[Jetrell]

After again reviewing the changes @sensei-hacker made in these commits. It seems like it now accounts for far more failure conditions.

Especially when it's the result of one guy, who likely had his PIDs tuned too tightly.

@MrD-RC I think that tuning the PID's too tight could always be a point of concern. Because it leaves little room for sensor deviation. I made a few notes about that in the Wiki.
When I was testing the RC4 logic using virtual airspeed. I travel a long distance in a straight line in Cruise to see what would happen if that data become untrusted.
I did notice some virtual airspeed fluctuations. However it didn't see it become untrusted.. The only time I seen this occur in flight, was once at launch. When the wind estimator was slow to provide data.. In this case, with the RC 4 logic. The roll axis started to oscillate for a quick second until the date became trusted.

Edit : @sensei-hacker we are heading off soon. But I'll have a quick look and see if I can find that log to DM it to you.

[Jetrell]

I started to write a draft for these changes to update the wiki once this is tested and merged.
But as I was writing I noticed that the default settings aren't really that adequate.
Even setting apa_pow = 0 as default to disable it isn't ideal. Because the default TPA + pitch angle settings aren't good. I mentioned this in the wiki. But most users will likely ignore it, while not grasping the fullness of how much pitch actually influences raw throttle in the adjustment of the gains when that function is in operation.

You may say. Isn't it the same attenuation/boost scaling as before. And the answer is yes. But now the base gains are tuned much tighter than they ever were with the old TPA/B method. And the dynamic gain control over TPA is much smoother and more incremental than before. With it always making adjustments as the planes pitch attitude changes.

I'll explain. The defaults for TPA + Pitch angle are as followed -

• tpa_breakpoint = 1500
  With no wind, this throttle value should provide an equal amount of thrust to what is required to hold fw_reference_airspeed for the APA function. This is so the base PID tune response is roughly the same, when switching between APA and TPA + Pitch angle.
  Remembering this is a shared setting between Planes and Multicopters.
  The default of 1500 isn't too bad for either. But being that both platforms are getting more powerful. This could be lowered to something like 1400 to 1450 for both.

• fw_tpa_time_constant = 1500 (0 to 5 seconds)
  The default of 1.5secs to delay the none instantaneous response of airspeed to a change in throttle. Its a little low to smooth gain transition for the average airframe. Increasing it to 2000 would be more useful for most models.

• tpa_rate = 0
  The main issue here is this setting is also shared between Planes and Multicopters.
  Multicopter = 0 - 100
  Fixedwing = 0 - 200
  The default value of Zero is ideal for the way multicopter tpa_rate works. But it's not good for the operation of Fixedwing TPA + Pitch angle.
  e.g. If the plane has the base gains tuned firmly at the tpa_breakpoint. And the user raises the throttle. No attenuation will be applied to those gains as the airspeed starts to increase, leading to control surface oscillations.
  Being that this setting ranges from 0 to 200. A conservative value of 60 at least provides some higher speed attenuation.
  For optimal user support. It would require being broken into two separate settings. One for each platform. i.e. mc_tpa_rate and fw_tpa_rate.. Or at the least. Providing different defaults settings to be loaded by the configurator, when a platform is selected in setup.

• tpa_pitch_compensation = 8 (0 to 20 - default is okay)

And when it comes to the APA side of things. I consider the default of fw_refernce_airspeed to also be a little low.
Holding a speed as low as 1500 or 54km/h on most airframes while tuning isn't that easy. They often exceed that speed easily.
That is why I set it as 70km/h in the graph. Because new users generally have little idea of what's a good value. So I figure a safer more marginal speed is better. While more advanced users can lower it to 50km/h if their goal is power management for long range.

[sensei-hacker]

Thanks, Jetrell. That all makes sense about the default TPA + Pitch angle settings.

Some of this comes back to a fundamental oversight in how TPA is currently implemented.

The fundamental problem is that it currently treats a commanded change of setpoint from pilot input the same as a uncommanded change of attitude from a wind gust or from pitch-roll coupling. Treats trying to change the attitude the same as resisting a change of attitude.

The proper response is different between those two. Between a command to change the setpoint vs an uncommanded disturbance to attitude. Trying to treat them as the same is what makes the tuning and settings necessary - trying to balance two things that shouldn't be mixed together at all. It's same thing that was discussed with the exponent for pow_apa. I'll have a PR for that in a future version.

The exponent should actually be 1, 2, or 0, depending on what you're trying to accomplish (the term). Are you trying to change course (commanding a change to the setpoint, feed-forward FF), or are you trying to resist the force of the camera gimbal acting as a rudder (uncommanded disturbance, the P-term)? The setting exists only because the current *PA code mixes these different things together, requiring a compromise between the correct value of 1 and the correct value of 2, for the different things. Trying to find a value you can live with for both when the correct value is 1 for the first thing and 2 for the second thing.
(Tuning to try to find Pi again 😃 )

Separating them will especially help for tailless planes ("flying wings"). If you command pitch, TPA should be applied at ^2 to the pitch commmand. But you will also get uncommanded roll and yaw because elevons. That correction should either not be TPAed at all, or arguably linearly. Treating them the same as why you have to do the testing and tuning to try to find a balance you can live with. So the to account for the fact that the pilot is WANTING the attitude to change.

But that's for future work. For now, we can adjust the default settings to work best with the TPA code we have.

[quadlawnmowerman-coder]

Gave this branch a try, quick first flight locally to test compile and flashing, had no issues and gave it the beans on 6s. Went out to a spot with some more room to test failures and first test with pitot sock left on failed. The code did not detect the poor data and did not display a OSD warning and I felt the impact of the increased gains almost immediately, could not test for long however as I had an ESC failure about 20sec into the flight so not much log data. Had to land some distance away from me that took a while to retrieve, so most of the log is just me fiddling the sticks on my walk to collect the airframe.

Worth noting I set the TPA rate to 0 and breakpoint to 2000 so it would not come into play during the simulated airspeed sensor data failure.

INAV_9.0.0_cli_20260106_160015.txt
LOG00002.TXT