Docs/consolidate documentation (#217)

* docs: rename FONT_MANAGER_USAGE.md to FONT_MANAGER.md Renamed for clearer naming convention. Part of documentation consolidation effort. * docs: consolidate Plugin Store guides (2→1) Merged: - PLUGIN_STORE_USER_GUIDE.md - PLUGIN_STORE_QUICK_REFERENCE.md Into: PLUGIN_STORE_GUIDE.md - Unified writing style to professional technical - Added Quick Reference section at top for easy access - Removed duplicate content - Added cross-references to related documentation - Updated formatting to match style guidelines * docs: create user-focused Web Interface Guide Created WEB_INTERFACE_GUIDE.md consolidating: - V3_INTERFACE_README.md (technical details) - User-facing interface documentation - Focused on end-user tasks and navigation - Removed technical implementation details - Added common tasks section - Included troubleshooting - Professional technical writing style * docs: consolidate WiFi setup guides (4→1) Merged: - WIFI_SETUP.md - OPTIMAL_WIFI_AP_FAILOVER_SETUP.md - AP_MODE_MANUAL_ENABLE.md - WIFI_ETHERNET_AP_MODE_FIX.md (behavior documentation) Into: WIFI_NETWORK_SETUP.md - Comprehensive coverage of WiFi setup and configuration - Clear explanation of AP mode failover and grace period - Configuration scenarios and best practices - Troubleshooting section combining all sources - Professional technical writing style - Added quick reference table for behavior * docs: consolidate troubleshooting guides (4→1) Merged: - TROUBLESHOOTING_QUICK_START.md - WEB_INTERFACE_TROUBLESHOOTING.md - CAPTIVE_PORTAL_TROUBLESHOOTING.md - WEATHER_TROUBLESHOOTING.md Into: TROUBLESHOOTING.md - Organized by issue category (web, WiFi, plugins) - Comprehensive diagnostic commands reference - Quick diagnosis steps at the top - Service file template preserved - Complete diagnostic script included - Professional technical writing style * docs: create consolidated Advanced Features guide Merged: - VEGAS_SCROLL_MODE.md - ON_DEMAND_DISPLAY_QUICK_START.md - ON_DEMAND_DISPLAY_API.md - ON_DEMAND_CACHE_MANAGEMENT.md - BACKGROUND_SERVICE_README.md - PERMISSION_MANAGEMENT_GUIDE.md Into: ADVANCED_FEATURES.md - Comprehensive guide covering all advanced features - Vegas scroll mode with integration examples - On-demand display with API reference - Cache management troubleshooting - Background service documentation - Permission management patterns - Professional technical writing style * docs: create Getting Started guide for first-time users Created GETTING_STARTED.md: - Quick start guide (5 minutes) - Initial configuration walkthrough - Common first-time issues and solutions - Next steps and quick reference - User-friendly tone for beginners - Links to detailed documentation * docs: archive consolidated source files and ephemeral docs Archived files that have been consolidated: - Plugin Store guides (2 files → PLUGIN_STORE_GUIDE.md) - Web Interface guide (V3_INTERFACE_README.md → WEB_INTERFACE_GUIDE.md) - WiFi Setup guides (4 files → WIFI_NETWORK_SETUP.md) - Troubleshooting guides (4 files → TROUBLESHOOTING.md) - Advanced Features (6 files → ADVANCED_FEATURES.md) Archived ephemeral/debug documentation: - DEBUG_WEB_ISSUE.md - BROWSER_ERRORS_EXPLANATION.md - FORM_VALIDATION_FIXES.md - WEB_UI_RELIABILITY_IMPROVEMENTS.md - CAPTIVE_PORTAL_TESTING.md - NEXT_STEPS_COMMANDS.md - STATIC_IMAGE_MULTI_UPLOAD_PLAN.md - RECONNECT_AFTER_CAPTIVE_PORTAL_TESTING.md Archived implementation summaries: - PLUGIN_CONFIG_TABS_SUMMARY.md - PLUGIN_CONFIG_SYSTEM_VERIFICATION.md - PLUGIN_SCHEMA_AUDIT_SUMMARY.md - STARTUP_OPTIMIZATION_SUMMARY.md - PLUGIN_DISPATCH_IMPLEMENTATION.md - NESTED_SCHEMA_IMPLEMENTATION.md - AP_MODE_MANUAL_ENABLE_CHANGES.md - PLUGIN_CONFIG_SYSTEM_EXPLANATION.md Total archived: 27 files Preserves git history while cleaning up main docs directory * docs: rename API_REFERENCE.md to REST_API_REFERENCE.md Renamed for clarity - this is specifically the REST API reference for the web interface, not a general API reference. * docs: update README.md to reflect consolidated documentation structure Updated documentation index: - Reflects new consolidated guides (51 → 16-17 files) - Updated Quick Start sections with new file names - Added consolidation history (January 2026) - Updated file references (API_REFERENCE → REST_API_REFERENCE) - Documented archival of 33 files - Added benefits of consolidation - Updated statistics and highlights - Removed outdated references - Professional writing style maintained throughout * docs: add Vegas scroll mode system architecture documentation Added comprehensive internal architecture section for Vegas mode: - Component overview with diagram - VegasModeCoordinator responsibilities and main loop - StreamManager buffering strategy and content flow - PluginAdapter integration and fallback behavior - RenderPipeline 125 FPS rendering process - Component interaction flows - Thread safety patterns - Performance characteristics Covers: - How the four components work together - Initialization and render loop flows - Config update handling - Frame rate management and optimization - Memory usage and CPU characteristics --------- Co-authored-by: Chuck <chuck@example.com>
2026-04-15 06:43:00 +00:00 · 2026-01-29 10:32:00 -05:00
parent 7524747e44
commit ddd300a117
42 changed files with 3954 additions and 95 deletions
--- a/docs/archive/WEATHER_TROUBLESHOOTING.md
+++ b/docs/archive/WEATHER_TROUBLESHOOTING.md
@@ -0,0 +1,298 @@
+# Weather Plugin Troubleshooting Guide
+
+## Quick Diagnosis
+
+Run the troubleshooting script on your Pi:
+
+```bash
+./troubleshoot_weather.sh
+```
+
+This will check:
+- Plugin installation
+- Configuration files
+- API key setup
+- Network connectivity
+- Cache status
+
+## Common Issues
+
+### 1. "No Weather Data" Message
+
+This appears when the weather plugin cannot fetch or access weather data.
+
+### 2. Missing or Invalid API Key
+
+**Symptoms:**
+- Plugin shows "No Weather Data"
+- Logs show "No valid OpenWeatherMap API key configured"
+- Plugin initialized but no data updates
+
+**Solution:**
+
+1. Get an API key from [OpenWeatherMap](https://openweathermap.org/api)
+   - Sign up for a free account
+   - Navigate to API Keys section
+   - Generate a new API key
+
+2. Add API key to `config/config_secrets.json` (recommended):
+   ```json
+   {
+     "ledmatrix-weather": {
+       "api_key": "your_actual_api_key_here"
+     }
+   }
+   ```
+
+   OR add directly to `config/config.json`:
+   ```json
+   {
+     "ledmatrix-weather": {
+       "enabled": true,
+       "api_key": "your_actual_api_key_here",
+       "location_city": "Dallas",
+       "location_state": "Texas",
+       "location_country": "US"
+     }
+   }
+   ```
+
+3. Restart the LEDMatrix service:
+   ```bash
+   sudo systemctl restart ledmatrix
+   ```
+
+### 3. Plugin Not Enabled
+
+**Symptoms:**
+- Plugin doesn't appear in display rotation
+- No weather data displayed
+
+**Solution:**
+
+Check `config/config.json` and ensure the plugin is enabled:
+
+```json
+{
+  "ledmatrix-weather": {
+    "enabled": true,
+    "display_duration": 30,
+    ...
+  }
+}
+```
+
+### 4. Network/API Connectivity Issues
+
+**Symptoms:**
+- Plugin shows "No Weather Data"
+- Logs show connection errors or timeouts
+
+**Solution:**
+
+1. Check internet connectivity:
+   ```bash
+   ping -c 4 api.openweathermap.org
+   ```
+
+2. Check firewall settings (if applicable)
+
+3. Verify DNS resolution:
+   ```bash
+   nslookup api.openweathermap.org
+   ```
+
+4. Test API directly:
+   ```bash
+   curl "https://api.openweathermap.org/data/2.5/weather?q=Dallas,TX,US&appid=YOUR_API_KEY&units=imperial"
+   ```
+
+### 5. API Rate Limits Exceeded
+
+**Symptoms:**
+- Plugin worked before but now shows "No Weather Data"
+- Logs show HTTP 429 errors
+
+**Solution:**
+
+OpenWeatherMap free tier limits:
+- 1,000 API calls per day
+- 60 calls per minute
+
+Default plugin settings use ~48 calls/day (1800s = 30 min intervals).
+
+If exceeded:
+- Wait for quota reset (daily)
+- Increase `update_interval` in config (minimum 300s = 5 minutes)
+- Upgrade OpenWeatherMap plan
+
+### 6. Invalid Location Configuration
+
+**Symptoms:**
+- Plugin shows "No Weather Data"
+- Logs show geocoding errors
+
+**Solution:**
+
+Ensure location is correctly configured in `config/config.json`:
+
+```json
+{
+  "ledmatrix-weather": {
+    "location_city": "Dallas",
+    "location_state": "Texas",
+    "location_country": "US"
+  }
+}
+```
+
+- Use proper city names
+- Include state for US cities to avoid ambiguity
+- Use ISO 3166-1 alpha-2 country codes (US, GB, CA, etc.)
+
+### 7. Stale Cache Data
+
+**Symptoms:**
+- Weather data not updating
+- Old data displayed
+
+**Solution:**
+
+Clear the cache:
+
+```bash
+# Find cache files
+find cache/ -name "*weather*" -type f
+
+# Remove cache files (plugin will fetch fresh data)
+rm cache/*weather*
+```
+
+### 8. Plugin Not Loading
+
+**Symptoms:**
+- Weather modes don't appear in available modes
+- Logs show plugin loading errors
+
+**Solution:**
+
+1. Check plugin directory exists:
+   ```bash
+   ls -la plugins/ledmatrix-weather/
+   ```
+
+2. Verify manifest.json is valid:
+   ```bash
+   python3 -m json.tool plugins/ledmatrix-weather/manifest.json
+   ```
+
+3. Check logs for specific errors:
+   ```bash
+   sudo journalctl -u ledmatrix -f | grep -i weather
+   ```
+
+4. Verify plugin dependencies are installed:
+   ```bash
+   pip3 install -r plugins/ledmatrix-weather/requirements.txt
+   ```
+
+## Checking Logs
+
+View real-time logs:
+
+```bash
+sudo journalctl -u ledmatrix -f
+```
+
+Filter for weather-related messages:
+
+```bash
+sudo journalctl -u ledmatrix -f | grep -i weather
+```
+
+View last 100 lines:
+
+```bash
+sudo journalctl -u ledmatrix -n 100 | grep -i weather
+```
+
+## Configuration Example
+
+Complete configuration in `config/config.json`:
+
+```json
+{
+  "ledmatrix-weather": {
+    "enabled": true,
+    "display_duration": 30,
+    "location_city": "Dallas",
+    "location_state": "Texas",
+    "location_country": "US",
+    "units": "imperial",
+    "update_interval": 1800,
+    "show_current_weather": true,
+    "show_hourly_forecast": true,
+    "show_daily_forecast": true,
+    "transition": {
+      "type": "redraw",
+      "speed": 2,
+      "enabled": true
+    }
+  }
+}
+```
+
+And in `config/config_secrets.json`:
+
+```json
+{
+  "ledmatrix-weather": {
+    "api_key": "your_openweathermap_api_key_here"
+  }
+}
+```
+
+## Plugin Configuration Schema
+
+The plugin expects configuration under either:
+- `ledmatrix-weather` (plugin ID from manifest)
+- `weather` (legacy/deprecated)
+
+The system checks both when loading configuration.
+
+## Testing the Plugin
+
+1. Enable the plugin in config
+2. Restart the service: `sudo systemctl restart ledmatrix`
+3. Check logs: `sudo journalctl -u ledmatrix -f`
+4. Wait for update interval (default 30 minutes) or force update
+5. Check if weather modes appear in display rotation
+
+## Still Having Issues?
+
+1. Run the troubleshooting script: `./troubleshoot_weather.sh`
+2. Check service status: `sudo systemctl status ledmatrix`
+3. Review logs for specific error messages
+4. Verify all configuration files are valid JSON
+5. Ensure file permissions are correct:
+   ```bash
+   ls -la config/config.json config/config_secrets.json
+   ```
+
+## API Key Security
+
+**Recommended:** Store API key in `config/config_secrets.json` with restricted permissions:
+
+```bash
+chmod 640 config/config_secrets.json
+```
+
+This file is not tracked by git (should be in .gitignore).
+
+## Plugin ID Note
+
+The weather plugin ID is `ledmatrix-weather` (from manifest.json). Configuration should use this ID, though the system also checks for `weather` for backward compatibility.
+
+
+
+