From ae3cf3c05bc2b2e87f98f53c41ed98e78596f66c Mon Sep 17 00:00:00 2001 From: ChuckBuilds <33324927+ChuckBuilds@users.noreply.github.com> Date: Wed, 30 Apr 2025 10:16:43 -0500 Subject: [PATCH] update Readme --- README.md | 431 +++++++++++++++++++++++++++--------------------------- 1 file changed, 215 insertions(+), 216 deletions(-) diff --git a/README.md b/README.md index bbd9e277..41147b36 100644 --- a/README.md +++ b/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 < +# 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 < -# 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 -``` -