This is an experimental RUST program, mostly created via A.I., to read Betaflight Blackbox CSV and produce meaningful graphs.

Table of Contents

• Prerequisites
• Build
• Usage
• Example execution commands
• Output
• Code Overview
• Development
  • Setting Up Development Environment
  • Required Commands Before Committing
  • CI Requirements
• License

Prerequisites

1. Rust installation page
2. blackbox_decode your BBL to CSV (--save-headers, --index <num>, and --limits parameters may be useful)

Build

cargo build --release

Usage

Notice: Default output is core plots only. Use --extended for all plots.

Usage: ./BlackBox_CSV_Render <input1> [<input2> ...] [OPTIONS]

=== INPUT/OUTPUT OPTIONS ===

  <inputX>: CSV files, directories, or wildcards (*.csv). Header files auto-excluded.
  -O, --output-dir <directory>: Output directory (default: source folder).
  -R, --recursive: Recursively find CSV files in subdirectories.

=== PLOT TYPE SELECTION ===

  --core           [default] Step Response, Gyro Spectrums, D-term Spectrums,
                   Setpoint vs Gyro, Gyro vs Unfiltered, Motor Spectrums.
  --extended       All plots except Bode — adds PIDsum/Error, PID Activity,
                   Setpoint Derivative, Gyro PSD, D-term PSD, and heatmaps.
  --step           Step response only.
  --bode           Bode only (requires chirp/sweep system-id test flight).

=== ANALYSIS OPTIONS ===

  --butterworth    Show Butterworth PT1 cutoffs on gyro/D-term spectrum plots.
  --dps <value>    Deg/s threshold for detailed step response plots (positive number).
  --estimate-optimal-p  [EXPERIMENTAL] Optimal P estimation from throttle-punch
                        dynamics. Requires .headers.csv; skips if absent.

=== GENERAL ===

  --debug          Show detailed metadata during processing.
  -h, --help       Show this help message and exit.
  -V, --version    Show version information.

Arguments can be in any order. Wildcards (e.g., *.csv) are shell-expanded and work with mixed file/directory patterns.

Example execution commands

./target/release/BlackBox_CSV_Render path/to/BTFL_Log.csv

./target/release/BlackBox_CSV_Render path/to/*LOG*.csv --dps 500 --butterworth

./target/release/BlackBox_CSV_Render path1/to/BTFL_*.csv path2/to/EMUF_*.csv --output-dir ./plots --butterworth

./target/release/BlackBox_CSV_Render path/to/ -R --step --output-dir ./step-only

./target/release/BlackBox_CSV_Render path/to/ --extended --output-dir ./all-plots

./target/release/BlackBox_CSV_Render path/to/BTFL_Log.csv --step --estimate-optimal-p

Output

PNG Files Generated

Core (default):

• *_Step_Response_stacked_plot_*.png — Step response analysis with P:D recommendations
• *_SetpointVsGyro_stacked.png — Setpoint vs. filtered gyro comparison
• *_GyroVsUnfilt_stacked.png — Filtered vs. unfiltered gyro comparison with delay estimates
• *_Gyro_Spectrums_comparative.png — Frequency-domain gyro amplitude spectrums
• *_D_Term_Spectrums_comparative.png — Frequency-domain D-term amplitude spectrums
• *_Motor_Spectrums_stacked.png — Motor output frequency analysis (supports any motor count; colors wrap every 8 motors)

Extended (--extended adds these to the core set):

• *_PIDsum_PIDerror_Setpoint_stacked.png — PIDsum, PID error, and setpoint traces
• *_PID_Activity_stacked.png — P, I, D term activity over time
• *_SetpointDerivative_stacked.png — Setpoint rate-of-change / feed-forward proxy
• *_Gyro_PSD_comparative.png — Gyro power spectral density (dB scale)
• *_D_Term_PSD_comparative.png — D-term power spectral density (dB scale)
• *_D_Term_Heatmap_comparative.png — D-term throttle/frequency heatmap
• *_Gyro_PSD_Spectrogram_comparative.png — Gyro spectrogram (PSD vs. time)
• *_Throttle_Freq_Heatmap_comparative.png — Throttle/frequency heatmap analysis

Markdown Report (always generated)

• *_report.md — Structured flight report written alongside PNGs on every run. Sections: Metadata (firmware, PIDs, sample rate, gyroUnfilt source), Filter Configuration (LPF1/LPF2/IMUF/Pseudo-Kalman table, Dynamic Notch, RPM filter), PID Tuning, Step Response Analysis (Roll/Pitch with P:D assessment and setpoint authority), Gyro Analysis (filtering delay, confidence, spectrum peaks per axis), D-Term Analysis (filtering delay with N/A reason, spectrum peaks), Motor Oscillation, and links to all generated PNGs. Optimal P Estimation and Bode Analysis sections appear when those features are active.

Console Output:

• Current P:D ratio and peak analysis with response assessment
• Conservative and Moderate tuning recommendations (with D/D-Min/D-Max values)
• Warning indicators for severe overshoot or unreasonable ratios
• Gyro filtering delay estimates (filtered vs. unfiltered, with confidence)
• Filter configuration parsing and spectrum peak detection summaries
• Optimal P estimation (--estimate-optimal-p): Td timing, target deviation, noise level, consistency, P/D recommendations and skip-reason warnings
• Use --debug flag for additional metadata: header information, flight data key mapping, sample header values, and debug mode identification

Code and Output Overview

For a detailed explanation of the program's functionality, especially the step-response calculation and comparison with other tools like PIDtoolbox (Matlab) and PlasmaTree PID-Analyzer (Python), please see OVERVIEW.md.

Development

Setting Up Development Environment

To set up your development environment with proper formatting and pre-commit hooks:

# Clone and setup
git clone https://github.com/nerdCopter/BlackBox_CSV_Render.git
cd BlackBox_CSV_Render

# Run setup script (optional but recommended)
chmod +x .github/setup-dev.sh
./.github/setup-dev.sh

Required Commands Before Committing

⚠️ IMPORTANT: Always run these commands before committing to avoid CI failures:

# 1. Check for clippy warnings (must be fixed first)
cargo clippy --all-targets --all-features -- -D warnings

# 2. Format code
cargo fmt --all

# 3. Check formatting compliance
cargo fmt --all -- --check

# 4. Run all tests
cargo test --verbose

# 5. Build release
cargo build --release

The development setup includes an automated pre-commit hook that will:

• Automatically format your code with cargo fmt
• Run clippy checks to catch code issues
• Prevent commits with formatting issues

CI Requirements

The project enforces strict formatting and code quality standards.

License

This project is dual-licensed under the terms of the AGPL-3.0-or-later and a commercial license.

• AGPL-3.0-or-later: You may use, distribute, and modify this software under the terms of the GNU Affero General Public License, version 3 or any later version. The full license text is available in the LICENSE file.

• Commercial License: If you wish to use this software in a commercial product without being bound by the terms of the AGPL, you must purchase a commercial license. For more information, please see the LICENSE_COMMERCIAL file.