Migrate GPS/Event frame parsing from CLI to crate library

[coderabbitai]

Background

PR #6 implemented the export infrastructure (CSV, GPX, Event) for the BBL parser crate. However, GPS and Event frame parsing logic currently exists only in the CLI binary and needs to be migrated to the crate library for full functionality.

Current State

In the crate (src/parser/frame.rs):

• GPS/Event vectors are initialized as empty
• G/H/E frames are skipped rather than parsed (lines 223-232)
• Export functions exist but receive empty data

In the CLI (src/main.rs):

• Full G-frame parsing with GPS coordinate construction (line 2147+)
• Dedicated parse_e_frame() function for Event frames (line 2491+)
• Complete Event frame construction with event descriptions (line 2649+)

Impact

Crate users calling parse_bbl_file() receive empty vectors for GPS/Event data, even when logs contain G/H/E frames:

• ✅ CSV export works (uses I/P/S frames)
• ❌ GPX export produces no data (empty gps_coordinates)
• ❌ Event export produces no data (empty event_frames)

Only the CLI binary currently provides full export functionality.

Required Work

1. Migrate GPS parsing from src/main.rs to src/parser/frame.rs:

   • Implement G-frame parsing in the 'G' match arm
   • Implement H-frame parsing in the 'H' match arm
   • Populate gps_coordinates and home_coordinates vectors

2. Migrate Event parsing from src/main.rs to src/parser/frame.rs:

   • Move parse_e_frame() logic or equivalent
   • Implement E-frame parsing in the 'E' match arm
   • Populate event_frames vector with proper event descriptions

3. Testing:

   • Verify GPX export produces correct output from crate
   • Verify Event export produces correct output from crate
   • Ensure CLI maintains compatibility

References

• Implemented in: PR fix: improve export_to_event parameter handling for multi-log files #6
• Requested by: @nerdCopter

[nerdCopter]

@coderabbitai, my AI agent is not resolving this issue ticket properly.

Propose a full AI instructional "how to" to feed into my AI agent. I believe it should contain iterative steps. maybe some flowchart or UML or whatever you recommend.

it is paramount, that all existing logic, import, reading, export, and processing is not broken and not re-invented nor re-implemented from scratch. again, the existing parsing/processing logic is 100% accurate and must not be changed.

the idea is that we want to add CRATE usability to this project without duplicating code. i suspect it should just be migrated to helpers, or otherwise reorganized for both CLI and CRATE usage.

[coderabbitai]

Implementation Plan

Approach

Migrate GPS (G/H frame) and Event (E frame) parsing logic from the CLI binary (src/main.rs) to the crate library (src/parser/) by extracting the existing, working implementation into reusable helper modules. This enables crate users to access GPS and Event data while eliminating code duplication between CLI and library.

Observations

The project is a Betaflight blackbox log parser with a library crate and CLI binary. The crate provides parsing through src/parser/frame.rs which currently skips G/H/E frames, while src/main.rs contains complete working implementations for these frame types. Types are centralized in src/types/, conversion utilities exist in src/conversion.rs, and export functions are in src/export.rs. Both G/H frames use the existing parse_frame_data() infrastructure with frame definitions, while E frames require custom binary reading logic.

Assumptions

Assumption 1: Code Organization Strategy

Options Considered:

• Move logic directly into src/parser/frame.rs (creates monolithic file, no reusability)
• Extract into separate helper modules in src/parser/ (clean separation, enables reuse by both CLI and library)
• Keep logic in main.rs and call from parser (creates backward dependency, poor architecture)

Chosen Option: Extract into separate helper modules in src/parser/ (clean separation, enables reuse by both CLI and library)

Rationale: This follows the existing modular pattern in the codebase, enables both CLI and library to share identical logic without duplication, and maintains clear separation of concerns. The CLI will be refactored to use these helpers, ensuring single source of truth.

Assumption 2: GPS Frame History Management

Options Considered:

