Metadata-Version: 2.4
Name: orangebox
Version: 0.5.0
Summary: A Cleanflight/Betaflight blackbox log parser written in Python 3
Project-URL: Bug Tracker, https://github.com/atomgomba/orangebox/issues
Project-URL: Source Code, https://github.com/atomgomba/orangebox
Author-email: Károly Kiripolszky <karcsi@ekezet.com>
License-Expression: GPL-3.0
License-File: LICENSE
Keywords: betaflight,blackbox,cleanflight,inav,rotorflight
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: System :: Archiving :: Compression
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# Orangebox

[![PyPI version](https://badge.fury.io/py/orangebox.svg)](https://badge.fury.io/py/orangebox) 
[![Documentation Status](https://readthedocs.org/projects/orangebox/badge/?version=latest)](https://orangebox.readthedocs.io/en/latest/?badge=latest)

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](https://github.com/betaflight/blackbox-log-viewer) hence produces the same output.

## Documentation

You can browse the full documentation online on [Read the Docs](https://orangebox.readthedocs.io), here's a quick example:

```python3
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](https://www.python.org/dev/peps/pep-0008/) Style Guido.
* [More info](https://orangebox.readthedocs.io/#development) in the docs.

## Changelog

### 0.5.0

* *Breaking change:* raise `RuntimeError` on unexpected end of log
* New features and fixes thanks to [@rtlopez](https://github.com/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](https://github.com/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](https://github.com/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](orangebox/events.py) comments)
* Some decoders are missing (see [TODO](orangebox/decoders.py) comments)

## Acknowledgement

Original blackbox data encoder and decoder was written by [Nicholas Sherlock](https://github.com/thenickdude).

## License

This project is licensed under GPLv3.
