Refactor device model handling: Update documentation and comments for clarity on identification and reporting without modifying TX power settings

Author: MrAlders0n

CLAUDE.md

@@ -77,7 +77,7 @@ The app uses a layered service architecture with clear separation of concerns:
 - `PingService`: TX/RX ping orchestration, coordinates with TxTracker/RxLogger
 - `ApiQueueService`: Hive-based persistent upload queue with batch POST and retry logic
 - `ApiService`: HTTP client for MeshMapper API endpoints
-- `DeviceModelService`: Loads `assets/device-models.json` and auto-configures TX power
+- `DeviceModelService`: Loads `assets/device-models.json` for device identification and power reporting
 
 **State Management** (`lib/providers/`):
 - `AppStateProvider`: Single ChangeNotifier for all app state using Provider pattern
@@ -90,15 +90,15 @@ Critical safety: The connection sequence MUST complete in order. See `docs/CONNE
 1. **BLE GATT Connect**: Platform-specific BLE connection
 2. **Protocol Handshake**: `deviceQuery()` with protocol version
 3. **Device Info**: `getDeviceName()`, `getPublicKey()`, `getDeviceSettings()`
-4. **Auto-Power Configuration**: Parse manufacturer string, match against `device-models.json`, set power level
+4. **Device Identification**: Parse manufacturer string, match against `device-models.json` (does NOT modify radio settings)
 5. **Time Sync**: `sendTime()` syncs device clock
 6. **API Slot Acquisition**: POST to `/capacitycheck.php` to reserve API slot
 7. **Channel Setup**: Create or use existing `#wardriving` channel
 8. **GPS Init**: Acquire GPS lock
 9. **Start Unified RX Handler**: Begin processing ALL incoming packets
 10. **Connected State**: Ready for wardriving
 
-**Critical Power Safety**: PA amplifier devices (30dBm, 33dBm) require specific input power levels. Incorrect values can damage hardware. Auto-power selection from device-models.json is MANDATORY for these devices.
+**Important**: The app does NOT modify the radio's TX power settings. It only identifies the device model to determine what power level to report in API calls. Users configure their radio's actual TX power through the device firmware.
 
 ### Unified RX Handler Architecture
 
@@ -282,7 +282,7 @@ Contains 30+ MeshCore device variants with manufacturer strings, TX power levels
 - `lib/services/ping_service.dart` - TX/RX ping orchestration
 - `lib/services/gps_service.dart` - GPS tracking and geofencing
 - `lib/services/api_queue_service.dart` - Persistent upload queue
-- `lib/services/device_model_service.dart` - Auto-power configuration
+- `lib/services/device_model_service.dart` - Device model identification
 - `assets/device-models.json` - Device database (30+ models)
 - `docs/CONNECTION_WORKFLOW.md` - Connection sequence documentation
 - `docs/PING_WORKFLOW.md` - Ping lifecycle documentation

README.md

