LEDMatrix

This is my personal testing fork.

• Any details you need about hardware or setting up the RPI can be found on the main ChuckBuilds github page.
• This fork will be for sports only. Besides the clock, I have or will be removing all other modules that are not sports related.
• Please send all love and thanks to ChuckBuilds for this project, I take and expect zero credit for this great project.

Connect with ChuckBuilds

• Show support on Youtube: https://www.youtube.com/@ChuckBuilds
• Check out the write-up on the ChuckBuilds website: https://www.chuck-builds.com/led-matrix/
• Stay in touch on Instagram: https://www.instagram.com/ChuckBuilds/
• Want to chat? Reach out on the ChuckBuilds Discord: https://discord.com/invite/uW36dVAtcT
• Feeling Generous? Buy ChuckBuilds a Coffee : https://buymeacoffee.com/chuckbuilds

---

Matrix Details

About

The system supports live, recent, and upcoming game information for multiple sports leagues:

• NHL (Hockey) (2x 64x32 Displays 4mm Pixel Pitch)

• NBA (Basketball)

• MLB (Baseball) (2x 64x32 Displays 4mm Pixel Pitch)

• NFL (Football) (2x 96x48 Displays 2.5mm Pixel Pitch)

• NCAA Football (2x 96x48 Displays 2.5mm Pixel Pitch)

• NCAA Men's Basketball

• NCAA Men's Baseball

• Soccer (Premier League, La Liga, Bundesliga, Serie A, Ligue 1, Liga Portugal, Champions League, Europa League, MLS)

• (Note, some of these sports seasons were not active during development and might need fine tuning when games are active)

Custom Display Features

• Custom Text display (2x 64x32 Displays 4mm Pixel Pitch)

• Font testing Display (not in rotation)

---

Installation Steps

System Setup & Installation

System Setup & Installation

1. Open PowerShell and ssh into your Raspberry Pi with ledpi@ledpi (or Username@Hostname)

ssh ledpi@ledpi

2. Update repositories, upgrade raspberry pi OS, install git

sudo apt update && sudo apt upgrade -y
sudo apt install -y git python3-pip cython3 build-essential python3-dev python3-pillow scons

3. Clone this repository:

git clone https://github.com/rampar20/LEDMatrix.git
cd LEDMatrix

4. First-time installation (recommended)

chmod +x first_time_install.sh
sudo ./first_time_install.sh

This single script installs services, dependencies, configures permissions and sudoers, and validates the setup.

Sports Configuration (Football Example)

Football Game-Based Configuration (NFL & NCAA FB)

For NFL and NCAA Football, the system now uses a game-based fetch approach instead of time-based windows. This is more practical for football since games are weekly and you want to show specific numbers of games rather than arbitrary time periods.

Configuration Options

Instead of using past_fetch_days and future_fetch_days, the system now uses:

• fetch_past_games: Number of recent games to fetch (default: 1)
• fetch_future_games: Number of upcoming games to fetch (default: 1)

Example Configuration

{
    "nfl_scoreboard": {
        "enabled": true,
        "fetch_past_games": 1,
        "fetch_future_games": 1,
        "favorite_teams": ["TB", "DAL"]
    },
    "ncaa_fb_scoreboard": {
        "enabled": true,
        "fetch_past_games": 1,
        "fetch_future_games": 1,
        "favorite_teams": ["UGA", "AUB"]
    }
}

How It Works

• fetch_past_games: 1: Shows the most recent game for your favorite teams
• fetch_future_games: 1: Shows the next upcoming game for your favorite teams
• fetch_future_games: 2: Shows the next two upcoming games (e.g., Week 1 and Week 2 matchups)

Benefits

