Enhance Blackbox Log Compatibility: INAV, QuickSilver, and KISS (2025+)

[nerdCopter]

Summary

Recent firmware updates (mid to late 2025) for INAV, QuickSilver, and KISS have introduced changes to their Blackbox log formats. While all three are based on Betaflight’s format, each has unique fields and minor structural differences that limit full compatibility with bbl_parser.

Note: Some INAV compatibility already exists in bbl_parser, but it is highly incomplete—navigation and advanced fields are not fully supported.

Technical Details

• INAV (7.x+):
  • Adds navigation-specific fields (e.g., , , ).
  • New/modified frame types for navigation and sensor data.
  • Some logs parse, but navigation/advanced fields are ignored or misparsed.
• QuickSilver (2.x+):
  • Streamlined Betaflight format with renamed/omitted fields.
  • New fields for sensors (e.g., , ).
  • Frame structure optimized for log size.
• KISS (v3.0+, 2025):
  • Now uses a minimally altered Betaflight Blackbox format.
  • Includes a header and a few KISS-specific fields.
  • Most Betaflight tools can parse KISS logs, but some fields are ignored or misnamed.

Action Items

1. Research and document log format differences for each firmware (2025+).
2. Gather sample logs from the community for regression testing and development.
3. Update parser to:
   • Detect and parse INAV, QuickSilver, and KISS log headers.
   • Map and support new/renamed fields and frame types.
   • Ensure backward compatibility with Betaflight logs.
4. Add tests with real-world logs from each firmware (2025+).
5. Update documentation to reflect new compatibility and limitations.

Community Call: Please contribute recent Blackbox logs from INAV, QuickSilver, and KISS for processing and testing!

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Migrate GPS/Event frame parsing from CLI to crate library #7
• Enhancement: Add GPS home waypoint to GPX export #20

🔗 Related PRs

#14 - resolve coderabbitAI feedback (#12), and resolve proper GPS/GPX date/time. [merged]

👤 Suggested Assignees

• coderabbitai
• nerdCopter

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Enhance bbl_parser to fully support recent firmware updates (2025+) from INAV 7.x+, QuickSilver 2.x+, and KISS v3.0+. While all three are based on Betaflight's Blackbox format with minor structural differences, INAV has incomplete support (navigation fields ignored), and QuickSilver/KISS are not explicitly detected. The parser needs firmware detection, field mapping support, and testing infrastructure while maintaining backward compatibility with Betaflight.

Observations

Codebase Summary

bbl_parser is a Rust-based Blackbox log parser with a modular architecture consisting of header parsing, frame parsing, field decoding, and export modules. The parser already uses dynamic field access via HashMaps and frame definitions read from log headers, making it naturally extensible to new fields without code changes. Current firmware awareness is limited to storing the firmware_revision string and using it for voltage/GPS conversions. Fields are accessed by name dynamically in exports, and the predictor/encoding system treats all firmware formats uniformly. This architecture means most new firmware fields will be automatically parsed and exported with minimal code changes.

Assumptions

Assumption 1: Frame structure compatibility across firmware types

Options Considered:

• Assume uniform frame structure with dynamic field definitions (fields vary, but structure is same)
• Assume firmware-specific frame types or encoding schemes requiring dedicated parsers

Chosen Option: Assume uniform frame structure with dynamic field definitions (fields vary, but structure is same)

Rationale: This aligns with the search results showing INAV uses standard I/P/S/G/H/E frames and the codebase's existing dynamic field parsing system. KISS FC is documented as using "minimally altered Betaflight Blackbox format," and QuickSilver as "streamlined Betaflight format." The parser's HashMap-based field access already handles arbitrary field names without code changes.

Assumption 2: Firmware identification approach

Options Considered:

• Parse firmware type from "H Firmware revision:" header string pattern matching
• Add separate "H Firmware type:" header parsing
• Use board info or craft name for firmware detection

Chosen Option: Parse firmware type from "H Firmware revision:" header string pattern matching

Rationale: The codebase exploration shows this header already contains firmware identification (e.g., "INAV %s (%s) %s" format from INAV source code). This is the most reliable and already-available method without requiring new header fields.

Assumption 3: Firmware-specific field conversion requirements

Options Considered:

• Add conversion functions for all new firmware-specific fields
• Only add conversions for fields that require unit transformations (following existing voltage/GPS patterns)
• Create firmware-specific export formatting for all fields

