A Cleanflight/Betaflight blackbox log parser written in Python 3. orangebox has no dependencies other than the Python standard library. It was roughly modeled after the one in Blackbox Log Viewer hence produces the same output. Merged files (flash chip logs) are supported since version 0.2.0.

The name “orangebox” comes from the fact that so-called black boxes (flight data recorders) are in fact orange to help the work of search and rescue teams by making it easier to find.

A Cockpit Voice and Data Recorder (CVDR), with its attached ULB visible on the left side of the unit


From package

For normal usage you can go down the common road and use pip:

pip install orangebox

From source

# fetch the source
git clone <repository-url> orangebox

# run install script
cd orangebox
sudo python install

Alternative install option for development is described here.

Code example

from orangebox import Parser

# Load a file
parser = Parser.load("btfl_all.bbl")
# or optionally select a log by index (1 is the default)
# parser = Parser.load("btfl_all.bbl", 1)

# Print headers
print("headers:", parser.headers)

# Print the names of fields
print("field names:", parser.field_names)

# Select a specific log within the file by index
print("log count:", parser.reader.log_count)

# Print field values frame by frame
for frame in parser.frames():
    print("first frame:",

# Complete list of events only available once all frames have been parsed

# Selecting another log changes the header and frame data produced by the Parser
# and also clears any previous results and state


For development you can use a virtual environment and install the package in “editable” mode.

# fetch the source
git clone <repository-url> orangebox

# create and activate virtual environment
cd orangebox
python3 -m venv env

# install orangebox for development in the active environment
env/bin/python develop

If you wish to remove the development install and keep the virtual env you can uninstall it:

$ env/bin/python develop --uninstall

Development tools

You can use to test against a CSV file generated by blackbox-tools or Blackbox Log Viewer. It compares the decoded values to the ones in the CSV file and shows the differences with some additional info.

Please note that blackbox_decode and exporting from Blackbox Log Viewer can produce different results. This is probably due to blackbox_decode is now less frequently maintained.

usage: [-h] [-i LOG_INDEX] [-a] [-v] path csv_path

positional arguments:
  path                  Path to a .BFL file
  csv_path              Path to a .CSV file for verification

optional arguments:
  -h, --help            show this help message and exit
  -i LOG_INDEX, --index LOG_INDEX
                        Log index number (In case of merged input) (default: 1)
  -a, --show-all-fields
                        Show all fields of differing frames (default: False)
  -v                    Control verbosity (can be used multiple times) (default: 0)

To profile or measure the parser’s execution you can use and with a single argument that’s a path to a BFL file:

$ python3 ~/logs/LOG00042.BFL