# 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)
![DSC01356](https://github.com/user-attachments/assets/64c359b6-4b99-4dee-aca0-b74debda30e0)
![DSC01339](https://github.com/user-attachments/assets/2ccc52af-b4ed-4c06-a341-581506c02153)
![DSC01337](https://github.com/user-attachments/assets/f4faf678-9f43-4d37-be56-89ecbd09acf6)

- NBA (Basketball)
- MLB (Baseball) (2x 64x32 Displays 4mm Pixel Pitch)
![DSC01359](https://github.com/user-attachments/assets/71e985f1-d2c9-4f0e-8ea1-13eaefeec01c)

- 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)
![DSC01379](https://github.com/user-attachments/assets/338b7578-9d4b-4465-851c-7e6a1d999e07)

- 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!  
