v2 Gambling Odds, WebUI, Improved Cache

Release v2: Odds, UI & Cache Performance Overhaul

This release introduces a major new feature set centered around sports gambling odds, a powerful web-based UI for remote control, and significant architectural improvements to the caching system, API data fetching, and overall performance.

🔧 Breaking Changes & Required Setup

A new setup script has been added to handle permissions for the cache directory. When the application is run as a systemd service under the ledpi user, it often lacks the necessary permissions to write to cache directories located in the project root. This script resolves potential PermissionDenied errors.

Execute the following command from the project root to apply the fix:

bash setup_cache.sh

This script creates the ~/.ledmatrix_cache directory and sets the appropriate write permissions for the service user.

✨ New Features & Technical Implementation

1. 🌐 Web-Based User Interface

A new, powerful web interface has been introduced, allowing for remote control of the LED Matrix directly from any web browser on the same network.

• Implementation: A lightweight Flask web server (web_interface.py) runs on the Raspberry Pi, providing a simple yet effective UI.
• Core Functionality:
  • Scheduling: Limit the display to run during a set schedule each day - from 7am to 11pm by default. (saves APi Calls and power)
  • Service Management: Send commands to restart, start, or stop the display as well as Enable / Disable autostart and download latest update from github.
  • Easier Config Management: Edit your config from a web browser instead of over ssh. Hope to continue to improve this in later versions.
• Access: The interface is accessible by navigating to http://<your-pi-ip-address>:5000 (ex 'http://ledpi:5000') in your web browser.

2. Scrolling Odds Ticker (OddsTickerManager)

A new, highly configurable display module has been added to show a continuous scrolling ticker of upcoming games.

• Implementation: Instead of redrawing text on every frame, the ticker generates a single, wide composite image (Pillow.Image) containing all game information. The scrolling effect is achieved by efficiently cropping and displaying a portion of this large image, which significantly improves performance and reduces CPU load.
• Content: The ticker dynamically integrates team logos, game records, start times, and live odds data.
• Broadcast Logos: The ticker now parses the broadcasts array from the ESPN API to display the logo of the broadcasting channel (e.g., ESPN, FOX, NBC). It has been updated to support the API's new data structure, which provides an array of broadcast names. The implementation remains backward-compatible.

3. Dedicated Odds Manager (OddsManager)

A new OddsManager class now centralizes all logic for fetching and caching gambling odds.

• Architecture: This manager abstracts the odds-fetching logic away from individual sports managers (MLBManager, NFLManager, etc.), reducing code duplication and creating a single source of truth for odds data.
• API Integration: It interfaces with the ESPN Core API (sports.core.api.espn.com) to retrieve odds, which are often available even when the main scoreboard API does not include them.

🚀 Architectural Improvements

1. Dynamic Caching Strategy (CacheManager)

The CacheManager has been overhauled to use a more intelligent, dynamic TTL (Time-To-Live) strategy for scoreboard data.

• Previous Method: Used a single, static cache duration for all API requests.
• New Method: The TTL is now determined by the game's date relative to the current date:
  • Past Games: Cached for a long duration (e.g., 30 days) as the data is static.
  • Today's Games: Cached for a short duration (e.g., 1 hour) to keep data fresh.
  • Future Games: Cached for a moderate duration (e.g., 12 hours).
• Benefit: This drastically reduces unnecessary API calls for static content while ensuring timely updates for current events, improving both performance and API rate-limit resilience.

2. Day-by-Day Game Date Filtering

The logic for fetching upcoming games has been re-engineered for greater reliability.

• Previous Method: Used a simple time window (now + timedelta) which could fail to capture games scheduled near midnight or across date boundaries.
• New Method: The system now iterates through each day, one by one, using a YYYYMMDD formatted date string. It fetches all games for each day up to the future_fetch_days limit defined in the config.
• Benefit: This ensures that all games within the specified future window are reliably fetched and displayed, eliminating edge cases from the previous implementation.
• • Cost: This can pull in a LOT of data via ESPN api calls when the season is too many days away and favorite teams aren't set. It will still try to search for 50 days and will try to cache progress if (when) you eventually run out of API calls.

3. Favorite Teams Enhancements & Display Modes

The logic for displaying games for favorite teams has been significantly improved, offering more granular control over what is shown on the screen for individual sports modules.

• Personalized Ticker: The odds_ticker can be configured via show_favorite_teams_only to exclusively display upcoming games involving teams listed in the user's favorites. The `show_favorite_teams_only: false' toggle chews up a LOT more API calls and is not recommended. It is also a work in progress.

• Favorite Team Toggle (show_favorite_teams_only): A flag has been implemented that applies to all individual scoreboard modules (nfl_scoreboard, mlb_scoreboard, etc.). When show_favorite_teams_only is set to true in a scoreboard's configuration, that module will only display games (live, recent, or upcoming) that involve one of the teams in your favorite_teams list. This provides a powerful way to filter out noise and focus only on the teams you care about for each sport. The "false" toggle chews up a LOT more API calls and is not recommended. It is also a work in progress.

• 🎯 Focused Game Display Modes (recent_games_to_show & upcoming_games_to_show):
  New configuration options have been introduced to control the behavior of the individual scoreboard modules. These settings allow for a focused, single-team display that can cycle through different states instead of time series collections of games. I.E. I want to see the last 3 NFL Team X's (Bucs) games instead of the last 21 days (3 weeks) of NFL Team X's(Bucs) Games.

  • upcoming_games_to_show: 1: Controls how many future games are displayed for a favorite team in its dedicated scoreboard view. When set to 1, the module will display the single next scheduled game for that team.

  • recent_games_to_show: 1: Controls how many past games are displayed. When set to 1, the module will show the result of the most recently completed game for that team.

  These settings work together with the display_modes configuration to create a rotational view of a team's status (e.g., show the live game if one is on; otherwise, cycle between showing the most recent result and the next upcoming game).

🛠️ General Improvements & Fixes

• API Logic: Refined the API fetching logic across all sports managers (MLB, NFL, NCAA, etc.) to be more efficient and consistent.
• Configuration: Added extensive configuration options in config.json for the new odds ticker and display modes.
• 📄 Short Date Formatting (use_short_date_format): A new global configuration option, use_short_date_format: true, has been added under the display settings. When enabled, dates will be displayed in a more compact format (e.g., Tue, 7/23 instead of Tuesday, July 23). This helps to save valuable screen space on the matrix and provides a cleaner look.
• Code Quality: Added comprehensive logging, new test scripts (test_odds_ticker_broadcast.py, check_espn_api.py), and documentation to improve maintainability.

---

This release represents a significant architectural enhancement, providing new, highly-requested features while improving the stability and efficiency of the existing codebase.

There were a lot of changes and I am sure there are bugs to be found. Reach out on Discord or create a ticket on Github.

Thanks for reading!