Initial Commit
This commit is contained in:
339
README.md
339
README.md
@@ -1,2 +1,339 @@
|
||||
# EOJHL-LED-Scoreboard
|
||||
# EOJHL LED Scoreboard
|
||||
|
||||
### 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!
|
||||
|
||||
Reference in New Issue
Block a user