V2.5 Bug fixes

Primary goal of this release is to have a clean reference to the last of the "old" managers before releasing v3 with plugins, new webui, api's, 3rd party display support, trixie support, and more.

No real new features in this.

v2.4: Bug Fixes & Persistent Configuration

BREAKING CHANGES:

Config file is now ignored by git. You will need to manually migrate config in the future using the button on the web interface. Shouldn't require much changes from you after this update.

First time after pulling the update you should execute "sudo bash first_time_install.sh" in terminal to re-configure permissions.

---

Thanks for your patience on this project!

V2.3 introduced a few bugs that I didn't catch before I pushed it out on the weekend. I was racing to get it up and working before the football games started.

Some of the issues included:

• Upcoming and Recent games only showing the 1st game found instead of one game per team. (Fixed)
• Music and Of the Day managers had permission issues with their accessible API key or json files (Fixed, if you have issues run "first_time_install.sh" again)
• NCAA FB ESPN api seemed to have had some issues / changed. (which I don't really understand as it still worked for Odds ticker and Live games, just not recent or upcoming) (Fixed, changed API endpoint)
• Some permission errors when accessing Auto_Downloaded team logos (Fixed)
• Some of the web ui save buttons were just reloading, not actually saving the changes (fixed)
• Font spacing broke on "Of the Day" and "Music Manager" (Fixed, sorta - Music manager is moving around on me)
• Reduced Log spam
• Improve Display scrolling for Odds Ticker by adding 1 display width of black buffer behind it
• added Portuguese soccer teams and logos
• updated wiki and readme

What's Changed

• Add NCAA FB AP Top 25 Rankings by @JScottyR in #17
• Add Emulator Support by @legoguy1000 in #35
• Add NCAA Hockey by @legoguy1000 in #36

New Contributors

• @legoguy1000 made their first contribution in #35

Full Changelog: v2.3...v2.4

v2.3: Rankings, Bug Fixes, Auto-Download Missing Team Logos and more

This was a big one and I honestly lost track of everything I did while moving.
Big call outs:

• Fix Time Zone error using UTC instead of user defined TZ
• Ability to Download missing NCAA Logos via ESPN API (Thanks @JScottyR )
• Leaderboard Manager display to show top X Teams in a league. (Default Top 10 NFL, Top 25 CFB)
• Added Rankings to NCAA FB Manager (replaces Record if ranked)
• Added Rankings to Odds Manager
• Improvements with Dynamic Durations (Not perfect but progress!)
• Various fixes and improvements.

What's Changed

• Add ability to try to download NCAA football logos not found in the assets folder from the ESPN API. by @JScottyR in #15

New Contributors

• @JScottyR made their first contribution in #15

Full Changelog: v2.2...v2.3

Thanks for your patience and comments

v2.2: Web Ui V2, bug fixes, cache improvements

This release is a little rushed but I wanted to get some bug fixes out there. The biggest changes are to the Web Ui v2 and initial startup script. The display seems to be working fine but there are some things in the web ui that don't work.

DO NOT USE THE EDITOR BUTTON IN THE WEB UI it' s very broken and you'll have to restart your pi.

BREAKING CHANGES:
After pulling the latest release, you need to execute sudo python start_web_conditionally.py to install the dependencies for the Web UI v2. It will likely error out when running this.

When it is done, run chmod +x first_time_install.sh followed by sudo bash first_time_install.sh, which resets permissions, sets automatic starting of the webui v2, and -tries- to clean everything up.

When you reboot you should get the web ui automatically started as long as "web_display_autostart": true in your config file.

Having issues? Let me know on discord: https://discord.gg/wQuwSM8tdq

What's Changed

• Sports news ticker with dynamic headline scrolling by @ChuckBuilds in #9
• Enhance web ui with LED matrix configuration and system info by @ChuckBuilds in #11

Full Changelog: v2.1...v2.2

Sorry for the messy release, I am in the middle of packing to move and didn't want to leave y'all hanging with breaking bugs for several more weeks.

v2.1 "OTD" and bug fixes

Summary

• A lot of bug fixes and some formatting improvements
• OTD = "Of The Day" , more on that in a bit
• A ton of font refactoring because bitmap glyphs are hard
• Stock Chart configurations (scroll speed, scroll display, toggle chart)
• Small font and placement adjustments across several displays

OTD = Of The Day Display

🚀 Key Features

• 📚 Multiple Categories: Run multiple "of the day" displays simultaneously (Word of the Day, Language Learning, Bible Verses, etc.)
• 🔄 Smart Rotation: Two-level rotation system with subtitle/description alternation and category switching
• 📅 Daily Content: Each day shows different content based on the day of the year (1–366)
• ⚙️ Highly Configurable: Customize display intervals, rotation timing, and content categories

---

📋 What's Included

Core Implementation

• src/of_the_day_manager.py: Main manager class handling display logic, rotation, and content loading
• of_the_day/OF_THE_DAY_GUIDE.md: Comprehensive documentation and setup guide

Sample Content

• of_the_day/word_of_the_day.json: 366 vocabulary words with definitions and examples
• of_the_day/slovenian_word_of_the_day.json: 366 Slovenian words with English translations

Configuration Integration

• Updated config/config.json with "of_the_day" section
• Integrated with src/display_controller.py for seamless display rotation
• Added to display duration management system

---

🎛️ Configuration

Add this to your config/config.json:

{
  "of_the_day": {
    "rotation_interval": 30,
    "subtitle_interval": 10,
    "categories": ["word_of_the_day", "slovenian_word_of_the_day"]
  }
}

---

🔄 Rotation System

The system features a sophisticated two-level rotation:

• Subtitle/Description Rotation: Within each category, alternates between subtitle and description every 10 seconds
• Category Rotation: Switches between different categories every 30 seconds

Example Display Flow:

[Word of the Day] — Subtitle ➡️ Description ➡️ [Slovenian Word of the Day] — Subtitle ➡️ Description ➡️ ...

---

📊 Data Format

Each category uses a JSON file with this structure:

{
  "1": {
    "title": "EXAMPLE",
    "subtitle": "Definition or Translation",
    "description": "Full explanation or use case"
  }
}

---

🎯 Use Cases

Educational Content

• Vocabulary Word of the Day: Expand your vocabulary with 366 carefully selected words
• Language Learning: Learn new words in different languages (Slovenian included)
• Math Problem of the Day: Daily mathematical challenges
• Science Fact of the Day: Interesting scientific facts and discoveries

Inspirational Content

• Bible Verse of the Day: Daily scripture and spiritual guidance
• Quote of the Day: Motivational and inspirational quotes
• Affirmation of the Day: Positive daily affirmations
• Meditation of the Day: Daily meditation prompts

Professional Development

• Programming Tip of the Day: Daily coding tips and best practices
• Business Quote of the Day: Business wisdom and insights
• Leadership Lesson of the Day: Leadership and management insights

---

🛠️ Technical Features

• Performance Optimized: Data files loaded once at startup, minimal display updates
• Error Handling: Comprehensive logging and error recovery
• Font Integration: Uses custom BDF fonts for optimal LED matrix display
• Text Wrapping: Intelligent text wrapping for long descriptions

---

📖 Documentation

Complete documentation is available in:

• of_the_day/OF_THE_DAY_GUIDE.md

Includes:

• Setup instructions
• Configuration options
• Custom category creation
• Troubleshooting guide

Always a work in progress, let me know if something is broken or behaving unexpectedly.

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!

v1.0.1 Minor Fixes and Updates

Some updates to the Readme and small bug fixes in some displays that hadn't been tested in awhile (NCAA FB)

v1.0.0 - Initial Release!

v1.0.0 - Initial Release

I'm very proud to present the v1.0.0 release of my LEDMatrix Project. This is very much a work in progress but this version seems to be fully functional for me and is at a state that I think is ready for most people.

🎉 Major Features

• Real-time Information Display
  • Clock and weather information
  • Sports scores and schedules
  • Stock and crypto market data
  • Music playback information
  • Custom text displays

📊 Sports Coverage

• Live and upcoming game information for:
  • NHL (Hockey)
  • NBA (Basketball)
  • MLB (Baseball)
  • NFL (Football)
  • NCAA Football
  • NCAA Men's Basketball
  • NCAA Men's Baseball
  • Soccer

🎵 Music Integration

• Spotify integration with authentication
• YouTube Music integration via YTMD Companion Server
• Album art display
• Now playing information with scrolling text

📈 Financial Information

• Real-time stock & crypto price updates
• Stock news headlines
• Customizable watchlists

🌤️ Weather Features

• Current conditions
• Daily forecasts
• Hourly forecasts
• Weather icons display

📅 Calendar Integration

• Google Calendar event display
• Upcoming events view
• Configurable event limits

🛠️ Technical Features

• Modular architecture for easy extension
• Robust caching system for API data
• Configurable display modes and rotation patterns
• Systemd service integration
• Font customization support

🔧 System Requirements

• Raspberry Pi 3b or 4 (NOT RPI5)
• Adafruit RGB Matrix Bonnet/HAT
• 2x LED Matrix panels (64x32)
• DC Power Supply for Adafruit RGB HAT

📝 Configuration

• JSON-based configuration system
• Separate configuration for API keys and secrets
• Customizable display durations
• Configurable sports team preferences
• Adjustable update intervals

🚀 Performance Optimizations

• Hardware timing optimizations
• Caching system for reduced API calls
• Atomic file operations for data safety
• Proper permission management

🔒 Security

• Secure API key management
• OAuth2 authentication for services
• Proper file permissions handling
• Safe configuration templates

📚 Documentation

• Comprehensive README
• Installation instructions
• Configuration guides
• Troubleshooting tips
• Service management documentation

🐛 Known Limitations

• Requires Raspberry Pi 3b or 4 (RPI5 not supported)
• Some sports seasons may need fine-tuning when active
• Requires proper hardware setup for optimal performance
• Some features require premium service accounts (e.g., Spotify)

🔄 Future Improvements

• Additional sports league support
• MQTT Support
• Gambling Information
• Enhanced weather forecasting
• Improved error handling
• Additional display customization options