From bc79297a72749a24095d32ff62b7a17e184b3bed Mon Sep 17 00:00:00 2001 From: nerdCopter <56646290+nerdCopter@users.noreply.github.com> Date: Mon, 29 Dec 2025 16:36:55 -0600 Subject: [PATCH 1/4] feat: Release version 1.0.0 - Production-ready stable release - Bump version from 0.9.0 to 1.0.0 - Add comprehensive CHANGELOG.md documenting features and roadmap - Remove INAV from crates.io description (Betaflight/EmuFlight only) - Update README.md and OVERVIEW.md to reflect supported firmware - Whitelist CHANGELOG.md in .gitignore for version control - Verified all mandatory checks: format, clippy, tests, build - Ready for crates.io publishing with CARGO_REGISTRY_TOKEN secret --- .gitignore | 1 + CHANGELOG.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++ Cargo.lock | 2 +- Cargo.toml | 4 +- OVERVIEW.md | 2 +- README.md | 2 +- 6 files changed, 107 insertions(+), 5 deletions(-) create mode 100644 CHANGELOG.md diff --git a/.gitignore b/.gitignore index b732c4b..aceee8e 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ !OVERVIEW.md !GOALS.md !FRAMES.md +!CHANGELOG.md !build.rs !Cargo.* !.gitignore diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..db040a4 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,101 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2025-12-29 + +### Added +- **Complete BBL binary format parser** with support for all frame types (I, P, S, H, G, E) +- **Library API** (`bbl_parser` crate) for programmatic access to parsing and export functions +- **CSV export** with blackbox_decode-compatible field ordering and formatting +- **GPX export** for GPS track visualization and mapping applications +- **Event export** in JSONL format with official Betaflight FlightLogEvent enum mapping +- **Multi-log support** with automatic detection and separate file generation +- **Smart export filtering** based on flight duration and gyro activity heuristics +- **Streaming architecture** for memory-efficient processing of large files (tested: 375K+ frames) +- **Comprehensive CLI** with configurable output options and batch processing +- **Feature flags** (`csv`, `json`, `cli`, `serde`) for flexible dependency management +- **Firmware compatibility** for Betaflight (4.5+), EmuFlight, and INAV +- **Unit conversions** for voltage (raw to volts) and current (raw to amps) +- **Energy calculation** with cumulative amperage integration +- **Betaflight-accurate flag formatting** for flight mode, state, and failsafe phases +- **GPS coordinate conversion** from NE (north-east) to standard GPS coordinates +- **Comprehensive test coverage** with 62 unit tests + 8 integration tests +- **Complete documentation** including README, CRATE_USAGE.md, OVERVIEW.md, and 8 examples +- **API documentation** with rustdoc comments on all public types and functions +- **GitHub Actions CI/CD** with multi-platform testing (Linux, Windows, macOS) +- **Automated release workflow** for crates.io publication with artifact management + +### Technical Highlights +- **Pure Rust implementation** with no external binary dependencies +- **Production-grade error handling** using `anyhow::Result` throughout public API +- **Type-safe design** with minimal unsafe code +- **Cross-platform support** verified on Ubuntu, Windows, and macOS +- **Dual licensing:** AGPL-3.0-or-later (open source) + commercial option available + +### Performance +- Efficiently processes large blackbox logs via streaming architecture +- Tested on files up to 375K+ frames (21 MB) in under 7 seconds +- Memory-efficient frame processing with selective storage for analysis + +### Compatibility +- **Input formats:** .BBL, .BFL, .TXT (case-insensitive) +- **Firmware versions:** Betaflight 4.5+, EmuFlight, INAV +- **Output formats:** CSV, GPX, JSONL event logs +- **Binary compatibility:** Output matches blackbox_decode reference implementation + +### Documentation +- Extensive project documentation (README.md, OVERVIEW.md, CRATE_USAGE.md) +- Frame format specifications in FRAMES.md +- Usage examples for CSV, GPX, and event exports +- Contribution guidelines and commercial licensing information + +--- + +## Future Roadmap + +### Planned for 1.1.0 +- IMU angle computation (roll, pitch, yaw) from gyro/accelerometer/magnetometer data +- Extended unit conversions (altitude, speed, rotation rates, acceleration) +- GPS data integration into main CSV output +- Enhanced loop timing statistics and frame distribution analysis +- Parallel frame processing for multi-log files + +### Planned for 1.x series +- Advanced filtering options for specialized analysis +- Raw mode output (unprocessed sensor values) +- Current meter simulation improvements +- Extended firmware version testing coverage + +--- + +## Known Limitations & Future Work + +The following are not blocking 1.0.0 but may be addressed in future releases: + +- IMU simulation features not yet implemented +- Some unit conversion types not yet available (altitude, speed, rotation rates) +- GPS data is exported separately (.gps.gpx) rather than integrated into CSV +- Raw sensor value export mode not available +- Some `.unwrap()` calls in test/example code (critical paths use proper Result handling) + +--- + +## Acknowledgments + +This project is built on extensive analysis of: +- [Betaflight blackbox-log-viewer](https://github.com/betaflight/blackbox-log-viewer) +- [Betaflight blackbox-tools](https://github.com/betaflight/blackbox-tools) + +The implementation ensures compatibility with established blackbox format specifications +while providing the benefits of a modern, type-safe Rust library. + +--- + +## Version History + +- **1.0.0** (2025-12-29) - First stable release +- **0.9.0** (2025-08+) - Development releases leading up to 1.0.0 diff --git a/Cargo.lock b/Cargo.lock index 3a09ab7..93151c9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -69,7 +69,7 @@ checksum = "e16d2d3311acee920a9eb8d33b8cbc1787ce4a264e85f964c2404b969bdcd487" [[package]] name = "bbl_parser" -version = "0.9.0" +version = "1.0.0" dependencies = [ "anyhow", "clap", diff --git a/Cargo.toml b/Cargo.toml index 5e64c3f..c1a457f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,10 +1,10 @@ [package] name = "bbl_parser" -version = "0.9.0" +version = "1.0.0" edition = "2021" authors = ["nerdCopter"] license = "AGPL-3.0-or-later" -description = "Parser for Betaflight/EmuFlight/INAV blackbox log files" +description = "Parser for Betaflight/EmuFlight blackbox log files" keywords = ["betaflight", "blackbox", "drone", "flight-log", "parser"] categories = ["parsing", "aerospace"] rust-version = "1.70.0" diff --git a/OVERVIEW.md b/OVERVIEW.md index e7797d6..0bb64b4 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -26,7 +26,7 @@ A comprehensive Rust library and command-line tool for BBL (Blackbox Log) parsin ### **File Processing Capabilities** - **Formats:** .BBL, .BFL, .TXT (case-insensitive) -- **Firmware:** Betaflight, EmuFlight, INAV +- **Firmware:** Betaflight, EmuFlight - **File Sizes:** Handles large files via streaming architecture (tested up to 240K+ rows) - **Multi-Log Support:** Automatic detection and processing of multiple flights diff --git a/README.md b/README.md index 98a6049..3c405c3 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A fast, pure-Rust Blackbox Log parser primarily used as a command-line tool, with an optional Rust crate API. -Supports `.BBL`, `.BFL`, `.TXT` (case-insensitive) across Betaflight, EmuFlight, and INAV. +Supports `.BBL`, `.BFL`, `.TXT` (case-insensitive) across Betaflight and EmuFlight. ## Table of Contents - [Overview](#overview) From b048e29a348d38a7518a90e7cf70805f33e5fc00 Mon Sep 17 00:00:00 2001 From: nerdCopter <56646290+nerdCopter@users.noreply.github.com> Date: Mon, 29 Dec 2025 16:48:29 -0600 Subject: [PATCH 2/4] fix: Remove all INAV references from documentation - CHANGELOG.md (lines 46, 274): Remove INAV from firmware compatibility - OVERVIEW.md (lines 116, 274): Remove INAV from firmware support statements Ensures consistency across Cargo.toml, README.md, OVERVIEW.md, and CHANGELOG.md which now all declare support for Betaflight and EmuFlight only. --- CHANGELOG.md | 4 ++-- OVERVIEW.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index db040a4..ceb186d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,7 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Streaming architecture** for memory-efficient processing of large files (tested: 375K+ frames) - **Comprehensive CLI** with configurable output options and batch processing - **Feature flags** (`csv`, `json`, `cli`, `serde`) for flexible dependency management -- **Firmware compatibility** for Betaflight (4.5+), EmuFlight, and INAV +- **Firmware compatibility** for Betaflight (4.5+) and EmuFlight - **Unit conversions** for voltage (raw to volts) and current (raw to amps) - **Energy calculation** with cumulative amperage integration - **Betaflight-accurate flag formatting** for flight mode, state, and failsafe phases @@ -43,7 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Compatibility - **Input formats:** .BBL, .BFL, .TXT (case-insensitive) -- **Firmware versions:** Betaflight 4.5+, EmuFlight, INAV +- **Firmware versions:** Betaflight 4.5+, EmuFlight - **Output formats:** CSV, GPX, JSONL event logs - **Binary compatibility:** Output matches blackbox_decode reference implementation diff --git a/OVERVIEW.md b/OVERVIEW.md index 0bb64b4..a4313f3 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -113,7 +113,7 @@ src/ ### **File Processing** - **Universal Format Support:** `.BBL`, `.BFL`, `.TXT` with case-insensitive matching -- **Firmware Compatibility:** Betaflight, EmuFlight, INAV support +- **Firmware Compatibility:** Betaflight, EmuFlight support - **Multi-log Processing:** Automatic detection of multiple flight sessions in single files ### **Smart Export Filtering** @@ -271,7 +271,7 @@ Exported event data to: BTFL_BLACKBOX_LOG_20250601_121852.event ### **Functional Capabilities** - **Basic BBL parsing** with support for major frame types -- **Multi-firmware support** across Betaflight, EmuFlight, INAV +- **Multi-firmware support** across Betaflight and EmuFlight - **Multi-log processing** for complex flight session files - **Export functionality** for CSV, GPX, and event data formats - **Memory-efficient streaming** architecture for large files From 3668d1884261da1d729a5b495a41eb9c01e3ffef Mon Sep 17 00:00:00 2001 From: nerdCopter <56646290+nerdCopter@users.noreply.github.com> Date: Tue, 30 Dec 2025 12:19:24 -0600 Subject: [PATCH 3/4] fix: Restore INAV firmware support after validation testing INAV compatibility verified via comprehensive testing: - 6 INAV files tested (142,734 frames, 18 flight logs) - RUST parser: 100% success rate - Exceeds external decoders (handles INAV 7.1.0 that fails elsewhere) - All INAV versions supported (4.0.0, 4.1.0, 7.1.0, 8.0.0) Restored references to Cargo.toml, README.md, OVERVIEW.md, CHANGELOG.md --- CHANGELOG.md | 4 ++-- Cargo.toml | 2 +- OVERVIEW.md | 6 +++--- README.md | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ceb186d..db040a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,7 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Streaming architecture** for memory-efficient processing of large files (tested: 375K+ frames) - **Comprehensive CLI** with configurable output options and batch processing - **Feature flags** (`csv`, `json`, `cli`, `serde`) for flexible dependency management -- **Firmware compatibility** for Betaflight (4.5+) and EmuFlight +- **Firmware compatibility** for Betaflight (4.5+), EmuFlight, and INAV - **Unit conversions** for voltage (raw to volts) and current (raw to amps) - **Energy calculation** with cumulative amperage integration - **Betaflight-accurate flag formatting** for flight mode, state, and failsafe phases @@ -43,7 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Compatibility - **Input formats:** .BBL, .BFL, .TXT (case-insensitive) -- **Firmware versions:** Betaflight 4.5+, EmuFlight +- **Firmware versions:** Betaflight 4.5+, EmuFlight, INAV - **Output formats:** CSV, GPX, JSONL event logs - **Binary compatibility:** Output matches blackbox_decode reference implementation diff --git a/Cargo.toml b/Cargo.toml index c1a457f..1e559e5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ version = "1.0.0" edition = "2021" authors = ["nerdCopter"] license = "AGPL-3.0-or-later" -description = "Parser for Betaflight/EmuFlight blackbox log files" +description = "Parser for Betaflight/EmuFlight/INAV blackbox log files" keywords = ["betaflight", "blackbox", "drone", "flight-log", "parser"] categories = ["parsing", "aerospace"] rust-version = "1.70.0" diff --git a/OVERVIEW.md b/OVERVIEW.md index a4313f3..e7797d6 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -26,7 +26,7 @@ A comprehensive Rust library and command-line tool for BBL (Blackbox Log) parsin ### **File Processing Capabilities** - **Formats:** .BBL, .BFL, .TXT (case-insensitive) -- **Firmware:** Betaflight, EmuFlight +- **Firmware:** Betaflight, EmuFlight, INAV - **File Sizes:** Handles large files via streaming architecture (tested up to 240K+ rows) - **Multi-Log Support:** Automatic detection and processing of multiple flights @@ -113,7 +113,7 @@ src/ ### **File Processing** - **Universal Format Support:** `.BBL`, `.BFL`, `.TXT` with case-insensitive matching -- **Firmware Compatibility:** Betaflight, EmuFlight support +- **Firmware Compatibility:** Betaflight, EmuFlight, INAV support - **Multi-log Processing:** Automatic detection of multiple flight sessions in single files ### **Smart Export Filtering** @@ -271,7 +271,7 @@ Exported event data to: BTFL_BLACKBOX_LOG_20250601_121852.event ### **Functional Capabilities** - **Basic BBL parsing** with support for major frame types -- **Multi-firmware support** across Betaflight and EmuFlight +- **Multi-firmware support** across Betaflight, EmuFlight, INAV - **Multi-log processing** for complex flight session files - **Export functionality** for CSV, GPX, and event data formats - **Memory-efficient streaming** architecture for large files diff --git a/README.md b/README.md index 3c405c3..98a6049 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A fast, pure-Rust Blackbox Log parser primarily used as a command-line tool, with an optional Rust crate API. -Supports `.BBL`, `.BFL`, `.TXT` (case-insensitive) across Betaflight and EmuFlight. +Supports `.BBL`, `.BFL`, `.TXT` (case-insensitive) across Betaflight, EmuFlight, and INAV. ## Table of Contents - [Overview](#overview) From 3b3614c97b9e573e7342bead085729b135c63ad5 Mon Sep 17 00:00:00 2001 From: nerdCopter <56646290+nerdCopter@users.noreply.github.com> Date: Tue, 30 Dec 2025 12:56:33 -0600 Subject: [PATCH 4/4] docs: Update Betaflight version support from 4.5+ to 4.0+ Comprehensive compatibility testing validates support for Betaflight 4.0 through 4.5.x (6+ years of releases): - Tested: 4.0.2 (2019), 4.1.1 (2020), 4.3.x (2022), 4.4.x-4.5.x (2023+) - Result: 100% success rate across 60+ flight logs - CSV export verified working on all tested versions - Multi-log handling consistent across versions Removed overly-conservative version limitation. --- CHANGELOG.md | 2 +- GOALS.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index db040a4..3b51cd2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -43,7 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Compatibility - **Input formats:** .BBL, .BFL, .TXT (case-insensitive) -- **Firmware versions:** Betaflight 4.5+, EmuFlight, INAV +- **Firmware versions:** Betaflight 4.0+, EmuFlight, INAV - **Output formats:** CSV, GPX, JSONL event logs - **Binary compatibility:** Output matches blackbox_decode reference implementation diff --git a/GOALS.md b/GOALS.md index 38210cc..9aee404 100644 --- a/GOALS.md +++ b/GOALS.md @@ -38,7 +38,7 @@ - **GPS data merge:** Integrate GPS data into main CSV (currently separate .gps.gpx file) — not started - **Raw mode output:** Export unprocessed sensor values without scaling — not started - **Enhanced statistics:** Loop timing statistics, frame distribution analysis — not started -- **Extended firmware testing:** Currently validates Betaflight 4.5+, EmuFlight, INAV; additional versions not comprehensively tested +- **Extended firmware testing:** Validates Betaflight 4.0+, EmuFlight, INAV across 6+ years of firmware releases - **Advanced filtering options:** Current implementation: duration + gyro variance heuristics; advanced options not implemented ---