Add comprehensive error handling and documentation for xtide module

Co-authored-by: SpudGunMan <12676665+SpudGunMan@users.noreply.github.com>

modules/xtide.md

@@ -0,0 +1,108 @@
+# xtide Module - Global Tide Predictions
+
+This module provides global tide prediction capabilities using the [tidepredict](https://github.com/windcrusader/tidepredict) library, which uses the University of Hawaii's Research Quality Dataset for worldwide tide station coverage.
+
+## Features
+
+- Global tide predictions (not limited to US locations like NOAA)
+- Offline predictions once station data is initialized
+- Automatic selection of nearest tide station
+- Compatible with existing tide command interface
+
+## Installation
+
+1. Install tidepredict library:
+```bash
+pip install tidepredict
+```
+
+2. Enable in `config.ini`:
+```ini
+[location]
+useTidePredict = True
+```
+
+## First-Time Setup
+
+On first use, tidepredict needs to download station data from the University of Hawaii FTP server. This requires internet access and happens automatically when you:
+
+1. Run the tide command for the first time with `useTidePredict = True`
+2. Or manually initialize with:
+```bash
+python3 -m tidepredict -l <location> -genharm
+```
+
+The station data is cached locally in `~/.tidepredict/` for offline use afterward.
+
+## Usage
+
+Once enabled, the existing `tide` command will automatically use tidepredict for global locations:
+
+```
+tide
+```
+
+The module will:
+1. Find the nearest tide station to your GPS coordinates
+2. Load harmonic constituents for that station
+3. Calculate tide predictions for today
+4. Format output compatible with mesh display
+
+## Configuration
+
+### config.ini Options
+
+```ini
+[location]
+# Enable global tide predictions using tidepredict
+useTidePredict = True
+
+# Standard location settings still apply
+lat = 48.50
+lon = -123.0
+useMetric = False
+```
+
+## Fallback Behavior
+
+If tidepredict is not available or encounters errors, the module will automatically fall back to the NOAA API for US locations.
+
+## Limitations
+
+- First-time setup requires internet access to download station database
+- Station coverage depends on University of Hawaii's dataset
+- Predictions may be less accurate for locations far from tide stations
+
+## Troubleshooting
+
+### "Station database not initialized" error
+
+This means the station data hasn't been downloaded yet. Ensure internet access and:
+
+```bash
+# Test station download
+python3 -m tidepredict -l Sydney
+
+# Or manually run initialization
+python3 -c "from tidepredict import process_station_list; process_station_list.create_station_dataframe()"
+```
+
+### "No tide station found nearby"
+
+The module couldn't find a nearby station. This may happen if:
+- You're in a location without nearby tide monitoring stations
+- The station database hasn't been initialized
+- Network issues prevented loading the station list
+
+## Data Source
+
+Tide predictions are based on harmonic analysis of historical tide data from:
+- University of Hawaii Sea Level Center (UHSLC)
+- Research Quality Dataset
+- Global coverage with 600+ stations
+
+## References
+
+- [tidepredict GitHub](https://github.com/windcrusader/tidepredict)
+- [UHSLC Data](https://uhslc.soest.hawaii.edu/)
+- [pytides](https://github.com/sam-cox/pytides) - Underlying tide calculation library

modules/xtide.py

@@ -27,10 +27,14 @@ def get_nearest_station(lat, lon):
         # Read the station list
         try:
             stations = pd.read_csv(constants.STATIONFILE)
-        except:
-            # If station file doesn't exist, create it
-            logger.info("xtide: Creating station database from online source")
-            stations = process_station_list.create_station_dataframe()
+        except FileNotFoundError:
+            # If station file doesn't exist, create it (requires network)
+            logger.info("xtide: Creating station database from online source (requires network)")
+            try:
+                stations = process_station_list.create_station_dataframe()
+            except Exception as net_error:
+                logger.error(f"xtide: Failed to download station database: {net_error}")
+                return None
         
         if stations.empty:
             logger.error("xtide: No stations found in database")
@@ -119,7 +123,7 @@ def get_tide_predictions(lat=0, lon=0, days=1):
         # Find nearest station
         station_info = get_nearest_station(float(lat), float(lon))
         if not station_info:
-            return "No tide station found nearby"
+            return "No tide station found nearby. Network may be required to download station data."
         
         station_code, station_name, station_country = station_info
         
@@ -128,8 +132,8 @@ def get_tide_predictions(lat=0, lon=0, days=1):
         
         # Check if harmonic data exists for this station
         if station_code not in station_dict:
-            logger.warning(f"xtide: No harmonic data for {station_name}. Generating from online data...")
-            return f"Tide data not available for {station_name}. Use 'tide ?' for more info."
+            logger.warning(f"xtide: No harmonic data for {station_name}.")
+            return f"Tide data not available for {station_name}. Station database may need initialization."
         
         # Reconstruct tide model
         tide = processdata.reconstruct_tide_model(station_dict, station_code)
@@ -186,6 +190,9 @@ def get_tide_predictions(lat=0, lon=0, days=1):
         else:
             return predictions
     
+    except FileNotFoundError as e:
+        logger.error(f"xtide: Station data file not found: {e}")
+        return "Tide station database not initialized. Network access required for first-time setup."
     except Exception as e:
         logger.error(f"xtide: Error getting tide predictions: {e}")
         return f"Error getting tide data: {str(e)}"