• Maintain history in parser/frame.rs and pass to helper (stateful parser, history managed centrally)
• Maintain history in helper module (stateless parser, history managed in helper)
• Create separate history manager module (over-engineering for simple Vec)

Chosen Option: Maintain history in parser/frame.rs and pass to helper (stateful parser, history managed centrally)

Rationale: This aligns with how I/P/S frame history is already managed (using pred_history vectors in the same module), keeps the parser as the orchestrator of all state, and makes the helpers pure functions with no side effects.

💡 User Tips

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

Plan

Phase 1: Extract GPS Parsing Logic to Helper Module

Create a dedicated GPS parsing module that encapsulates all G-frame and H-frame processing logic, making it reusable by both the library parser and CLI binary.

Task 1: Create GPS Helper Module with Frame Parsing Functions

Establish src/parser/gps.rs containing two public functions that replicate the exact GPS parsing logic currently in main.rs.

• Create pub fn parse_g_frame() that accepts stream, header, frame definitions, GPS frame history reference, and timestamp, returning Result<Option<GpsCoordinate>> - logic should match main.rs lines 2068-2171 exactly
• Create pub fn parse_h_frame() that accepts stream, header, frame definitions, and timestamp, returning Result<Option<GpsHomeCoordinate>> - logic should match main.rs lines 2034-2067 exactly
• Both functions should use the existing bbl_format::parse_frame_data() infrastructure with appropriate frame definitions (g_frame_def, h_frame_def)
• Import necessary dependencies: types (GpsCoordinate, GpsHomeCoordinate), conversion functions from conversion.rs, anyhow for error handling
• Handle the differential encoding pattern for G-frames by accepting and updating the GPS frame history vector
• Extract field values from the parsed frame_data HashMap exactly as main.rs does (GPS_coord[0], GPS_coord[1], GPS_altitude, etc.)

Task 2: Update Parser Module to Export GPS Helper

Configure the parser module structure to make GPS helpers available.

• Add mod gps; declaration in src/parser/mod.rs
• Re-export GPS functions with pub use gps::*; to maintain clean module API
• Ensure the module has access to all required types through existing use crate::types::*; import

🤖 Prompt for AI agents

This phase extracts GPS parsing logic (G-frame and H-frame) from main.rs into a
new reusable helper module.

Create src/parser/gps.rs with two public functions:
- parse_g_frame() accepting stream, header, frame definitions, GPS frame history
reference, and timestamp, returning Result<Option<GpsCoordinate>>
- parse_h_frame() accepting stream, header, frame definitions, and timestamp,
returning Result<Option<GpsHomeCoordinate>>

Both functions replicate exact logic from main.rs (lines 2068-2171 for G-frame,
lines 2034-2067 for H-frame)
Use existing parse_frame_data() infrastructure with appropriate frame
definitions
Import required types (GpsCoordinate, GpsHomeCoordinate), conversion functions,
and anyhow
Handle differential encoding for G-frames using provided history vector
Extract fields from parsed frame_data HashMap matching main.rs pattern

Update src/parser/mod.rs:
- Add mod gps; declaration
- Re-export with pub use gps::*;

Phase 2: Extract Event Parsing Logic to Helper Module

Create a dedicated Event parsing module that encapsulates all E-frame processing logic, preserving the existing event type handling patterns.

Task 1: Create Event Helper Module with Frame Parsing Function

Establish src/parser/event.rs containing the event parsing function that replicates the exact logic from main.rs.

• Create pub fn parse_e_frame() that accepts stream and debug flag, returning Result<EventFrame> - function signature and implementation should match main.rs lines 2491-2655 exactly
• Preserve all 16 documented event types (0, 1, 2, 3, 4, 5, 6, 10, 11, 12, 13, 14, 15, 30, 255) and default case with identical data reading patterns
• Maintain variable-length data handling: simple events (type 0) read no additional bytes, complex events (type 2) read 1 byte + 3 signed VB values, conditional events (type 4/13) read based on function value
• Generate identical event descriptions (event_name field) as main.rs implementation
• Import necessary dependencies: types (EventFrame), bit_cursor for variable-byte encoding, anyhow for error handling
• Note: EventFrame will be constructed with timestamp_us: 0 initially - timestamp assignment happens in caller context

