A Rotorflight-focused GUI workflow for tuning PID gains from blackbox step response analysis.

This project combines the orangebox BBL parser with PID step response analysis (inspired by PIDtoolbox). The recommended workflow is to run gui_step_response.py, analyze .bbl logs, and tune Roll/Pitch/Yaw gains based on measured rise time, overshoot, and settling behavior.

New to this? If you have never used Python or the command line before, start with the Prerequisites section below. It explains everything you need to install before running this application.

When you fly a Rotorflight helicopter, your flight controller records detailed sensor data into a blackbox log (a .bbl file stored on an SD card or onboard flash memory). This tool reads those logs and produces a step response graph — a visual measure of how quickly and smoothly each axis (Roll, Pitch, Yaw) responds to your stick inputs.

By comparing step response graphs across flights you can systematically raise or lower your PID gains to achieve the best possible flying feel without guesswork.

Before running this application you need a few things installed on your computer. These are one-time setup steps.

Python is the programming language this application is written in. You need it installed to run the tool.

• Download Python: https://www.python.org/downloads/
• Click "Download Python 3.x.x" (the big yellow button) and run the installer.
• Windows users: During installation, make sure to tick "Add Python to PATH" before clicking Install.
• macOS users: After installing, open Terminal (press ⌘ Space, type "Terminal", press Enter) and run python3 --version to confirm it installed correctly.
• Linux users: Python 3 is typically pre-installed. Run python3 --version in a terminal to check.

pip (the Python package manager) is included automatically with Python 3.4 and later — you do not need to install it separately.

If you prefer to download the code as a ZIP file instead of using Git, you can skip this step.

• Download Git: https://git-scm.com/downloads
• Run the installer and accept the defaults.

• Rotorflight Step Response Tuning: GUI-first workflow for practical PID tuning
• BBL File Parsing: Parse blackbox logs and handle multiple logs per file
• Step Response Analysis: Calculate step response using FFT-based deconvolution
• Metrics Calculation:
  • Rise time (time to reach 63.2% of final value)
  • Maximum overshoot ratio
  • Settling time
• PID Parameter Extraction: Extract P, I, D, FF, Boost, and D-min when available
• Interactive GUI: Inspect Roll/Pitch/Yaw response curves and export JSON results

Option A — Download as a ZIP (easiest, no Git required)

1. Go to the repository page on GitHub.
2. Click the green "Code" button near the top right.
3. Select "Download ZIP".
4. Extract the ZIP to a folder you will remember, for example C:\Users\YourName\orangebox-pid-step-resp on Windows or ~/orangebox-pid-step-resp on macOS/Linux.

Option B — Clone with Git

Open a terminal (or Git Bash on Windows) and run:

git clone https://github.com/pigd0g/orangebox-pid-step-resp.git
cd orangebox-pid-step-resp

You need to run the following commands from inside the project folder you downloaded or cloned.

• Windows: Open File Explorer, navigate to the folder, then type cmd in the address bar and press Enter.
  Alternatively, hold Shift and right-click an empty area in the folder, then select "Open PowerShell window here".
• macOS: Open Terminal (⌘ Space → "Terminal"), then type cd (with a trailing space), drag the project folder onto the Terminal window, and press Enter.
• Linux: Open a terminal and use cd /path/to/orangebox-pid-step-resp.

A virtual environment is an isolated copy of Python for this project only. It prevents conflicts with other software on your computer. This is a one-time step per installation.

Windows PowerShell:

python -m venv venv
.\venv\Scripts\Activate.ps1

Note for Windows users: If you see a security error about running scripts, run this command first and then try again:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows Command Prompt (cmd):

python -m venv venv
venv\Scripts\activate.bat

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

Once activated, your terminal prompt will show (venv) at the start — this confirms the virtual environment is active. You need to activate it every time you open a new terminal before running the application.

With the virtual environment active, install all required packages:

pip install -r requirements.txt

