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.