milb debugging

wiki/WIKI_ARCHITECTURE.md

@@ -0,0 +1,587 @@
+# System Architecture
+
+The LEDMatrix system is built with a modular, extensible architecture that separates concerns and allows for easy maintenance and extension. This guide explains how all components work together.
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    LEDMatrix System                        │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
+│  │   Display   │  │   Display   │  │   Display   │      │
+│  │ Controller  │  │  Manager    │  │  Managers   │      │
+│  │             │  │             │  │             │      │
+│  │ • Main Loop │  │ • Hardware  │  │ • Weather   │      │
+│  │ • Rotation  │  │ • Rendering │  │ • Stocks    │      │
+│  │ • Scheduling│  │ • Fonts     │  │ • Sports    │      │
+│  │ • Live Mode │  │ • Graphics  │  │ • Music     │      │
+│  └─────────────┘  └─────────────┘  └─────────────┘      │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
+│  │   Config    │  │   Cache     │  │   Web       │      │
+│  │  Manager    │  │  Manager    │  │ Interface   │      │
+│  │             │  │             │  │             │      │
+│  │ • Settings  │  │ • Data      │  │ • Control   │      │
+│  │ • Validation│  │ • Persistence│  │ • Status    │      │
+│  │ • Loading   │  │ • Fallbacks │  │ • Settings  │      │
+│  └─────────────┘  └─────────────┘  └─────────────┘      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### 1. Display Controller (`src/display_controller.py`)
+
+**Purpose**: Main orchestrator that manages the entire display system.
+
+**Responsibilities**:
+- Initialize all display managers
+- Control display rotation and timing
+- Handle live game priority
+- Manage system scheduling
+- Coordinate data updates
+- Handle error recovery
+
+**Key Methods**:
+```python
+class DisplayController:
+    def __init__(self):
+        # Initialize all managers and configuration
+        
+    def run(self):
+        # Main display loop
+        
+    def _update_modules(self):
+        # Update all enabled modules
+        
+    def _check_live_games(self):
+        # Check for live games and prioritize
+        
+    def _rotate_team_games(self, sport):
+        # Rotate through team games
+```
+
+**Data Flow**:
+1. Load configuration
+2. Initialize display managers
+3. Start main loop
+4. Check for live games
+5. Rotate through enabled displays
+6. Handle scheduling and timing
+
+### 2. Display Manager (`src/display_manager.py`)
+
+**Purpose**: Low-level hardware interface and graphics rendering.
+
+**Responsibilities**:
+- Initialize RGB LED matrix hardware
+- Handle font loading and management
+- Provide drawing primitives
+- Manage display buffers
+- Handle hardware configuration
+- Provide text rendering utilities
+
+**Key Features**:
+```python
+class DisplayManager:
+    def __init__(self, config):
+        # Initialize hardware and fonts
+        
+    def draw_text(self, text, x, y, color, font):
+        # Draw text on display
+        
+    def update_display(self):
+        # Update physical display
+        
+    def clear(self):
+        # Clear display
+        
+    def draw_weather_icon(self, condition, x, y, size):
+        # Draw weather icons
+```
+
+**Hardware Interface**:
+- RGB Matrix library integration
+- GPIO pin management
+- PWM timing control
+- Double buffering for smooth updates
+- Font rendering (TTF and BDF)
+
+### 3. Configuration Manager (`src/config_manager.py`)
+
+**Purpose**: Load, validate, and manage system configuration.
+
+**Responsibilities**:
+- Load JSON configuration files
+- Validate configuration syntax
+- Provide default values
+- Handle configuration updates
+- Manage secrets and API keys
+
+**Configuration Sources**:
+```python
+class ConfigManager:
+    def load_config(self):
+        # Load main config.json
+        
+    def load_secrets(self):
+        # Load config_secrets.json
+        
+    def validate_config(self):
+        # Validate configuration
+        
+    def get_defaults(self):
+        # Provide default values
+```
+
+**Configuration Structure**:
+- Main settings in `config/config.json`
+- API keys in `config/config_secrets.json`
+- Validation and error handling
+- Default value fallbacks
+
+### 4. Cache Manager (`src/cache_manager.py`)
+
+**Purpose**: Intelligent data caching to reduce API calls and improve performance.
+
+**Responsibilities**:
+- Store API responses
+- Manage cache expiration
+- Handle cache persistence
+- Provide fallback data
+- Optimize storage usage
+
+**Cache Strategy**:
+```python
+class CacheManager:
+    def get(self, key):
+        # Retrieve cached data
+        
+    def set(self, key, data, ttl):
+        # Store data with expiration
+        
+    def is_valid(self, key):
+        # Check if cache is still valid
+        
+    def clear_expired(self):
+        # Remove expired cache entries
+```
+
+**Cache Locations** (in order of preference):
+1. `~/.ledmatrix_cache/` (user's home directory)
+2. `/var/cache/ledmatrix/` (system cache directory)
+3. `/tmp/ledmatrix_cache/` (temporary directory)
+
+## Display Manager Architecture
+
+### Manager Interface
+
+All display managers follow a consistent interface:
+
+```python
+class BaseManager:
+    def __init__(self, config, display_manager):
+        self.config = config
+        self.display_manager = display_manager
+        self.cache_manager = CacheManager()
+        
+    def update_data(self):
+        """Fetch and process new data"""
+        pass
+        
+    def display(self, force_clear=False):
+        """Render content to display"""
+        pass
+        
+    def is_enabled(self):
+        """Check if manager is enabled"""
+        return self.config.get('enabled', False)
+        
+    def get_duration(self):
+        """Get display duration"""
+        return self.config.get('duration', 30)
+```
+
+### Data Flow Pattern
+
+Each manager follows this pattern:
+
+1. **Initialization**: Load configuration and setup
+2. **Data Fetching**: Retrieve data from APIs or local sources
+3. **Caching**: Store data using CacheManager
+4. **Processing**: Transform raw data into display format
+5. **Rendering**: Use DisplayManager to show content
+6. **Cleanup**: Return control to main controller
+
+### Error Handling
+
+- **API Failures**: Fall back to cached data
+- **Network Issues**: Use last known good data
+- **Invalid Data**: Filter out bad entries
+- **Hardware Errors**: Graceful degradation
+- **Configuration Errors**: Use safe defaults
+
+## Sports Manager Architecture
+
+### Sports Manager Pattern
+
+Each sport follows a three-manager pattern:
+
+```python
+# Live games (currently playing)
+class NHLLiveManager(BaseSportsManager):
+    def fetch_games(self):
+        # Get currently playing games
+        
+    def display_games(self):
+        # Show live scores and status
+
+# Recent games (completed)
+class NHLRecentManager(BaseSportsManager):
+    def fetch_games(self):
+        # Get recently completed games
+        
+    def display_games(self):
+        # Show final scores
+
+# Upcoming games (scheduled)
+class NHLUpcomingManager(BaseSportsManager):
+    def fetch_games(self):
+        # Get scheduled games
+        
+    def display_games(self):
+        # Show game times and matchups
+```
+
+### Base Sports Manager
+
+Common functionality shared by all sports:
+
+```python
+class BaseSportsManager:
+    def __init__(self, config, display_manager):
+        # Common initialization
+        
+    def fetch_espn_data(self, sport, endpoint):
+        # Fetch from ESPN API
+        
+    def process_game_data(self, games):
+        # Process raw game data
+        
+    def display_game(self, game):
+        # Display individual game
+        
+    def get_team_logo(self, team_abbr):
+        # Load team logo
+        
+    def format_score(self, score):
+        # Format score display
+```
+
+### ESPN API Integration
+
+All sports use ESPN's API for data:
+
+```python
+def fetch_espn_data(self, sport, endpoint):
+    url = f"http://site.api.espn.com/apis/site/v2/sports/{sport}/{endpoint}"
+    response = requests.get(url)
+    return response.json()
+```
+
+**Supported Sports**:
+- NHL (hockey)
+- NBA (basketball)
+- MLB (baseball)
+- NFL (football)
+- NCAA Football
+- NCAA Basketball
+- NCAA Baseball
+- Soccer (multiple leagues)
+- MiLB (minor league baseball)
+
+## Financial Data Architecture
+
+### Stock Manager
+
+```python
+class StockManager:
+    def __init__(self, config, display_manager):
+        # Initialize stock and crypto settings
+        
+    def fetch_stock_data(self, symbol):
+        # Fetch from Yahoo Finance
+        
+    def fetch_crypto_data(self, symbol):
+        # Fetch crypto data
+        
+    def display_stocks(self):
+        # Show stock ticker
+        
+    def display_crypto(self):
+        # Show crypto prices
+```
+
+### Stock News Manager
+
+```python
+class StockNewsManager:
+    def __init__(self, config, display_manager):
+        # Initialize news settings
+        
+    def fetch_news(self, symbols):
+        # Fetch financial news
+        
+    def display_news(self):
+        # Show news headlines
+```
+
+## Weather Architecture
+
+### Weather Manager
+
+```python
+class WeatherManager:
+    def __init__(self, config, display_manager):
+        # Initialize weather settings
+        
+    def fetch_weather(self):
+        # Fetch from OpenWeatherMap
+        
+    def display_current_weather(self):
+        # Show current conditions
+        
+    def display_hourly_forecast(self):
+        # Show hourly forecast
+        
+    def display_daily_forecast(self):
+        # Show daily forecast
+```
+
+### Weather Icons
+
+```python
+class WeatherIcons:
+    def __init__(self):
+        # Load weather icon definitions
+        
+    def get_icon(self, condition):
+        # Get icon for weather condition
+        
+    def draw_icon(self, condition, x, y, size):
+        # Draw weather icon
+```
+
+## Music Architecture
+
+### Music Manager
+
+```python
+class MusicManager:
+    def __init__(self, display_manager, config):
+        # Initialize music settings
+        
+    def start_polling(self):
+        # Start background polling
+        
+    def update_music_display(self):
+        # Update music information
+        
+    def display_spotify(self):
+        # Display Spotify info
+        
+    def display_ytm(self):
+        # Display YouTube Music info
+```
+
+### Spotify Client
+
+```python
+class SpotifyClient:
+    def __init__(self, config):
+        # Initialize Spotify API
+        
+    def authenticate(self):
+        # Handle OAuth authentication
+        
+    def get_current_track(self):
+        # Get currently playing track
+```
+
+### YouTube Music Client
+
+```python
+class YTMClient:
+    def __init__(self, config):
+        # Initialize YTM companion server
+        
+    def get_current_track(self):
+        # Get current track from YTMD
+```
+
+## Web Interface Architecture
+
+### Web Interface
+
+```python
+class WebInterface:
+    def __init__(self, config):
+        # Initialize Flask app
+        
+    def start_server(self):
+        # Start web server
+        
+    def get_status(self):
+        # Get system status
+        
+    def control_display(self, action):
+        # Control display actions
+```
+
+**Features**:
+- System status monitoring
+- Display control (start/stop)
+- Configuration management
+- Service management
+- Real-time status updates
+
+## Service Architecture
+
+### Systemd Service
+
+```ini
+[Unit]
+Description=LEDMatrix Display Service
+After=network.target
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/home/ledpi/LEDMatrix
+ExecStart=/usr/bin/python3 display_controller.py
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**Service Features**:
+- Automatic startup
+- Crash recovery
+- Log management
+- Resource monitoring
+
+## Data Flow Architecture
+
+### 1. Configuration Loading
+
+```
+config.json → ConfigManager → DisplayController → Display Managers
+```
+
+### 2. Data Fetching
+
+```
+API Sources → CacheManager → Display Managers → Display Manager
+```
+
+### 3. Display Rendering
+
+```
+Display Managers → Display Manager → RGB Matrix → LED Display
+```
+
+### 4. User Control
+
+```
+Web Interface → Display Controller → Display Managers
+```
+
+## Performance Architecture
+
+### Caching Strategy
+
+1. **API Response Caching**: Store API responses with TTL
+2. **Processed Data Caching**: Cache processed display data
+3. **Font Caching**: Cache loaded fonts
+4. **Image Caching**: Cache team logos and icons
+
+### Resource Management
+
+1. **Memory Usage**: Monitor and optimize memory usage
+2. **CPU Usage**: Minimize processing overhead
+3. **Network Usage**: Optimize API calls
+4. **Storage Usage**: Manage cache storage
+
+### Error Recovery
+
+1. **API Failures**: Use cached data
+2. **Network Issues**: Retry with exponential backoff
+3. **Hardware Errors**: Graceful degradation
+4. **Configuration Errors**: Use safe defaults
+
+## Extension Architecture
+
+### Adding New Display Managers
+
+1. **Create Manager Class**: Extend base manager pattern
+2. **Add Configuration**: Add to config.json
+3. **Register in Controller**: Add to DisplayController
+4. **Add Assets**: Include logos, icons, fonts
+5. **Test Integration**: Verify with main system
+
+### Example New Manager
+
+```python
+class CustomManager(BaseManager):
+    def __init__(self, config, display_manager):
+        super().__init__(config, display_manager)
+        
+    def update_data(self):
+        # Fetch custom data
+        
+    def display(self, force_clear=False):
+        # Display custom content
+```
+
+## Security Architecture
+
+### API Key Management
+
+1. **Separate Secrets**: Store in config_secrets.json
+2. **Environment Variables**: Support for env vars
+3. **Access Control**: Restrict file permissions
+4. **Key Rotation**: Support for key updates
+
+### Network Security
+
+1. **HTTPS Only**: Use secure API endpoints
+2. **Rate Limiting**: Respect API limits
+3. **Error Handling**: Don't expose sensitive data
+4. **Logging**: Secure log management
+
+## Monitoring Architecture
+
+### Logging System
+
+```python
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s:%(name)s:%(message)s'
+)
+```
+
+### Health Monitoring
+
+1. **API Health**: Monitor API availability
+2. **Display Health**: Monitor display functionality
+3. **Cache Health**: Monitor cache performance
+4. **System Health**: Monitor system resources
+
+---
+
+*This architecture provides a solid foundation for the LEDMatrix system while maintaining flexibility for future enhancements and customizations.* 

wiki/WIKI_CONFIGURATION.md

@@ -0,0 +1,654 @@
+# Configuration Guide
+
+The LEDMatrix system is configured through JSON files that control every aspect of the display. This guide covers all configuration options and their effects.
+
+## Configuration Files
+
+### Main Configuration (`config/config.json`)
+Contains all non-sensitive settings for the system.
+
+### Secrets Configuration (`config/config_secrets.json`)
+Contains API keys and sensitive credentials.
+
+## System Configuration
+
+### Display Hardware Settings
+
+```json
+{
+  "display": {
+    "hardware": {
+      "rows": 32,
+      "cols": 64,
+      "chain_length": 2,
+      "parallel": 1,
+      "brightness": 95,
+      "hardware_mapping": "adafruit-hat-pwm",
+      "scan_mode": 0,
+      "pwm_bits": 9,
+      "pwm_dither_bits": 1,
+      "pwm_lsb_nanoseconds": 130,
+      "disable_hardware_pulsing": false,
+      "inverse_colors": false,
+      "show_refresh_rate": false,
+      "limit_refresh_rate_hz": 120
+    },
+    "runtime": {
+      "gpio_slowdown": 3
+    }
+  }
+}
+```
+
+**Hardware Settings Explained**:
+- **`rows`/`cols`**: Physical LED matrix dimensions (32x64 for 2 panels)
+- **`chain_length`**: Number of LED panels connected (2 for 128x32 total)
+- **`parallel`**: Number of parallel chains (usually 1)
+- **`brightness`**: Display brightness (0-100)
+- **`hardware_mapping`**: 
+  - `"adafruit-hat-pwm"`: With jumper mod (recommended)
+  - `"adafruit-hat"`: Without jumper mod
+- **`pwm_bits`**: Color depth (8-11, higher = better colors)
+- **`gpio_slowdown`**: Timing adjustment (3 for Pi 3, 4 for Pi 4)
+
+### Display Durations
+
+```json
+{
+  "display": {
+    "display_durations": {
+      "clock": 15,
+      "weather": 30,
+      "stocks": 30,
+      "hourly_forecast": 30,
+      "daily_forecast": 30,
+      "stock_news": 20,
+      "odds_ticker": 60,
+      "nhl_live": 30,
+      "nhl_recent": 30,
+      "nhl_upcoming": 30,
+      "nba_live": 30,
+      "nba_recent": 30,
+      "nba_upcoming": 30,
+      "nfl_live": 30,
+      "nfl_recent": 30,
+      "nfl_upcoming": 30,
+      "ncaa_fb_live": 30,
+      "ncaa_fb_recent": 30,
+      "ncaa_fb_upcoming": 30,
+      "ncaa_baseball_live": 30,
+      "ncaa_baseball_recent": 30,
+      "ncaa_baseball_upcoming": 30,
+      "calendar": 30,
+      "youtube": 30,
+      "mlb_live": 30,
+      "mlb_recent": 30,
+      "mlb_upcoming": 30,
+      "milb_live": 30,
+      "milb_recent": 30,
+      "milb_upcoming": 30,
+      "text_display": 10,
+      "soccer_live": 30,
+      "soccer_recent": 30,
+      "soccer_upcoming": 30,
+      "ncaam_basketball_live": 30,
+      "ncaam_basketball_recent": 30,
+      "ncaam_basketball_upcoming": 30,
+      "music": 30,
+      "of_the_day": 40
+    }
+  }
+}
+```
+
+**Duration Settings**:
+- Each value controls how long (in seconds) that display mode shows
+- Higher values = more time for that content
+- Total rotation time = sum of all enabled durations
+
+### System Settings
+
+```json
+{
+  "web_display_autostart": true,
+  "schedule": {
+    "enabled": true,
+    "start_time": "07:00",
+    "end_time": "23:00"
+  },
+  "timezone": "America/Chicago",
+  "location": {
+    "city": "Dallas",
+    "state": "Texas",
+    "country": "US"
+  }
+}
+```
+
+**System Settings Explained**:
+- **`web_display_autostart`**: Start web interface automatically
+- **`schedule`**: Control when display is active
+- **`timezone`**: System timezone for accurate times
+- **`location`**: Default location for weather and other location-based services
+
+## Display Manager Configurations
+
+### Clock Configuration
+
+```json
+{
+  "clock": {
+    "enabled": false,
+    "format": "%I:%M %p",
+    "update_interval": 1
+  }
+}
+```
+
+**Clock Settings**:
+- **`enabled`**: Enable/disable clock display
+- **`format`**: Time format string (Python strftime)
+- **`update_interval`**: Update frequency in seconds
+
+**Common Time Formats**:
+- `"%I:%M %p"` → `12:34 PM`
+- `"%H:%M"` → `14:34`
+- `"%I:%M:%S %p"` → `12:34:56 PM`
+
+### Weather Configuration
+
+```json
+{
+  "weather": {
+    "enabled": false,
+    "update_interval": 1800,
+    "units": "imperial",
+    "display_format": "{temp}°F\n{condition}"
+  }
+}
+```
+
+**Weather Settings**:
+- **`enabled`**: Enable/disable weather display
+- **`update_interval`**: Update frequency in seconds (1800 = 30 minutes)
+- **`units`**: `"imperial"` (Fahrenheit) or `"metric"` (Celsius)
+- **`display_format`**: Custom format string for weather display
+
+**Weather Display Modes**:
+- Current weather with icon
+- Hourly forecast (next 24 hours)
+- Daily forecast (next 7 days)
+
+### Stocks Configuration
+
+```json
+{
+  "stocks": {
+    "enabled": false,
+    "update_interval": 600,
+    "scroll_speed": 1,
+    "scroll_delay": 0.01,
+    "toggle_chart": false,
+    "symbols": ["ASTS", "SCHD", "INTC", "NVDA", "T", "VOO", "SMCI"]
+  },
+  "crypto": {
+    "enabled": false,
+    "update_interval": 600,
+    "symbols": ["BTC-USD", "ETH-USD"]
+  }
+}
+```
+
+**Stock Settings**:
+- **`enabled`**: Enable/disable stock display
+- **`update_interval`**: Update frequency in seconds (600 = 10 minutes)
+- **`scroll_speed`**: Pixels per scroll update
+- **`scroll_delay`**: Delay between scroll updates
+- **`toggle_chart`**: Show/hide mini price charts
+- **`symbols`**: Array of stock symbols to display
+
+**Crypto Settings**:
+- **`enabled`**: Enable/disable crypto display
+- **`symbols`**: Array of crypto symbols (use `-USD` suffix)
+
+### Stock News Configuration
+
+```json
+{
+  "stock_news": {
+    "enabled": false,
+    "update_interval": 3600,
+    "scroll_speed": 1,
+    "scroll_delay": 0.01,
+    "max_headlines_per_symbol": 1,
+    "headlines_per_rotation": 2
+  }
+}
+```
+
+**News Settings**:
+- **`enabled`**: Enable/disable news display
+- **`update_interval`**: Update frequency in seconds
+- **`max_headlines_per_symbol`**: Max headlines per stock
+- **`headlines_per_rotation`**: Headlines shown per rotation
+
+### Music Configuration
+
+```json
+{
+  "music": {
+    "enabled": true,
+    "preferred_source": "ytm",
+    "YTM_COMPANION_URL": "http://192.168.86.12:9863",
+    "POLLING_INTERVAL_SECONDS": 1
+  }
+}
+```
+
+**Music Settings**:
+- **`enabled`**: Enable/disable music display
+- **`preferred_source`**: `"spotify"` or `"ytm"`
+- **`YTM_COMPANION_URL`**: YouTube Music companion server URL
+- **`POLLING_INTERVAL_SECONDS`**: How often to check for updates
+
+### Calendar Configuration
+
+```json
+{
+  "calendar": {
+    "enabled": false,
+    "credentials_file": "credentials.json",
+    "token_file": "token.pickle",
+    "update_interval": 3600,
+    "max_events": 3,
+    "calendars": ["birthdays"]
+  }
+}
+```
+
+**Calendar Settings**:
+- **`enabled`**: Enable/disable calendar display
+- **`credentials_file`**: Google API credentials file
+- **`token_file`**: Authentication token file
+- **`update_interval`**: Update frequency in seconds
+- **`max_events`**: Maximum events to display
+- **`calendars`**: Array of calendar IDs to monitor
+
+## Sports Configurations
+
+### Common Sports Settings
+
+All sports managers share these common settings:
+
+```json
+{
+  "nhl_scoreboard": {
+    "enabled": false,
+    "live_priority": true,
+    "live_game_duration": 20,
+    "show_odds": true,
+    "test_mode": false,
+    "update_interval_seconds": 3600,
+    "live_update_interval": 30,
+    "recent_update_interval": 3600,
+    "upcoming_update_interval": 3600,
+    "show_favorite_teams_only": true,
+    "favorite_teams": ["TB"],
+    "logo_dir": "assets/sports/nhl_logos",
+    "show_records": true,
+    "display_modes": {
+      "nhl_live": true,
+      "nhl_recent": true,
+      "nhl_upcoming": true
+    }
+  }
+}
+```
+
+**Common Sports Settings**:
+- **`enabled`**: Enable/disable this sport
+- **`live_priority`**: Give live games priority over other content
+- **`live_game_duration`**: How long to show live games
+- **`show_odds`**: Display betting odds (where available)
+- **`test_mode`**: Use test data instead of live API
+- **`update_interval_seconds`**: How often to fetch new data
+- **`live_update_interval`**: How often to update live games
+- **`show_favorite_teams_only`**: Only show games for favorite teams
+- **`favorite_teams`**: Array of team abbreviations
+- **`logo_dir`**: Directory containing team logos
+- **`show_records`**: Display team win/loss records
+- **`display_modes`**: Enable/disable specific display modes
+
+### Football-Specific Settings
+
+NFL and NCAA Football use game-based fetching:
+
+```json
+{
+  "nfl_scoreboard": {
+    "enabled": false,
+    "recent_games_to_show": 0,
+    "upcoming_games_to_show": 2,
+    "favorite_teams": ["TB", "DAL"]
+  }
+}
+```
+
+**Football Settings**:
+- **`recent_games_to_show`**: Number of recent games to display
+- **`upcoming_games_to_show`**: Number of upcoming games to display
+
+### Soccer Configuration
+
+```json
+{
+  "soccer_scoreboard": {
+    "enabled": false,
+    "recent_game_hours": 168,
+    "favorite_teams": ["LIV"],
+    "leagues": ["eng.1", "esp.1", "ger.1", "ita.1", "fra.1", "uefa.champions", "usa.1"]
+  }
+}
+```
+
+**Soccer Settings**:
+- **`recent_game_hours`**: Hours back to show recent games
+- **`leagues`**: Array of league codes to monitor
+
+## Odds Ticker Configuration
+
+```json
+{
+  "odds_ticker": {
+    "enabled": false,
+    "show_favorite_teams_only": true,
+    "games_per_favorite_team": 1,
+    "max_games_per_league": 5,
+    "show_odds_only": false,
+    "sort_order": "soonest",
+    "enabled_leagues": ["nfl", "mlb", "ncaa_fb", "milb"],
+    "update_interval": 3600,
+    "scroll_speed": 1,
+    "scroll_delay": 0.01,
+    "loop": true,
+    "future_fetch_days": 50,
+    "show_channel_logos": true
+  }
+}
+```
+
+**Odds Ticker Settings**:
+- **`enabled`**: Enable/disable odds ticker
+- **`show_favorite_teams_only`**: Only show odds for favorite teams
+- **`games_per_favorite_team`**: Games per team to show
+- **`max_games_per_league`**: Maximum games per league
+- **`enabled_leagues`**: Leagues to include in ticker
+- **`sort_order`**: `"soonest"` or `"latest"`
+- **`future_fetch_days`**: Days ahead to fetch games
+- **`show_channel_logos`**: Display broadcast network logos
+
+## Custom Display Configurations
+
+### Text Display
+
+```json
+{
+  "text_display": {
+    "enabled": false,
+    "text": "Subscribe to ChuckBuilds",
+    "font_path": "assets/fonts/press-start-2p.ttf",
+    "font_size": 8,
+    "scroll": true,
+    "scroll_speed": 40,
+    "text_color": [255, 0, 0],
+    "background_color": [0, 0, 0],
+    "scroll_gap_width": 32
+  }
+}
+```
+
+**Text Display Settings**:
+- **`enabled`**: Enable/disable text display
+- **`text`**: Text to display
+- **`font_path`**: Path to TTF font file
+- **`font_size`**: Font size in pixels
+- **`scroll`**: Enable/disable scrolling
+- **`scroll_speed`**: Scroll speed in pixels
+- **`text_color`**: RGB color for text
+- **`background_color`**: RGB color for background
+- **`scroll_gap_width`**: Gap between text repetitions
+
+### YouTube Display
+
+```json
+{
+  "youtube": {
+    "enabled": false,
+    "update_interval": 3600
+  }
+}
+```
+
+**YouTube Settings**:
+- **`enabled`**: Enable/disable YouTube stats
+- **`update_interval`**: Update frequency in seconds
+
+### Of The Day Display
+
+```json
+{
+  "of_the_day": {
+    "enabled": true,
+    "display_rotate_interval": 20,
+    "update_interval": 3600,
+    "subtitle_rotate_interval": 10,
+    "category_order": ["word_of_the_day", "slovenian_word_of_the_day", "bible_verse_of_the_day"],
+    "categories": {
+      "word_of_the_day": {
+        "enabled": true,
+        "data_file": "of_the_day/word_of_the_day.json",
+        "display_name": "Word of the Day"
+      },
+      "slovenian_word_of_the_day": {
+        "enabled": true,
+        "data_file": "of_the_day/slovenian_word_of_the_day.json",
+        "display_name": "Slovenian Word of the Day"
+      },
+      "bible_verse_of_the_day": {
+        "enabled": true,
+        "data_file": "of_the_day/bible_verse_of_the_day.json",
+        "display_name": "Bible Verse of the Day"
+      }
+    }
+  }
+}
+```
+
+**Of The Day Settings**:
+- **`enabled`**: Enable/disable of the day display
+- **`display_rotate_interval`**: How long to show each category
+- **`update_interval`**: Update frequency in seconds
+- **`subtitle_rotate_interval`**: How long to show subtitles
+- **`category_order`**: Order of categories to display
+- **`categories`**: Configuration for each category
+
+## API Configuration (config_secrets.json)
+
+### Weather API
+
+```json
+{
+  "weather": {
+    "api_key": "your_openweathermap_api_key"
+  }
+}
+```
+
+### YouTube API
+
+```json
+{
+  "youtube": {
+    "api_key": "your_youtube_api_key",
+    "channel_id": "your_channel_id"
+  }
+}
+```
+
+### Music APIs
+
+```json
+{
+  "music": {
+    "SPOTIFY_CLIENT_ID": "your_spotify_client_id",
+    "SPOTIFY_CLIENT_SECRET": "your_spotify_client_secret",
+    "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
+  }
+}
+```
+
+## Configuration Best Practices
+
+### Performance Optimization
+
+1. **Update Intervals**: Balance between fresh data and API limits
+   - Weather: 1800 seconds (30 minutes)
+   - Stocks: 600 seconds (10 minutes)
+   - Sports: 3600 seconds (1 hour)
+   - Music: 1 second (real-time)
+
+2. **Display Durations**: Balance content visibility
+   - Live sports: 20-30 seconds
+   - Weather: 30 seconds
+   - Stocks: 30-60 seconds
+   - Clock: 15 seconds
+
+3. **Favorite Teams**: Reduce API calls by focusing on specific teams
+
+### Caching Strategy
+
+```json
+{
+  "cache_settings": {
+    "persistent_cache": true,
+    "cache_directory": "/var/cache/ledmatrix",
+    "fallback_cache": "/tmp/ledmatrix_cache"
+  }
+}
+```
+
+### Error Handling
+
+- Failed API calls use cached data
+- Network timeouts are handled gracefully
+- Invalid data is filtered out
+- Logging provides debugging information
+
+## Configuration Validation
+
+### Required Settings
+
+1. **Hardware Configuration**: Must match your physical setup
+2. **API Keys**: Required for enabled services
+3. **Location**: Required for weather and timezone
+4. **Team Abbreviations**: Must match official team codes
+
+### Optional Settings
+
+1. **Display Durations**: Defaults provided if missing
+2. **Update Intervals**: Defaults provided if missing
+3. **Favorite Teams**: Can be empty for all teams
+4. **Custom Text**: Can be any string
+
+## Configuration Examples
+
+### Minimal Configuration
+
+```json
+{
+  "display": {
+    "hardware": {
+      "rows": 32,
+      "cols": 64,
+      "chain_length": 2,
+      "brightness": 90,
+      "hardware_mapping": "adafruit-hat-pwm"
+    }
+  },
+  "clock": {
+    "enabled": true
+  },
+  "weather": {
+    "enabled": true
+  }
+}
+```
+
+### Full Sports Configuration
+
+```json
+{
+  "nhl_scoreboard": {
+    "enabled": true,
+    "favorite_teams": ["TB", "DAL"],
+    "show_favorite_teams_only": true
+  },
+  "nba_scoreboard": {
+    "enabled": true,
+    "favorite_teams": ["DAL"],
+    "show_favorite_teams_only": true
+  },
+  "nfl_scoreboard": {
+    "enabled": true,
+    "favorite_teams": ["TB", "DAL"],
+    "show_favorite_teams_only": true
+  },
+  "odds_ticker": {
+    "enabled": true,
+    "enabled_leagues": ["nfl", "nba", "mlb"]
+  }
+}
+```
+
+### Financial Focus Configuration
+
+```json
+{
+  "stocks": {
+    "enabled": true,
+    "symbols": ["AAPL", "MSFT", "GOOGL", "TSLA", "NVDA"],
+    "update_interval": 300
+  },
+  "crypto": {
+    "enabled": true,
+    "symbols": ["BTC-USD", "ETH-USD", "ADA-USD"]
+  },
+  "stock_news": {
+    "enabled": true,
+    "update_interval": 1800
+  }
+}
+```
+
+## Troubleshooting Configuration
+
+### Common Issues
+
+1. **No Display**: Check hardware configuration
+2. **No Data**: Verify API keys and network
+3. **Wrong Times**: Check timezone setting
+4. **Performance Issues**: Reduce update frequencies
+
+### Validation Commands
+
+```bash
+# Validate JSON syntax
+python3 -m json.tool config/config.json
+
+# Check configuration loading
+python3 -c "from src.config_manager import ConfigManager; c = ConfigManager(); print('Config valid')"
+```
+
+---
+
+*For detailed information about specific display managers, see the [Display Managers](WIKI_DISPLAY_MANAGERS.md) page.* 

wiki/WIKI_DISPLAY_MANAGERS.md

@@ -0,0 +1,501 @@
+# Display Managers Guide
+
+The LEDMatrix system uses a modular architecture where each feature is implemented as a separate "Display Manager". This guide covers all available display managers and their configuration options.
+
+## Overview
+
+Each display manager is responsible for:
+1. **Data Fetching**: Retrieving data from APIs or local sources
+2. **Data Processing**: Transforming raw data into displayable format
+3. **Display Rendering**: Creating visual content for the LED matrix
+4. **Caching**: Storing data to reduce API calls
+5. **Configuration**: Managing settings and preferences
+
+## Core Display Managers
+
+### 🕐 Clock Manager (`src/clock.py`)
+**Purpose**: Displays current time in various formats
+
+**Configuration**:
+```json
+{
+  "clock": {
+    "enabled": true,
+    "format": "%I:%M %p",
+    "update_interval": 1
+  }
+}
+```
+
+**Features**:
+- Real-time clock display
+- Configurable time format
+- Automatic timezone handling
+- Minimal resource usage
+
+**Display Format**: `12:34 PM`
+
+---
+
+### 🌤️ Weather Manager (`src/weather_manager.py`)
+**Purpose**: Displays current weather, hourly forecasts, and daily forecasts
+
+**Configuration**:
+```json
+{
+  "weather": {
+    "enabled": true,
+    "update_interval": 1800,
+    "units": "imperial",
+    "display_format": "{temp}°F\n{condition}"
+  }
+}
+```
+
+**Features**:
+- Current weather conditions
+- Hourly forecast (next 24 hours)
+- Daily forecast (next 7 days)
+- Weather icons and animations
+- UV index display
+- Wind speed and direction
+- Humidity and pressure data
+
+**Display Modes**:
+- Current weather with icon
+- Hourly forecast with temperature trend
+- Daily forecast with high/low temps
+
+---
+
+### 💰 Stock Manager (`src/stock_manager.py`)
+**Purpose**: Displays stock prices, crypto prices, and financial data
+
+**Configuration**:
+```json
+{
+  "stocks": {
+    "enabled": true,
+    "update_interval": 600,
+    "scroll_speed": 1,
+    "scroll_delay": 0.01,
+    "toggle_chart": false,
+    "symbols": ["AAPL", "MSFT", "GOOGL", "TSLA"]
+  },
+  "crypto": {
+    "enabled": true,
+    "update_interval": 600,
+    "symbols": ["BTC-USD", "ETH-USD"]
+  }
+}
+```
+
+**Features**:
+- Real-time stock prices
+- Cryptocurrency prices
+- Price change indicators (green/red)
+- Percentage change display
+- Optional mini charts
+- Scrolling ticker format
+- Company/crypto logos
+
+**Data Sources**:
+- Yahoo Finance API for stocks
+- Yahoo Finance API for crypto
+- Automatic market hours detection
+
+---
+
+### 📰 Stock News Manager (`src/stock_news_manager.py`)
+**Purpose**: Displays financial news headlines for configured stocks
+
+**Configuration**:
+```json
+{
+  "stock_news": {
+    "enabled": true,
+    "update_interval": 3600,
+    "scroll_speed": 1,
+    "scroll_delay": 0.01,
+    "max_headlines_per_symbol": 1,
+    "headlines_per_rotation": 2
+  }
+}
+```
+
+**Features**:
+- Financial news headlines
+- Stock-specific news filtering
+- Scrolling text display
+- Configurable headline limits
+- Automatic rotation
+
+---
+
+### 🎵 Music Manager (`src/music_manager.py`)
+**Purpose**: Displays currently playing music from Spotify or YouTube Music
+
+**Configuration**:
+```json
+{
+  "music": {
+    "enabled": true,
+    "preferred_source": "ytm",
+    "YTM_COMPANION_URL": "http://192.168.86.12:9863",
+    "POLLING_INTERVAL_SECONDS": 1
+  }
+}
+```
+
+**Features**:
+- Spotify integration
+- YouTube Music integration
+- Album art display
+- Song title and artist
+- Playback status
+- Real-time updates
+
+**Supported Sources**:
+- Spotify (requires API credentials)
+- YouTube Music (requires YTMD companion server)
+
+---
+
+### 📅 Calendar Manager (`src/calendar_manager.py`)
+**Purpose**: Displays upcoming Google Calendar events
+
+**Configuration**:
+```json
+{
+  "calendar": {
+    "enabled": true,
+    "credentials_file": "credentials.json",
+    "token_file": "token.pickle",
+    "update_interval": 3600,
+    "max_events": 3,
+    "calendars": ["birthdays"]
+  }
+}
+```
+
+**Features**:
+- Google Calendar integration
+- Event date and time display
+- Event title (wrapped to fit display)
+- Multiple calendar support
+- Configurable event limits
+
+---
+
+### 🏈 Sports Managers
+
+The system includes separate managers for each sports league:
+
+#### NHL Managers (`src/nhl_managers.py`)
+- **NHLLiveManager**: Currently playing games
+- **NHLRecentManager**: Completed games (last 48 hours)
+- **NHLUpcomingManager**: Scheduled games
+
+#### NBA Managers (`src/nba_managers.py`)
+- **NBALiveManager**: Currently playing games
+- **NBARecentManager**: Completed games
+- **NBAUpcomingManager**: Scheduled games
+
+#### MLB Managers (`src/mlb_manager.py`)
+- **MLBLiveManager**: Currently playing games
+- **MLBRecentManager**: Completed games
+- **MLBUpcomingManager**: Scheduled games
+
+#### NFL Managers (`src/nfl_managers.py`)
+- **NFLLiveManager**: Currently playing games
+- **NFLRecentManager**: Completed games
+- **NFLUpcomingManager**: Scheduled games
+
+#### NCAA Managers
+- **NCAA Football** (`src/ncaa_fb_managers.py`)
+- **NCAA Baseball** (`src/ncaa_baseball_managers.py`)
+- **NCAA Basketball** (`src/ncaam_basketball_managers.py`)
+
+#### Soccer Managers (`src/soccer_managers.py`)
+- **SoccerLiveManager**: Currently playing games
+- **SoccerRecentManager**: Completed games
+- **SoccerUpcomingManager**: Scheduled games
+
+#### MiLB Managers (`src/milb_manager.py`)
+- **MiLBLiveManager**: Currently playing games
+- **MiLBRecentManager**: Completed games
+- **MiLBUpcomingManager**: Scheduled games
+
+**Common Sports Configuration**:
+```json
+{
+  "nhl_scoreboard": {
+    "enabled": true,
+    "live_priority": true,
+    "live_game_duration": 20,
+    "show_odds": true,
+    "test_mode": false,
+    "update_interval_seconds": 3600,
+    "live_update_interval": 30,
+    "show_favorite_teams_only": true,
+    "favorite_teams": ["TB"],
+    "logo_dir": "assets/sports/nhl_logos",
+    "show_records": true,
+    "display_modes": {
+      "nhl_live": true,
+      "nhl_recent": true,
+      "nhl_upcoming": true
+    }
+  }
+}
+```
+
+**Sports Features**:
+- Live game scores and status
+- Team logos and records
+- Game times and venues
+- Odds integration (where available)
+- Favorite team filtering
+- Automatic game switching
+- ESPN API integration
+
+---
+
+### 🎲 Odds Ticker Manager (`src/odds_ticker_manager.py`)
+**Purpose**: Displays betting odds for upcoming sports games
+
+**Configuration**:
+```json
+{
+  "odds_ticker": {
+    "enabled": true,
+    "show_favorite_teams_only": true,
+    "games_per_favorite_team": 1,
+    "max_games_per_league": 5,
+    "show_odds_only": false,
+    "sort_order": "soonest",
+    "enabled_leagues": ["nfl", "mlb", "ncaa_fb", "milb"],
+    "update_interval": 3600,
+    "scroll_speed": 1,
+    "scroll_delay": 0.01,
+    "loop": true,
+    "future_fetch_days": 50,
+    "show_channel_logos": true
+  }
+}
+```
+
+**Features**:
+- Multi-league support (NFL, NBA, MLB, NCAA)
+- Spread, money line, and over/under odds
+- Team logos display
+- Scrolling text format
+- Game time display
+- ESPN API integration
+
+---
+
+### 🎨 Custom Display Managers
+
+#### Text Display Manager (`src/text_display.py`)
+**Purpose**: Displays custom text messages
+
+**Configuration**:
+```json
+{
+  "text_display": {
+    "enabled": true,
+    "text": "Subscribe to ChuckBuilds",
+    "font_path": "assets/fonts/press-start-2p.ttf",
+    "font_size": 8,
+    "scroll": true,
+    "scroll_speed": 40,
+    "text_color": [255, 0, 0],
+    "background_color": [0, 0, 0],
+    "scroll_gap_width": 32
+  }
+}
+```
+
+**Features**:
+- Custom text messages
+- Configurable fonts and colors
+- Scrolling text support
+- Static text display
+- Background color options
+
+#### YouTube Display Manager (`src/youtube_display.py`)
+**Purpose**: Displays YouTube channel statistics
+
+**Configuration**:
+```json
+{
+  "youtube": {
+    "enabled": true,
+    "update_interval": 3600
+  }
+}
+```
+
+**Features**:
+- Subscriber count display
+- Video count display
+- View count display
+- YouTube API integration
+
+#### Of The Day Manager (`src/of_the_day_manager.py`)
+**Purpose**: Displays various "of the day" content
+
+**Configuration**:
+```json
+{
+  "of_the_day": {
+    "enabled": true,
+    "display_rotate_interval": 20,
+    "update_interval": 3600,
+    "subtitle_rotate_interval": 10,
+    "category_order": ["word_of_the_day", "slovenian_word_of_the_day", "bible_verse_of_the_day"],
+    "categories": {
+      "word_of_the_day": {
+        "enabled": true,
+        "data_file": "of_the_day/word_of_the_day.json",
+        "display_name": "Word of the Day"
+      },
+      "slovenian_word_of_the_day": {
+        "enabled": true,
+        "data_file": "of_the_day/slovenian_word_of_the_day.json",
+        "display_name": "Slovenian Word of the Day"
+      },
+      "bible_verse_of_the_day": {
+        "enabled": true,
+        "data_file": "of_the_day/bible_verse_of_the_day.json",
+        "display_name": "Bible Verse of the Day"
+      }
+    }
+  }
+}
+```
+
+**Features**:
+- Word of the day
+- Slovenian word of the day
+- Bible verse of the day
+- Rotating display categories
+- Local JSON data files
+
+---
+
+## Display Manager Architecture
+
+### Common Interface
+All display managers follow a consistent interface:
+
+```python
+class DisplayManager:
+    def __init__(self, config, display_manager):
+        # Initialize with configuration and display manager
+        
+    def update_data(self):
+        # Fetch and process new data
+        
+    def display(self, force_clear=False):
+        # Render content to the display
+        
+    def is_enabled(self):
+        # Check if manager is enabled
+```
+
+### Data Flow
+1. **Configuration**: Manager reads settings from `config.json`
+2. **Data Fetching**: Retrieves data from APIs or local sources
+3. **Caching**: Stores data using `CacheManager`
+4. **Processing**: Transforms data into display format
+5. **Rendering**: Uses `DisplayManager` to show content
+6. **Rotation**: Returns to main display controller
+
+### Error Handling
+- API failures fall back to cached data
+- Network timeouts are handled gracefully
+- Invalid data is filtered out
+- Logging provides debugging information
+
+## Configuration Best Practices
+
+### Enable/Disable Managers
+```json
+{
+  "weather": {
+    "enabled": true  // Set to false to disable
+  }
+}
+```
+
+### Set Display Durations
+```json
+{
+  "display": {
+    "display_durations": {
+      "weather": 30,      // 30 seconds
+      "stocks": 60,       // 1 minute
+      "nhl_live": 20      // 20 seconds
+    }
+  }
+}
+```
+
+### Configure Update Intervals
+```json
+{
+  "weather": {
+    "update_interval": 1800  // Update every 30 minutes
+  }
+}
+```
+
+### Set Favorite Teams
+```json
+{
+  "nhl_scoreboard": {
+    "show_favorite_teams_only": true,
+    "favorite_teams": ["TB", "DAL"]
+  }
+}
+```
+
+## Performance Considerations
+
+### API Rate Limits
+- Weather: 1000 calls/day (OpenWeatherMap)
+- Stocks: 2000 calls/hour (Yahoo Finance)
+- Sports: ESPN API (no documented limits)
+- Music: Spotify/YouTube Music APIs
+
+### Caching Strategy
+- Data cached based on `update_interval`
+- Cache persists across restarts
+- Failed API calls use cached data
+- Automatic cache invalidation
+
+### Resource Usage
+- Each manager runs independently
+- Disabled managers use no resources
+- Memory usage scales with enabled features
+- CPU usage minimal during idle periods
+
+## Troubleshooting Display Managers
+
+### Common Issues
+1. **No Data Displayed**: Check API keys and network connectivity
+2. **Outdated Data**: Verify update intervals and cache settings
+3. **Display Errors**: Check font files and display configuration
+4. **Performance Issues**: Reduce update frequency or disable unused managers
+
+### Debugging
+- Enable logging for specific managers
+- Check cache directory for data files
+- Verify API credentials in `config_secrets.json`
+- Test individual managers in isolation
+
+---
+
+*For detailed technical information about each display manager, see the [Display Manager Details](WIKI_DISPLAY_MANAGER_DETAILS.md) page.* 

wiki/WIKI_HOME.md

@@ -0,0 +1,115 @@
+# LEDMatrix Wiki
+
+Welcome to the LEDMatrix Wiki! This comprehensive documentation will help you understand, configure, and customize your LED matrix display system.
+
+## 🏠 [Home](WIKI_HOME.md) - You are here
+The main wiki page with overview and navigation.
+
+## 📋 [Quick Start Guide](WIKI_QUICK_START.md)
+Get your LEDMatrix up and running in minutes with this step-by-step guide.
+
+## 🏗️ [System Architecture](WIKI_ARCHITECTURE.md)
+Understand how the LEDMatrix system is organized and how all components work together.
+
+## ⚙️ [Configuration Guide](WIKI_CONFIGURATION.md)
+Complete guide to configuring all aspects of your LEDMatrix system.
+
+## 🎯 [Display Managers](WIKI_DISPLAY_MANAGERS.md)
+Detailed documentation for each display manager and their configuration options.
+
+## 🎨 [Display Manager Details](WIKI_DISPLAY_MANAGER_DETAILS.md)
+In-depth technical details about each display manager's functionality and API integration.
+
+## 🔧 [Hardware Setup](WIKI_HARDWARE.md)
+Complete hardware requirements, assembly instructions, and troubleshooting.
+
+## 🐧 [Raspberry Pi Setup](WIKI_RASPBERRY_PI.md)
+Step-by-step instructions for setting up your Raspberry Pi for LEDMatrix.
+
+## 🚀 [Installation & Deployment](WIKI_INSTALLATION.md)
+Complete installation process, service setup, and deployment options.
+
+## 🔐 [API Authentication](WIKI_API_AUTH.md)
+How to set up API keys and authentication for all supported services.
+
+## 🎵 [Music Integration](WIKI_MUSIC.md)
+Complete guide to Spotify and YouTube Music integration.
+
+## 🏈 [Sports Integration](WIKI_SPORTS.md)
+Detailed documentation for all sports leagues and their configuration.
+
+## 💰 [Financial Data](WIKI_FINANCIAL.md)
+Stock ticker, crypto, and financial news display configuration.
+
+## 🌤️ [Weather Display](WIKI_WEATHER.md)
+Weather current conditions, forecasts, and icon system.
+
+## 📅 [Calendar Integration](WIKI_CALENDAR.md)
+Google Calendar integration and event display.
+
+## 🎨 [Custom Displays](WIKI_CUSTOM_DISPLAYS.md)
+Text display, YouTube stats, and custom content creation.
+
+## 🔧 [Troubleshooting](WIKI_TROUBLESHOOTING.md)
+Common issues, solutions, and debugging techniques.
+
+## 🛠️ [Development Guide](WIKI_DEVELOPMENT.md)
+How to extend the system, add new features, and contribute.
+
+## 📚 [API Reference](WIKI_API_REFERENCE.md)
+Technical reference for all classes, methods, and configuration options.
+
+---
+
+## Quick Navigation
+
+### Core Features
+- [Display Managers](WIKI_DISPLAY_MANAGERS.md) - All display modules
+- [Configuration](WIKI_CONFIGURATION.md) - Complete config guide
+- [Hardware Setup](WIKI_HARDWARE.md) - Physical setup
+
+### Integrations
+- [Sports](WIKI_SPORTS.md) - All sports leagues
+- [Music](WIKI_MUSIC.md) - Spotify & YouTube Music
+- [Weather](WIKI_WEATHER.md) - Weather display
+- [Financial](WIKI_FINANCIAL.md) - Stocks & crypto
+- [Calendar](WIKI_CALENDAR.md) - Google Calendar
+
+### Technical
+- [Architecture](WIKI_ARCHITECTURE.md) - System design
+- [API Reference](WIKI_API_REFERENCE.md) - Technical docs
+- [Development](WIKI_DEVELOPMENT.md) - Extending the system
+
+---
+
+## About LEDMatrix
+
+LEDMatrix is a comprehensive LED matrix display system that provides real-time information display capabilities for various data sources. The system is highly configurable and supports multiple display modes that can be enabled or disabled based on user preferences.
+
+### Key Features
+- **Modular Design**: Each feature is a separate manager that can be enabled/disabled
+- **Real-time Updates**: Live data from APIs with intelligent caching
+- **Multiple Sports**: NHL, NBA, MLB, NFL, NCAA, Soccer, and more
+- **Financial Data**: Stock ticker, crypto prices, and financial news
+- **Weather**: Current conditions, hourly and daily forecasts
+- **Music**: Spotify and YouTube Music integration
+- **Custom Content**: Text display, YouTube stats, and more
+- **Scheduling**: Configurable display rotation and timing
+- **Caching**: Intelligent caching to reduce API calls
+
+### System Requirements
+- Raspberry Pi 3B+ or 4 (NOT Pi 5)
+- Adafruit RGB Matrix Bonnet/HAT
+- 2x LED Matrix panels (64x32)
+- 5V 4A DC Power Supply
+- Internet connection for API access
+
+### Quick Links
+- [YouTube Setup Video](https://www.youtube.com/watch?v=_HaqfJy1Y54)
+- [Project Website](https://www.chuck-builds.com/led-matrix/)
+- [GitHub Repository](https://github.com/ChuckBuilds/LEDMatrix)
+- [Discord Community](https://discord.com/invite/uW36dVAtcT)
+
+---
+
+*This wiki is designed to help you get the most out of your LEDMatrix system. Each page contains detailed information, configuration examples, and troubleshooting tips.* 

wiki/WIKI_QUICK_START.md

@@ -0,0 +1,364 @@
+# Quick Start Guide
+
+Get your LEDMatrix system up and running in minutes! This guide covers the essential steps to get your display working.
+
+## Prerequisites
+
+### Hardware Requirements
+- Raspberry Pi 3B+ or 4 (NOT Pi 5)
+- Adafruit RGB Matrix Bonnet/HAT
+- 2x LED Matrix panels (64x32 each)
+- 5V 4A DC Power Supply
+- Micro SD card (8GB or larger)
+
+### Software Requirements
+- Internet connection
+- SSH access to Raspberry Pi
+- Basic command line knowledge
+
+## Step 1: Prepare Raspberry Pi
+
+### 1.1 Create Raspberry Pi Image
+1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
+2. Choose your Raspberry Pi model
+3. Select "Raspbian OS Lite (64-bit)"
+4. Choose your micro SD card
+5. Click "Next" then "Edit Settings"
+
+### 1.2 Configure OS Settings
+1. **General Tab**:
+   - Set hostname: `ledpi`
+   - Enable SSH
+   - Set username and password
+   - Configure WiFi
+
+2. **Services Tab**:
+   - Enable SSH
+   - Use password authentication
+
+3. Click "Save" and write the image
+
+### 1.3 Boot and Connect
+1. Insert SD card into Raspberry Pi
+2. Power on and wait for boot
+3. Connect via SSH:
+   ```bash
+   ssh ledpi@ledpi
+   ```
+
+## Step 2: Install LEDMatrix
+
+### 2.1 Update System
+```bash
+sudo apt update && sudo apt upgrade -y
+sudo apt install -y git python3-pip cython3 build-essential python3-dev python3-pillow scons
+```
+
+### 2.2 Clone Repository
+```bash
+git clone https://github.com/ChuckBuilds/LEDMatrix.git
+cd LEDMatrix
+```
+
+### 2.3 Install Dependencies
+```bash
+sudo pip3 install --break-system-packages -r requirements.txt
+```
+
+### 2.4 Install RGB Matrix Library
+```bash
+cd rpi-rgb-led-matrix-master
+sudo make build-python PYTHON=$(which python3)
+cd bindings/python
+sudo python3 setup.py install
+```
+
+### 2.5 Test Installation
+```bash
+python3 -c 'from rgbmatrix import RGBMatrix, RGBMatrixOptions; print("Success!")'
+```
+
+## Step 3: Configure Hardware
+
+### 3.1 Remove Audio Services
+```bash
+sudo apt-get remove bluez bluez-firmware pi-bluetooth triggerhappy pigpio
+```
+
+### 3.2 Blacklist Sound Module
+```bash
+cat <<EOF | sudo tee /etc/modprobe.d/blacklist-rgb-matrix.conf
+blacklist snd_bcm2835
+EOF
+
+sudo update-initramfs -u
+sudo reboot
+```
+
+### 3.3 Optimize Performance
+```bash
+# Edit cmdline.txt
+sudo nano /boot/firmware/cmdline.txt
+# Add "isolcpus=3" at the end
+
+# Edit config.txt
+sudo nano /boot/firmware/config.txt
+# Change "dtparam=audio=on" to "dtparam=audio=off"
+
+sudo reboot
+```
+
+## Step 4: Configure LEDMatrix
+
+### 4.1 Basic Configuration
+```bash
+sudo nano config/config.json
+```
+
+**Minimal Configuration**:
+```json
+{
+  "display": {
+    "hardware": {
+      "rows": 32,
+      "cols": 64,
+      "chain_length": 2,
+      "brightness": 90,
+      "hardware_mapping": "adafruit-hat-pwm"
+    }
+  },
+  "clock": {
+    "enabled": true
+  },
+  "weather": {
+    "enabled": true
+  }
+}
+```
+
+### 4.2 Set Permissions
+```bash
+sudo chmod o+x /home/ledpi
+```
+
+### 4.3 Setup Cache (Optional)
+```bash
+chmod +x setup_cache.sh
+./setup_cache.sh
+```
+
+## Step 5: Test Basic Display
+
+### 5.1 Run Display
+```bash
+sudo python3 display_controller.py
+```
+
+**Expected Behavior**:
+- Display should show "Initializing" message
+- Clock should display current time
+- Weather should show current conditions (if API key configured)
+
+### 5.2 Stop Display
+Press `Ctrl+C` to stop the display
+
+## Step 6: Configure APIs (Optional)
+
+### 6.1 Weather API
+1. Get free API key from [OpenWeatherMap](https://openweathermap.org/api)
+2. Create secrets file:
+   ```bash
+   cp config/config_secrets.template.json config/config_secrets.json
+   sudo nano config/config_secrets.json
+   ```
+3. Add your API key:
+   ```json
+   {
+     "weather": {
+       "api_key": "your_api_key_here"
+     }
+   }
+   ```
+
+### 6.2 Test Weather Display
+```bash
+sudo python3 display_controller.py
+```
+
+## Step 7: Install as Service
+
+### 7.1 Install Service
+```bash
+chmod +x install_service.sh
+sudo ./install_service.sh
+```
+
+### 7.2 Control Service
+```bash
+# Start display
+sudo systemctl start ledmatrix.service
+
+# Stop display
+sudo systemctl stop ledmatrix.service
+
+# Check status
+sudo systemctl status ledmatrix.service
+
+# Enable autostart
+sudo systemctl enable ledmatrix.service
+```
+
+### 7.3 Convenience Scripts
+```bash
+chmod +x start_display.sh stop_display.sh
+
+# Start display
+sudo ./start_display.sh
+
+# Stop display
+sudo ./stop_display.sh
+```
+
+## Step 8: Add More Features
+
+### 8.1 Enable Stocks
+Edit `config/config.json`:
+```json
+{
+  "stocks": {
+    "enabled": true,
+    "symbols": ["AAPL", "MSFT", "GOOGL", "TSLA"]
+  }
+}
+```
+
+### 8.2 Enable Sports
+```json
+{
+  "nhl_scoreboard": {
+    "enabled": true,
+    "favorite_teams": ["TB"]
+  }
+}
+```
+
+### 8.3 Enable Music
+```json
+{
+  "music": {
+    "enabled": true,
+    "preferred_source": "ytm"
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **No Display**:
+   - Check hardware connections
+   - Verify `hardware_mapping` setting
+   - Ensure power supply is adequate
+
+2. **Permission Errors**:
+   ```bash
+   sudo chmod o+x /home/ledpi
+   ```
+
+3. **Import Errors**:
+   ```bash
+   cd rpi-rgb-led-matrix-master/bindings/python
+   sudo python3 setup.py install
+   ```
+
+4. **Cache Issues**:
+   ```bash
+   chmod +x fix_cache_permissions.sh
+   ./fix_cache_permissions.sh
+   ```
+
+### Test Individual Components
+
+```bash
+# Test clock
+python3 -c "from src.clock import Clock; from src.display_manager import DisplayManager; c = Clock(DisplayManager({})); c.display()"
+
+# Test weather (requires API key)
+python3 -c "from src.weather_manager import WeatherManager; from src.display_manager import DisplayManager; w = WeatherManager({'weather': {'enabled': True}}, DisplayManager({})); w.display_weather()"
+```
+
+## Next Steps
+
+### 1. Configure Your Preferences
+- Edit `config/config.json` to enable desired features
+- Add API keys to `config/config_secrets.json`
+- Customize display durations and settings
+
+### 2. Add Sports Teams
+- Configure favorite teams for each sport
+- Set up odds ticker for betting information
+- Customize display modes
+
+### 3. Set Up Music Integration
+- Configure Spotify or YouTube Music
+- Set up authentication
+- Test music display
+
+### 4. Customize Display
+- Add custom text messages
+- Configure YouTube stats
+- Set up "of the day" content
+
+### 5. Web Interface
+- Access web interface at `http://ledpi:5000`
+- Control display remotely
+- Monitor system status
+
+## Quick Reference
+
+### Essential Commands
+```bash
+# Start display manually
+sudo python3 display_controller.py
+
+# Start service
+sudo systemctl start ledmatrix.service
+
+# Stop service
+sudo systemctl stop ledmatrix.service
+
+# Check status
+sudo systemctl status ledmatrix.service
+
+# View logs
+journalctl -u ledmatrix.service
+
+# Edit configuration
+sudo nano config/config.json
+
+# Edit secrets
+sudo nano config/config_secrets.json
+```
+
+### Configuration Files
+- `config/config.json` - Main configuration
+- `config/config_secrets.json` - API keys
+- `ledmatrix.service` - Systemd service
+
+### Important Directories
+- `/var/cache/ledmatrix/` - Cache directory
+- `assets/` - Logos, fonts, icons
+- `src/` - Source code
+- `config/` - Configuration files
+
+---
+
+**Congratulations!** Your LEDMatrix system is now running. Check out the other wiki pages for detailed configuration options and advanced features.
+
+## Need Help?
+
+- [YouTube Setup Video](https://www.youtube.com/watch?v=_HaqfJy1Y54)
+- [Discord Community](https://discord.com/invite/uW36dVAtcT)
+- [Project Website](https://www.chuck-builds.com/led-matrix/)
+- [GitHub Issues](https://github.com/ChuckBuilds/LEDMatrix/issues) 

wiki/WIKI_TROUBLESHOOTING.md

@@ -0,0 +1,516 @@
+# Troubleshooting Guide
+
+This guide covers common issues you may encounter with your LEDMatrix system and their solutions.
+
+## Quick Diagnosis
+
+### Check System Status
+```bash
+# Check service status
+sudo systemctl status ledmatrix.service
+
+# Check logs
+journalctl -u ledmatrix.service -f
+
+# Check display manually
+sudo python3 display_controller.py
+```
+
+### Check Hardware
+```bash
+# Check GPIO access
+sudo python3 -c "import RPi.GPIO as GPIO; GPIO.setmode(GPIO.BCM); print('GPIO OK')"
+
+# Check RGB matrix library
+python3 -c 'from rgbmatrix import RGBMatrix, RGBMatrixOptions; print("RGB Matrix OK")'
+```
+
+## Common Issues
+
+### 1. No Display Output
+
+**Symptoms**: LED matrix shows no output or remains dark
+
+**Possible Causes**:
+- Hardware connection issues
+- Incorrect hardware configuration
+- Power supply problems
+- GPIO conflicts
+
+**Solutions**:
+
+1. **Check Hardware Connections**:
+   ```bash
+   # Verify Adafruit HAT is properly seated
+   # Check ribbon cable connections
+   # Ensure power supply is 5V 4A
+   ```
+
+2. **Verify Hardware Configuration**:
+   ```json
+   {
+     "display": {
+       "hardware": {
+         "rows": 32,
+         "cols": 64,
+         "chain_length": 2,
+         "hardware_mapping": "adafruit-hat-pwm"
+       }
+     }
+   }
+   ```
+
+3. **Test Basic Display**:
+   ```bash
+   # Test minimal configuration
+   sudo python3 -c "
+   from rgbmatrix import RGBMatrix, RGBMatrixOptions
+   options = RGBMatrixOptions()
+   options.rows = 32
+   options.cols = 64
+   options.chain_length = 2
+   options.hardware_mapping = 'adafruit-hat-pwm'
+   matrix = RGBMatrix(options=options)
+   print('Matrix initialized successfully')
+   "
+   ```
+
+4. **Check Audio Conflicts**:
+   ```bash
+   # Remove audio services
+   sudo apt-get remove bluez bluez-firmware pi-bluetooth triggerhappy pigpio
+   
+   # Blacklist sound module
+   echo "blacklist snd_bcm2835" | sudo tee /etc/modprobe.d/blacklist-rgb-matrix.conf
+   sudo update-initramfs -u
+   sudo reboot
+   ```
+
+### 2. Permission Errors
+
+**Symptoms**: `Permission denied` or `Access denied` errors
+
+**Solutions**:
+
+1. **Set Home Directory Permissions**:
+   ```bash
+   sudo chmod o+x /home/ledpi
+   ```
+
+2. **Check File Permissions**:
+   ```bash
+   # Check config file permissions
+   ls -la config/
+   
+   # Fix permissions if needed
+   sudo chown ledpi:ledpi config/config.json
+   sudo chmod 644 config/config.json
+   ```
+
+3. **Cache Directory Permissions**:
+   ```bash
+   chmod +x fix_cache_permissions.sh
+   ./fix_cache_permissions.sh
+   ```
+
+### 3. Import Errors
+
+**Symptoms**: `ModuleNotFoundError` or `ImportError`
+
+**Solutions**:
+
+1. **Reinstall RGB Matrix Library**:
+   ```bash
+   cd rpi-rgb-led-matrix-master
+   sudo make build-python PYTHON=$(which python3)
+   cd bindings/python
+   sudo python3 setup.py install
+   ```
+
+2. **Check Python Path**:
+   ```bash
+   python3 -c "import sys; print(sys.path)"
+   ```
+
+3. **Reinstall Dependencies**:
+   ```bash
+   sudo pip3 install --break-system-packages -r requirements.txt
+   ```
+
+### 4. No Data Displayed
+
+**Symptoms**: Display shows but no content appears
+
+**Solutions**:
+
+1. **Check Configuration**:
+   ```bash
+   # Validate JSON syntax
+   python3 -m json.tool config/config.json
+   
+   # Check if features are enabled
+   grep -A 5 '"enabled"' config/config.json
+   ```
+
+2. **Check API Keys**:
+   ```bash
+   # Verify secrets file exists
+   ls -la config/config_secrets.json
+   
+   # Check API key format
+   cat config/config_secrets.json
+   ```
+
+3. **Test Individual Components**:
+   ```bash
+   # Test clock
+   python3 -c "from src.clock import Clock; from src.display_manager import DisplayManager; c = Clock(DisplayManager({})); c.display()"
+   
+   # Test weather (requires API key)
+   python3 -c "from src.weather_manager import WeatherManager; from src.display_manager import DisplayManager; w = WeatherManager({'weather': {'enabled': True}}, DisplayManager({})); w.display_weather()"
+   ```
+
+### 5. Performance Issues
+
+**Symptoms**: Flickering, slow updates, or system lag
+
+**Solutions**:
+
+1. **Optimize Hardware Settings**:
+   ```json
+   {
+     "display": {
+       "hardware": {
+         "gpio_slowdown": 3,
+         "limit_refresh_rate_hz": 120,
+         "pwm_bits": 9
+       }
+     }
+   }
+   ```
+
+2. **Reduce Update Frequency**:
+   ```json
+   {
+     "weather": {
+       "update_interval": 3600
+     },
+     "stocks": {
+       "update_interval": 1800
+     }
+   }
+   ```
+
+3. **Disable Unused Features**:
+   ```json
+   {
+     "stock_news": {
+       "enabled": false
+     },
+     "odds_ticker": {
+       "enabled": false
+     }
+   }
+   ```
+
+### 6. Network/API Issues
+
+**Symptoms**: No weather, stocks, or sports data
+
+**Solutions**:
+
+1. **Check Internet Connection**:
+   ```bash
+   ping -c 3 google.com
+   curl -I https://api.openweathermap.org
+   ```
+
+2. **Verify API Keys**:
+   ```bash
+   # Test OpenWeatherMap API
+   curl "http://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY"
+   
+   # Test Yahoo Finance
+   curl "https://query1.finance.yahoo.com/v8/finance/chart/AAPL"
+   ```
+
+3. **Check Rate Limits**:
+   - OpenWeatherMap: 1000 calls/day
+   - Yahoo Finance: 2000 calls/hour
+   - ESPN API: No documented limits
+
+### 7. Service Issues
+
+**Symptoms**: Service won't start or stops unexpectedly
+
+**Solutions**:
+
+1. **Check Service Status**:
+   ```bash
+   sudo systemctl status ledmatrix.service
+   sudo journalctl -u ledmatrix.service -f
+   ```
+
+2. **Reinstall Service**:
+   ```bash
+   sudo systemctl stop ledmatrix.service
+   sudo systemctl disable ledmatrix.service
+   chmod +x install_service.sh
+   sudo ./install_service.sh
+   ```
+
+3. **Check Service File**:
+   ```bash
+   cat /etc/systemd/system/ledmatrix.service
+   ```
+
+### 8. Cache Issues
+
+**Symptoms**: Data not updating or cache warnings
+
+**Solutions**:
+
+1. **Setup Persistent Cache**:
+   ```bash
+   chmod +x setup_cache.sh
+   ./setup_cache.sh
+   ```
+
+2. **Clear Cache**:
+   ```bash
+   sudo rm -rf /var/cache/ledmatrix/*
+   sudo rm -rf /tmp/ledmatrix_cache/*
+   ```
+
+3. **Check Cache Permissions**:
+   ```bash
+   ls -la /var/cache/ledmatrix/
+   ls -la /tmp/ledmatrix_cache/
+   ```
+
+### 9. Font/Display Issues
+
+**Symptoms**: Text not displaying correctly or missing fonts
+
+**Solutions**:
+
+1. **Check Font Files**:
+   ```bash
+   ls -la assets/fonts/
+   ```
+
+2. **Reinstall Fonts**:
+   ```bash
+   # Copy fonts from repository
+   sudo cp assets/fonts/* /usr/share/fonts/truetype/
+   sudo fc-cache -fv
+   ```
+
+3. **Test Font Loading**:
+   ```bash
+   python3 -c "from PIL import ImageFont; font = ImageFont.truetype('assets/fonts/PressStart2P-Regular.ttf', 8); print('Font loaded')"
+   ```
+
+### 10. Music Integration Issues
+
+**Symptoms**: Spotify or YouTube Music not working
+
+**Solutions**:
+
+1. **Spotify Authentication**:
+   ```bash
+   sudo python3 src/authenticate_spotify.py
+   sudo chmod 644 config/spotify_auth.json
+   ```
+
+2. **YouTube Music Setup**:
+   ```bash
+   # Ensure YTMD companion server is running
+   # Check URL in config
+   sudo python3 src/authenticate_ytm.py
+   ```
+
+3. **Check Music Configuration**:
+   ```json
+   {
+     "music": {
+       "enabled": true,
+       "preferred_source": "ytm",
+       "YTM_COMPANION_URL": "http://192.168.1.100:9863"
+     }
+   }
+   ```
+
+## Advanced Troubleshooting
+
+### Debug Mode
+
+Enable detailed logging:
+```bash
+# Edit display_controller.py
+# Change logging level to DEBUG
+logging.basicConfig(level=logging.DEBUG)
+```
+
+### Test Individual Managers
+
+```bash
+# Test weather manager
+python3 -c "
+from src.weather_manager import WeatherManager
+from src.display_manager import DisplayManager
+config = {'weather': {'enabled': True}}
+w = WeatherManager(config, DisplayManager(config))
+w.display_weather()
+"
+
+# Test stock manager
+python3 -c "
+from src.stock_manager import StockManager
+from src.display_manager import DisplayManager
+config = {'stocks': {'enabled': True, 'symbols': ['AAPL']}}
+s = StockManager(config, DisplayManager(config))
+s.display_stocks()
+"
+```
+
+### Hardware Diagnostics
+
+```bash
+# Check GPIO pins
+sudo python3 -c "
+import RPi.GPIO as GPIO
+GPIO.setmode(GPIO.BCM)
+pins = [12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27]
+for pin in pins:
+    try:
+        GPIO.setup(pin, GPIO.OUT)
+        GPIO.output(pin, GPIO.HIGH)
+        print(f'Pin {pin}: OK')
+    except:
+        print(f'Pin {pin}: ERROR')
+"
+```
+
+### Performance Monitoring
+
+```bash
+# Monitor system resources
+htop
+
+# Check memory usage
+free -h
+
+# Monitor network
+iftop
+
+# Check disk usage
+df -h
+```
+
+## Recovery Procedures
+
+### Complete Reset
+
+If all else fails, perform a complete reset:
+
+1. **Backup Configuration**:
+   ```bash
+   cp config/config.json config/config.json.backup
+   cp config/config_secrets.json config/config_secrets.json.backup
+   ```
+
+2. **Reinstall System**:
+   ```bash
+   sudo systemctl stop ledmatrix.service
+   sudo systemctl disable ledmatrix.service
+   sudo rm -rf /var/cache/ledmatrix
+   sudo rm -rf /tmp/ledmatrix_cache
+   ```
+
+3. **Fresh Installation**:
+   ```bash
+   cd ~
+   rm -rf LEDMatrix
+   git clone https://github.com/ChuckBuilds/LEDMatrix.git
+   cd LEDMatrix
+   # Follow installation steps again
+   ```
+
+### Emergency Mode
+
+If the system won't start, try emergency mode:
+
+```bash
+# Stop all services
+sudo systemctl stop ledmatrix.service
+
+# Run with minimal config
+sudo python3 display_controller.py --emergency
+
+# Or run individual components
+sudo python3 -c "
+from src.clock import Clock
+from src.display_manager import DisplayManager
+c = Clock(DisplayManager({}))
+while True:
+    c.display()
+    import time
+    time.sleep(1)
+"
+```
+
+## Getting Help
+
+### Before Asking for Help
+
+1. **Collect Information**:
+   ```bash
+   # System info
+   uname -a
+   cat /etc/os-release
+   
+   # Service status
+   sudo systemctl status ledmatrix.service
+   
+   # Recent logs
+   journalctl -u ledmatrix.service --since "1 hour ago"
+   
+   # Configuration
+   cat config/config.json
+   ```
+
+2. **Test Basic Functionality**:
+   ```bash
+   # Test RGB matrix
+   python3 -c 'from rgbmatrix import RGBMatrix, RGBMatrixOptions; print("RGB Matrix OK")'
+   
+   # Test display
+   sudo python3 display_controller.py
+   ```
+
+3. **Check Common Issues**:
+   - Verify hardware connections
+   - Check API keys
+   - Validate configuration
+   - Test network connectivity
+
+### Where to Get Help
+
+1. **Discord Community**: [ChuckBuilds Discord](https://discord.com/invite/uW36dVAtcT)
+2. **GitHub Issues**: [LEDMatrix Issues](https://github.com/ChuckBuilds/LEDMatrix/issues)
+3. **YouTube**: [ChuckBuilds Channel](https://www.youtube.com/@ChuckBuilds)
+4. **Project Website**: [ChuckBuilds.com](https://www.chuck-builds.com/led-matrix/)
+
+### When Reporting Issues
+
+Include the following information:
+- Hardware setup (Pi model, matrix type)
+- Software version (OS, Python version)
+- Error messages and logs
+- Steps to reproduce
+- What you've already tried
+
+---
+
+*This troubleshooting guide covers the most common issues. If you're still having problems, check the community resources for additional help.* 

wiki/cache_management.md

@@ -0,0 +1,231 @@
+# Cache Management
+
+The LEDMatrix application uses caching to improve performance and reduce API calls. However, sometimes cache data can become stale or corrupted, leading to issues like false live game detection or outdated information.
+
+## Cache Clearing Utility
+
+The `clear_cache.py` script provides a command-line interface for managing the LEDMatrix cache. This utility is essential for debugging cache-related issues and ensuring fresh data retrieval.
+
+### Basic Usage
+
+```bash
+# Show help and current cache status
+python clear_cache.py
+
+# List all available cache keys
+python clear_cache.py --list
+
+# Clear all cache data
+python clear_cache.py --clear-all
+
+# Clear a specific cache key
+python clear_cache.py --clear KEY_NAME
+
+# Show information about a specific cache key
+python clear_cache.py --info KEY_NAME
+```
+
+### Command Reference
+
+| Command | Short | Description |
+|---------|-------|-------------|
+| `--list` | `-l` | List all available cache keys |
+| `--clear-all` | `-a` | Clear all cache data |
+| `--clear KEY` | `-c` | Clear a specific cache key |
+| `--info KEY` | `-i` | Show information about a specific cache key |
+
+## Common Cache Keys
+
+### MiLB (Minor League Baseball)
+- `milb_live_api_data` - Live game data from MiLB API
+- `milb_upcoming_api_data` - Upcoming game schedules
+- `milb_recent_api_data` - Recent game results
+
+### MLB (Major League Baseball)
+- `mlb_live_api_data` - Live game data from MLB API
+- `mlb_upcoming_api_data` - Upcoming game schedules
+- `mlb_recent_api_data` - Recent game results
+
+### Soccer
+- `soccer_live_api_data` - Live soccer match data
+- `soccer_upcoming_api_data` - Upcoming soccer matches
+
+### Other Services
+- `weather_api_data` - Weather information
+- `news_api_data` - News headlines
+- `stocks_api_data` - Stock market data
+
+## Usage Examples
+
+### Scenario 1: False Live Game Detection
+
+**Problem**: The MiLB manager is showing "Tam vs Dun" as a live game when it's actually old data.
+
+**Solution**:
+```bash
+# First, check what's in the MiLB live cache
+python clear_cache.py --info milb_live_api_data
+
+# Clear the problematic cache
+python clear_cache.py --clear milb_live_api_data
+
+# Restart the application to fetch fresh data
+```
+
+### Scenario 2: Stale Upcoming Games
+
+**Problem**: The display is showing outdated game schedules.
+
+**Solution**:
+```bash
+# Clear all MiLB cache data
+python clear_cache.py --clear milb_upcoming_api_data
+python clear_cache.py --clear milb_live_api_data
+python clear_cache.py --clear milb_recent_api_data
+```
+
+### Scenario 3: Complete Cache Reset
+
+**Problem**: Multiple cache-related issues or corrupted data.
+
+**Solution**:
+```bash
+# Nuclear option - clear everything
+python clear_cache.py --clear-all
+
+# Verify cache is empty
+python clear_cache.py --list
+```
+
+### Scenario 4: Debugging Cache Issues
+
+**Problem**: Unusual behavior that might be cache-related.
+
+**Solution**:
+```bash
+# List all cache keys to see what's stored
+python clear_cache.py --list
+
+# Inspect specific cache entries
+python clear_cache.py --info milb_live_api_data
+python clear_cache.py --info weather_api_data
+
+# Clear specific problematic caches
+python clear_cache.py --clear milb_live_api_data
+```
+
+## Troubleshooting
+
+### Cache Directory Issues
+
+If you encounter errors about cache directories:
+
+```bash
+# Check if cache directory exists
+ls -la ~/.ledmatrix_cache/
+
+# If it doesn't exist, the application will create it automatically
+# You can also manually create it:
+mkdir -p ~/.ledmatrix_cache/
+```
+
+### Permission Issues
+
+If you get permission errors:
+
+```bash
+# Check cache directory permissions
+ls -la ~/.ledmatrix_cache/
+
+# Fix permissions if needed
+chmod 755 ~/.ledmatrix_cache/
+chown $USER:$USER ~/.ledmatrix_cache/
+```
+
+### Import Errors
+
+If you get import errors when running the script:
+
+```bash
+# Make sure you're in the LEDMatrix root directory
+cd /path/to/LEDMatrix
+
+# Check that the src directory exists
+ls -la src/
+
+# Run the script from the correct location
+python clear_cache.py --list
+```
+
+## When to Use Cache Clearing
+
+### Recommended Times to Clear Cache
+
+1. **After configuration changes** - Clear relevant caches when you modify team preferences or display settings
+2. **When experiencing false live data** - Clear live game caches if old games appear as "live"
+3. **After API changes** - Clear caches if you notice API endpoints have changed
+4. **For debugging** - Clear caches when investigating display or data issues
+5. **After long periods of inactivity** - Clear caches if the application hasn't been used for days
+
+### Cache Types and Their Impact
+
+| Cache Type | Impact of Clearing | When to Clear |
+|------------|-------------------|---------------|
+| Live game data | Forces fresh live data fetch | False live game detection |
+| Upcoming games | Refreshes schedules | Outdated game times |
+| Recent games | Updates final scores | Missing recent results |
+| Weather | Gets current conditions | Stale weather data |
+| News | Fetches latest headlines | Old news stories |
+
+## Best Practices
+
+1. **Targeted Clearing**: Clear specific cache keys rather than all cache when possible
+2. **Verify Results**: Use `--info` to check cache contents before and after clearing
+3. **Restart Application**: Restart the LEDMatrix application after clearing caches
+4. **Monitor Logs**: Check application logs after cache clearing to ensure fresh data is fetched
+5. **Backup Important Data**: Cache data is automatically regenerated, but be aware that clearing will force new API calls
+
+## Integration with Application
+
+The cache clearing utility works independently of the main application. You can run it while the application is running, but for best results:
+
+1. Stop the LEDMatrix application
+2. Clear relevant caches
+3. Restart the application
+
+This ensures the application starts with fresh data and doesn't immediately re-cache potentially problematic data.
+
+## Advanced Usage
+
+### Scripting Cache Management
+
+You can integrate cache clearing into scripts or cron jobs:
+
+```bash
+#!/bin/bash
+# Daily cache cleanup script
+
+# Clear old live game data at midnight
+python clear_cache.py --clear milb_live_api_data
+python clear_cache.py --clear mlb_live_api_data
+
+# Log the cleanup
+echo "$(date): Cache cleared" >> /var/log/ledmatrix_cache.log
+```
+
+### Conditional Cache Clearing
+
+```bash
+#!/bin/bash
+# Only clear cache if it's older than 24 hours
+
+# Check cache age and clear if needed
+# (This would require additional logic to check cache timestamps)
+```
+
+## Related Documentation
+
+- [Configuration Guide](../config/README.md)
+- [Troubleshooting Guide](troubleshooting.md)
+- [API Integration](api_integration.md)
+- [Display Controller](display_controller.md)