1. Predictable Results: Always shows exactly the number of games you specify
2. Season Flexibility: Works well both during the season and in the off-season
3. Future Planning: Can show games far in the future (e.g., Week 1 when it's 40 days away)
4. Efficient: Only fetches the games you actually want to see

Use Cases

• During Season: fetch_future_games: 1 shows next week's game
• Off-Season: fetch_future_games: 1 shows the first scheduled game (even if it's months away)
• Planning: fetch_future_games: 2 shows the next two matchups for planning purposes

---

Managing the Service

Service Commands

The following commands are available to manage the service:

# Stop the display
sudo systemctl stop ledmatrix.service

# Start the display
sudo systemctl start ledmatrix.service

# Check service status
sudo systemctl status ledmatrix.service

# View logs
journalctl -u ledmatrix.service

# Disable autostart
sudo systemctl disable ledmatrix.service

# Enable autostart
sudo systemctl enable ledmatrix.service

Convenience Scripts

Convenience Scripts

Two convenience scripts are provided for easy service management:

• start_display.sh - Starts the LED matrix display service
• stop_display.sh - Stops the LED matrix display service

Make them executable with:

chmod +x start_display.sh stop_display.sh

Then use them to control the service:

sudo ./start_display.sh
sudo ./stop_display.sh

---

Information

Display Settings from RGBLEDMatrix Library

Display Settings

If you are copying my setup, you can likely leave this alone.

• hardware: Configures how the matrix is driven.
  • rows, cols, chain_length: Physical panel configuration.
  • brightness: Display brightness (0–100).
  • hardware_mapping: Use "adafruit-hat-pwm" for Adafruit bonnet WITH the jumper mod. Remove -pwm if you did not solder the jumper.
  • pwm_bits, pwm_dither_bits, pwm_lsb_nanoseconds: Affect color fidelity.
  • limit_refresh_rate_hz: Cap refresh rate for better stability.
• runtime:
  • gpio_slowdown: Tweak this depending on your Pi model. Match it to the generation (e.g., Pi 3 → 3, Pi 4 -> 4).
• display_durations:
  • Control how long each display module stays visible in seconds. For example, if you want more focus on stocks, increase that value.

Modules

• Each module (weather, stocks, crypto, calendar, etc.) has enabled, update_interval, and often display_format settings.
• Sports modules also support test_mode, live_update_interval, and favorite_teams.
• Logos are loaded from the logo_dir path under assets/sports/...

Cache Information

Persistent Caching Setup

The LEDMatrix system uses persistent caching to improve performance and reduce API calls. When running with sudo, the system needs a persistent cache directory that survives restarts.

First-Time Setup: Run the setup script to create a persistent cache directory:

chmod +x setup_cache.sh
./setup_cache.sh

This will:

• Create /var/cache/ledmatrix/ directory
• Set proper ownership to your user account
• Set permissions to allow the daemon user (which the system runs as) to write
• Test writability for both your user and the daemon user

If You Still See Cache Warnings: If you see warnings about using temporary cache directory, run the permissions fix:

chmod +x fix_cache_permissions.sh
./fix_cache_permissions.sh

Manual Setup: If you prefer to set up manually:

sudo mkdir -p /var/cache/ledmatrix
sudo chown $USER:$USER /var/cache/ledmatrix
sudo chmod 777 /var/cache/ledmatrix

Cache Locations (in order of preference):

1. ~/.ledmatrix_cache/ (user's home directory) - Most persistent
2. /var/cache/ledmatrix/ (system cache directory) - Persistent across restarts
3. /opt/ledmatrix/cache/ (alternative persistent location)
4. /tmp/ledmatrix_cache/ (temporary directory) - NOT persistent

Note: If the system falls back to /tmp/ledmatrix_cache/, you'll see a warning message and the cache will not persist across restarts.

Caching System

The LEDMatrix system includes a robust caching mechanism to optimize API calls and reduce network traffic:

Cache Location

• Default cache directory: /tmp/ledmatrix_cache
• Cache files are stored with proper permissions (755 for directories, 644 for files)
• When running as root/sudo, cache ownership is automatically adjusted to the real user

Cached Data Types

• Weather data (current conditions and forecasts)
• Stock prices and market data
• Stock news headlines
• ESPN game information

Cache Behavior

• Data is cached based on update intervals defined in config.json
• Cache is automatically invalidated when:
  • Update interval has elapsed
  • Market is closed (for stock data)
  • Data has changed significantly
• Failed API calls fall back to cached data when available
• Cache files use atomic operations to prevent corruption

Cache Management

• Cache files are automatically created and managed
• No manual intervention required
• Cache directory is created with proper permissions on first run
• Temporary files are used for safe updates
• JSON serialization handles all data types including timestamps

Date Format Configuration

Date Format Configuration

You can customize the date format for upcoming games across all sports displays. The use_short_date_format setting in config/config.json under the display section controls this behavior.

• "use_short_date_format": true: Displays dates in a short, numerical format (e.g., "8/30").
• "use_short_date_format": false (Default): Displays dates in a more descriptive format with an ordinal suffix (e.g., "Aug 30th").

Example config.json

"display": {
    "hardware": {
        ...
    },
    "runtime": {
        ...
    },
    "display_durations": {
        ...
    },
    "use_short_date_format": false // Set to true for "8/30" format
},

Final Notes

• Most configuration is done via config/config.json
• A caching system reduces API strain and helps ensure the display doesn't hammer external services (and ruin it for everyone)
• I purposely did not include the same detailed information as the main project readme, if you need those details please visit the main project GIT.

If you've read this far — thanks!