{"id":29600666,"url":"https://github.com/nerdcopter/bbl_parser","last_synced_at":"2025-07-20T12:07:45.122Z","repository":{"id":300632888,"uuid":"1006680557","full_name":"nerdCopter/bbl_parser","owner":"nerdCopter","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-11T19:33:44.000Z","size":344,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-11T21:22:56.537Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nerdCopter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T19:29:39.000Z","updated_at":"2025-07-11T19:33:47.000Z","dependencies_parsed_at":"2025-07-11T21:13:40.223Z","dependency_job_id":"f8ab3b76-17a2-4ccb-a754-7138ac341903","html_url":"https://github.com/nerdCopter/bbl_parser","commit_stats":null,"previous_names":["nerdcopter/bbl_parser"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nerdCopter/bbl_parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdCopter%2Fbbl_parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdCopter%2Fbbl_parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdCopter%2Fbbl_parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdCopter%2Fbbl_parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nerdCopter","download_url":"https://codeload.github.com/nerdCopter/bbl_parser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdCopter%2Fbbl_parser/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266120920,"owners_count":23879413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-20T12:07:39.982Z","updated_at":"2025-07-20T12:07:45.117Z","avatar_url":"https://github.com/nerdCopter.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BBL Parser v0.9.0 (Work-in-Progress)\n\nA high-performance Rust implementation of BBL (Blackbox Log) parser for flight controller blackbox data analysis.\n\n**Version:** 0.9.0 🚧 **Work-in-Progress**  \n**Status:** Under active development  \n**Supported Formats:** `.BBL`, `.BFL`, `.TXT` (case-insensitive) - Compatible with Betaflight, EmuFlight, and INAV\n\n## Current Features\n\n- **Pure Rust Implementation**: Direct parsing logic without external dependencies\n- **Universal File Support**: All common BBL formats with case-insensitive extension matching  \n- **Complete Frame Support**: I, P, H, S, E, G frames with all encoding formats (SIGNED_VB, UNSIGNED_VB, NEG_14BIT, TAG8_8SVB, TAG2_3S32, TAG8_4S16)\n- **Multi-Log Processing**: Automatic detection and processing of multiple flight logs within single files\n- **Streaming Architecture**: Memory-efficient processing for large files (500K+ frames)\n- **Advanced Frame Prediction**: Full predictor implementation for accurate P-frame decoding\n- **CSV Export**: Flight data and header export with blackbox_decode compatibility\n- **GPS Export**: GPX file generation for GPS-enabled flight logs\n- **Event Export**: Flight event data extraction in JSONL format\n- **Command Line Interface**: Glob patterns, debug mode, configurable output directories\n\n## Export Formats\n\n### CSV Export (`--csv`)\n\nExports blackbox logs to CSV format with blackbox_decode compatibility:\n\n- **`.XX.csv`**: Main flight data file containing I, P, S, G frame data\n  - Field names header row in blackbox_decode compatible order\n  - Time field labeled as \"time (us)\" for microsecond precision\n  - All flight loop data (I frames) and status data (S frames) \n  - GPS data (G frames) when available\n  - Time-sorted chronological data rows\n- **`.XX.headers.csv`**: Complete header information file\n  - Field,Value format with all configuration parameters\n  - Frame definitions, system settings, firmware information\n  - All BBL header metadata for analysis tools\n\n### GPS Export (`--gpx`)\n\nExports GPS data to GPX format for mapping applications:\n\n- **`.gps.gpx`**: GPS track file in standard GPX format\n  - Geographic coordinates from GPS frames\n  - Altitude information with proper firmware scaling\n  - Timestamp data for track visualization\n  - Compatible with Google Earth, GPS visualization tools\n\n### Event Export (`--event`)\n\nExports flight events to JSONL format:\n\n- **`.event`**: Flight event data in JSON Lines format\n  - Individual JSON objects per line for streaming compatibility\n  - Event types based on official Betaflight FlightLogEvent enum\n  - Includes sync beeps, disarm events, flight mode changes, log boundaries\n  - Compatible with log analysis tools expecting JSONL format\n\nWhere `XX` represents the flight log number (01, 02, 03, etc.) for multiple logs within a single BBL file.\n\n**Example files generated:**\n```\nBTFL_LOG_20250601_121852.01.csv         # Flight data for log 1\nBTFL_LOG_20250601_121852.01.headers.csv # Headers for log 1\nBTFL_LOG_20250601_121852.gps.gpx        # GPS track data\nBTFL_LOG_20250601_121852.event          # Flight events\nBTFL_LOG_20250601_121852.02.csv         # Flight data for log 2  \nBTFL_LOG_20250601_121852.02.headers.csv # Headers for log 2\n```\n\n## Installation \u0026 Usage\n\n```bash\ngit clone \u003crepository-url\u003e\ncd bbl_parser\ncargo build --release\n```\n\n### Basic Usage\n```bash\n# Analysis and console statistics only\n./target/release/bbl_parser file.BBL\n\n# CSV export \n./target/release/bbl_parser --csv logs/*.BBL\n\n# GPS export to GPX format (console stats + GPX file)\n./target/release/bbl_parser --gpx logs/*.BBL\n\n# Event data export (console stats + event file)\n./target/release/bbl_parser --event logs/*.BBL\n\n# All export formats\n./target/release/bbl_parser --csv --gpx --event logs/*.BBL\n\n# Multiple files and formats\n./target/release/bbl_parser file1.BBL file2.BFL file3.TXT\n\n# Glob patterns\n./target/release/bbl_parser logs/*.{BBL,BFL,TXT}\n\n# Debug mode\n./target/release/bbl_parser --debug logs/*.BBL\n\n# Custom output directory\n./target/release/bbl_parser --csv --output-dir ./output logs/*.BBL\n```\n\n## Output\n\n### Console Statistics (Always Displayed)\n\n```\nProcessing: flight_log.BBL\n\nLog 1 of 1, frames: 84235\nFirmware: Betaflight 4.5.2 (024f8e13d) STM32F7X2\nBoard: AXFL AXISFLYINGF7PRO  \nCraft: Volador 5\n\nStatistics\nLooptime         125 avg\nI frames     1316\nP frames    82845\nH frames        1\nG frames      833\nE frames        4\nS frames        6\nFrames      84235\nData ver        2\n```\n\n### Export Output (When Enabled)\n\nAdditional output when export flags are used:\n```\nExported GPS data to: flight_log.gps.gpx      # When --gpx used\nExported event data to: flight_log.event      # When --event used\n```\n\n### Debug Output\n\nDebug mode adds frame data tables for detailed analysis:\n\n```\n=== FRAME DATA ===\n\nI-frame data (25 frames):\n     Index     Time(μs)     Loop accSmooth[ accSmooth[ gyroADC[0]  motor[0]  motor[1] ... (40 more fields)\n         0            0        4          0          0         -5      1270      1270 ...\n         1     36147802    71168       -163        130       2289      1260      1277 ...\n       ...          ...      ... ... (18 frames skipped)\n        23     36853826    73984       -332        -12       3512      1215      1210 ...\n        24     36885919    74112       -430         26       3552      1205      1210 ...\n\nP-frame data (50 frames):\n     Index     Time(μs)     Loop accSmooth[ accSmooth[ gyroADC[0]  motor[0]  motor[1] ... (40 more fields)\n         0 18446744073709551615        5        -11          9         27       632       637 ...\n         1 18446744073709551615        6        -11          9         26       948       958 ...\n       ...          ...      ... ... (18 frames skipped)\n        49    939855786    71193        -75         94       1504       854       841 ...\n```\n\n**Debug mode** provides detailed analysis including:\n- File size and binary data inspection\n- Field definitions and encoding details  \n- **Frame data tables** organized by type (I, P, S, G, E, H frames)\n- Smart sampling: shows all frames ≤30, or first 5 + middle 5 + last 5 when \u003e30 frames\n\n## Frame Support \u0026 Compatibility\n\n**Frame Types:** I, P, H, S, E, G frames  \n**Encoding:** All major BBL formats (SIGNED_VB, UNSIGNED_VB, NEG_14BIT, TAG8_8SVB, TAG2_3S32, TAG8_4S16)  \n**Predictors:** Reference-compliant implementation for P-frame decoding\n\n### Event Frame Support\n\nEvent parsing uses the official Betaflight FlightLogEvent enum:\n- **Type 0**: Sync beep (initialization)\n- **Type 15**: Disarm event \n- **Type 30**: Flight mode change\n- **Type 255**: Log end marker\n- **Additional types**: Autotune, inflight adjustment, logging resume events\n\n## Performance \u0026 Limitations\n\n**⚠️ Development Status**: This is work-in-progress software with the following limitations:\n- Limited testing with GPS and Event frame processing\n- May have compatibility issues with some specialized log formats\n- Performance optimizations still in development\n- API may change between versions\n\n**Current Capabilities:**\n- Extensively tested with Betaflight and EmuFlight log files\n- Memory-efficient streaming architecture for large files\n- Processes files that may cause external decoders to fail\n- Zero external dependencies - no blackbox_decode tools required\n\n## Dependencies\n\n- `clap` (v4.0+) - CLI parsing\n- `glob` (v0.3) - File patterns  \n- `anyhow` (v1.0) - Error handling\n\n## Betaflight Firmware Compatibility\n\n**Flight Mode Flags, State Flags, and Failsafe Phases:** This parser outputs data that matches current Betaflight firmware specifications exactly.\n\n- **Flight Mode Flags**: Current `flightModeFlags_e` enum from Betaflight runtime_config.h\n  - Supports: ANGLE_MODE, HORIZON_MODE, MAG, BARO, GPS_HOLD, HEADFREE, PASSTHRU, FAILSAFE_MODE, GPS_RESCUE_MODE\n  - Output format: `\"ANGLE_MODE|HORIZON_MODE\"` (pipe-separated for CSV compatibility)\n  - Includes GPS_RESCUE_MODE flag (bit 11) from current firmware\n\n- **State Flags**: Current `stateFlags_t` enum from Betaflight runtime_config.h  \n  - Supports: GPS_FIX_HOME, GPS_FIX, CALIBRATE_MAG, SMALL_ANGLE, FIXED_WING\n  - Output format: `\"GPS_FIX_HOME|GPS_FIX\"` (pipe-separated for CSV compatibility)\n\n- **Failsafe Phase**: Current `failsafePhase_e` enum from Betaflight failsafe.h\n  - Supports: IDLE, RX_LOSS_DETECTED, LANDING, LANDED, RX_LOSS_MONITORING, RX_LOSS_RECOVERED, GPS_RESCUE\n  - Includes phases 4-6 from current firmware\n\n**Reference Compatibility:** Verified against blackbox-tools and current Betaflight master branch.\n\n## Overview\n\n- [GOALS.md](./GOALS.md)\n- [FRAMES.md](./FRAMES.md)\n- [OVERVIEW.md](./OVERVIEW.md)\n\n## Contributing\n\n**⚠️ Development Project**: This is work-in-progress software. Contributions welcome with understanding that:\n- APIs may change between versions\n- Not all edge cases have been tested\n- Performance optimizations are ongoing\n\n**Priority Areas:** Testing across firmware versions, file format compatibility, performance optimization\n\n## License\n\nThis project is provided as-is for educational and development use with flight controller blackbox logs.  \n\n## Acknowledgments\n\nBased on [Betaflight Blackbox Log Viewer](https://github.com/betaflight/blackbox-log-viewer) and [blackbox-tools](https://github.com/betaflight/blackbox-tools)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerdcopter%2Fbbl_parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnerdcopter%2Fbbl_parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerdcopter%2Fbbl_parser/lists"}