Task 2: Update Parser Module to Export Event Helper

Configure the parser module structure to make Event helpers available.

• Add mod event; declaration in src/parser/mod.rs
• Re-export Event functions with pub use event::*; to maintain clean module API

🤖 Prompt for AI agents

This phase extracts Event parsing logic (E-frame) from main.rs into a new
reusable helper module.

Create src/parser/event.rs with public function:
- parse_e_frame() accepting stream and debug flag, returning Result<EventFrame>

Replicate exact logic from main.rs lines 2491-2655
Preserve all 16 event types (0, 1, 2, 3, 4, 5, 6, 10, 11, 12, 13, 14, 15, 30,
255) and default case
Maintain variable-length data handling for each event type
Generate identical event descriptions matching main.rs implementation
Import required types (EventFrame), bit_cursor, and anyhow
Construct EventFrame with timestamp_us: 0 (caller will assign timestamp)

Update src/parser/mod.rs:
- Add mod event; declaration
- Re-export with pub use event::*;

Phase 3: Integrate GPS/Event Helpers into Library Parser

Replace the G/H/E frame skipping logic in the library's frame parser with calls to the new helper functions, enabling crate users to access GPS and Event data.

Task 1: Implement G-frame Parsing in Frame Parser

Update the 'G' match arm in src/parser/frame.rs to parse GPS coordinates instead of skipping.

• Replace skip_frame() call in 'G' match arm (around line 223) with call to parse_g_frame()
• Pass required arguments: stream, header, g_frame_def, reference to gps_frame_history vector, timestamp
• Initialize gps_frame_history: Vec<i32> variable near other frame history vectors (around line 1758 in main.rs pattern)
• On successful parse, push returned GpsCoordinate to gps_coordinates vector
• Update g_frame_count counter after processing
• Handle Option return type appropriately (only push if Some)

Task 2: Implement H-frame Parsing in Frame Parser

Update the 'H' match arm in src/parser/frame.rs to parse home coordinates instead of skipping.

• Replace skip_frame() call in 'H' match arm with call to parse_h_frame()
• Pass required arguments: stream, header, h_frame_def, timestamp
• On successful parse, push returned GpsHomeCoordinate to home_coordinates vector
• Update h_frame_count counter after processing
• Handle Option return type appropriately (only push if Some)

Task 3: Implement E-frame Parsing in Frame Parser

Update the 'E' match arm in src/parser/frame.rs to parse event frames instead of skipping.

• Replace skip_frame() call in 'E' match arm with call to parse_e_frame()
• Pass required arguments: stream, debug flag
• On successful parse, set event_frame.timestamp_us = last_main_frame_timestamp to inherit timestamp from most recent I/P frame (following main.rs pattern)
• Push completed EventFrame to event_frames vector
• Update e_frame_count counter after processing

🤖 Prompt for AI agents

This phase integrates the new GPS and Event helper functions into the library
parser, replacing skip_frame() calls.

In src/parser/frame.rs:

For G-frame (around line 223):
- Replace skip_frame() with parse_g_frame() call
- Pass stream, header, g_frame_def, reference to gps_frame_history, and
timestamp
- Initialize gps_frame_history: Vec<i32> near other frame history vectors
- Push returned GpsCoordinate to gps_coordinates vector if Some
- Update g_frame_count counter

For H-frame:
- Replace skip_frame() with parse_h_frame() call
- Pass stream, header, h_frame_def, and timestamp
- Push returned GpsHomeCoordinate to home_coordinates vector if Some
- Update h_frame_count counter

For E-frame:
- Replace skip_frame() with parse_e_frame() call
- Pass stream and debug flag
- Set event_frame.timestamp_us = last_main_frame_timestamp after parsing
- Push EventFrame to event_frames vector
- Update e_frame_count counter

Phase 4: Refactor CLI Binary to Use Shared Helpers