@@ -8,7 +8,7 @@ Cross-platform wardriving app for MeshCore devices. A Flutter port of the [MeshM
 - **BLE Connectivity**: Connect to MeshCore devices via Bluetooth Low Energy
 - **GPS Tracking**: High-accuracy location tracking with 25m distance filter
 - **Geofencing**: Enforces 150km boundary from Ottawa (service area)
-- **Auto-Power Selection**: Automatically configures TX power based on device model
+- **Device Recognition**: Automatically identifies device model for accurate power reporting
 - **Real-time Map**: View TX/RX ping markers on OpenStreetMap
 - **API Queue**: Persistent queue with batch upload and retry logic
 - **Dark Mode**: System theme support

docs/ARCHITECTURE.md

@@ -34,7 +34,7 @@ lib/
 │   ├── gps_service.dart                # GPS tracking and geofencing
 │   ├── api_service.dart                # HTTP API client
 │   ├── api_queue_service.dart          # Persistent upload queue
-│   ├── device_model_service.dart       # Device database and auto-power
+│   ├── device_model_service.dart       # Device database and model identification
 │   └── ping_service.dart               # TX/RX orchestration
 ├── providers/
 │   └── app_state_provider.dart         # Main app state
@@ -76,7 +76,7 @@ The `MeshCoreConnection` class handles the 10-step connection workflow:
 1. BLE GATT Connect
 2. Protocol Handshake
 3. Device Info Query
-4. Auto-Power Configuration
+4. Device Identification (for display/reporting only - does NOT modify radio settings)
 5. Time Sync
 6. API Slot Acquisition
 7. Channel Setup
@@ -155,13 +155,13 @@ class AppStateProvider extends ChangeNotifier {
 - RX Characteristic: `6E400002-B5A3-F393-E0A9-E50E24DCCA9E`
 - TX Characteristic: `6E400003-B5A3-F393-E0A9-E50E24DCCA9E`
 
-### Power Configuration Safety
-PA amplifier devices require specific power values:
-- 33dBm models: txPower=9, power=2.0
-- 30dBm models: txPower=20, power=1.0
-- Standard: txPower=22, power=0.3
+### Power Level Reporting
+The app identifies device models to determine what power level to report in API calls:
+- 33dBm models: 2.0W
+- 30dBm models: 1.0W
+- Standard (22dBm): 0.3W
 
-**WARNING**: Incorrect power settings can damage PA amplifier hardware.
+**Important**: The app does NOT modify the radio's TX power settings. It only reads device information and reports the appropriate power level to the API. Users configure their radio's actual TX power through the device firmware.
 
 ## Dependencies
 

docs/DEVELOPMENT_REQUIREMENTS.md

@@ -47,7 +47,7 @@ All debug log messages **MUST** include a descriptive tag in square brackets at
 | `[AUTH]` | Authentication API operations |
 | `[HEARTBEAT]` | Session heartbeat operations |
 | `[API]` | General API operations |
-| `[MODEL]` | Device model detection and auto-power |
+| `[MODEL]` | Device model identification and power reporting |
 | `[MAP]` | Map widget operations |
 
 **Examples:**

lib/models/connection_state.dart

@@ -31,7 +31,7 @@ enum ConnectionStep {
   /// Step 3: Device info query
   deviceQuery,
 
-  /// Step 4: Auto-power configuration based on device model
+  /// Step 4: Device identification (match device model for display/reporting)
   powerConfiguration,
 
   /// Step 5: Time synchronization
@@ -87,7 +87,7 @@ extension ConnectionStepExtension on ConnectionStep {
       case ConnectionStep.deviceQuery:
         return 'Querying device info...';
       case ConnectionStep.powerConfiguration:
-        return 'Configuring power...';
+        return 'Identifying device...';
       case ConnectionStep.timeSync:
         return 'Syncing time...';
       case ConnectionStep.slotAcquisition:

lib/providers/app_state_provider.dart

@@ -591,17 +591,18 @@ class AppStateProvider extends ChangeNotifier {
         _deviceModelService.models,
       );
 
-      // Update preferences if auto-power was configured
-      if (connectionResult.autoPowerConfigured && connectionResult.deviceModel != null) {
+      // Update preferences if device model was recognized (for display/API reporting)
+      // Note: This does NOT change the radio's TX power - it only sets what power level to REPORT
+      if (connectionResult.deviceModelMatched && connectionResult.deviceModel != null) {
         final device = connectionResult.deviceModel!;
         _preferences = _preferences.copyWith(
           powerLevel: device.power,
           txPower: device.txPower,
-          autoPowerSet: true,
+          autoPowerSet: true, // Indicates power was auto-detected from device model
         );
         // TODO: Persist to SharedPreferences when implemented
         notifyListeners();
-        debugLog('[MODEL] Power auto-configured: ${device.power}W (${device.shortName})');
+        debugLog('[MODEL] Device recognized: ${device.shortName} - reporting ${device.power}W in API calls');
       }
 
       // Note: API session acquisition is now handled by the auth callback

lib/screens/connection_screen.dart

@@ -75,9 +75,9 @@ class _ConnectionScreenState extends State<ConnectionScreen> with WidgetsBinding
     final appState = context.watch<AppStateProvider>();
     final isLandscape = MediaQuery.of(context).orientation == Orientation.landscape;
 
-    // Build FAB for scanning
+    // Build FAB for scanning - only show when fully disconnected and idle
     Widget? fab;
-    if (!appState.isScanning && !appState.isConnected) {
+    if (appState.connectionStep == ConnectionStep.disconnected) {
       final canScan = appState.inZone == true || appState.offlineMode;
       fab = isLandscape
           ? FloatingActionButton.small(

lib/services/meshcore/connection.dart

@@ -48,12 +48,12 @@ class SelfInfo {
 
 /// MeshCore connection manager
 /// Ported from content/mc/connection/connection.js in WebClient repo
-/// 
+///
 /// Implements the 10-step connection workflow:
 /// 1. BLE GATT Connect
 /// 2. Protocol Handshake
 /// 3. Device Info Query
-/// 4. Device Model Auto-Power Selection
+/// 4. Device Identification (match device model for display/reporting)
 /// 5. Time Sync
 /// 6. API Capacity Check (slot acquisition)
 /// 7. Channel Setup
@@ -171,9 +171,10 @@ class MeshCoreConnection {
   }
 
   /// Execute the full connection workflow
-  /// Returns (deviceModel, autoPowerConfigured) for preferences update
-  Future<({DeviceModel? deviceModel, bool autoPowerConfigured})> connect(String deviceId, List<DeviceModel> deviceModels) async {
-    bool autoPowerConfigured = false;
+  /// Returns (deviceModel, deviceModelMatched) for display/reporting purposes
+  /// Note: This method does NOT modify radio TX power settings - it only reads device info
+  Future<({DeviceModel? deviceModel, bool deviceModelMatched})> connect(String deviceId, List<DeviceModel> deviceModels) async {
+    bool deviceModelMatched = false;
 
     try {
       // Step 1: BLE Connect
@@ -199,13 +200,15 @@ class MeshCoreConnection {
         throw Exception('Failed to acquire device public key: $e');
       }
 
-      // Step 4: Power Configuration (auto-select based on device model)
+      // Step 4: Device Identification (match device model for display/reporting purposes)
+      // Note: We do NOT modify the radio's TX power - we only read device info
       _updateStep(ConnectionStep.powerConfiguration);
       _deviceModel = _matchDeviceModel(_deviceInfo!.manufacturer, deviceModels);
       if (_deviceModel != null) {
-        await setTxPower(_deviceModel!.txPower);
-        autoPowerConfigured = true;
-        debugLog('[CONN] Auto-configured power: ${_deviceModel!.power}W (${_deviceModel!.txPower}dBm) for ${_deviceModel!.shortName}');
+        deviceModelMatched = true;
+        debugLog('[CONN] Device identified: ${_deviceModel!.shortName} (reports ${_deviceModel!.power}W / ${_deviceModel!.txPower}dBm)');
+      } else {
+        debugLog('[CONN] Device model not recognized - user must manually select power level for reporting');
       }
 
       // Step 5: Time Sync
@@ -253,7 +256,7 @@ class MeshCoreConnection {
       // This may fail on older firmware (< v1.11.0)
       _startNoiseFloorPolling();
 
-      return (deviceModel: _deviceModel, autoPowerConfigured: autoPowerConfigured);
+      return (deviceModel: _deviceModel, deviceModelMatched: deviceModelMatched);
     } catch (e) {
       debugError('[CONN] Connection failed: $e');
       _updateStep(ConnectionStep.error);