FPV PID Lab - Structured Blackbox Analysis

This project provides a manual, explainable analysis pipeline for Betaflight Blackbox logs. It intentionally does not perform PID tuning yet.

What It Does

1. Parses Blackbox CSV exports into a normalized data model.
2. Segments flight logs into:
   • hover (steady throttle)
   • step response (sharp stick/setpoint inputs)
   • propwash (throttle drop follow-up windows)
3. Computes per-segment metrics.
4. Produces:
   • machine-readable JSON
   • human-readable text summary

Segment Metrics

• Hover
  • Gyro noise (RMS)
  • Frequency spectrum (dominant bins from Welch PSD)
• Step response
  • Tracking error (gyro vs setpoint RMS)
  • Overshoot
  • Rise time
• Propwash
  • Oscillation energy after throttle drop
  • Signal decay time

Installation

pip install -e .

Usage

fpv-analyze path/to/blackbox_export.csv --json-out reports/analysis.json --summary-out reports/summary.txt

Outputs are also printed to stdout.

Input Columns

The parser normalizes common Blackbox Explorer export names and expects:

• time_s (or time_ms)
• throttle
• gyro_roll, gyro_pitch, gyro_yaw
• setpoint_roll, setpoint_pitch, setpoint_yaw

Project Structure

flight-control-lab/
├── configs/                    # YAML/TOML configuration files
├── data/                       # Sample Blackbox CSV files
├── examples/                   # Example input files
│   └── sample_blackbox.csv
├── notebooks/                  # Exploratory analysis notebooks
├── src/
│   └── fpv_pid_lab/
│       ├── parser/             # Blackbox CSV log parsing adapter
│       ├── segmentation/       # Flight segment detection
│       ├── features/           # Metric extraction per segment
│       ├── tuning/             # (future) Rule-based PID tuning modules
│       ├── validation/         # (future) Result validation modules
│       ├── models.py           # Shared data models
│       ├── pipeline.py         # Orchestration
│       ├── reporting.py        # JSON + text reporting
│       └── cli.py              # Command line interface
└── tests/
    ├── test_pipeline.py        # Synthetic end-to-end validation
    ├── test_parser.py
    ├── test_segmentation.py
    ├── test_features.py
    ├── test_tuning.py
    └── test_validation.py

Design For Future Extension

The current architecture is designed to add later without refactoring:

• Rule-based tuning modules in src/fpv_pid_lab/tuning/ consuming the metric JSON
• Scoring system that aggregates segment-level quality signals
• Optimization loops that propose PID/filter parameter candidates
• Configuration files in configs/ for tunable thresholds (YAML/TOML)