Update the CLI binary to eliminate duplicated parsing logic by consuming the newly created helper functions from the parser module.

Task 1: Remove GPS Parsing Duplication from CLI

Replace inline G/H frame parsing in main.rs with calls to parser helpers.

• In main.rs around lines 2034-2171, replace G-frame parsing block with import and call to parse_g_frame() from parser module
• Replace H-frame parsing block with import and call to parse_h_frame() from parser module
• Remove the local GPS frame history initialization and management (now handled by helper)
• Ensure identical behavior by passing same arguments the helper expects
• Verify the resulting gps_coordinates and home_coordinates vectors are populated identically

Task 2: Remove Event Parsing Duplication from CLI

Replace the parse_e_frame() function definition in main.rs with an import from the parser module.

• Remove the parse_e_frame() function definition from main.rs (lines 2491-2655)
• Import parse_e_frame from the parser module at top of main.rs
• Verify E-frame processing around line 2649+ continues to work identically with helper function
• Ensure event description generation and timestamp assignment behavior remains unchanged

🤖 Prompt for AI agents

This phase refactors the CLI binary to use the shared helper functions,
eliminating code duplication.

In src/main.rs:

For GPS parsing (lines 2034-2171):
- Import parse_g_frame and parse_h_frame from parser module
- Replace G-frame parsing block with call to parse_g_frame()
- Replace H-frame parsing block with call to parse_h_frame()
- Remove local GPS frame history initialization and management
- Pass same arguments helpers expect
- Verify gps_coordinates and home_coordinates vectors populated identically

For Event parsing (lines 2491-2655):
- Remove parse_e_frame() function definition
- Import parse_e_frame from parser module at top of file
- Verify E-frame processing continues to work with helper function
- Ensure event description generation and timestamp assignment unchanged

Phase 5: Verification and Validation

Ensure the migration maintains complete compatibility for both crate users and CLI binary users.

Task 1: Test Crate Export Functionality

Verify that GPS and Event exports work correctly when called through the crate API.

• Run gpx_export.rs example from examples/ directory - should now produce GPX output with GPS coordinates
• Run event_export.rs example from examples/ directory - should now produce Event output with event descriptions
• Verify exported GPX files contain latitude, longitude, altitude, timestamp, and optional fields (satellites, speed, course)
• Verify exported Event files contain event names, timestamps, and appropriate data values
• Confirm parse_bbl_file() now returns populated gps_coordinates, home_coordinates, and event_frames vectors

Task 2: Test CLI Binary Compatibility

Verify that the CLI binary maintains identical behavior after refactoring.

• Run CLI binary with BBL files containing G/H/E frames
• Compare GPX export output before and after migration - should be byte-for-byte identical
• Compare Event export output before and after migration - should be byte-for-byte identical
• Verify CSV export still works (uses I/P/S frames, should be unaffected)
• Confirm frame counts and statistics remain accurate

🤖 Prompt for AI agents

This phase validates that the migration maintains complete compatibility for
both crate and CLI users.

Test crate functionality:
- Run gpx_export.rs example and verify GPX output with GPS coordinates
- Run event_export.rs example and verify Event output with event descriptions
- Verify GPX files contain all expected fields (latitude, longitude, altitude,
timestamp, satellites, speed, course)
- Verify Event files contain event names, timestamps, and data values
- Confirm parse_bbl_file() returns populated gps_coordinates, home_coordinates,
and event_frames vectors

Test CLI compatibility:
- Run CLI binary with BBL files containing G/H/E frames
- Compare GPX export output before/after - should be byte-for-byte identical
- Compare Event export output before/after - should be byte-for-byte identical
- Verify CSV export still works (unaffected by changes)
- Confirm frame counts and statistics remain accurate

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase extracts GPS parsing logic (G-frame and H-frame) from main.rs into a
new reusable helper module.

Create src/parser/gps.rs with two public functions:
- parse_g_frame() accepting stream, header, frame definitions, GPS frame history
reference, and timestamp, returning Result<Option<GpsCoordinate>>
- parse_h_frame() accepting stream, header, frame definitions, and timestamp,
returning Result<Option<GpsHomeCoordinate>>

