mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-10 21:03:01 +00:00
501 lines
11 KiB
Markdown
501 lines
11 KiB
Markdown
# 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.* |