merge: master into 20260402_Quickflash-ESO

Resolve OVERVIEW.md conflict: drop stale --eso-axis and --report/
Statistical Report section; take master's cleaned ESO-only text.
src/constants.rs merged cleanly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nerdCopter

OVERVIEW.md

@@ -28,8 +28,7 @@ All analysis parameters, thresholds, plot dimensions, and algorithmic constants
     * Additional options include `--help` and `--version` for user assistance.
     * The `--output-dir` parameter now requires a directory path when specified. If omitted, plots are saved in the source folder (input file's directory).
     * Handles multiple input files and determines if a directory prefix should be added to output filenames to avoid collisions when processing files from different directories.
-    * **ESO flags:** `--eso` enables 2nd-order LESO bandwidth optimization; `--eso-axis <roll,pitch,yaw>` selects axes (default: all); `--eso-b0 <value>` sets control effectiveness (default: 1.0).
-    * **Report flag:** `--report` writes a markdown statistical report (`<stem>_report.md`) alongside plot outputs.
+    * **ESO flags:** `--eso` enables 2nd-order LESO bandwidth optimization; `--eso-b0 <value>` sets control effectiveness (default: 1.0).
 
 2.  **File Processing (`src/main.rs:process_file`):**
     * For each input CSV:
@@ -169,7 +168,7 @@ All analysis parameters, thresholds, plot dimensions, and algorithmic constants
 ### ESO Gain Optimization (Optional)
 
 * **Purpose:** Offline system identification of 2nd-order LESO (Linear Extended State Observer) bandwidth (omega_0) from recorded flight data. Finds observer gains that minimise tracking error against measured gyro rate.
-* **Activation:** Disabled by default; enable with `--eso`. Optionally restrict axes with `--eso-axis roll,pitch,yaw` and set control effectiveness with `--eso-b0 <value>`.
+* **Activation:** Disabled by default; enable with `--eso`. Set control effectiveness with `--eso-b0 <value>`.
 * **Algorithm (`src/eso.rs`):**
     * Extracts filtered gyro (omega) and PID sum (P+I+D+F) per axis as measured output and control input respectively.
     * Simulates a discrete Euler-forward 2nd-order LESO at each candidate omega_0:
@@ -179,17 +178,10 @@ All analysis parameters, thresholds, plot dimensions, and algorithmic constants
     * Bandwidth parameterisation (Gao 2003): `beta1 = 2*omega_0`, `beta2 = omega_0^2`.
     * Minimises MSE(omega_hat, omega_meas) via golden-section search over `[ESO_OMEGA0_MIN, min(sample_rate/3, ESO_OMEGA0_MAX)]`.
 * **Stability constraint:** omega_0 < sample_rate / 3 (enforced automatically).
-* **Output:** Prints optimal omega_0, beta1, beta2, and MSE per axis to console. Results are also included in the markdown report if `--report` is also given.
+* **Output:** Prints optimal omega_0, beta1, beta2, and MSE per axis to console.
 * **Limitations:** `b0=1.0` (default) is dimensionless. For absolute accuracy co-tune b0 using known frame inertia. The cost function is MSE on the closed-loop observer output; unimodality is assumed over the search range.
 
-### Statistical Report Output (Optional)
 
-* **Purpose:** Produces a markdown file summarising per-axis signal statistics and optional ESO results alongside plot outputs.
-* **Activation:** Enable with `--report`. File is written as `<stem>_report.md` in the output directory.
-* **Content (`src/report.rs`):**
-    * **Metadata:** Sample rate, total row count, flight duration, selected firmware/configuration keys.
-    * **Per-axis tables:** Mean, std dev, min, max, RMS, sample count for gyro (filtered), setpoint, PID sum, P-term, I-term, and D-term.
-    * **ESO table (when `--eso` is also active):** omega_0, beta1, beta2, b0, MSE, and sample count per axis.
 
 
 
@@ -212,8 +204,6 @@ When `--step` flag is not used, all plots below are generated:
 
 #### Generated Reports
 
-- **`*_report.md`** — Markdown statistical report (requires `--report`). Per-axis signal statistics table and, when combined with `--eso`, the optimised LESO gains.
-
 #### P:D Ratio Recommendations
 
 The system provides intelligent P:D tuning recommendations based on step-response peak analysis:

src/constants.rs

@@ -393,3 +393,8 @@ pub const TORQUE_PROFILER_P_SCALE: f64 = 100.0;
 /// Empirically calibrated on a 5" 6S freestyle build (HELIO H7); may need
 /// adjustment for significantly heavier or lighter aircraft classes.
 pub const TORQUE_PROFILER_ACHIEVABILITY_FACTOR: f64 = 2.50;
+
+/// Betaflight/EmuFlight debug_mode value for GYRO_SCALED.
+/// Only this mode populates debug[0-2] with raw unfiltered gyro data,
+/// making it a valid fallback source for gyroUnfilt.
+pub const DEBUG_MODE_GYRO_SCALED: u32 = 6;

src/data_input/log_parser.rs

@@ -6,6 +6,7 @@ use std::fs::File;
 use std::io::{BufRead, BufReader, Seek, SeekFrom};
 use std::path::Path;
 
+use crate::constants::DEBUG_MODE_GYRO_SCALED;
 use crate::data_input::log_data::LogRowData;
 use crate::types::LogParseResult;
 
@@ -206,6 +207,7 @@ pub fn parse_log_file(input_file_path: &Path, debug_mode: bool) -> LogParseResul
 
     let header_indices: Vec<Option<usize>>;
     let mut motor_indices: Vec<usize> = Vec::new();
+    let using_debug_fallback: bool;
 
     // Read CSV header and map target headers to indices.
     {
@@ -442,22 +444,39 @@ pub fn parse_log_file(input_file_path: &Path, debug_mode: bool) -> LogParseResul
             .into());
         }
 
