LEDMatrix

Setup video and feature walkthrough on Youtube (Outdated but still useful) :

---

Connect with ChuckBuilds

• Show support on Youtube: https://www.youtube.com/@ChuckBuilds
• Check out the write-up on my 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 Me a Coffee : https://buymeacoffee.com/chuckbuilds

---

Special Thanks to:

• Hzeller @ GitHub for his groundwork on controlling an LED Matrix from the Raspberry Pi
• Basmilius @ GitHub for his free and extensive weather icons
• nvstly @ GitHub for their Stock and Crypto Icons
• ESPN for their sports API
• Yahoo Finance for their Stock API
• OpenWeatherMap for their Free Weather API
• Randomwire @ https://www.thingiverse.com/thing:5169867 for their 4mm Pixel Pitch LED Matrix Stand

---

⚠️ Breaking Changes

Important for users upgrading from older versions:

Script paths have been reorganized. If you have automation, cron jobs, or custom tooling that references old script paths, you must update them. See the Migration Guide for details.

Quick Reference:

• Installation scripts moved: install_service.sh → scripts/install/install_service.sh
• Permission scripts moved: fix_cache_permissions.sh → scripts/fix_perms/fix_cache_permissions.sh

Full migration instructions: See MIGRATION_GUIDE.md

---

Core Features

Core Features

## Core Features Modular, rotating Displays that can be individually enabled or disabled per the user's needs with some configuration around display durations, teams, stocks, weather, timezones, and more. Displays include:

Time and Weather

• Real-time clock display (2x 64x32 Displays 4mm Pixel Pitch)

• Current Weather, Daily Weather, and Hourly Weather Forecasts (2x 64x32 Displays 4mm Pixel Pitch)

• Google Calendar event display (2x 64x32 Displays 4mm Pixel Pitch)

Sports Information

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)

Financial Information

• Near real-time stock & crypto price updates
• Stock news headlines
• Customizable stock & crypto watchlists (2x 64x32 Displays 4mm Pixel Pitch)

Entertainment

• Music playback information from multiple sources:
  • Spotify integration
  • YouTube Music integration
• Album art display
• Now playing information with scrolling text (2x 64x32 Displays 4mm Pixel Pitch)

Custom Display Features

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

• Youtube Subscriber Count Display (2x 64x32 Displays 4mm Pixel Pitch)

• Font testing Display (not in rotation)

---

Plugins

LEDMatrix uses a plugin-based architecture where all display functionality (except the core calendar) is implemented as plugins. All managers that were previously built into the core system are now available as plugins through the Plugin Store.

Plugin Store

The easiest way to discover and install plugins is through the Plugin Store in the LEDMatrix web interface:

