Enhance GPS failure handling and status messages in wardrive.js and STATUS_MESSAGES.md

Author: MrAlders0n

content/wardrive.js

@@ -545,6 +545,7 @@ const state = {
   lastFix: null, // { lat, lon, accM, tsMs }
   bluefyLockEnabled: false,
   gpsState: "idle", // "idle", "acquiring", "acquired", "error"
+  lastGpsFailureReason: null, // "inaccurate", "stale", "error", or null
   gpsAgeUpdateTimer: null, // Timer for updating GPS age display
   meshMapperTimer: null, // Timer for delayed MeshMapper API call
   cooldownEndTime: null, // Timestamp when cooldown period ends
@@ -2316,6 +2317,7 @@ async function getValidGpsForZoneCheck(maxRetries = 3, retryDelayMs = 5000) {
           await new Promise(resolve => setTimeout(resolve, retryDelayMs));
           continue;
         }
+        state.lastGpsFailureReason = "stale";
         return null;
       }
 
@@ -2327,10 +2329,12 @@ async function getValidGpsForZoneCheck(maxRetries = 3, retryDelayMs = 5000) {
           await new Promise(resolve => setTimeout(resolve, retryDelayMs));
           continue;
         }
+        state.lastGpsFailureReason = "inaccurate";
         return null;
       }
 
       debugLog(`[GPS] [GEO AUTH] Valid GPS acquired: lat=${lat.toFixed(6)}, lon=${lng.toFixed(6)}, accuracy=${accuracy_m.toFixed(1)}m, age=${ageMs}ms`);
+      state.lastGpsFailureReason = null; // Clear any previous failure reason on success
       return { lat, lon: lng, accuracy_m, timestamp };
 
     } catch (error) {
@@ -2343,6 +2347,10 @@ async function getValidGpsForZoneCheck(maxRetries = 3, retryDelayMs = 5000) {
   }
 
   debugError(`[GPS] [GEO AUTH] GPS acquisition failed after ${maxRetries} attempts`);
+  // If no specific reason was set, mark as general error
+  if (!state.lastGpsFailureReason) {
+    state.lastGpsFailureReason = "error";
+  }
   return null;
 }
 
@@ -6406,8 +6414,17 @@ function updateConnectButtonState() {
       debugLog("[UI] External antenna not selected - showing message in status bar");
       setDynamicStatus("Select external antenna to connect", STATUS_COLORS.warning);
     } else if (!inValidZone) {
-      debugLog("[UI] Not in valid zone - showing waiting for location status");
-      setDynamicStatus("Waiting for location...", STATUS_COLORS.info);
+      // Show more informative message based on GPS failure reason
+      let gpsStatusMsg = "Waiting for location...";
+      if (state.lastGpsFailureReason === "inaccurate") {
+        gpsStatusMsg = "GPS too inaccurate (max 50m)";
+      } else if (state.lastGpsFailureReason === "stale") {
+        gpsStatusMsg = "GPS too stale, acquiring...";
+      } else if (state.lastGpsFailureReason === "error") {
+        gpsStatusMsg = "GPS unavailable";
+      }
+      debugLog(`[UI] Not in valid zone - showing status: ${gpsStatusMsg}`);
+      setDynamicStatus(gpsStatusMsg, STATUS_COLORS.info);
     } else {
       debugLog("[UI] External antenna selected and in valid zone - ready to connect");
       // Only set Idle if not showing a disconnect error

docs/STATUS_MESSAGES.md

@@ -574,11 +574,35 @@ These messages use a hybrid approach: **first display respects 500ms minimum**,
 ##### Waiting for location...
 - **Message**: `"Waiting for location..."`
 - **Color**: Blue (info)
-- **When**: External antenna is selected but zone check is still in progress (location display shows "Checking...")
+- **When**: External antenna is selected but zone check is still in progress with no specific GPS failure
 - **Terminal State**: Yes (persists until zone check completes)
 - **Notes**: Displayed in Dynamic Status Bar to inform user that the app is waiting for GPS location and zone validation before allowing connection. Once zone check passes, status changes to "Idle" and Connect button becomes enabled.
 - **Source**: `content/wardrive.js:updateConnectButtonState()`
 
+##### GPS too inaccurate (max 50m)
+- **Message**: `"GPS too inaccurate (max 50m)"`
+- **Color**: Blue (info)
+- **When**: External antenna is selected but GPS accuracy exceeds 50m threshold after all retries
+- **Terminal State**: Yes (persists until GPS improves or zone check passes)
+- **Notes**: More specific message explaining why zone check failed. User should move to area with better GPS reception (outdoors, away from buildings). 30s slot refresh timer will auto-retry zone check.
+- **Source**: `content/wardrive.js:updateConnectButtonState()`
+
+##### GPS too stale, acquiring...
+- **Message**: `"GPS too stale, acquiring..."`
+- **Color**: Blue (info)
+- **When**: External antenna is selected but GPS data is older than 60 seconds after all retries
+- **Terminal State**: Yes (persists until fresh GPS is acquired or zone check passes)
+- **Notes**: More specific message explaining why zone check failed. User should wait for fresh GPS fix. 30s slot refresh timer will auto-retry zone check.
+- **Source**: `content/wardrive.js:updateConnectButtonState()`
+
+##### GPS unavailable
+- **Message**: `"GPS unavailable"`
+- **Color**: Blue (info)
+- **When**: External antenna is selected but GPS acquisition failed due to error (permissions, hardware, etc.)
+- **Terminal State**: Yes (persists until GPS becomes available or zone check passes)
+- **Notes**: Generic GPS error message when acquisition fails completely. User should check GPS permissions and hardware.
+- **Source**: `content/wardrive.js:updateConnectButtonState()`
+
 ##### Select radio power to connect
 - **Message**: `"Select radio power to connect"`
 - **Color**: Amber (warning)