Chosen Option: Only add conversions for fields that require unit transformations (following existing voltage/GPS patterns)

Rationale: The existing conversion.rs already handles firmware-specific voltage scaling and GPS altitude. New fields like INAV's navPos, navVel, navTgtPos are stored as raw centimeter/velocity values and don't need conversion unless export formatting requires it. This minimizes code changes and leverages the existing dynamic system.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Firmware Type Detection and Infrastructure

Add explicit firmware type recognition to enable firmware-aware processing while maintaining the existing dynamic field parsing system.

Task 1: Define Firmware Type Enum

Create a firmware type enumeration to replace the current string-only firmware identification.

• Add FirmwareType enum in src/types/header.rs with variants: Betaflight, INAV, QuickSilver, KISS, and Unknown
• Include helper methods: from_revision_string() for pattern matching firmware revision headers, as_str() for display/logging
• Pattern matching logic should detect: "INAV" in revision string → INAV, "Quicksilver"/"QuickSilver" → QuickSilver, "KISS" → KISS, default → Betaflight

Task 2: Integrate Firmware Type into BBLHeader

Store the detected firmware type alongside the existing firmware_revision string.

• Add firmware_type: FirmwareType field to BBLHeader struct in src/types/header.rs
• Update header parsing in src/parser/header.rs to detect firmware type when "H Firmware revision:" is parsed
• Call FirmwareType::from_revision_string() on the firmware_revision value and store result
• Ensure backward compatibility by maintaining existing firmware_revision string field

Task 3: Update Firmware-Aware Conversion Functions

Modify existing conversion functions to accept and use FirmwareType enum instead of string matching.

• Update convert_vbat_to_volts() signature in src/conversion.rs to accept FirmwareType parameter
• Update convert_gps_altitude() signature to accept FirmwareType parameter
• Replace string pattern matching logic with enum matching for cleaner firmware-specific behavior
• Update all call sites in src/parser/gps.rs, src/parser/frame.rs, and src/export.rs to pass firmware_type instead of firmware_revision string

🤖 Prompt for AI agents

Implement firmware type detection infrastructure to enable firmware-aware
processing.

Create FirmwareType enum in src/types/header.rs:
- Add variants: Betaflight, INAV, QuickSilver, KISS, Unknown
- Implement from_revision_string() method with pattern matching ("INAV" → INAV,
"Quicksilver"/"QuickSilver" → QuickSilver, "KISS" → KISS, default → Betaflight)
- Implement as_str() for display

Integrate firmware type into BBLHeader:
- Add firmware_type field to BBLHeader struct
- Update header parsing to detect and store firmware type from "H Firmware
revision:" header
- Maintain backward compatibility with existing firmware_revision string

Refactor conversion functions:
- Update convert_vbat_to_volts() and convert_gps_altitude() signatures to accept
FirmwareType
- Replace string matching with enum matching
- Update all call sites to pass firmware_type

Phase 2: Documentation and Field Mapping Support

Document firmware-specific fields and prepare the codebase for firmware-aware field interpretation without breaking existing functionality.

Task 1: Add Firmware-Specific Field Documentation

Create documentation for known firmware-specific fields to aid users and future development.

