Merge 9.x to master

docs/Blackbox.md

@@ -166,13 +166,36 @@ The CLI command `blackbox` allows setting which Blackbox fields are recorded to
 * `PEAKS_R` - Roll axis noise peak
 * `PEAKS_P` - Pitch axis noise peak
 * `PEAKS_Y` - Yaw axis noise peak
+* `SERVOS` - Servo outputs (for planes, tris, etc.)
 
 Usage:
 
 * `blackbox` currently enabled Blackbox fields
 * `blackbox list` all available fields
 * `blackbox -MOTORS` disable MOTORS logging
-* `blackbox MOTOR` enable MOTORS logging
+* `blackbox MOTORS` enable MOTORS logging
+
+### Debug Mode Logging
+
+In addition to the standard blackbox fields above, INAV supports logging debug values for troubleshooting and analysis via the `debug_mode` setting. When a debug mode is active, it populates 8 debug values (`debug[0]` through `debug[7]`) with mode-specific data that gets logged to the blackbox.
+
+Available debug modes include:
+- `FLOW_RAW` - Optical flow sensor raw data (useful for sensor alignment)
+- `LANDING` - Landing mode debugging
+- `POS_EST` - Position estimation debugging
+- `GPS` - GPS debugging
+- `ALTITUDE` - Altitude estimation debugging
+- And 20+ other modes for specific subsystems
+
+To use debug mode logging:
+```
+set debug_mode = FLOW_RAW    # Enable a specific debug mode
+set debug_mode = NONE        # Disable debug mode (default)
+```
+
+You can view current debug values in the CLI with the `debug` command, or display them in real-time on your OSD using the `OSD_DEBUG` element.
+
+For technical details on debug logging and blackbox internals, see the [Blackbox Internals](development/Blackbox%20Internals.md) documentation.
 
 ## Usage
 

docs/Settings.md

@@ -434,11 +434,11 @@ Max Antigravity gain. `1` means Antigravity is disabled, `2` means Iterm is allo
 
 ### apa_pow
 
-Use airspeed instead of throttle position for PID attenuation if airspeed is available on fixedwing. pid_multiplier = (referenceAirspeed/airspeed)**(apa_pow/100). Set to 0 will disable this feature and use throttle based PID attenuation;
+Use airspeed instead of throttle position for PID attenuation if airspeed is available on fixedwing. Scales P/D/FF with airspeed (I-term scaled less aggressively). Gains range from 30% (high speed) to 150% (low speed). Set to 0 to disable and use throttle-based attenuation. Recommended: 120 for aircraft with validated pitot sensor.
 
 | Default | Min | Max |
 | --- | --- | --- |
-| 120 | 0 | 200 |
+| 0 | 0 | 200 |
 
 ---
 
@@ -1478,7 +1478,7 @@ TPA smoothing and delay time constant to reflect non-instant speed/throttle resp
 
 | Default | Min | Max |
 | --- | --- | --- |
-| 1500 | 0 | 5000 |
+| 2000 | 0 | 5000 |
 
 ---
 

docs/USB Flashing.md

@@ -68,14 +68,26 @@ With the board connected and in bootloader mode (reset it by sending the charact
 
 Put the device into DFU mode by **one** of the following:
 
-* Use the hardware button on the board
-* Send a single 'R' character to the serial device, e.g. on POSIX OS using `/dev/ttyACM0` at 115200 baudrate.
+* **Hardware button:** Press and hold the DFU/BOOT button while plugging in USB
 
+* **Serial CLI sequence:** Send `####\r\n`, wait for CLI prompt, then send `dfu\r\n`
+
+```bash
+# Enter CLI mode
+echo -ne '####\r\n' > /dev/ttyACM0
+
+# Wait for "CLI" prompt (important - don't skip!)
+# Recommended: use a proper script that reads serial response
+
+# Send DFU command
+echo -ne 'dfu\r\n' > /dev/ttyACM0
 ```
-stty 115200 < /dev/ttyACM0
-echo -ne 'R' > /dev/ttyACM0
-```
-* Use the CLI command `dfu`
+
+**Note:** The simple single 'R' character method shown in older documentation is unreliable. The above sequence is required for proper CLI entry.
+
+* **CLI command:** If already connected to CLI via configurator or terminal: type `dfu`
+
+* **MSP command:** Use MSP_REBOOT with DFU parameter (INAV 9.x+) - most reliable programmatic method
 
 It is necessary to convert the `.hex` file into `Intel binary`. This can be done using the GCC `objcopy` command; e.g. for the notional `inav_x.y.z_NNNNNN.hex`.
 

docs/development/msp/format.md

@@ -39,7 +39,7 @@
 **reply**: null or dict of data received\
 **variable_len**: Optional boolean, if true, message does not have a predefined fixed length and needs appropriate handling\
 **variants**: Optional special case, message has different cases of reply/request. Key/description is not a strict expression or code; just a readable condition\
-**not_implemented**: Optional special case, message is not implemented\
+**not_implemented**: Optional special case, message is not implemented (never or deprecated)\
 **notes**: String with details of message
 
 ## Data dict fields:

docs/development/msp/gen_enum_md.py

@@ -62,7 +62,7 @@ def is_plain_int_literal(expr: str) -> Optional[int]:
 
 # ---------- Parsing regexes ----------
 
-RE_ENUM_START   = re.compile(r'^\s*typedef\s+enum\s*\{')
+RE_ENUM_START   = re.compile(r'^\s*typedef\s+enum(?:\s+[A-Za-z_]\w*)?\s*\{')
 RE_ENUM_END     = re.compile(r'^\s*\}\s*([A-Za-z_]\w*)\s*;')
 RE_LINE_COMMENT = re.compile(r'^\s*//\s*(.+?)\s*$')
 
@@ -273,6 +273,9 @@ def render_markdown(enums: List[EnumDef]) -> str:
             cond = it.cond
             out.append(f"| {name_md} | {val} | {cond} |")
             jsonfile[e.name][name_md.strip('`')] = [val, cond] if len(cond)>0 else val
+        # normalize source to a stable inav/src/... path
+        if '_source' in jsonfile[e.name]:
+            jsonfile[e.name]['_source'] = jsonfile[e.name]['_source'].replace('../../../src', 'inav/src')
         out.append("")
     # While we're at it, chuck this all into a JSON file
     Path("inav_enums.json").write_text(json.dumps(jsonfile,indent=4), encoding="utf-8")