1. Open the web interface (http://your-pi-ip:5000)
2. Navigate to the Plugin Manager tab
3. Browse available plugins in the Plugin Store
4. Click Install on any plugin you want
5. Configure and enable plugins through the web UI

Installing 3rd-Party Plugins

You can also install plugins directly from GitHub repositories:

• Single Plugin: Install from any GitHub repository URL
• Registry/Monorepo: Install multiple plugins from a single repository

See the Plugin Store documentation for detailed installation instructions.

For plugin development, check out the Hello World Plugin repository as a starter template.

⚠️ Breaking Changes

Important for users upgrading from older versions:

1. Script Path Reorganization: Installation scripts have been moved to scripts/install/:

   • ./install_service.sh → ./scripts/install/install_service.sh
   • ./install_web_service.sh → ./scripts/install/install_web_service.sh
   • ./configure_web_sudo.sh → ./scripts/install/configure_web_sudo.sh

   If you have automation, cron jobs, or custom tooling that references these scripts, you must update them to use the new paths. See the Migration Guide for complete details.

2. Built-in Managers Deprecated: The built-in managers (hockey, football, stocks, etc.) are now deprecated and have been moved to the plugin system. You must install replacement plugins from the Plugin Store in the web interface instead. The plugin system provides the same functionality with better maintainability and extensibility.

---

Hardware

Hardware Requirements

## Hardware Requirements

Raspberry Pi

• Raspberry Pi 3B or 4 (NOT RPi 5!)
  Amazon Affiliate Link – Raspberry Pi 4 4GB

RGB Matrix Bonnet / HAT

• Adafruit RGB Matrix Bonnet/HAT – supports one “chain” of horizontally connected displays
• Adafruit Triple LED Matrix Bonnet – supports up to 3 vertical “chains” of horizontally connected displays (use regular-pi1 as hardware mapping)
• Electrodragon RGB HAT – supports up to 3 vertical “chains”
• Seengreat Matrix Adapter Board – single-chain LED Matrix (use regular as hardware mapping)

LED Matrix Panels

(2x in a chain recommended)

• Adafruit 64×32 – designed for 128×32 but works with dynamic scaling on many displays (pixel pitch is user preference)
• Waveshare 64×32 - Does not require E addressable pad
• Waveshare 92×46 – higher resolution, requires soldering the E addressable pad on the Adafruit RGB Bonnet to “8” OR toggling the DIP switch on the Adafruit Triple LED Matrix Bonnet (no soldering required!)

  Amazon Affiliate Link – ChuckBuilds receives a small commission on purchases

Power Supply

• 5V 4A DC Power Supply (good for 2 -3 displays, depending on brightness and pixel density, you'll need higher amperage for more)
• 5V 10AM DC Power Supply (good for 6-8 displays, depending on brightness and pixel density)

Optional but recommended mod for Adafruit RGB Matrix Bonnet

• By soldering a jumper between pins 4 and 18, you can run a specialized command for polling the matrix display. This provides better brightness, less flicker, and better color.
• If you do the mod, we will use the default config with led-gpio-mapping=adafruit-hat-pwm, otherwise just adjust your mapping in config.json to adafruit-hat
• More information available: https://github.com/hzeller/rpi-rgb-led-matrix/tree/master?tab=readme-ov-file

Possibly required depending on the display you are using.

• Some LED Matrix displays require an "E" addressable line to draw the display properly. The 64x32 Adafruit display does NOT require the E addressable line, however the 92x46 Waveshare display DOES require the "E" Addressable line.
• Various ways to enable this depending on your Bonnet / HAT.

Your display will look like it is "sort of" working but still messed up. or or

How to set addressable E line on various HATs:

• Adafruit Single Chain HATs or

• Adafruit Triple Chain HAT

• ElectroDragon RGB LED Matrix Panel Drive Board

2 Matrix display with Rpi connected to Adafruit Single Chain HAT.

Mount / Stand options

Mount/Stand

I 3D printed stands to keep the panels upright and snug. STL Files are included in the Repo but are also available at https://www.thingiverse.com/thing:5169867 Thanks to "Randomwire" for making these for the 4mm Pixel Pitch LED Matrix.

Special Thanks for Rmatze for making:

• 3mm Pixel Pitch RGB Stand for 32x64 Display : https://www.thingiverse.com/thing:7149818
• 4mm Pixel Pitch RGB Stand for 32x64 Display : https://www.thingiverse.com/thing:7165993

These are not required and you can probably rig up something basic with stuff you have around the house. I used these screws: https://amzn.to/4mFwNJp (Amazon Affiliate Link)

---

Installation Steps

Preparing the Raspberry Pi

Preparing the Raspberry Pi

1. Create RPI Image on a Micro-SD card (I use 16gb because I have it, size is not too important but I would use 8gb or more) using Raspberry Pi Imager
2. Choose your Raspberry Pi (3B+ in my case)
3. For Operating System (OS), choose "Other", then choose Raspbian OS (64-bit) Lite
4. For Storage, choose your micro-sd card
5. Press Next then Edit Settings
6. Inside the OS Customization Settings, choose a name for your device. I use "ledpi". Choose a password, enter your WiFi information, and set your timezone.
7. Under the Services Tab, make sure that SSH is enabled. I recommend using password authentication for ease of use - it is the password you just chose above.
8. Then Click "Save" and Agree to Overwrite the Micro-SD card.

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/ChuckBuilds/LEDMatrix.git
cd LEDMatrix

4. First-time installation (recommended)

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

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

Configuration

Configuration

Configuration

Initial Setup

The system uses a template-based configuration approach to avoid Git conflicts during updates:

1. First-time setup: The previous "First_time_install.sh" script should've already copied the template to create your config.json:

2. Edit your configuration:

   sudo nano config/config.json
   

or edit via web interface at http://ledpi:5000

3. Having Issues?: Run the First Time Script again:

sudo ./first_time_install.sh

API Keys and Secrets

For sensitive settings like API keys:

1. Copy the secrets template: cp config/config_secrets.template.json config/config_secrets.json
2. Edit config/config_secrets.json with your API keys via sudo nano config/config_secrets.json
3. Ctrl + X to exit, Y to overwrite, Enter to Confirm

Automatic Configuration Migration

The system automatically handles configuration updates:

• New installations: Creates config.json from the template automatically
• Existing installations: Automatically adds new configuration options with default values when the system starts
• Backup protection: Creates a backup of your current config before applying updates
• No conflicts: Your custom settings are preserved while new options are added

Everything is configured via config/config.json and config/config_secrets.json. The config.json file is not tracked by Git to prevent conflicts during updates.

Calendar Display Configuration

Calendar Display Configuration

The calendar display module shows upcoming events from your Google Calendar. To configure it:

1. In config/config.json, add the following section:

{
    "calendar": {
        "enabled": true,
        "update_interval": 300,  // Update interval in seconds (default: 300)
        "max_events": 3,         // Maximum number of events to display
        "calendars": ["primary"] // List of calendar IDs to display
    }
}

2. Set up Google Calendar API access:

   1. Go to the Google Cloud Console
   2. Create a new project or select an existing one
   3. Enable the Google Calendar API
   4. Create OAuth 2.0 credentials:
      • Application type: TV and Limited Input Device
      • Download the credentials file as credentials.json
   5. Place the credentials.json file in your project root directory

3. On first run, the application will:

   • Provide a code to enter at https://www.google.com/device for Google authentication
   • Request calendar read-only access
   • Save the authentication token as token.pickle

The calendar display will show:

• Event date and time
• Event title (wrapped to fit the display)
• Up to 3 upcoming events (configurable)

Odds Ticker Configuration

Odds Ticker Configuration

The odds ticker displays betting odds for upcoming sports games. To configure it:

1. In config/config.json, add the following section:

{
    "odds_ticker": {
        "enabled": true,
        "enabled_leagues": ["nfl", "nba", "mlb", "ncaa_fb"],
        "update_interval": 3600,
        "scroll_speed": 2,
        "scroll_delay": 0.05,
        "display_duration": 30
    }
}

Configuration Options

• enabled: Enable/disable the odds ticker (default: false)
• enabled_leagues: Array of leagues to display (options: "nfl", "nba", "mlb", "ncaa_fb")
• update_interval: How often to fetch new odds data in seconds (default: 3600)
• scroll_speed: Pixels to scroll per update (default: 1)
• scroll_delay: Delay between scroll updates in seconds (default: 0.05)
• display_duration: How long to show each game in seconds (default: 30)

How it works:

• The ticker intelligently filters games based on the "show_favorite_teams_only" setting within each individual sport's configuration block (e.g., "nfl_scoreboard"). If set to true for a sport, only favorite teams from that sport will appear in the ticker.
• Games are sorted by the soonest start time.

Display Format

The odds ticker shows information in this format:

[12:00 PM] DAL -6.5 ML -200 O/U 47.5 vs NYG ML +175

Where:

• [12:00 PM] - Game time in local timezone
• DAL - Away team abbreviation
• -6.5 - Spread for away team (negative = favored)
• ML -200 - Money line for away team
• O/U 47.5 - Over/under total
• vs - Separator
• NYG - Home team abbreviation
• ML +175 - Money line for home team

Team Logos

The ticker displays team logos alongside the text:

• Away team logo appears to the left of the text
• Home team logo appears to the right of the text
• Logos are automatically resized to fit the display

Requirements

• ESPN API access for odds data
• Team logo files in the appropriate directories:
  • assets/sports/nfl_logos/
  • assets/sports/nba_logos/
  • assets/sports/mlb_logos/
  • assets/sports/ncaa_logos/

Troubleshooting

No Games Displayed:

1. League Configuration: Ensure the leagues you want are enabled in their respective config sections
2. Favorite Teams: If show_favorite_teams_only is true, ensure you have favorite teams configured
3. API Access: Verify ESPN API is accessible and returning data
4. Time Window: The ticker only shows games in the next 7 days

No Odds Data:

1. API Timing: Odds may not be available immediately when games are scheduled
2. League Support: Not all leagues may have odds data available
3. API Limits: ESPN API may have rate limits or temporary issues

Performance Issues:

1. Reduce scroll_speed: Try setting it to 1 instead of 2
2. Increase scroll_delay: Try 0.1 instead of 0.05
3. Check system resources: Ensure the Raspberry Pi has adequate resources

Testing

You can test the odds ticker functionality using:

python test_odds_ticker.py

This will:

1. Initialize the odds ticker
2. Fetch upcoming games and odds
3. Display sample games
4. Test the scrolling functionality

Stocks Configuration

Stocks Configuration

The stocks display shows real-time stock and crypto prices in a scrolling ticker format. To configure it:

1. In config/config.json, add the following section:

{
    "stocks": {
        "enabled": true,
        "symbols": ["AAPL", "MSFT", "GOOGL", "TSLA"],
        "update_interval": 600,
        "scroll_speed": 1,
        "scroll_delay": 0.01,
        "toggle_chart": false
    }
}

Configuration Options

• enabled: Enable/disable the stocks display (default: false)
• symbols: Array of stock symbols to display (e.g., ["AAPL", "MSFT", "GOOGL"])
• update_interval: How often to fetch new stock data in seconds (default: 600)
• scroll_speed: Pixels to scroll per update (default: 1)
• scroll_delay: Delay between scroll updates in seconds (default: 0.01)
• toggle_chart: Enable/disable mini charts in the scrolling ticker (default: false)

Display Format

The stocks display shows information in this format:

[Logo] SYMBOL
       $PRICE
       +CHANGE (+PERCENT%)

Where:

• [Logo] - Stock/crypto logo (if available)
• SYMBOL - Stock symbol (e.g., AAPL, MSFT)
• $PRICE - Current stock price
• +CHANGE - Price change (green for positive, red for negative)
• +PERCENT% - Percentage change

Chart Toggle Feature

The toggle_chart setting controls whether mini price charts are displayed alongside each stock:

• "toggle_chart": true: Shows mini line charts on the right side of each stock display
• "toggle_chart": false: Shows only text information (symbol, price, change)

When charts are disabled, the text is centered more prominently on the display.

Crypto Support

The system also supports cryptocurrency symbols. Add crypto symbols to the symbols array:

{
    "stocks": {
        "enabled": true,
        "symbols": ["AAPL", "MSFT", "BTC-USD", "ETH-USD"],
        "update_interval": 600,
        "scroll_speed": 1,
        "scroll_delay": 0.01,
        "toggle_chart": false
    }
}

Requirements

• Yahoo Finance API access for stock data
• Stock/crypto logo files in the appropriate directories:
  • assets/stocks/ticker_icons/ (for stocks)
  • assets/stocks/crypto_icons/ (for cryptocurrencies)

Troubleshooting

No Stock Data Displayed:

1. Symbol Format: Ensure stock symbols are correct (e.g., "AAPL" not "apple")
2. API Access: Verify Yahoo Finance API is accessible
3. Market Hours: Some data may be limited during off-hours
4. Symbol Validity: Check that symbols exist and are actively traded

Performance Issues:

1. Reduce scroll_speed: Try setting it to 1 instead of higher values
2. Increase scroll_delay: Try 0.05 instead of 0.01 for smoother scrolling
3. Reduce symbols: Limit the number of symbols to improve performance

Testing

You can test the stocks functionality using:

python test/test_stock_toggle_chart.py

This will:

1. Test the toggle_chart functionality
2. Verify configuration loading
3. Test cache clearing behavior

Football Configuration

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

Music Display Configuration

Music Display Configuration

The Music Display module shows information about the currently playing track from either Spotify or YouTube Music (via the YouTube Music Desktop App companion server).

Setup Requirements:

1. Spotify:

   • Requires a Spotify account (for API access).
   • You need to register an application on the Spotify Developer Dashboard to get API credentials.
     • Go to the dashboard, log in, and click "Create App".
     • Give it a name (e.g., "LEDMatrix Display") and description.
     • For the "Redirect URI", enter http://127.0.0.1:8888/callback (or another unused port if 8888 is taken). You must add this exact URI in your app settings on the Spotify dashboard.
     • Note down the Client ID and Client Secret.

2. YouTube Music (YTM):

   • Requires the YouTube Music Desktop App (YTMD) to be installed and running on a computer on the same network as the Raspberry Pi.
   • In YTMD settings, enable the "Companion Server" under Integration options. Note the URL it provides (usually http://localhost:9863 if running on the same machine, or http://<YTMD-Computer-IP>:9863 if running on a different computer).

preferred_source Options:

• "spotify": Only uses Spotify. Ignores YTM.
• "ytm": Only uses the YTM Companion Server. Ignores Spotify.

Spotify Authentication for Music Display

If you are using the Spotify integration to display currently playing music, you will need to authenticate with Spotify. This project uses an authentication flow that requires a one-time setup. Due to how the display controller script may run with specific user permissions (even when using sudo), the following steps are crucial:

1. Initial Setup & Secrets:

   • Ensure you have your Spotify API Client ID, Client Secret, and Redirect URI.
   • The Redirect URI should be set to http://127.0.0.1:8888/callback in your Spotify Developer Dashboard.
   • Copy config/config_secrets.template.json to config/config_secrets.json.
   • Edit config/config_secrets.json and fill in your Spotify credentials under the "music" section:

     {
       "music": {
         "SPOTIFY_CLIENT_ID": "YOUR_SPOTIFY_CLIENT_ID",
         "SPOTIFY_CLIENT_SECRET": "YOUR_SPOTIFY_CLIENT_SECRET",
         "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
       }
     }
     

2. Run the Authentication Script:

   • Execute the authentication script using sudo. This is important because it needs to create an authentication cache file (spotify_auth.json) that will be owned by root.

     sudo python3 src/authenticate_spotify.py
     

   • The script will output a URL. Copy this URL and paste it into a web browser on any device.
   • Log in to Spotify and authorize the application.
   • Your browser will be redirected to a URL starting with http://127.0.0.1:8888/callback?code=.... It will likely show an error page like "This site can't be reached" – this is expected.
   • Copy the entire redirected URL from your browser's address bar.
   • Paste this full URL back into the terminal when prompted by the script.
   • If successful, it will indicate that token info has been cached.

3. Adjust Cache File Permissions:

   • The main display script (display_controller.py), even when run with sudo, might operate with an effective User ID (e.g., UID 1 for 'daemon') that doesn't have permission to read the spotify_auth.json file created by root (which has -rw------- permissions by default).
   • To allow the display script to read this cache file, change its permissions:

     sudo chmod 644 config/spotify_auth.json
     

   This makes the file readable by all users, including the effective user of the display script.

4. Run the Main Application:

   • You should now be able to run your main display controller script using sudo:

     sudo python3 display_controller.py
     

   • The Spotify client should now authenticate successfully using the cached token.

Why these specific permissions steps?

The authenticate_spotify.py script, when run with sudo, creates config/spotify_auth.json owned by root. If the main display_controller.py (also run with sudo) effectively runs as a different user (e.g., UID 1/daemon, as observed during troubleshooting), that user won't be able to read the root-owned file unless its permissions are relaxed (e.g., to 644). The chmod 644 command allows the owner (root) to read/write, and everyone else (including the daemon user) to read.

Youtube Music Authentication for Music Display

The system can display currently playing music information from YouTube Music Desktop (YTMD) via its Companion server API.

YouTube Display Configuration & API Key

The YouTube display module shows channel statistics for a specified YouTube channel. To configure it:

1. In config/config.json, add the following section:

{
    "youtube": {
        "enabled": true,
        "update_interval": 300  // Update interval in seconds (default: 300)
    }
}

2. In config/config_secrets.json, add your YouTube API credentials:

{
    "youtube": {
        "api_key": "YOUR_YOUTUBE_API_KEY",
        "channel_id": "YOUR_CHANNEL_ID"
    }
}

To get these credentials:

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the YouTube Data API v3
4. Create credentials (API key)
5. For the channel ID, you can find it in your YouTube channel URL or use the YouTube Data API to look it up

Setup:

1. Enable Companion Server in YTMD:

   • In the YouTube Music Desktop application, go to Settings -> Integrations.
   • Enable the "Companion Server".
   • Note the IP address and Port it's listening on (default is usually http://localhost:9863), you'll need to know the local ip address if playing music on a device other than your rpi (probably are).

2. Configure config/config.json:

   • Update the music section in your config/config.json:

     "music": {
         "enabled": true,
         "preferred_source": "ytm",
         "YTM_COMPANION_URL": "http://YOUR_YTMD_IP_ADDRESS:PORT", // e.g., "http://localhost:9863" or "http://192.168.1.100:9863"
         "POLLING_INTERVAL_SECONDS": 1
     }
     

3. Initial Authentication & Token Storage:

   • The first time you run python3 src/authenticate_ytm.py after enabling YTM, it will attempt to register itself with the YTMD Companion Server.
   • You will see log messages in the terminal prompting you to approve the "LEDMatrixController" application within the YouTube Music Desktop app. You typically have 30 seconds to do this.
   • Once approved, an authentication token is saved to your config/ytm_auth.json.
   • This ensures the ledpi user owns the config directory and file, and has the necessary write permissions.

Troubleshooting:

• "No authorized companions" in YTMD: Ensure you've approved the LEDMatrixController in YTMD settings after the first run.
• Connection errors: Double-check the YTM_COMPANION_URL in config.json matches what YTMD's companion server is set to.
• Ensure your firewall (Windows Firewall) allows YTM Desktop app to access local networks.

---

Before Running the Display

• To allow the script to properly access fonts, you need to set the correct permissions on your home directory:

  sudo chmod o+x /home/ledpi
  

• Replace ledpi with your actual username, if different. You can confirm your username by executing: whoami

Running the Display

From the project root directory:

sudo python3 display_controller.py

This will start the display cycle but only stays active as long as your ssh session is active.

---

Run on Startup Automatically with Systemd Service Installation

Run on Startup Automatically with Systemd Service Installation

The LEDMatrix can be installed as a systemd service to run automatically at boot and be managed easily. The service runs as root to ensure proper hardware timing access for the LED matrix.

Installing the Service (this is included in the first_time_install.sh)

1. Make the install script executable:

chmod +x scripts/install/install_service.sh

2. Run the install script with sudo:

sudo ./scripts/install/install_service.sh

The script will:

• Detect your user account and home directory
• Install the service file with the correct paths
• Enable the service to start on boot
• Start the service immediately

Managing the Service

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

-----------------------------------------------------------------------------------

Web Interface Installation (V2)

The LEDMatrix system includes Web Interface V2 that runs on port 5000 and provides real-time display preview, configuration management, and on-demand display controls.

Installing the Web Interface Service

1. Make the install script executable:

chmod +x install_web_service.sh

2. Run the install script with sudo:

sudo ./install_web_service.sh

The script will:

• Copy the web service file to /etc/systemd/system/
• Enable the service to start on boot
• Start the service immediately
• Show the service status

Web Interface Configuration

The web interface can be configured to start automatically with the main display service:

1. In config/config.json, ensure the web interface autostart is enabled:

{
    "web_display_autostart": true
}

2. The web interface will now start automatically when:
   • The system boots
   • The web_display_autostart setting is true in your config

Accessing the Web Interface

Once installed, you can access the web interface at:

http://your-pi-ip:5000

Managing the Web Interface Service

# Check service status
sudo systemctl status ledmatrix-web.service

# View logs
journalctl -u ledmatrix-web.service -f

# Stop the service
sudo systemctl stop ledmatrix-web.service

# Start the service
sudo systemctl start ledmatrix-web.service

# Disable autostart
sudo systemctl disable ledmatrix-web.service

# Enable autostart
sudo systemctl enable ledmatrix-web.service

Web Interface Features

• Real-time Display Preview: See what's currently displayed on the LED matrix
• Configuration Management: Edit settings through a web interface
• On-Demand Controls: Start specific displays (weather, stocks, sports) on demand
• Service Management: Start/stop the main display service
• System Controls: Restart, update code, and manage the system
• API Metrics: Monitor API usage and system performance
• Logs: View system logs in real-time

Troubleshooting Web Interface

Web Interface Not Accessible After Restart:

1. Check if the web service is running: sudo systemctl status ledmatrix-web.service
2. Verify the service is enabled: sudo systemctl is-enabled ledmatrix-web.service
3. Check logs for errors: journalctl -u ledmatrix-web.service -f
4. Ensure web_display_autostart is set to true in config/config.json

Port 5000 Not Accessible:

1. Check if the service is running on the correct port
2. Verify firewall settings allow access to port 5000
3. Check if another service is using port 5000

Service Fails to Start:

1. Check Python dependencies are installed
2. Verify the virtual environment is set up correctly
3. Check file permissions and ownership

---

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 scripts/fix_perms/fix_cache_permissions.sh
sudo ./scripts/fix_perms/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
},

---

Passwordless Sudo for Web Interface Actions

Granting Passwordless Sudo Access for Web Interface Actions

The web interface needs to run certain commands with sudo (e.g., reboot, systemctl start/stop/enable/disable ledmatrix.service, python display_controller.py). To avoid needing to enter a password for these actions through the web UI, you can configure the sudoers file to allow the user running the Flask application to execute these specific commands without a password.

1. Shortcut to automate the below steps: chmod +x configure_web_sudo.sh then ./configure_web_sudo.sh

Manual Method:

WARNING: Be very careful when editing the sudoers file. Incorrect syntax can lock you out of sudo access.

1. Identify the user: Determine which user is running the web_interface.py script. Often, this might be the default user like pi on a Raspberry Pi, or a dedicated user you've set up.

2. Open the sudoers file for editing: Use the visudo command, which locks the sudoers file and checks for syntax errors before saving.

   sudo visudo
   

3. Add the permission lines: Scroll to the bottom of the file and add lines similar to the following. Replace your_flask_user with the actual username running the Flask application. You'll need to specify the full paths to the commands. You can find these using the which command (e.g., which python, which systemctl, which reboot).

   # Allow your_flask_user to run specific commands without a password for the LED Matrix web interface
   your_flask_user ALL=(ALL) NOPASSWD: /sbin/reboot
   your_flask_user ALL=(ALL) NOPASSWD: /bin/systemctl start ledmatrix.service
   your_flask_user ALL=(ALL) NOPASSWD: /bin/systemctl stop ledmatrix.service
   your_flask_user ALL=(ALL) NOPASSWD: /bin/systemctl enable ledmatrix.service
   your_flask_user ALL=(ALL) NOPASSWD: /bin/systemctl disable ledmatrix.service
   your_flask_user ALL=(ALL) NOPASSWD: /usr/bin/python /path/to/your/display_controller.py 
   your_flask_user ALL=(ALL) NOPASSWD: /bin/bash /path/to/your/stop_display.sh
   

   • Important:
     • Replace your_flask_user with the correct username.
     • Replace /path/to/your/display_controller.py with the absolute path to your display_controller.py script.
     • Replace /path/to/your/stop_display.sh with the absolute path to your stop_display.sh script.
     • The paths to python, systemctl, reboot, and bash might vary slightly depending on your system. Use which <command> to find the correct paths if you are unsure. For example, which python might output /usr/bin/python3 - use that full path.

4. Save and Exit:

   • If you're in nano (common default for visudo): Ctrl+X, then Y to confirm, then Enter.
   • If you're in vim: Esc, then :wq, then Enter.

   visudo will check the syntax. If there's an error, it will prompt you to re-edit or quit. Do not quit without fixing errors if possible.

5. Test: After saving, try running one of the specified commands as your_flask_user using sudo from a regular terminal session to ensure it doesn't ask for a password. For example:

   sudo -u your_flask_user sudo /sbin/reboot
   

   (Don't actually reboot if you're not ready, but it should proceed without a password prompt if configured correctly. You can test with a less disruptive command like sudo -u your_flask_user sudo systemctl status ledmatrix.service).

Security Considerations: Granting passwordless sudo access, even for specific commands, has security implications. Ensure that the scripts and commands allowed are secure and cannot be easily exploited. The web interface itself should also be secured if it's exposed to untrusted networks. For display_controller.py and stop_display.sh, ensure their file permissions restrict write access to only trusted users, preventing unauthorized modification of these scripts which run with elevated privileges.

Web Interface V2 (simplified quick start)

1) Run the helper (does the above and starts the server):

python3 start_web_v2.py

2) Start the web UI v2

python web_interface_v2.py

3) Autostart (recommended)

Set "web_display_autostart": true in config/config.json. Ensure your systemd service calls start_web_conditionally.py (installed by install_service.sh).

4) Permissions (optional but recommended)

• Add the service user to systemd-journal for viewing logs without sudo.
• Configure passwordless sudo for actions (start/stop service, reboot, shutdown) if desired.
  • Required for web Ui actions, look in the section above for the commands to run (chmod +x scripts/install/configure_web_sudo.sh & sudo ./scripts/install/configure_web_sudo.sh)

Final Notes

• Most configuration is done via config/config.json
• Refresh intervals for sports/weather/stocks are customizable
• A caching system reduces API strain and helps ensure the display doesn't hammer external services (and ruin it for everyone)
• Font files should be placed in assets/fonts/
• You can test each module individually for debugging

##What's Next?

• Adding MQTT/HomeAssistant integration

If you've read this far — thanks!