340 lines
11 KiB
Markdown
340 lines
11 KiB
Markdown
# EOJHL LED Scoreboardx
|
||
|
||
### This is my personal development 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 EOJHL/CCHL only. Besides the clock, I have or will be removing all other modules that are not sports related.
|
||
|
||
### Connect with ChuckBuilds
|
||
|
||
- Git Address: https://github.com/ChuckBuilds/LEDMatrix
|
||
|
||
-----------------------------------------------------------------------------------
|
||
|
||
### Matrix Details
|
||
|
||
<details>
|
||
|
||
<summary>About</summary>
|
||
|
||
|
||
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)
|
||
<img width="2109" height="541" alt="image" src="https://github.com/user-attachments/assets/d10212c9-0d45-4f87-b61d-0a33afb9f160" />
|
||
- NCAA Football (2x 96x48 Displays 2.5mm Pixel Pitch)
|
||
<img width="2417" height="610" alt="image" src="https://github.com/user-attachments/assets/9be92869-ee29-4809-9337-69977f228e23" />
|
||
|
||
- 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)
|
||
</details>
|
||
|
||
-----------------------------------------------------------------------------------
|
||
## Installation Steps
|
||
|
||
<details>
|
||
<summary>System Setup & Installation</summary>
|
||
|
||
# System Setup & Installation
|
||
|
||
1. Open PowerShell and ssh into your Raspberry Pi with ledpi@ledpi (or Username@Hostname)
|
||
```bash
|
||
ssh ledpi@ledpi
|
||
```
|
||
|
||
2. Update repositories, upgrade raspberry pi OS, install git
|
||
```bash
|
||
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:
|
||
```bash
|
||
git clone https://github.com/rampar20/LEDMatrix.git
|
||
cd LEDMatrix
|
||
```
|
||
|
||
|
||
4. First-time installation (recommended)
|
||
|
||
```bash
|
||
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.
|
||
|
||
</details>
|
||
|
||
<details>
|
||
|
||
<summary>Sports Configuration (Football Example)</summary>
|
||
|
||
|
||
## 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
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
</details>
|
||
|
||
-----------------------------------------------------------------------------------
|
||
### Managing the Service
|
||
|
||
<details>
|
||
|
||
<summary>Service Commands</summary>
|
||
|
||
The following commands are available to manage the service:
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
</details>
|
||
|
||
<details>
|
||
|
||
<summary>Convenience Scripts</summary>
|
||
|
||
|
||
### 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:
|
||
```bash
|
||
chmod +x start_display.sh stop_display.sh
|
||
```
|
||
|
||
Then use them to control the service:
|
||
```bash
|
||
sudo ./start_display.sh
|
||
sudo ./stop_display.sh
|
||
```
|
||
</details>
|
||
|
||
-----------------------------------------------------------------------------------
|
||
## Information
|
||
|
||
<details>
|
||
|
||
<summary>Display Settings from RGBLEDMatrix Library</summary>
|
||
|
||
|
||
## 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/...
|
||
|
||
</details>
|
||
|
||
|
||
<details>
|
||
|
||
<summary>Cache Information</summary>
|
||
|
||
|
||
### 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:
|
||
```bash
|
||
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:
|
||
```bash
|
||
chmod +x fix_cache_permissions.sh
|
||
./fix_cache_permissions.sh
|
||
```
|
||
|
||
**Manual Setup:**
|
||
If you prefer to set up manually:
|
||
```bash
|
||
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
|
||
|
||
</details>
|
||
|
||
|
||
<details>
|
||
|
||
<summary>Date Format Configuration </summary>
|
||
|
||
## 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`
|
||
|
||
```json
|
||
"display": {
|
||
"hardware": {
|
||
...
|
||
},
|
||
"runtime": {
|
||
...
|
||
},
|
||
"display_durations": {
|
||
...
|
||
},
|
||
"use_short_date_format": false // Set to true for "8/30" format
|
||
},
|
||
```
|
||
|
||
</details>
|
||
|
||
## 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!
|