This downloads and installs NumPy, PySide6, pyqtgraph, and matplotlib. It may take a minute or two on a slow connection. You only need to do this once per installation (or after updating the code).

python gui_step_response.py

The application window should open. If you see any error messages, refer to the Troubleshooting section below.

If you want to share the tool with others who do not have Python installed, you can build a self-contained Windows .exe. This step requires Windows.

Install the additional build tool:

pip install -r requirements-windows-build.txt

Build the executable bundle:

python scripts/build_windows_exe.py

The packaged application will be created under dist/orangebox-step-response/. Run dist/orangebox-step-response/orangebox-step-response.exe to launch it — no Python installation required on the target machine.

Use --onefile if you prefer a single .exe file instead of a folder:

python scripts/build_windows_exe.py --onefile

1. Copy your .bbl file from your flight controller's SD card to your computer.
2. Click Open (or drag the .bbl file) in the GUI to load the log.
3. Click Analyze.
4. The GUI displays step response curves for Roll, Pitch, and Yaw, along with rise time, overshoot, and settling time metrics.
5. Optionally click Export JSON to save the numeric results to a file for comparison between flights.

Use this as a repeatable baseline process across flights.

• Set Feedforward (FF) = 0.
• Set Boost = 0.
• Keep your mechanical setup unchanged during a tuning session (blades, head speed, filtering, weight).

1. Fly a short tuning flight with consistent stick inputs.
2. Save the .bbl and analyze it in gui_step_response.py.
3. Review each axis step response for rise time, overshoot, and settling.
4. Increase P gain slightly (small increment) on the target axis.
5. Repeat over multiple flights, comparing responses after each increment.

• Roll: Increase P until response becomes crisp but not oscillatory; avoid sustained ringing after step inputs.
• Pitch: Increase P similarly; watch for bounce-back or overshoot spikes during aggressive pitch commands.
• Yaw: Increase P carefully in smaller steps; check for tail wag or slow settling.

• Stop increasing P when overshoot/ringing clearly increases or the axis starts to oscillate.
• Back off to the previous stable value.
• Keep FF and Boost at zero during this phase so P behavior is isolated and measurable.

Python was not added to your PATH during installation.
Fix: Reinstall Python from python.org and make sure to tick "Add Python to PATH" on the first installer screen.
Alternatively, try python3 instead of python.

Windows blocks unsigned scripts by default.
Fix: Run this once in PowerShell (as your normal user, not as Administrator):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then reactivate the virtual environment with .\venv\Scripts\Activate.ps1.

The dependencies were not installed, or the virtual environment is not active.
Fix:

1. Activate the virtual environment (you must do this every time you open a new terminal):
   • Windows: .\venv\Scripts\Activate.ps1
   • macOS/Linux: source venv/bin/activate
2. Then install dependencies: pip install -r requirements.txt

• Make sure you are using the minimum Python version listed in Prerequisites: run python --version to check.
• Make sure your virtual environment is active (you should see (venv) in your prompt).
• Re-install dependencies: pip install --upgrade -r requirements.txt.

• Make sure the file ends in .bbl. Some flight controllers save logs with a numbered suffix (e.g., .bbl.001) — rename or copy the file to end in .bbl if needed.
• Make sure blackbox logging was enabled in Rotorflight Configurator before the flight.

python -m unittest

To run only the step-response tests with verbose output:

python -m unittest tests.test_step_response -v

• Contributions are very welcome!
• Please follow the PEP8 Style Guide.
• More info in the docs.

• No explicit validation of raw data against corruption (except for headers), but it's highly likely that a Python exception will be raised in these cases anyway
• Tested only on logs generated by Betaflight
• Not all event frames are parsed (see TODO comments)
• Some decoders are missing (see TODO comments)

• Original blackbox data encoder and decoder was written by Nicholas Sherlock.
• Step response algorithm based on PIDtoolbox by Brian White.

This project is licensed under GPLv3.