Enhancement: Add GPS home waypoint to GPX export

[coderabbitai]

Context

This issue addresses the TODO comment at line 1497 in main.rs:

_home_coords: &[GpsHomeCoordinate], // TODO: Use home coordinates for reference point

Current Status: Functionally Correct ✅

After deep analysis and comparison with blackbox-tools and blackbox-log-viewer, the current implementation is already correct:

What's Working:

1. ✅ H frames (GPS home) are correctly parsed from blackbox logs (src/parser/frame.rs:343-367)
2. ✅ Home coordinates are correctly used as reference points during GPS decoding (src/parser/frame.rs:430-443)
3. ✅ GPS G frames contain deltas from home per Betaflight spec
4. ✅ Actual coordinates are calculated as: actual_position = home_position + delta
5. ✅ GPX export receives absolute lat/lon coordinates (not deltas)

Why home_coordinates appears "unused" in GPX export:

The home coordinates are already incorporated into the GPS coordinates during frame parsing. By the time we reach GPX export, gps_coordinates contains absolute positions, so home coordinates don't need to be referenced again.

Enhancement Opportunity: Home Waypoint Marker

While functionally correct, we could enhance GPX files by adding a home position waypoint for better visualization in mapping tools.

Reference Implementation Analysis

Betaflight Blackbox Specification:

• H frames record GPS home position (latitude, longitude)
• H frames are logged periodically to maintain decoder state
• G frames store position deltas from home
• Predictor Migrate GPS/Event frame parsing from CLI to crate library #7 ("home-coord") uses most recent H frame values

GPX 1.1 Specification:

GPX files support both track points (<trkpt>) and waypoints (<wpt>):

<wpt lat="37.123456" lon="-122.123456">
  <name>Home</name>
  <sym>Flag</sym>
  <type>Home Position</type>
</wpt>

Proposed Enhancement

Add a home position waypoint to GPX exports when home coordinates are available. This would:

• ✅ Improve visualization in GPS mapping tools (Google Earth, Garmin BaseCamp, etc.)
• ✅ Provide a clear reference point for flight analysis
• ✅ Match behavior of some GPS analysis tools
• ✅ Remain backward compatible (waypoints are optional in GPX)

Implementation Plan

Phase 1: Add Home Waypoint to GPX Export (Est. 1-2 hours)

File: src/export.rs, function export_to_gpx

Changes:

1. Remove underscore prefix from _home_coordinates parameter (line 296)
2. After writing GPX metadata but before <trk> element, add waypoint logic:

// Add home position waypoint if available
if let Some(home) = home_coordinates.first() {
    writeln!(
        gpx_file,
        r#"  <wpt lat="{:.7}" lon="{:.7}">#",
        home.home_latitude, home.home_longitude
    )?;
    writeln!(gpx_file, "    <name>Home</name>")?;
    writeln!(gpx_file, "    <sym>Flag</sym>")?;
    writeln!(gpx_file, "    <type>Home Position</type>")?;
    writeln!(gpx_file, "  </wpt>")?;
}

3. Update the duplicate logic in src/main.rs function export_gpx (line 1497) - remove underscore and apply same logic

Validation:

# Test with GPS-enabled log
cargo run -- test.BBL --gpx

# Verify GPX contains home waypoint
grep -A 4 '<wpt' output.gpx

# Validate GPX schema
xmllint --schema http://www.topografix.com/GPX/1/1/gpx.xsd output.gpx

Phase 2: Add Tests (Est. 1 hour)

File: New test in tests/gps_tests.rs or src/export.rs

#[test]
fn test_gpx_includes_home_waypoint() {
    let home_coords = vec![GpsHomeCoordinate {
        home_latitude: 37.7749,
        home_longitude: -122.4194,
        timestamp_us: 0,
    }];
    
    let gps_coords = vec![/* test coordinates */];
    
    // Export GPX
    export_to_gpx(/* params */).unwrap();
    
    // Read and verify GPX contains waypoint
    let gpx_content = std::fs::read_to_string("output.gpx").unwrap();
    assert!(gpx_content.contains("<wpt lat=\"37.7749\""));
    assert!(gpx_content.contains("<name>Home</name>"));
}

Phase 3: Documentation (Est. 30 minutes)

File: README.md or docs/GPS_EXPORT.md

Document:

• GPX files now include home waypoint marker
• Home position derived from H frames in blackbox log
• Waypoint compatible with standard GPS tools

Phase 4: Comparison with blackbox-tools (Est. 1 hour)

Validation:

1. Export GPX using blackbox_decode from reference implementation
2. Export GPX using bbl_parser
3. Compare waypoint handling (they may or may not include home waypoint)
4. Document any differences and rationale for bbl_parser's approach

Alternative Considerations

Option A: Only show home waypoint (implemented above)

• Pro: Simple, clear, widely compatible
• Con: Minimal information

Option B: Add metadata to home waypoint

<wpt lat="..." lon="...">
  <name>Home</name>
  <desc>GPS home position recorded at flight start</desc>
  <time>2025-03-26T05:00:00.000000Z</time>
  <sym>Flag</sym>
</wpt>

• Pro: More informative, includes timestamp
• Con: Slightly more complex

Option C: Add both home and multiple flight phases as waypoints

• Pro: Rich analysis capability
• Con: Complex, may clutter map view

Recommendation: Start with Option A (simple waypoint), consider Option B if users request more detail.

Testing Checklist

• GPX with home coordinates includes waypoint
• GPX without home coordinates works (no waypoint)
• GPX validates against GPX 1.1 schema
• Google Earth imports and shows home marker
• Garmin BaseCamp displays home correctly
• Multiple logs in single file each show their home
• Backward compatibility: old GPX readers still work

Reference Links

• GPX 1.1 Schema
• Betaflight Blackbox Specification
• blackbox-log-viewer (shows home on map)
• PR #17 Context

Priority

Low-Medium Priority - This is a quality-of-life enhancement, not a bug fix. Current implementation is functionally correct and produces valid GPS tracks. The enhancement would improve user experience when visualizing flights in mapping tools.

Estimated Effort

Total: 3-4 hours

• Implementation: 1-2 hours
• Testing: 1 hour
• Documentation: 30 minutes
• Validation: 1 hour

---

AI Implementation Instructions:

If implementing this enhancement, follow the iterative approach:

1. Start with Phase 1 - core functionality
2. Validate output with sample GPS logs before proceeding
3. Add tests in Phase 2 to prevent regressions
4. Complete documentation only after functionality is confirmed working
5. Optional Phase 4 - compare with reference tools if desired

Each phase should be a separate commit for easy review and potential rollback if needed.