mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-10 13:02:59 +00:00
update Readme
This commit is contained in:
ChuckBuilds
431
README.md
431
README.md
@@ -2,6 +2,8 @@
|
||||
|
||||
A modular LED matrix display system for sports information using Raspberry Pi and RGB LED matrices.
|
||||
|
||||
# Work in Progress, things may break. I'll try to keep the main branch as stable as I can but this is absolutely in a pre-release state. There are also a ton of commits as it's an easy way to get the changes to the rpi for testing.
|
||||
|
||||
## Hardware Requirements
|
||||
- Raspberry Pi 4 or older
|
||||
- Adafruit RGB Matrix Bonnet/HAT
|
||||
@@ -32,6 +34,193 @@ cp config/config.example.json config/config.json
|
||||
|
||||
2. Edit `config/config.json` with your preferences
|
||||
|
||||
|
||||
## Important: Sound Module Configuration
|
||||
|
||||
1. Remove unnecessary services that might interfere with the LED matrix:
|
||||
```bash
|
||||
sudo apt-get remove bluez bluez-firmware pi-bluetooth triggerhappy pigpio
|
||||
```
|
||||
|
||||
2. Blacklist the sound module:
|
||||
```bash
|
||||
cat <<EOF | sudo tee /etc/modprobe.d/blacklist-rgb-matrix.conf
|
||||
blacklist snd_bcm2835
|
||||
EOF
|
||||
|
||||
sudo update-initramfs -u
|
||||
```
|
||||
|
||||
3. Reboot:
|
||||
```bash
|
||||
sudo reboot
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
To reduce flickering and improve display quality:
|
||||
|
||||
1. Edit `/boot/firmware/cmdline.txt`:
|
||||
```bash
|
||||
sudo nano /boot/firmware/cmdline.txt
|
||||
```
|
||||
|
||||
2. Add `isolcpus=3` at the end of the line
|
||||
|
||||
3. Add `dtparam=audio=off` at the end of the line
|
||||
|
||||
4. Ctrl + X to exit, Y to save
|
||||
|
||||
5. Save and reboot:
|
||||
```bash
|
||||
sudo reboot
|
||||
```
|
||||
|
||||
### Running without Sudo (Optional and not recommended)
|
||||
|
||||
To run the display script without `sudo`, the user executing the script needs access to GPIO pins. Add the user to the `gpio` group:
|
||||
|
||||
```bash
|
||||
sudo usermod -a -G gpio <your_username>
|
||||
# Example for user 'ledpi':
|
||||
# sudo usermod -a -G gpio ledpi
|
||||
```
|
||||
|
||||
**Important:** You must **reboot** the Raspberry Pi after adding the user to the group for the change to take effect.
|
||||
|
||||
You also need to disable hardware pulsing in the code (see `src/display_manager.py`, set `options.disable_hardware_pulsing = True`). This may result in a flickerying display
|
||||
|
||||
If configured correctly, you can then run:
|
||||
|
||||
```bash
|
||||
python3 display_controller.py
|
||||
```
|
||||
|
||||
## Running the Display
|
||||
|
||||
From the project root directory:
|
||||
```bash
|
||||
sudo python3 display_controller.py
|
||||
```
|
||||
|
||||
The display will alternate between showing:
|
||||
- Current time
|
||||
- Weather information (requires API key configuration)
|
||||
|
||||
## 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
|
||||
|
||||
1. Make the install script executable:
|
||||
```bash
|
||||
chmod +x install_service.sh
|
||||
```
|
||||
|
||||
2. Run the install script with sudo:
|
||||
```bash
|
||||
sudo ./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:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
## API Keys
|
||||
|
||||
For sensitive settings like API keys:
|
||||
1. Copy the 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 save
|
||||
|
||||
## NHL, NBA, MLB Scoreboard Display
|
||||
|
||||
The LEDMatrix system includes a comprehensive NHL, NBA scoreboard display system with three display modes:
|
||||
|
||||
### Display Modes
|
||||
- **Live Games**: Shows currently playing games with live scores and game status
|
||||
- **Recent Games**: Displays completed games from the last 48 hours (configurable)
|
||||
- **Upcoming Games**: Shows scheduled games for favorite teams
|
||||
|
||||
### Features
|
||||
- Real-time score updates from ESPN API
|
||||
- Team logo display
|
||||
- Game status indicators (period, time remaining)
|
||||
- Power play and penalty information
|
||||
- Configurable favorite teams
|
||||
- Automatic game switching
|
||||
- Built-in caching to reduce API calls
|
||||
- Test mode for development
|
||||
|
||||
### Configuration
|
||||
In `config.json`, under the `nhl_scoreboard` section:
|
||||
```json
|
||||
{
|
||||
"nhl_scoreboard": {
|
||||
"enabled": true,
|
||||
"test_mode": false,
|
||||
"update_interval_seconds": 300,
|
||||
"live_update_interval": 60,
|
||||
"recent_update_interval": 1800,
|
||||
"upcoming_update_interval": 1800,
|
||||
"recent_game_hours": 48,
|
||||
"favorite_teams": ["TB", "DAL"],
|
||||
"logo_dir": "assets/sports/nhl_logos",
|
||||
"display_modes": {
|
||||
"nhl_live": true,
|
||||
"nhl_recent": true,
|
||||
"nhl_upcoming": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### YouTube Display Configuration
|
||||
|
||||
The YouTube display module shows channel statistics for a specified YouTube channel. To configure it:
|
||||
@@ -98,56 +287,36 @@ The calendar display will show:
|
||||
- Event title (wrapped to fit the display)
|
||||
- Up to 3 upcoming events (configurable)
|
||||
|
||||
## API Keys
|
||||
## Development
|
||||
|
||||
For sensitive settings like API keys:
|
||||
1. Copy the 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 save
|
||||
|
||||
|
||||
## Important: Sound Module Configuration
|
||||
|
||||
1. Remove unnecessary services that might interfere with the LED matrix:
|
||||
```bash
|
||||
sudo apt-get remove bluez bluez-firmware pi-bluetooth triggerhappy pigpio
|
||||
The project structure is organized as follows:
|
||||
```
|
||||
|
||||
2. Blacklist the sound module:
|
||||
```bash
|
||||
cat <<EOF | sudo tee /etc/modprobe.d/blacklist-rgb-matrix.conf
|
||||
blacklist snd_bcm2835
|
||||
EOF
|
||||
|
||||
sudo update-initramfs -u
|
||||
LEDMatrix/
|
||||
├── config/ # Configuration files
|
||||
│ ├── config.json # Main configuration
|
||||
│ └── config_secrets.json # API keys and sensitive data
|
||||
├── src/ # Source code
|
||||
│ ├── config_manager.py # Configuration loading
|
||||
│ ├── display_manager.py # LED matrix display handling
|
||||
│ ├── clock.py # Clock display module
|
||||
│ ├── weather_manager.py # Weather display module
|
||||
│ ├── stock_manager.py # Stock ticker display module
|
||||
│ └── stock_news_manager.py # Stock news display module
|
||||
└── display_controller.py # Main application controller
|
||||
```
|
||||
## Project Structure
|
||||
|
||||
3. Reboot:
|
||||
```bash
|
||||
sudo reboot
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
To reduce flickering and improve display quality:
|
||||
|
||||
1. Edit `/boot/firmware/cmdline.txt`:
|
||||
```bash
|
||||
sudo nano /boot/firmware/cmdline.txt
|
||||
```
|
||||
|
||||
2. Add `isolcpus=3` at the end of the line
|
||||
|
||||
3. Add `dtparam=audio=off` at the end of the line
|
||||
|
||||
4. Ctrl + X to exit, Y to save
|
||||
|
||||
5. Save and reboot:
|
||||
```bash
|
||||
sudo reboot
|
||||
```
|
||||
- `src/`
|
||||
- `display_controller.py` - Main application controller
|
||||
- `config_manager.py` - Configuration management
|
||||
- `display_manager.py` - LED matrix display handling
|
||||
- `clock.py` - Clock display module
|
||||
- `weather_manager.py` - Weather display module
|
||||
- `stock_manager.py` - Stock ticker display module
|
||||
- `stock_news_manager.py` - Stock news display module
|
||||
- `config/`
|
||||
- `config.json` - Configuration settings
|
||||
- `config_secrets.json` - Private settings (not in git)
|
||||
|
||||
## Caching System
|
||||
|
||||
@@ -181,175 +350,5 @@ The LEDMatrix system includes a robust caching mechanism to optimize API calls a
|
||||
- Temporary files are used for safe updates
|
||||
- JSON serialization handles all data types including timestamps
|
||||
|
||||
## NHL, NBA Scoreboard Display
|
||||
|
||||
The LEDMatrix system includes a comprehensive NHL, NBA scoreboard display system with three display modes:
|
||||
|
||||
### Display Modes
|
||||
- **Live Games**: Shows currently playing games with live scores and game status
|
||||
- **Recent Games**: Displays completed games from the last 48 hours (configurable)
|
||||
- **Upcoming Games**: Shows scheduled games for favorite teams
|
||||
|
||||
### Features
|
||||
- Real-time score updates from ESPN API
|
||||
- Team logo display
|
||||
- Game status indicators (period, time remaining)
|
||||
- Power play and penalty information
|
||||
- Configurable favorite teams
|
||||
- Automatic game switching
|
||||
- Built-in caching to reduce API calls
|
||||
- Test mode for development
|
||||
|
||||
### Configuration
|
||||
In `config.json`, under the `nhl_scoreboard` section:
|
||||
```json
|
||||
{
|
||||
"nhl_scoreboard": {
|
||||
"enabled": true,
|
||||
"test_mode": false,
|
||||
"update_interval_seconds": 300,
|
||||
"live_update_interval": 60,
|
||||
"recent_update_interval": 1800,
|
||||
"upcoming_update_interval": 1800,
|
||||
"recent_game_hours": 48,
|
||||
"favorite_teams": ["TB", "DAL"],
|
||||
"logo_dir": "assets/sports/nhl_logos",
|
||||
"display_modes": {
|
||||
"nhl_live": true,
|
||||
"nhl_recent": true,
|
||||
"nhl_upcoming": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Running without Sudo (Optional)
|
||||
|
||||
To run the display script without `sudo`, the user executing the script needs access to GPIO pins. Add the user to the `gpio` group:
|
||||
|
||||
```bash
|
||||
sudo usermod -a -G gpio <your_username>
|
||||
# Example for user 'ledpi':
|
||||
# sudo usermod -a -G gpio ledpi
|
||||
```
|
||||
|
||||
**Important:** You must **reboot** the Raspberry Pi after adding the user to the group for the change to take effect.
|
||||
|
||||
You also need to disable hardware pulsing in the code (see `src/display_manager.py`, set `options.disable_hardware_pulsing = True`). This may result in a flickerying display
|
||||
|
||||
If configured correctly, you can then run:
|
||||
|
||||
```bash
|
||||
python3 display_controller.py
|
||||
```
|
||||
|
||||
## Running the Display
|
||||
|
||||
From the project root directory:
|
||||
```bash
|
||||
sudo python3 display_controller.py
|
||||
```
|
||||
|
||||
The display will alternate between showing:
|
||||
- Current time
|
||||
- Weather information (requires API key configuration)
|
||||
|
||||
## Development
|
||||
|
||||
The project structure is organized as follows:
|
||||
```
|
||||
LEDMatrix/
|
||||
├── config/ # Configuration files
|
||||
│ ├── config.json # Main configuration
|
||||
│ └── config_secrets.json # API keys and sensitive data
|
||||
├── src/ # Source code
|
||||
│ ├── config_manager.py # Configuration loading
|
||||
│ ├── display_manager.py # LED matrix display handling
|
||||
│ ├── clock.py # Clock display module
|
||||
│ ├── weather_manager.py # Weather display module
|
||||
│ ├── stock_manager.py # Stock ticker display module
|
||||
│ └── stock_news_manager.py # Stock news display module
|
||||
└── display_controller.py # Main application controller
|
||||
```
|
||||
## Project Structure
|
||||
|
||||
- `src/`
|
||||
- `display_controller.py` - Main application controller
|
||||
- `config_manager.py` - Configuration management
|
||||
- `display_manager.py` - LED matrix display handling
|
||||
- `clock.py` - Clock display module
|
||||
- `weather_manager.py` - Weather display module
|
||||
- `stock_manager.py` - Stock ticker display module
|
||||
- `stock_news_manager.py` - Stock news display module
|
||||
- `config/`
|
||||
- `config.json` - Configuration settings
|
||||
- `config_secrets.json` - Private settings (not in git)
|
||||
|
||||
|
||||
## Fonts
|
||||
You can add any font to the assets/fonts/ folder but they need to be .ttf and updated in display_manager.py
|
||||
|
||||
## 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
|
||||
|
||||
1. Make the install script executable:
|
||||
```bash
|
||||
chmod +x install_service.sh
|
||||
```
|
||||
|
||||
2. Run the install script with sudo:
|
||||
```bash
|
||||
sudo ./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:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user