Fix inverted tpa_pitch_compensation documentation and comment

[sensei-hacker]

Summary

The tpa_pitch_compensation setting's description and the matching inline comment in calculateTPAThtrottle() (src/main/flight/pid.c) say the virtual TPA throttle increases when pitching up. That's backwards: the code (and its own groundCos math, positive while diving) actually raises the virtual throttle — and so attenuates PID gains — when pitching down.

That's the aerodynamically correct direction: diving increases airspeed, so gains should attenuate (matching normal TPA behavior at high airspeed); climbing reduces airspeed, so gains should stay more aggressive. tpa_pitch_compensation is a proxy for airspeed on airframes with no airspeed sensor.

Related

#11952 investigated this exact mismatch between the code and its documentation, but concluded the code was wrong and flipped its sign to match the (incorrectly worded) description — that would have made the runtime behavior backwards. This PR instead corrects the description and comment, leaving the working code untouched.

Changes

• src/main/fc/settings.yaml: corrected tpa_pitch_compensation description
• src/main/flight/pid.c: corrected the matching inline comment (no logic change)
• docs/Settings.md: regenerated via src/utils/update_cli_docs.py

Testing

Documentation/comment-only change — no code logic modified, so no functional testing applies. Verified docs/Settings.md regeneration produces only the expected single-line diff.

[qodo-code-review]

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Correct TPA pitch compensation direction documentation

🐞 Bug fix 📝 Documentation 🕐 Less than 10 minutes

AI Description

• Correct fixed-wing pitch compensation wording to describe attenuation while diving.
• Clarify the existing PID comment without changing runtime behavior.
• Regenerate the settings reference from the corrected YAML source.

Diagram

graph TD
  A["Settings YAML"] -->|generates via| B["Docs Generator"] --> C["Settings Guide"]
  A -->|describes| D["PID Runtime"] -->|adjusts| E["TPA Gains"]

Loading

High-Level Assessment

Correcting the canonical YAML description, regenerating the derived settings guide, and aligning the nearby code comment is the optimal approach. Changing the calculation sign was considered and dismissed because the existing behavior correctly increases virtual throttle—and attenuates gains—while diving.

Files changed (3) +3 / -3

Documentation (3) +3 / -3

Settings.mdRegenerate corrected TPA pitch compensation documentation +1/-1

Regenerate corrected TPA pitch compensation documentation

• Updates the generated settings reference to explain that positive compensation raises virtual throttle while diving, attenuating PID gains as airspeed increases.

docs/Settings.md

settings.yamlCorrect the canonical pitch compensation description +1/-1

Correct the canonical pitch compensation description

• Fixes the setting description to identify pitch compensation as an airspeed proxy and accurately document its behavior during dives and climbs.

src/main/fc/settings.yaml

pid.cAlign the TPA calculation comment with runtime behavior +1/-1

Align the TPA calculation comment with runtime behavior

• Replaces the inverted pitch-direction comment with an explanation of positive groundCos during dives and the resulting PID gain attenuation. No calculation or runtime behavior changes.

src/main/flight/pid.c

[github-actions]

RAM / Flash usage vs. base commit 13485eb — commit 261f9b4

Target	Flash Δ	RAM Δ
MATEKF405	±0 B (±0.00%)	CCM: ±0 B (±0.00%) RAM: ±0 B (±0.00%)
MATEKF722	±0 B (±0.00%)	ITCM_RAM: ±0 B (±0.00%) RAM: ±0 B (±0.00%) TCM: ±0 B (±0.00%)
MATEKF765	±0 B (±0.00%)	DTCM_RAM: ±0 B (±0.00%) SRAM1: ±0 B (±0.00%)
MATEKH743	±0 B (±0.00%)	D2_RAM: ±0 B (±0.00%) DTCM_RAM: ±0 B (±0.00%) ITCM_RAM: ±0 B (±0.00%) RAM: ±0 B (±0.00%)

See RAM/flash optimization guide for techniques to reduce usage.

[github-actions]

Test firmware build ready — commit 261f9b4

Download firmware for PR #11956

245 targets built. Find your board's .hex file by name on that page (e.g. MATEKF405SE.hex). Files are individually downloadable — no GitHub login required.

Development build for testing only. Use Full Chip Erase when flashing.

[Jetrell]

That's a much better explanation than it had.
There is this one open too.
I think it too gets the point across, but I don't think it should include the math. It just confuses most users.

[breadoven]

I might have a look at cleaning this up properly. The logic is a bit inconsistent and it would be better to not mix it up with throttle but just call it what it is, i.e. pitch TPA ... or some such term.

[Jetrell]

I might have a look at cleaning this up properly. The logic is a bit inconsistent and it would be better to not mix it up with throttle.

No complaints here !
As we spoke of in the other PR. TPA+PA now accounts for low-throttle pitch-down to prevent control surface oscillations in a dive, which was a problem in previous iterations of fixedwing TPA.
But the thing I keep forgetting to test. Is how it now reacts if you place a plane into a high throttle dive with the pitch angle gain reversal.. I would have thought the high throttle would attenuate the gains to 0.4 when level, Then soon as the nose is pitched downwards at high throttle, the gains would start it become less attenuated (or slightly boosted) depending on how you want to word it.
The same can be said for an over powered plane in a vertical climb at high throttle, that doesn't experience speed wash-off in a climb.. This also could lead to a condition of the gains being more boosted than you might like.

but just call it what it is, i.e. pitch TPA ... or some such term.

I think it was named TPA+PA so it wouldn't get mixed-up with the old fixedwing TPA, in its operation.