Both functions replicate exact logic from main.rs (lines 2068-2171 for G-frame,
lines 2034-2067 for H-frame)
Use existing parse_frame_data() infrastructure with appropriate frame
definitions
Import required types (GpsCoordinate, GpsHomeCoordinate), conversion functions,
and anyhow
Handle differential encoding for G-frames using provided history vector
Extract fields from parsed frame_data HashMap matching main.rs pattern

Update src/parser/mod.rs:
- Add mod gps; declaration
- Re-export with pub use gps::*;
===============================================================================

Task: 2

This phase extracts Event parsing logic (E-frame) from main.rs into a new
reusable helper module.

Create src/parser/event.rs with public function:
- parse_e_frame() accepting stream and debug flag, returning Result<EventFrame>

Replicate exact logic from main.rs lines 2491-2655
Preserve all 16 event types (0, 1, 2, 3, 4, 5, 6, 10, 11, 12, 13, 14, 15, 30,
255) and default case
Maintain variable-length data handling for each event type
Generate identical event descriptions matching main.rs implementation
Import required types (EventFrame), bit_cursor, and anyhow
Construct EventFrame with timestamp_us: 0 (caller will assign timestamp)

Update src/parser/mod.rs:
- Add mod event; declaration
- Re-export with pub use event::*;
===============================================================================

Task: 3

This phase integrates the new GPS and Event helper functions into the library
parser, replacing skip_frame() calls.

In src/parser/frame.rs:

For G-frame (around line 223):
- Replace skip_frame() with parse_g_frame() call
- Pass stream, header, g_frame_def, reference to gps_frame_history, and
timestamp
- Initialize gps_frame_history: Vec<i32> near other frame history vectors
- Push returned GpsCoordinate to gps_coordinates vector if Some
- Update g_frame_count counter

For H-frame:
- Replace skip_frame() with parse_h_frame() call
- Pass stream, header, h_frame_def, and timestamp
- Push returned GpsHomeCoordinate to home_coordinates vector if Some
- Update h_frame_count counter

For E-frame:
- Replace skip_frame() with parse_e_frame() call
- Pass stream and debug flag
- Set event_frame.timestamp_us = last_main_frame_timestamp after parsing
- Push EventFrame to event_frames vector
- Update e_frame_count counter
===============================================================================

Task: 4

This phase refactors the CLI binary to use the shared helper functions,
eliminating code duplication.

In src/main.rs:

For GPS parsing (lines 2034-2171):
- Import parse_g_frame and parse_h_frame from parser module
- Replace G-frame parsing block with call to parse_g_frame()
- Replace H-frame parsing block with call to parse_h_frame()
- Remove local GPS frame history initialization and management
- Pass same arguments helpers expect
- Verify gps_coordinates and home_coordinates vectors populated identically

For Event parsing (lines 2491-2655):
- Remove parse_e_frame() function definition
- Import parse_e_frame from parser module at top of file
- Verify E-frame processing continues to work with helper function
- Ensure event description generation and timestamp assignment unchanged
===============================================================================

Task: 5

This phase validates that the migration maintains complete compatibility for
both crate and CLI users.

Test crate functionality:
- Run gpx_export.rs example and verify GPX output with GPS coordinates
- Run event_export.rs example and verify Event output with event descriptions
- Verify GPX files contain all expected fields (latitude, longitude, altitude,
timestamp, satellites, speed, course)
- Verify Event files contain event names, timestamps, and data values
- Confirm parse_bbl_file() returns populated gps_coordinates, home_coordinates,
and event_frames vectors

Test CLI compatibility:
- Run CLI binary with BBL files containing G/H/E frames
- Compare GPX export output before/after - should be byte-for-byte identical
- Compare Event export output before/after - should be byte-for-byte identical
- Verify CSV export still works (unaffected by changes)
- Confirm frame counts and statistics remain accurate

💡 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.

[nerdCopter]

resolved by #8