LEDMatrix/WIKI_DISPLAY_MANAGERS.md

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

{
  "weather": {
    "enabled": true  // Set to false to disable
  }
}

Set Display Durations

{
  "display": {
    "display_durations": {
      "weather": 30,      // 30 seconds
      "stocks": 60,       // 1 minute
      "nhl_live": 20      // 20 seconds
    }
  }
}

Configure Update Intervals

{
  "weather": {
    "update_interval": 1800  // Update every 30 minutes
  }
}

Set Favorite Teams

{
  "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 page.