Implement debug logging utility and integrate into application flow

Author: MrAlders0n

lib/main.dart

@@ -8,12 +8,18 @@ import 'screens/home_screen.dart';
 import 'services/bluetooth/bluetooth_service.dart';
 import 'services/bluetooth/mobile_bluetooth.dart';
 import 'services/bluetooth/web_bluetooth.dart';
+import 'utils/debug_logger_io.dart';
 
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
 
+  // Initialize debug logger (checks for ?debug=1 URL param on web)
+  DebugLogger.initialize();
+  debugLog('[APP] MeshMapper starting...');
+  
   // Initialize Hive for local storage
   await Hive.initFlutter();
+  debugLog('[APP] Hive initialized');
 
   runApp(const MeshMapperApp());
 }

lib/providers/app_state_provider.dart

@@ -14,6 +14,15 @@ import '../services/device_model_service.dart';
 import '../services/gps_service.dart';
 import '../services/meshcore/connection.dart';
 import '../services/ping_service.dart';
+import '../utils/debug_logger_io.dart';
+
+/// Auto-ping mode (matches MeshMapper_WebClient behavior)
+enum AutoMode {
+  /// TX/RX Auto: Sends pings on movement, listens for RX responses
+  txRx,
+  /// RX Auto: Passive listening only (no transmit)
+  rxOnly,
+}
 
 /// Main application state provider
 class AppStateProvider extends ChangeNotifier {
@@ -44,6 +53,7 @@ class AppStateProvider extends ChangeNotifier {
   // Ping state
   PingStats _pingStats = const PingStats();
   bool _autoPingEnabled = false;
+  AutoMode _autoMode = AutoMode.txRx;
   int _queueSize = 0;
 
   // Discovered devices
@@ -73,6 +83,7 @@ class AppStateProvider extends ChangeNotifier {
   String? get manufacturerString => _manufacturerString;
   PingStats get pingStats => _pingStats;
   bool get autoPingEnabled => _autoPingEnabled;
+  AutoMode get autoMode => _autoMode;
   int get queueSize => _queueSize;
   List<DiscoveredDevice> get discoveredDevices => _discoveredDevices;
   bool get isScanning => _isScanning;
@@ -287,18 +298,29 @@ class AppStateProvider extends ChangeNotifier {
   /// Send a manual TX ping
   Future<bool> sendPing() async {
     if (_pingService == null) return false;
+    debugLog('[PING] Sending manual TX ping');
     return await _pingService!.sendTxPing();
   }
 
-  /// Toggle auto-ping mode
-  void toggleAutoPing() {
+  /// Toggle auto-ping mode (TX/RX or RX-only)
+  void toggleAutoPing(AutoMode mode) {
     if (_pingService == null) return;
 
-    if (_autoPingEnabled) {
+    // If currently running the same mode, stop it
+    if (_autoPingEnabled && _autoMode == mode) {
+      debugLog('[PING] Stopping auto mode: ${mode.name}');
       _pingService!.disableAutoPing();
       _autoPingEnabled = false;
     } else {
-      _pingService!.enableAutoPing();
+      // Stop any existing mode first
+      if (_autoPingEnabled) {
+        _pingService!.disableAutoPing();
+      }
+      
+      // Start new mode
+      debugLog('[PING] Starting auto mode: ${mode.name}');
+      _autoMode = mode;
+      _pingService!.enableAutoPing(rxOnly: mode == AutoMode.rxOnly);
       _autoPingEnabled = true;
     }
 

lib/services/bluetooth/web_bluetooth.dart

@@ -4,6 +4,7 @@ import 'dart:typed_data';
 import 'package:flutter_web_bluetooth/flutter_web_bluetooth.dart' as fwb;
 
 import '../../models/connection_state.dart';
+import '../../utils/debug_logger_io.dart';
 import '../meshcore/protocol_constants.dart';
 import 'bluetooth_service.dart';
 
@@ -63,13 +64,14 @@ class WebBluetoothService implements BluetoothService {
     // Web Bluetooth doesn't support scanning - uses requestDevice dialog
     // This is a stub that will yield devices from the request dialog
     _updateStatus(ConnectionStatus.scanning);
+    debugLog('[BLE] Opening device picker with service filter: ${BleUuids.serviceUuid}');
 
     try {
-      // Request device with MeshCore service filter
+      // Request device filtered by MeshCore service UUID (matches JS implementation)
       final device = await _webBluetooth.requestDevice(
-        fwb.RequestOptionsBuilder.acceptAllDevices(
-          optionalServices: [BleUuids.serviceUuid.toLowerCase()],
-        ),
+        fwb.RequestOptionsBuilder([
+          fwb.RequestFilterBuilder(services: [BleUuids.serviceUuid.toLowerCase()]),
+        ]),
       );
 
       if (device != null) {
@@ -97,12 +99,13 @@ class WebBluetoothService implements BluetoothService {
   Future<void> connect(String deviceId) async {
     try {
       _updateStatus(ConnectionStatus.connecting);
+      debugLog('[BLE] Connecting to device: $deviceId');
 
-      // Request device again (Web Bluetooth requires this)
+      // Request device filtered by MeshCore service UUID (matches JS implementation)
       _device = await _webBluetooth.requestDevice(
-        fwb.RequestOptionsBuilder.acceptAllDevices(
-          optionalServices: [BleUuids.serviceUuid.toLowerCase()],
-        ),
+        fwb.RequestOptionsBuilder([
+          fwb.RequestFilterBuilder(services: [BleUuids.serviceUuid.toLowerCase()]),
+        ]),
       );
 
       if (_device == null) {

lib/services/ping_service.dart

@@ -4,6 +4,7 @@ import 'package:geolocator/geolocator.dart';
 
 import '../models/connection_state.dart';
 import '../models/ping_data.dart';
+import '../utils/debug_logger_io.dart';
 import 'api_queue_service.dart';
 import 'gps_service.dart';
 import 'meshcore/connection.dart';
@@ -41,6 +42,7 @@ class PingService {
 
   // Auto-ping mode
   bool _autoPingEnabled = false;
+  bool _rxOnlyMode = false;
   StreamSubscription? _positionSubscription;
 
   /// Callback for ping events
@@ -228,15 +230,24 @@ class PingService {
   }
 
   /// Enable auto-ping mode
-  void enableAutoPing() {
+  /// @param rxOnly - If true, only listens for RX (no TX pings)
+  void enableAutoPing({bool rxOnly = false}) {
     if (_autoPingEnabled) return;
 
     _autoPingEnabled = true;
+    _rxOnlyMode = rxOnly;
+    debugLog('[PING] Auto-ping enabled, rxOnly: $rxOnly');
 
     // Listen for position updates and auto-ping when conditions are met
     _positionSubscription = _gpsService.positionStream.listen((position) async {
       if (!_autoPingEnabled) return;
 
+      // RX-only mode doesn't send pings
+      if (_rxOnlyMode) {
+        debugLog('[RX] RX-only mode - listening for signals');
+        return;
+      }
+      
       final validation = canPing();
       if (validation == PingValidation.valid) {
         await sendTxPing();
@@ -246,7 +257,9 @@ class PingService {
 
   /// Disable auto-ping mode
   void disableAutoPing() {
+    debugLog('[PING] Auto-ping disabled');
     _autoPingEnabled = false;
+    _rxOnlyMode = false;
     _positionSubscription?.cancel();
     _positionSubscription = null;
   }

lib/utils/debug_logger.dart

@@ -0,0 +1,139 @@
+// This file is for web platform only - uses dart:html
+// For non-web, see debug_logger_stub.dart
+// Export via debug_logger_io.dart for conditional import
+
+// ignore: avoid_web_libraries_in_flutter
+import 'dart:html' as html show window;
+// ignore: avoid_web_libraries_in_flutter
+import 'dart:js_util' as js_util;
+
+import 'package:flutter/foundation.dart';
+
+/// Debug logging utility that mirrors MeshMapper_WebClient debug system.
+/// 
+/// Logs are only output when DEBUG_ENABLED is true (set via `?debug=1` URL param).
+/// All log messages should use tagged format: `[TAG] message`
+/// 
+/// Common tags: [BLE], [GPS], [PING], [API], [RX], [UI], [CONN]
+class DebugLogger {
+  static bool _debugEnabled = false;
+  static bool _initialized = false;
+
+  /// Initialize the debug logger by checking URL parameters.
+  /// Call this early in app startup (e.g., in main.dart).
+  static void initialize() {
+    if (_initialized) return;
+    _initialized = true;
+
+    if (kIsWeb) {
+      try {
+        // Parse URL parameters from browser
+        final uri = Uri.base;
+        final debugParam = uri.queryParameters['debug'];
+        _debugEnabled = debugParam == '1' || debugParam == 'true';
+        
+        if (_debugEnabled) {
+          _consoleLog('[DEBUG] Debug logging ENABLED via URL param');
+        }
+      } catch (e) {
+        // Fallback - URL parsing failed
+        _debugEnabled = false;
+      }
+    } else {
+      // On mobile, check for debug mode compile flag
+      _debugEnabled = kDebugMode;
+    }
+  }
+
+  /// Check if debug logging is enabled
+  static bool get isEnabled => _debugEnabled;
+
+  /// Manually enable/disable debug logging (for testing)
+  static void setEnabled(bool enabled) {
+    _debugEnabled = enabled;
+  }
+
+  /// Log a general info message to the console.
+  /// Use tagged format: debugLog('[BLE] Connected to device');
+  static void log(String message, [Object? arg1, Object? arg2, Object? arg3]) {
+    if (!_debugEnabled) return;
+    
+    final args = [message, if (arg1 != null) arg1, if (arg2 != null) arg2, if (arg3 != null) arg3];
+    
+    if (kIsWeb) {
+      _consoleLog(args.join(' '));
+    } else {
+      debugPrint(args.join(' '));
+    }
+  }
+
+  /// Log a warning message to the console.
+  /// Use tagged format: debugWarn('[GPS] Position stale, re-acquiring');
+  static void warn(String message, [Object? arg1, Object? arg2, Object? arg3]) {
+    if (!_debugEnabled) return;
+    
+    final args = ['⚠️', message, if (arg1 != null) arg1, if (arg2 != null) arg2, if (arg3 != null) arg3];
+    
+    if (kIsWeb) {
+      _consoleWarn(args.join(' '));
+    } else {
+      debugPrint('WARN: ${args.join(' ')}');
+    }
+  }
+
+  /// Log an error message to the console.
+  /// Use tagged format: debugError('[API] Failed to post queue', error);
+  static void error(String message, [Object? arg1, Object? arg2, Object? arg3]) {
+    if (!_debugEnabled) return;
+    
+    final args = ['❌', message, if (arg1 != null) arg1, if (arg2 != null) arg2, if (arg3 != null) arg3];
+    
+    if (kIsWeb) {
+      _consoleError(args.join(' '));
+    } else {
+      debugPrint('ERROR: ${args.join(' ')}');
+    }
+  }
+
+  // Web console methods using dart:js_util for proper browser console output
+  static void _consoleLog(String message) {
+    try {
+      js_util.callMethod(html.window.console, 'log', [message]);
+    } catch (e) {
+      // Fallback
+      // ignore: avoid_print
+      print(message);
+    }
+  }
+
+  static void _consoleWarn(String message) {
+    try {
+      js_util.callMethod(html.window.console, 'warn', [message]);
+    } catch (e) {
+      // ignore: avoid_print
+      print('WARN: $message');
+    }
+  }
+
+  static void _consoleError(String message) {
+    try {
+      js_util.callMethod(html.window.console, 'error', [message]);
+    } catch (e) {
+      // ignore: avoid_print
+      print('ERROR: $message');
+    }
+  }
+}
+
+/// Convenience global functions matching MeshMapper_WebClient API
+void debugLog(String message, [Object? arg1, Object? arg2, Object? arg3]) {
+  DebugLogger.log(message, arg1, arg2, arg3);
+}
+
+void debugWarn(String message, [Object? arg1, Object? arg2, Object? arg3]) {
+  DebugLogger.warn(message, arg1, arg2, arg3);
+}
+
+void debugError(String message, [Object? arg1, Object? arg2, Object? arg3]) {
+  DebugLogger.error(message, arg1, arg2, arg3);
+}

lib/utils/debug_logger_io.dart

@@ -0,0 +1,13 @@
+/// Debug logger with conditional imports for web vs mobile platforms.
+/// 
+/// Usage:
+/// ```dart
+/// import 'package:meshmapper/utils/debug_logger_io.dart';
+/// 
+/// DebugLogger.initialize();
+/// debugLog('[TAG] message');
+/// debugWarn('[TAG] warning');
+/// debugError('[TAG] error');
+/// ```
+export 'debug_logger_stub.dart'
+    if (dart.library.html) 'debug_logger.dart';