feat: migrate GPS/Event frame parsing from CLI to crate library (Issue #7) (#8)

* feat: migrate GPS/Event frame parsing from CLI to crate library (Issue #7)

- Create GPS helper module (src/parser/gps.rs) with H-frame and G-frame parsing
  - parse_h_frame(): Parse GPS home position data
  - parse_g_frame(): Parse GPS position data with differential encoding
  - extract_home_coordinate() and extract_gps_coordinate() helpers

- Create Event helper module (src/parser/event.rs) with E-frame parsing
  - parse_e_frame(): Full event type handling and description generation
  - Supports all event types: Sync beep, Autotune, Adjustment, Resume, Disarm, etc.

- Integrate GPS/Event parsing into library frame parser (src/parser/frame.rs)
  - Replace G/H/E frame skipping with actual parsing using helpers
  - Populate gps_coordinates, home_coordinates, and event_frames vectors
  - Track last_main_frame_timestamp for proper GPS/Event timestamping

- Update types to support both CLI and crate usage
  - Updated EventFrame struct with event_data field
  - Renamed event_description to event_name for consistency

- CLI remains fully functional with no behavior changes
  - All existing parsing logic preserved
  - Export functions work identically for both CLI and crate

Tests:
- cargo clippy: ✓ No warnings
- cargo fmt: ✓ Properly formatted
- cargo test: ✓ All tests pass
- cargo build --release: ✓ No errors

Resolves: Issue #7

* fix: prevent potential panic in parse_g_frame with incorrect history length

Address CodeRabbit review feedback:
- Changed is_empty() check to len() != frame_def.count comparison
- Use resize() instead of vec assignment to handle pre-populated history
- Prevents panic in copy_from_slice when caller passes history with wrong length
- Added clarifying comment explaining the safety guarantee

* refactor: address CodeRabbit nitpick feedback

Address all 6 nitpick comments from CodeRabbit review:

1. examples/test_crate_gps.rs:
   - Add CLI argument handling instead of hardcoded input path
   - Follow pattern from gpx_export.rs for better usability

2. src/parser/event.rs:
   - Extract parse_inflight_adjustment() helper function
   - Reduce code duplication between event types 4 and 13

3. src/parser/gps.rs:
   - Add debug logging for read errors in fallback encoding handler
   - Use debug parameter with logging for G-frame parsing
   - Simplify duplicate home coordinate lookup using map/unwrap_or

* fix: propagate errors for unsupported H-frame encodings instead of silently swallowing

Replace fallback encoding handler in parse_h_frame to return a descriptive error
instead of silently continuing with default values.

Changes:
- Detect unsupported encoding and return Err with descriptive message
- Include field name and encoding value in error message
- Prevents stream desynchronization from being masked by default values
- Allows caller to handle the error appropriately

This ensures that encountering an unsupported H-frame encoding properly
propagates an error through the Result type, rather than continuing to read
from the stream with potentially corrupted data.

* docs: improve comments and debug logging for event/GPS parsing

Address CodeRabbit nitpick feedback:

1. src/parser/event.rs (types 5 and 14):
   - Add clarifying comment explaining why both event types have identical
     implementations and appear in different firmware versions

2. src/parser/gps.rs (missing home coordinates):
   - Add debug logging when home_coordinates are empty
   - Logs when defaulting to (0.0, 0.0) as home position
   - Helps users understand GPS coordinate behavior

* fix: align read_neg_14bit implementation with established pattern

The read_neg_14bit() method was reading two raw bytes directly, which differs
from the established encoding pattern used elsewhere in the codebase.

Fix:
- Change to use read_unsigned_vb() to read the value (consistent with other encodings)
- Apply sign-extension using the same 14-bit logic as sign_extend_14bit()
- Negate the result to implement NEG_14BIT encoding
- Matches the pattern used in src/main.rs for H-frame parsing

This ensures consistency across the codebase while maintaining the same
effective behavior and output (verified via MD5 hash matching master).

* fix: correct read_neg_14bit implementation and add comprehensive tests

- Fix truncation bug: operate on full u32 from read_unsigned_vb() instead of casting to u16
- Fix sign-extension: use correct 14-bit two's complement with mask 0x3FFF and bit 13 as sign bit
- Remove double negation and confusing masking logic
- Add sign_extend_14bit() helper function following same pattern as other sign extensions
- Add 6 unit tests covering:
  - Positive values (0, 1, max 8191)
  - Negative values (-8192 to -1)
  - Boundary conditions
  - Value overflow (>14 bits masked correctly)

All tests pass, no clippy warnings, release build successful.

* fix: add explicit directory whitelisting to .gitignore for src/** paths

The pattern 'src/**/*.rs' alone doesn't work because parent directories
need explicit whitelisting. Added '!src/**' to properly include all
subdirectories under src/, allowing all .rs files to be staged.

* refactor: address CodeRabbit nitpick feedback in stream.rs

- Simplify read_neg_14bit casting chain (u32 → i32 → u16 becomes u32 → u16)
- Rename sign_extend_14bit to sign_extend_14bit_twos_complement to disambiguate
  from bbl_format.rs::sign_extend_14bit which uses sign-magnitude encoding
- Add documentation clarifying the two's complement semantics
- Fix comment hex value in test_read_neg_14bit_masks_14_bits (0xFFFFF → 0x1FFFFF)

Author: nerdCopter

.gitignore

@@ -15,7 +15,7 @@
 
 # Whitelist src directory and all Rust files within it
 !src/
-!src/*.rs
+!src/**
 !src/**/*.rs
 
 # Whitelist examples directory

examples/gpx_export.rs

@@ -1,9 +1,7 @@
 //! GPX Export Example
 //!
 //! Demonstrates how to export GPS data to GPX format for use with mapping applications.
-//! Note: GPS data collection requires the parser to populate gps_coordinates.
-//!       Currently, the parser module returns empty GPS vectors.
-//!       Use the CLI for GPS export: `bbl_parser --gps flight.BBL`
+//! The parser module now fully supports GPS frame parsing (G-frames and H-frames).
 
 use bbl_parser::{export_to_gpx, parse_bbl_file, ExportOptions};
 use std::path::Path;
@@ -54,8 +52,8 @@ fn main() -> anyhow::Result<()> {
         println!("  Exported {} GPS coordinates", log.gps_coordinates.len());
     } else {
         println!("\n⊘ No GPS coordinates available");
-        println!("Note: GPS data collection in parser module not yet implemented.");
-        println!("For GPS export, use the CLI: bbl_parser --gps flight.BBL");
+        println!("Note: This BBL file may not contain GPS data (no G-frames).");
+        println!("Check that your flight controller has GPS enabled and connected.");
     }
 
     Ok(())

examples/test_crate_gps.rs

@@ -0,0 +1,40 @@
+use bbl_parser::{parse_bbl_file, ExportOptions};
+use std::path::Path;
+
+fn main() -> anyhow::Result<()> {
+    let input_file = std::env::args().nth(1).unwrap_or_else(|| {
+        println!("Usage: test_crate_gps <input.BBL> [output_dir]");
+        println!("Example: test_crate_gps flight.BBL ./output");
+        println!("Note: Demonstrates GPS and Event frame parsing via the crate library");
+        std::process::exit(1);
+    });
+
+    let output_dir = std::env::args().nth(2);
+
+    let export_opts = ExportOptions {
+        csv: false,
+        gpx: true,
+        event: true,
+        output_dir,
+        force_export: false,
+    };
+
+    println!("Parsing: {}", input_file);
+    let log = parse_bbl_file(Path::new(&input_file), export_opts, false)?;
+
+    println!("\nCrate Library Results:");
+    println!("  Total frames: {}", log.stats.total_frames);
+    println!("  I frames: {}", log.stats.i_frames);
+    println!("  P frames: {}", log.stats.p_frames);
+    println!("  G frames: {}", log.stats.g_frames);
+    println!("  H frames: {}", log.stats.h_frames);
+    println!("  E frames: {}", log.stats.e_frames);
+    println!("  GPS coordinates collected: {}", log.gps_coordinates.len());
+    println!(
+        "  GPS home coords collected: {}",
+        log.home_coordinates.len()
+    );
+    println!("  Event frames collected: {}", log.event_frames.len());
+
+    Ok(())
+}

src/main.rs

@@ -357,7 +357,7 @@ struct EventFrame {
     event_type: u8,
     #[allow(dead_code)]
     event_data: Vec<u8>,
-    event_description: String,
+    event_name: String,
 }
 
 #[derive(Debug)]
@@ -2498,7 +2498,7 @@ fn parse_e_frame(stream: &mut bbl_format::BBLDataStream, debug: bool) -> Result<
 
     // Read event data - the length depends on the event type
     let mut event_data = Vec::new();
-    let event_description = match event_type {
+    let event_name = match event_type {
         0 => {
             // FLIGHT_LOG_EVENT_SYNC_BEEP
             "Sync beep".to_string()
@@ -2642,15 +2642,15 @@ fn parse_e_frame(stream: &mut bbl_format::BBLDataStream, debug: bool) -> Result<
     if debug {
         println!(
             "DEBUG: Event - Type: {}, Description: {}",
-            event_type, event_description
+            event_type, event_name
         );
     }
 
     Ok(EventFrame {
         timestamp_us: 0, // Will be set later from context
         event_type,
         event_data,
-        event_description,
+        event_name,
     })
 }
 
@@ -3163,7 +3163,7 @@ fn export_event_file(
         writeln!(
             event_file,
             r#"{{"name":"{}", "time":{}}}"#,
-            event.event_description.replace('"', "\\\""),
+            event.event_name.replace('"', "\\\""),
             event.timestamp_us
         )?;
     }

src/parser/event.rs

@@ -0,0 +1,174 @@
+//! Event frame parsing helper module
+//!
+//! Contains functions for parsing E-frames (Event data) from blackbox log data.
+//! These helpers are used by both the library parser and CLI binary.
+
+use crate::parser::stream::BBLDataStream;
+use crate::types::EventFrame;
+use crate::Result;
+
+/// Helper function to parse inflight adjustment events (types 4 and 13)
+/// Returns the event description string
+fn parse_inflight_adjustment(
+    stream: &mut BBLDataStream,
+    event_data: &mut Vec<u8>,
+) -> Result<String> {
+    let adjustment_function = stream.read_byte()?;
+    event_data.extend_from_slice(&[adjustment_function]);
+    if adjustment_function > 127 {
+        let new_value = stream.read_unsigned_vb()? as f32;
+        Ok(format!(
+            "Inflight adjustment - Function: {}, New value: {:.3}",
+            adjustment_function, new_value
+        ))
+    } else {
+        let new_value = stream.read_signed_vb()?;
+        Ok(format!(
+            "Inflight adjustment - Function: {}, New value: {}",
+            adjustment_function, new_value
+        ))
+    }
+}
+
+/// Parse E-frame (Event frame) data from the stream
+///
+/// E-frames contain various event types such as sync beeps, autotune cycles,
+/// inflight adjustments, logging resume, disarm, flight mode changes, and log end.
+/// Each event type has its own data format that this function decodes.
+pub fn parse_e_frame(stream: &mut BBLDataStream, debug: bool) -> Result<EventFrame> {
+    if debug {
+        println!("Parsing E frame (Event frame)");
+    }
+
+    // Read event type (1 byte)
+    let event_type = stream.read_byte()?;
+
+    // Read event data - the length depends on the event type
+    let mut event_data = Vec::new();
+    let event_name = match event_type {
+        0 => {
+            // FLIGHT_LOG_EVENT_SYNC_BEEP
+            "Sync beep".to_string()
+        }
+        1 => {
+            // FLIGHT_LOG_EVENT_AUTOTUNE_CYCLE_START
+            "Autotune cycle start".to_string()
+        }
+        2 => {
+            // FLIGHT_LOG_EVENT_AUTOTUNE_CYCLE_RESULT
+            let axis = stream.read_byte()?;
+            let p_gain = stream.read_signed_vb()? as f32 / 1000.0;
+            let i_gain = stream.read_signed_vb()? as f32 / 1000.0;
+            let d_gain = stream.read_signed_vb()? as f32 / 1000.0;
+            event_data.extend_from_slice(&[axis]);
+            format!(
+                "Autotune cycle result - Axis: {}, P: {:.3}, I: {:.3}, D: {:.3}",
+                axis, p_gain, i_gain, d_gain
+            )
+        }
+        3 => {
+            // FLIGHT_LOG_EVENT_AUTOTUNE_TARGETS
+            let current_angle = stream.read_signed_vb()?;
+            let target_angle = stream.read_signed_vb()?;
+            let target_angle_at_peak = stream.read_signed_vb()?;
+            let first_peak_angle = stream.read_signed_vb()?;
+            let second_peak_angle = stream.read_signed_vb()?;
+            format!(
+                "Autotune targets - Current: {}, Target: {}, Peak target: {}, First peak: {}, Second peak: {}",
+                current_angle, target_angle, target_angle_at_peak, first_peak_angle, second_peak_angle
+            )
+        }
+        4 => {
+            // FLIGHT_LOG_EVENT_INFLIGHT_ADJUSTMENT
+            parse_inflight_adjustment(stream, &mut event_data)?
+        }
+        5 => {
+            // FLIGHT_LOG_EVENT_LOGGING_RESUME
+            // Note: Event type 14 has identical implementation - both use this newer numbering
+            let log_iteration = stream.read_unsigned_vb()?;
+            let current_time = stream.read_unsigned_vb()?;
+            format!(
+                "Logging resume - Iteration: {}, Time: {}",
+                log_iteration, current_time
+            )
+        }
+        6 => {
+            // FLIGHT_LOG_EVENT_LOG_END (old numbering)
+            // Read end message bytes
+            for _ in 0..4 {
+                if !stream.eof {
+                    event_data.push(stream.read_byte()?);
+                }
+            }
+            "Log end".to_string()
+        }
+        10 => {
+            // FLIGHT_LOG_EVENT_AUTOTUNE_CYCLE_START (UNUSED)
+            "Autotune cycle start (unused)".to_string()
+        }
+        11 => {
+            // FLIGHT_LOG_EVENT_AUTOTUNE_CYCLE_RESULT (UNUSED)
+            "Autotune cycle result (unused)".to_string()
+        }
+        12 => {
+            // FLIGHT_LOG_EVENT_AUTOTUNE_TARGETS (UNUSED)
+            "Autotune targets (unused)".to_string()
+        }
+        13 => {
+            // FLIGHT_LOG_EVENT_INFLIGHT_ADJUSTMENT
+            parse_inflight_adjustment(stream, &mut event_data)?
+        }
+        14 => {
+            // FLIGHT_LOG_EVENT_LOGGING_RESUME (newer numbering, same as type 5)
+            // Both event type numbers are used in different firmware versions
+            let log_iteration = stream.read_unsigned_vb()?;
+            let current_time = stream.read_unsigned_vb()?;
+            format!(
+                "Logging resume - Iteration: {}, Time: {}",
+                log_iteration, current_time
+            )
+        }
+        15 => {
+            // FLIGHT_LOG_EVENT_DISARM
+            "Disarm".to_string()
+        }
+        30 => {
+            // FLIGHT_LOG_EVENT_FLIGHTMODE - flight mode status event
+            // Read flight mode data
+            for _ in 0..4 {
+                if !stream.eof {
+                    event_data.push(stream.read_byte()?);
+                }
+            }
+            "Flight mode change".to_string()
+        }
+        255 => {
+            // FLIGHT_LOG_EVENT_LOG_END
+            "Log end".to_string()
+        }
+        _ => {
+            // Unknown event type - read a few bytes as data
+            for _ in 0..8 {
+                if stream.eof {
+                    break;
+                }
+                event_data.push(stream.read_byte()?);
+            }
+            format!("Unknown event type: {}", event_type)
+        }
+    };
+
+    if debug {
+        println!(
+            "DEBUG: Event - Type: {}, Description: {}",
+            event_type, event_name
+        );
+    }
+
+    Ok(EventFrame {
+        timestamp_us: 0, // Will be set later from context
+        event_type,
+        event_data,
+        event_name,
+    })
+}