• Add docs/FIRMWARE_FIELDS.md documenting known field differences across firmware types
• Document INAV-specific fields: navPos[0-2], navVel[0-2], navTgtPos[0-2], navTgtVel[0-2], navAccNEU[0-2] (navigation state arrays in NED frame), hwHealthStatus (hardware sensor status bitfield)
• Document QuickSilver-specific fields: sensor naming differences, streamlined field set (based on what's discovered in sample logs)
• Document KISS-specific fields: ESC telemetry fields, any KISS-unique identifiers (based on what's discovered in sample logs)
• Note that most fields are automatically parsed and exported due to dynamic field system

Task 2: Enhance CSV Export Field Formatting

Add firmware-aware field formatting hints for clearer exports without breaking existing functionality.

• Update CSV field mapping in src/export.rs to recognize common firmware-specific fields
• Add formatting comments or units for INAV navigation fields (e.g., navPos values are in centimeters)
• Add handling for QuickSilver/KISS fields that need special units or display formatting
• Maintain existing dynamic field export as fallback for unknown fields

Task 3: Add Firmware Type to Export Metadata

Include firmware type information in exported files for traceability.

• Add firmware type to CSV header comments in src/export.rs (e.g., "# Firmware: INAV 7.0.0")
• Update GPX metadata to include firmware type information
• Ensure event export includes firmware type in generated files

🤖 Prompt for AI agents

Add firmware-aware field documentation and export enhancements.

Create docs/FIRMWARE_FIELDS.md:
- Document INAV fields: navPos[0-2], navVel[0-2], navTgtPos[0-2],
navTgtVel[0-2], navAccNEU[0-2], hwHealthStatus
- Document QuickSilver and KISS specific fields
- Note automatic parsing via dynamic field system

Enhance CSV export formatting:
- Update src/export.rs to recognize firmware-specific fields
- Add unit comments for INAV navigation fields (centimeters, etc.)
- Add formatting for QuickSilver/KISS fields
- Maintain dynamic field export fallback

Add firmware metadata to exports:
- Include firmware type in CSV header comments
- Update GPX metadata with firmware type
- Add firmware type to event exports

Phase 3: Testing Infrastructure and Validation

Establish testing infrastructure to validate multi-firmware support with real-world logs.

Task 1: Create Test Directory Structure

Organize test resources for firmware-specific validation.

• Create tests/fixtures/logs/ directory structure with subdirectories: betaflight/, inav/, quicksilver/, kiss/
• Add .gitignore entries to prevent committing large test logs to repository
• Create tests/fixtures/README.md with instructions for obtaining and placing test logs
• Document expected log characteristics for each firmware type

Task 2: Add Firmware Detection Tests

Validate firmware type detection from log headers.

• Add unit tests in src/parser/header.rs testing FirmwareType::from_revision_string()
• Test detection of: "INAV 7.0.0" → FirmwareType::INAV, "Betaflight 4.5.0" → FirmwareType::Betaflight, "Quicksilver 2.1.0" → FirmwareType::QuickSilver, "KISS v3.0" → FirmwareType::KISS
• Test unknown/malformed firmware strings default to appropriate fallback behavior

Task 3: Add Integration Tests for Multi-Firmware Parsing

Create integration tests that validate end-to-end parsing for each firmware type.

• Add integration test module in tests/multi_firmware_tests.rs
• Create test cases that parse sample logs (when available) and validate: firmware type detection, field parsing completeness, export generation without errors
• Use conditional compilation to skip tests when sample logs are not available (avoiding test failures in CI)
• Document how to run tests with sample logs in tests/README.md

Task 4: Add Sample Log Request Documentation

Document the community call for sample logs and contribution process.

• Update README.md with section on firmware compatibility status
• Add CONTRIBUTING.md section on how to contribute sample logs for testing
• Include privacy guidelines (remove GPS coordinates, craft names if desired)
• Specify that logs should be from 2025+ firmware versions for INAV 7.x+, QuickSilver 2.x+, KISS v3.0+

🤖 Prompt for AI agents

Build testing infrastructure for multi-firmware validation.

Set up test directory structure:
- Create tests/fixtures/logs/ with subdirectories for each firmware type
- Add .gitignore for test logs
- Create tests/fixtures/README.md with log acquisition instructions

Add firmware detection unit tests:
- Test FirmwareType::from_revision_string() in src/parser/header.rs
- Cover all firmware types: INAV, Betaflight, QuickSilver, KISS
- Test fallback behavior for unknown strings

Create integration tests:
- Add tests/multi_firmware_tests.rs module
- Validate end-to-end parsing for each firmware type
- Use conditional compilation for optional sample logs
- Document test execution in tests/README.md

Document sample log contributions:
- Update README.md with firmware compatibility status
- Add CONTRIBUTING.md section for log contributions
- Include privacy guidelines and version requirements

Phase 4: Documentation Updates

Update user-facing documentation to reflect enhanced firmware support.

Task 1: Update README with Firmware Compatibility Matrix

Clearly communicate supported firmware types and known limitations.

• Add firmware compatibility section to README.md with table showing: Firmware type, Version tested, Parse support status, Export support status, Known limitations
• Mark INAV, QuickSilver, KISS as supported with notes about field coverage
• Document that navigation fields and firmware-specific fields are parsed but may not have specialized formatting

Task 2: Update OVERVIEW and GOALS Documentation

Reflect the enhanced firmware support in project documentation.

• Update OVERVIEW.md to highlight multi-firmware architecture and dynamic field parsing
• Update GOALS.md to mark firmware compatibility enhancements as complete
• Add notes about extensibility for future firmware types

Task 3: Create Firmware-Specific Troubleshooting Guide

Help users diagnose firmware-specific parsing issues.

• Add docs/TROUBLESHOOTING.md with firmware-specific sections
• Document how to verify firmware detection from parsed logs
• Include common issues: fields appearing as raw values, missing expected fields, conversion errors
• Provide guidance on reporting firmware-specific issues with necessary log details

🤖 Prompt for AI agents

Update user-facing documentation to reflect enhanced firmware support.

Create firmware compatibility matrix in README.md:
- Add table with firmware type, versions tested, support status, and limitations
- Mark INAV, QuickSilver, KISS as supported
- Note field coverage details

Update project documentation:
- Enhance OVERVIEW.md with multi-firmware architecture details
- Mark firmware compatibility complete in GOALS.md
- Document extensibility for future firmware types

Create troubleshooting guide:
- Add docs/TROUBLESHOOTING.md with firmware-specific sections
- Document firmware detection verification
- Cover common issues: raw values, missing fields, conversion errors
- Provide issue reporting guidance

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement firmware type detection infrastructure to enable firmware-aware
processing.

Create FirmwareType enum in src/types/header.rs:
- Add variants: Betaflight, INAV, QuickSilver, KISS, Unknown
- Implement from_revision_string() method with pattern matching ("INAV" → INAV,
"Quicksilver"/"QuickSilver" → QuickSilver, "KISS" → KISS, default → Betaflight)
- Implement as_str() for display

Integrate firmware type into BBLHeader:
- Add firmware_type field to BBLHeader struct
- Update header parsing to detect and store firmware type from "H Firmware
revision:" header
- Maintain backward compatibility with existing firmware_revision string

Refactor conversion functions:
- Update convert_vbat_to_volts() and convert_gps_altitude() signatures to accept
FirmwareType
- Replace string matching with enum matching
- Update all call sites to pass firmware_type
===============================================================================

Task: 2

Add firmware-aware field documentation and export enhancements.

Create docs/FIRMWARE_FIELDS.md:
- Document INAV fields: navPos[0-2], navVel[0-2], navTgtPos[0-2],
navTgtVel[0-2], navAccNEU[0-2], hwHealthStatus
- Document QuickSilver and KISS specific fields
- Note automatic parsing via dynamic field system

Enhance CSV export formatting:
- Update src/export.rs to recognize firmware-specific fields
- Add unit comments for INAV navigation fields (centimeters, etc.)
- Add formatting for QuickSilver/KISS fields
- Maintain dynamic field export fallback

Add firmware metadata to exports:
- Include firmware type in CSV header comments
- Update GPX metadata with firmware type
- Add firmware type to event exports
===============================================================================

Task: 3

Build testing infrastructure for multi-firmware validation.

Set up test directory structure:
- Create tests/fixtures/logs/ with subdirectories for each firmware type
- Add .gitignore for test logs
- Create tests/fixtures/README.md with log acquisition instructions

Add firmware detection unit tests:
- Test FirmwareType::from_revision_string() in src/parser/header.rs
- Cover all firmware types: INAV, Betaflight, QuickSilver, KISS
- Test fallback behavior for unknown strings

Create integration tests:
- Add tests/multi_firmware_tests.rs module
- Validate end-to-end parsing for each firmware type
- Use conditional compilation for optional sample logs
- Document test execution in tests/README.md

Document sample log contributions:
- Update README.md with firmware compatibility status
- Add CONTRIBUTING.md section for log contributions
- Include privacy guidelines and version requirements
===============================================================================

Task: 4

Update user-facing documentation to reflect enhanced firmware support.

Create firmware compatibility matrix in README.md:
- Add table with firmware type, versions tested, support status, and limitations
- Mark INAV, QuickSilver, KISS as supported
- Note field coverage details

Update project documentation:
- Enhance OVERVIEW.md with multi-firmware architecture details
- Mark firmware compatibility complete in GOALS.md
- Document extensibility for future firmware types

Create troubleshooting guide:
- Add docs/TROUBLESHOOTING.md with firmware-specific sections
- Document firmware detection verification
- Cover common issues: raw values, missing fields, conversion errors
- Provide issue reporting guidance

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!