-        // Report debug fallback usage if applicable
-        let using_debug_fallback = !gyro_unfilt_header_found.iter().any(|&found| found)
-            && debug_header_found.iter().take(3).any(|&found| found);
-
-        if using_debug_fallback {
-            println!("  ⚠️  Using debug[0-2] as fallback for gyroUnfilt[0-2]");
-
-            // Try to report which debug mode is being used
-            if let Some((_, debug_mode_value)) =
-                header_metadata.iter().find(|(k, _)| k == "debug_mode")
-            {
-                if let Ok(debug_int) = debug_mode_value.parse::<u32>() {
-                    println!("  Debug mode value: {}", debug_int);
+        // Apply debug[0-2] fallback for gyroUnfilt only when debug_mode=GYRO_SCALED (6).
+        // Other debug modes do not populate debug[0-2] with raw gyro data.
+        let have_gyro_unfilt = gyro_unfilt_header_found.iter().any(|&found| found);
+        let have_debug_axes = debug_header_found.iter().take(3).any(|&found| found);
+        using_debug_fallback = if !have_gyro_unfilt && have_debug_axes {
+            let debug_mode_val = header_metadata
+                .iter()
+                .find(|(k, _)| k == "debug_mode")
+                .and_then(|(_, v)| v.parse::<u32>().ok());
+            match debug_mode_val {
+                Some(DEBUG_MODE_GYRO_SCALED) => {
+                    // GYRO_SCALED: debug[0-2] contains raw unfiltered gyro
+                    println!(
+                        "  ⚠️  Using debug[0-2] as gyroUnfilt fallback (debug_mode=GYRO_SCALED)"
+                    );
+                    true
+                }
+                Some(mode) => {
+                    println!(
+                        "  ⚠️  Skipping debug[0-2] gyroUnfilt fallback: debug_mode={} is not GYRO_SCALED ({}) — unfiltered gyro analysis unavailable",
+                        mode, DEBUG_MODE_GYRO_SCALED
+                    );
+                    false
+                }
+                None => {
+                    // debug_mode absent from headers — allow but warn
+                    println!("  ⚠️  Using debug[0-2] as gyroUnfilt fallback (debug_mode unknown, assuming GYRO_SCALED)");
+                    true
                 }
             }
-        }
+        } else {
+            false
+        };
     }
 
     // --- Data Reading and Storage ---
@@ -547,10 +566,12 @@ pub fn parse_log_file(input_file_path: &Path, debug_mode: bool) -> LogParseResul
                     }
 
                     // Apply Fallback Logic for gyro_unfilt (debug[0-2] --> gyroUnfilt[0-2])
+                    // Fallback is only valid when debug_mode=GYRO_SCALED (6); see using_debug_fallback.
                     for axis in 0..crate::axis_names::AXIS_NAMES.len() {
                         current_row_data.gyro_unfilt[axis] = match parsed_gyro_unfilt[axis] {
                             Some(val) => Some(val),
-                            None => parsed_debug[axis],
+                            None if using_debug_fallback => parsed_debug[axis],
+                            None => None,
                         };
                     }