wiki updates

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_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_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_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_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_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.*