Orangebox

A Cleanflight/Betaflight blackbox log parser written in Python 3.

Orangebox has no dependencies other than the Python standard library, although it might be worthy to investigate how using numpy could possibly bring some performance gain in the future. If so, it shouldn't be a usability barrier since any user wanting to make something out of the decoded data will more than likely have numpy installed transitively as well as it's also a dependency of libraries like matplotlib and pandas (among others).

This parser was roughly modeled after the one in Blackbox Log Viewer hence produces the same output.

Documentation

You can browse the full documentation online on Read the Docs, here's a quick 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)
parser.set_log_index(2)

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

# Complete list of events only available once all frames have been parsed
print("events:", parser.events)

# Selecting another log changes the header and frame data produced by the Parser
# and also clears any previous results and state
parser.set_log_index(1)

Contributing

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

Changelog

0.5.0

• Breaking change: raise RuntimeError on unexpected end of log
• New features and fixes thanks to @rtlopez!
  • Add support for Inav and Rotorflight events
  • Handle unexpected end of log
  • Event parsing bugfix

0.4.0

• Inspect log files for potentially missing required headers
• Allow skipping of badly formatted headers via the allow_invalid_header argument

0.3.1

• Add bb2gpx utility for converting GPS data into GPX

0.3.0

• Add support for GPS frames (thanks to @tblaha!)

0.2.0

• Improved Reader class can now handle multiple logs in a single file
• Add bbsplit command-line script for splitting flashchip logs (thanks to @ysoldak!)
• Improved logging
• Added HTML documentation
• Fix parsing stats

0.1.1-beta

• Add bb2csv command-line script for converting logs into CSV

0.1.0-beta

• First release (with a lot of missing parts)

Known issues

• 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)

Acknowledgement

Original blackbox data encoder and decoder was written by Nicholas Sherlock.

License

This project is licensed under GPLv3.