feat: improve file naming logic and documentation

- Remove .01 suffix for single log files (cleaner output)
- Apply consistent naming across CSV, GPX, and event exports
- Update README with clear filename examples for single vs multiple logs
- Fix debug output formatting examples with proper field name display
- Maintain blackbox_decode compatibility while improving user experience

Author: nerdCopter

README.md

@@ -29,13 +29,13 @@ A high-performance Rust library and command-line tool for parsing BBL (Blackbox
 
 Exports blackbox logs to CSV format with blackbox_decode compatibility:
 
-- **`.XX.csv`**: Main flight data file containing I, P, S, G frame data
+- **`[.XX].csv`**: Main flight data file containing I, P, S, G frame data
   - Field names header row in blackbox_decode compatible order
   - Time field labeled as "time (us)" for microsecond precision
   - All flight loop data (I frames) and status data (S frames) 
   - GPS data (G frames) when available
   - Time-sorted chronological data rows
-- **`.XX.headers.csv`**: Complete header information file
+- **`[.XX].headers.csv`**: Complete header information file
   - Field,Value format with all configuration parameters
   - Frame definitions, system settings, firmware information
   - All BBL header metadata for analysis tools
@@ -44,7 +44,7 @@ Exports blackbox logs to CSV format with blackbox_decode compatibility:
 
 Exports GPS data to GPX format for mapping applications:
 
-- **`.gps.gpx`**: GPS track file in standard GPX format
+- **`[.XX].gps.gpx`**: GPS track file in standard GPX format
   - Geographic coordinates from GPS frames
   - Altitude information with proper firmware scaling
   - Timestamp data for track visualization
@@ -54,22 +54,36 @@ Exports GPS data to GPX format for mapping applications:
 
 Exports flight events to JSONL format:
 
-- **`.event`**: Flight event data in JSON Lines format
+- **`[.XX].event`**: Flight event data in JSON Lines format
   - Individual JSON objects per line for streaming compatibility
   - Event types based on official Betaflight FlightLogEvent enum
   - Includes sync beeps, disarm events, flight mode changes, log boundaries
   - Compatible with log analysis tools expecting JSONL format
 
-Where `XX` represents the flight log number (01, 02, 03, etc.) for multiple logs within a single BBL file.
+**Filename Logic:**
+- **Single log files**: Clean filenames without numbering (`flight_log.csv`, `flight_log.event`, `flight_log.gps.gpx`)
+- **Multiple log files**: Numbered sequence for clarity (`flight_log.01.csv`, `flight_log.02.event`, etc.)
 
 **Example files generated:**
+
+*Single log in BBL file:*
+```
+BTFL_LOG_20250601_121852.csv         # Flight data  
+BTFL_LOG_20250601_121852.headers.csv # Headers
+BTFL_LOG_20250601_121852.gps.gpx     # GPS track data
+BTFL_LOG_20250601_121852.event       # Flight events
+```
+
+*Multiple logs in BBL file:*
 ```
 BTFL_LOG_20250601_121852.01.csv         # Flight data for log 1
 BTFL_LOG_20250601_121852.01.headers.csv # Headers for log 1
-BTFL_LOG_20250601_121852.gps.gpx        # GPS track data
-BTFL_LOG_20250601_121852.event          # Flight events
+BTFL_LOG_20250601_121852.01.gps.gpx     # GPS data for log 1
+BTFL_LOG_20250601_121852.01.event       # Events for log 1
 BTFL_LOG_20250601_121852.02.csv         # Flight data for log 2  
 BTFL_LOG_20250601_121852.02.headers.csv # Headers for log 2
+BTFL_LOG_20250601_121852.02.gps.gpx     # GPS data for log 2
+BTFL_LOG_20250601_121852.02.event       # Events for log 2
 ```
 
 ## Installation & Usage
@@ -340,8 +354,10 @@ Data ver        2
 
 Additional output when export flags are used:
 ```
-Exported GPS data to: flight_log.gps.gpx      # When --gpx used
-Exported event data to: flight_log.event      # When --event used
+Exported headers to: flight_log[.XX].headers.csv
+Exported flight data to: flight_log[.XX].csv
+Exported GPS data to: flight_log[.XX].gps.gpx      # When --gpx used
+Exported event data to: flight_log[.XX].event      # When --event used
 ```
 
 ### Debug Output
@@ -352,15 +368,15 @@ Debug mode adds frame data tables for detailed analysis:
 === FRAME DATA ===
 
 I-frame data (25 frames):
-     Index     Time(μs)     Loop accSmooth[ accSmooth[ gyroADC[0]  motor[0]  motor[1] ... (40 more fields)
+     Index     Time(μs)     Loop   accSmooth   accSmooth   gyroADC[0]    motor[0]    motor[1] ... (40 more fields)
          0            0        4          0          0         -5      1270      1270 ...
          1     36147802    71168       -163        130       2289      1260      1277 ...
        ...          ...      ... ... (18 frames skipped)
         23     36853826    73984       -332        -12       3512      1215      1210 ...
         24     36885919    74112       -430         26       3552      1205      1210 ...
 
 P-frame data (50 frames):
-     Index     Time(μs)     Loop accSmooth[ accSmooth[ gyroADC[0]  motor[0]  motor[1] ... (40 more fields)
+     Index     Time(μs)     Loop   accSmooth   accSmooth   gyroADC[0]    motor[0]    motor[1] ... (40 more fields)
          0 18446744073709551615        5        -11          9         27       632       637 ...
          1 18446744073709551615        6        -11          9         26       948       958 ...
        ...          ...      ... ... (18 frames skipped)

src/main.rs

@@ -1227,7 +1227,7 @@ fn export_logs_to_csv(
         let log_suffix = if logs.len() > 1 {
             format!(".{:02}", log.log_number)
         } else {
-            ".01".to_string()
+            "".to_string()
         };
 
         // Export plaintext headers to separate CSV
@@ -1272,7 +1272,7 @@ fn export_single_log_to_csv(
     let log_suffix = if log.total_logs > 1 {
         format!(".{:02}", log.log_number)
     } else {
-        ".01".to_string()
+        "".to_string()
     };
 
     // Export plaintext headers to separate CSV
@@ -2647,6 +2647,7 @@ fn parse_bbl_file_streaming(
             if let Err(e) = export_gpx_file(
                 file_path,
                 log_index,
+                log_positions.len(),
                 &gps_coords,
                 &home_coords,
                 export_options,
@@ -2664,7 +2665,13 @@ fn parse_bbl_file_streaming(
 
         // Export event data to JSON if requested
         if export_options.event && !events.is_empty() {
-            if let Err(e) = export_event_file(file_path, log_index, &events, export_options) {
+            if let Err(e) = export_event_file(
+                file_path,
+                log_index,
+                log_positions.len(),
+                &events,
+                export_options,
+            ) {
                 let filename = file_path
                     .file_name()
                     .and_then(|n| n.to_str())
@@ -2835,6 +2842,7 @@ fn convert_gps_course(raw_value: i32) -> f64 {
 fn export_gpx_file(
     file_path: &Path,
     log_number: usize,
+    total_logs: usize,
     gps_coords: &[GpsCoordinate],
     _home_coords: &[GpsHomeCoordinate], // TODO: Use home coordinates for reference point
     export_options: &ExportOptions,
@@ -2853,11 +2861,13 @@ fn export_gpx_file(
         .as_deref()
         .unwrap_or_else(|| file_path.parent().unwrap().to_str().unwrap());
 
-    let gpx_filename = if log_number > 0 {
-        format!("{}/{}.{:02}.gps.gpx", output_dir, base_name, log_number + 1)
+    // Use consistent naming: only add suffix for multiple logs
+    let log_suffix = if total_logs > 1 {
+        format!(".{:02}", log_number + 1)
     } else {
-        format!("{}/{}.gps.gpx", output_dir, base_name)
+        "".to_string()
     };
+    let gpx_filename = format!("{}/{}{}.gps.gpx", output_dir, base_name, log_suffix);
 
     let mut gpx_file = std::fs::File::create(&gpx_filename)?;
     writeln!(gpx_file, r#"<?xml version="1.0" encoding="UTF-8"?>"#)?;
@@ -2906,6 +2916,7 @@ fn export_gpx_file(
 fn export_event_file(
     file_path: &Path,
     log_number: usize,
+    total_logs: usize,
     events: &[EventFrame],
     export_options: &ExportOptions,
 ) -> Result<()> {
@@ -2923,11 +2934,13 @@ fn export_event_file(
         .as_deref()
         .unwrap_or_else(|| file_path.parent().unwrap().to_str().unwrap());
 
-    let event_filename = if log_number > 0 {
-        format!("{}/{}.{:02}.event", output_dir, base_name, log_number + 1)
+    // Use consistent naming: only add suffix for multiple logs
+    let log_suffix = if total_logs > 1 {
+        format!(".{:02}", log_number + 1)
     } else {
-        format!("{}/{}.event", output_dir, base_name)
+        "".to_string()
     };
+    let event_filename = format!("{}/{}{}.event", output_dir, base_name, log_suffix);
 
     let mut event_file = std::fs::File::create(&event_filename)?;