mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-10 21:03:01 +00:00
Update README.md
Signed-off-by: Chuck <33324927+ChuckBuilds@users.noreply.github.com>
This commit is contained in:
Chuck
215
README.md
215
README.md
@@ -16,18 +16,30 @@ Modular, rotating Displays that can be individually enabled or disabled per the
|
|||||||
|
|
||||||
### Time and Weather
|
### Time and Weather
|
||||||
- Real-time clock display
|
- Real-time clock display
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
- Current Weather, Daily Weather, and Hourly Weather Forecasts
|
- Current Weather, Daily Weather, and Hourly Weather Forecasts
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
- Google Calendar event display
|
- Google Calendar event display
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Sports Information
|
### Sports Information
|
||||||
The system supports live, recent, and upcoming game information for multiple sports leagues:
|
The system supports live, recent, and upcoming game information for multiple sports leagues:
|
||||||
- NHL (Hockey)
|
- NHL (Hockey)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
- NBA (Basketball)
|
- NBA (Basketball)
|
||||||
- MLB (Baseball)
|
- MLB (Baseball)
|
||||||
|
|
||||||
|
|
||||||
- NFL (Football)
|
- NFL (Football)
|
||||||
- NCAA Football
|
- NCAA Football
|
||||||
@@ -40,6 +52,8 @@ The system supports live, recent, and upcoming game information for multiple spo
|
|||||||
- Near real-time stock & crypto price updates
|
- Near real-time stock & crypto price updates
|
||||||
- Stock news headlines
|
- Stock news headlines
|
||||||
- Customizable stock & crypto watchlists
|
- Customizable stock & crypto watchlists
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -49,15 +63,19 @@ The system supports live, recent, and upcoming game information for multiple spo
|
|||||||
- YouTube Music integration
|
- YouTube Music integration
|
||||||
- Album art display
|
- Album art display
|
||||||
- Now playing information with scrolling text
|
- Now playing information with scrolling text
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Custom Display Features
|
### Custom Display Features
|
||||||
- Custom Text display
|
- Custom Text display
|
||||||
- Youtube Subscriber Count Display
|
|
||||||
|
|
||||||
- Font testing and customization
|
- Youtube Subscriber Count Display
|
||||||
- Configurable display modes
|
|
||||||
|
|
||||||
|
- Font testing Display (not in rotation)
|
||||||
|
|
||||||
## System Architecture
|
## System Architecture
|
||||||
|
|
||||||
@@ -79,24 +97,26 @@ The system can be configured through a JSON configuration file that allows users
|
|||||||
|
|
||||||
|
|
||||||
## Hardware Requirements
|
## Hardware Requirements
|
||||||
- Raspberry Pi 3b or 4 (NOT RPI5!)
|
- Raspberry Pi 3b or 4 (NOT RPI5!) : Amazon Affiliate Link: Raspberry Pi 4 4GB (https://amzn.to/4dJixuX)
|
||||||
-- Amazon Affiliate Link: Raspberry Pi 4 4GB (https://amzn.to/4dJixuX)
|
- Adafruit RGB Matrix Bonnet/HAT : https://www.adafruit.com/product/3211
|
||||||
- Adafruit RGB Matrix Bonnet/HAT
|
- 2x LED Matrix panels (64x32) (Designed for 128x32 but has a lot of dynamic scaling elements that could work on a variety of displays, pixel pitch is user preference) : https://www.adafruit.com/product/2278
|
||||||
-- https://www.adafruit.com/product/3211
|
- 5V 4A DC Power Supply for Adafruit RGB HAT : https://www.adafruit.com/product/1466
|
||||||
- 2x LED Matrix panels (64x32) (Designed for 128x32 but has a lot of dynamic scaling elements that could work on a variety of displays, pixel pitch is user preference)
|
|
||||||
-- https://www.adafruit.com/product/2278
|
|
||||||
- 5V 4A DC Power Supply for Adafruit RGB HAT
|
|
||||||
-- https://www.adafruit.com/product/1466
|
|
||||||
|
|
||||||
## Optional but recommended mod for Adafruit RGB Matrix Bonnet
|
## Optional but recommended mod for Adafruit RGB Matrix Bonnet
|
||||||
- By soldering a jumper between pins 4 and 18, you can run a specialized command for polling the matrix display. This provides better brightness, less flicker, and better color.
|
- By soldering a jumper between pins 4 and 18, you can run a specialized command for polling the matrix display. This provides better brightness, less flicker, and better color.
|
||||||
- If you do the mod, we will use the command: --led-gpio-mapping=adafruit-hat-pwm, otherwise just use --led-gpio-mapping=adafruit-hat
|
- If you do the mod, we will use the default config with led-gpio-mapping=adafruit-hat-pwm, otherwise just adjust your mapping in config.json to adafruit-hat
|
||||||
- More information available: https://github.com/hzeller/rpi-rgb-led-matrix/tree/master?tab=readme-ov-file
|
- More information available: https://github.com/hzeller/rpi-rgb-led-matrix/tree/master?tab=readme-ov-file
|
||||||
|
|
||||||
|
|
||||||
|
-----------------------------------------------------------------------------------
|
||||||
|
## Mount/Stand
|
||||||
|
I 3D printed stands to keep the panels upright and snug. STL Files are included in the Repo but are also available at https://www.thingiverse.com/thing:5169867 Thanks to "Randomwire" for making these for the 4mm Pixel Pitch LED Matrix.
|
||||||
|
|
||||||
|
These are not required and you can probably rig up something basic with stuff you have around the house. I used these screws: https://amzn.to/4mFwNJp (Amazon Affiliate Link)
|
||||||
|
|
||||||
Overall 2 Matrix display with Rpi connected.
|
-----------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
2 Matrix display with Rpi connected.
|
||||||
|
|
||||||
|
|
||||||
-----------------------------------------------------------------------------------
|
-----------------------------------------------------------------------------------
|
||||||
@@ -119,8 +139,10 @@ Overall 2 Matrix display with Rpi connected.
|
|||||||
|
|
||||||
# System Setup & Installation
|
# System Setup & Installation
|
||||||
|
|
||||||
1. Open PowerShell and ssh into your Raspberry Pi with ledpi@ledpi
|
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
|
2. Update repositories, upgrade raspberry pi OS, install git
|
||||||
```bash
|
```bash
|
||||||
@@ -141,7 +163,7 @@ sudo pip3 install --break-system-packages -r requirements.txt
|
|||||||
--break-system-packages allows us to install without a virtual environment
|
--break-system-packages allows us to install without a virtual environment
|
||||||
|
|
||||||
|
|
||||||
5. Install rpi-rgb-led-matrix dependenices:
|
5. Install rpi-rgb-led-matrix dependencies:
|
||||||
```bash
|
```bash
|
||||||
cd rpi-rgb-led-matrix-master
|
cd rpi-rgb-led-matrix-master
|
||||||
```
|
```
|
||||||
@@ -193,7 +215,7 @@ sudo nano /boot/firmware/cmdline.txt
|
|||||||
|
|
||||||
2. Add `isolcpus=3` at the end of the line
|
2. Add `isolcpus=3` at the end of the line
|
||||||
|
|
||||||
3. Ctrl + X to exit, Y to save
|
3. Ctrl + X to exit, Y to save, Enter to Confirm
|
||||||
|
|
||||||
4. Edit /boot/firmware/config.txt with
|
4. Edit /boot/firmware/config.txt with
|
||||||
```bash
|
```bash
|
||||||
@@ -202,7 +224,7 @@ sudo nano /boot/firmware/config.txt
|
|||||||
|
|
||||||
6. Edit the `dtparam=audio=on` section to `dtparam=audio=off`
|
6. Edit the `dtparam=audio=on` section to `dtparam=audio=off`
|
||||||
|
|
||||||
7. Ctrl + X to exit, Y to save
|
7. Ctrl + X to exit, Y to save, Enter to Confirm
|
||||||
|
|
||||||
8. Save and reboot:
|
8. Save and reboot:
|
||||||
```bash
|
```bash
|
||||||
@@ -220,7 +242,7 @@ sudo reboot
|
|||||||
For sensitive settings like API keys:
|
For sensitive settings like API keys:
|
||||||
Copy the template: `cp config/config_secrets.template.json config/config_secrets.json`
|
Copy the template: `cp config/config_secrets.template.json config/config_secrets.json`
|
||||||
Edit `config/config_secrets.json` with your API keys via `sudo nano config/config_secrets.json`
|
Edit `config/config_secrets.json` with your API keys via `sudo nano config/config_secrets.json`
|
||||||
Ctrl + X to exit, Y to overwrite, Enter to save
|
Ctrl + X to exit, Y to overwrite, Enter to Confirm
|
||||||
|
|
||||||
Everything is configured via `config/config.json` and `config/config_secrets.json`.
|
Everything is configured via `config/config.json` and `config/config_secrets.json`.
|
||||||
|
|
||||||
@@ -228,57 +250,7 @@ Everything is configured via `config/config.json` and `config/config_secrets.jso
|
|||||||
|
|
||||||
-----------------------------------------------------------------------------------
|
-----------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## Calendar Display Configuration
|
||||||
|
|
||||||
# Configuration
|
|
||||||
|
|
||||||
1.Edit `config/config.json` with your preferences via `sudo nano config/config.json`
|
|
||||||
|
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### YouTube Display Configuration
|
|
||||||
|
|
||||||
The YouTube display module shows channel statistics for a specified YouTube channel. To configure it:
|
|
||||||
|
|
||||||
1. In `config/config.json`, add the following section:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"youtube": {
|
|
||||||
"enabled": true,
|
|
||||||
"update_interval": 300 // Update interval in seconds (default: 300)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
2. In `config/config_secrets.json`, add your YouTube API credentials:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"youtube": {
|
|
||||||
"api_key": "YOUR_YOUTUBE_API_KEY",
|
|
||||||
"channel_id": "YOUR_CHANNEL_ID"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
To get these credentials:
|
|
||||||
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
|
|
||||||
2. Create a new project or select an existing one
|
|
||||||
3. Enable the YouTube Data API v3
|
|
||||||
4. Create credentials (API key)
|
|
||||||
5. For the channel ID, you can find it in your YouTube channel URL or use the YouTube Data API to look it up
|
|
||||||
|
|
||||||
### Calendar Display Configuration
|
|
||||||
|
|
||||||
The calendar display module shows upcoming events from your Google Calendar. To configure it:
|
The calendar display module shows upcoming events from your Google Calendar. To configure it:
|
||||||
|
|
||||||
@@ -313,7 +285,7 @@ The calendar display will show:
|
|||||||
- Event title (wrapped to fit the display)
|
- Event title (wrapped to fit the display)
|
||||||
- Up to 3 upcoming events (configurable)
|
- Up to 3 upcoming events (configurable)
|
||||||
|
|
||||||
### Music Display Configuration
|
## Music Display Configuration
|
||||||
|
|
||||||
The Music Display module shows information about the currently playing track from either Spotify or YouTube Music (via the [YouTube Music Desktop App](https://ytmdesktop.app/) companion server).
|
The Music Display module shows information about the currently playing track from either Spotify or YouTube Music (via the [YouTube Music Desktop App](https://ytmdesktop.app/) companion server).
|
||||||
|
|
||||||
@@ -335,7 +307,7 @@ The Music Display module shows information about the currently playing track fro
|
|||||||
* `"spotify"`: Only uses Spotify. Ignores YTM.
|
* `"spotify"`: Only uses Spotify. Ignores YTM.
|
||||||
* `"ytm"`: Only uses the YTM Companion Server. Ignores Spotify.
|
* `"ytm"`: Only uses the YTM Companion Server. Ignores Spotify.
|
||||||
|
|
||||||
## Spotify Authentication for Music Display
|
### Spotify Authentication for Music Display
|
||||||
|
|
||||||
If you are using the Spotify integration to display currently playing music, you will need to authenticate with Spotify. This project uses an authentication flow that requires a one-time setup. Due to how the display controller script may run with specific user permissions (even when using `sudo`), the following steps are crucial:
|
If you are using the Spotify integration to display currently playing music, you will need to authenticate with Spotify. This project uses an authentication flow that requires a one-time setup. Due to how the display controller script may run with specific user permissions (even when using `sudo`), the following steps are crucial:
|
||||||
|
|
||||||
@@ -389,6 +361,37 @@ The `authenticate_spotify.py` script, when run with `sudo`, creates `config/spot
|
|||||||
|
|
||||||
The system can display currently playing music information from [YouTube Music Desktop (YTMD)](https://ytmdesktop.app/) via its Companion server API.
|
The system can display currently playing music information from [YouTube Music Desktop (YTMD)](https://ytmdesktop.app/) via its Companion server API.
|
||||||
|
|
||||||
|
### YouTube Display Configuration & API Key
|
||||||
|
|
||||||
|
The YouTube display module shows channel statistics for a specified YouTube channel. To configure it:
|
||||||
|
|
||||||
|
1. In `config/config.json`, add the following section:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"youtube": {
|
||||||
|
"enabled": true,
|
||||||
|
"update_interval": 300 // Update interval in seconds (default: 300)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. In `config/config_secrets.json`, add your YouTube API credentials:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"youtube": {
|
||||||
|
"api_key": "YOUR_YOUTUBE_API_KEY",
|
||||||
|
"channel_id": "YOUR_CHANNEL_ID"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
To get these credentials:
|
||||||
|
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
|
||||||
|
2. Create a new project or select an existing one
|
||||||
|
3. Enable the YouTube Data API v3
|
||||||
|
4. Create credentials (API key)
|
||||||
|
5. For the channel ID, you can find it in your YouTube channel URL or use the YouTube Data API to look it up
|
||||||
|
|
||||||
**Setup:**
|
**Setup:**
|
||||||
|
|
||||||
1. **Enable Companion Server in YTMD:**
|
1. **Enable Companion Server in YTMD:**
|
||||||
@@ -418,6 +421,7 @@ The system can display currently playing music information from [YouTube Music D
|
|||||||
* Connection errors: Double-check the `YTM_COMPANION_URL` in `config.json` matches what YTMD's companion server is set to.
|
* Connection errors: Double-check the `YTM_COMPANION_URL` in `config.json` matches what YTMD's companion server is set to.
|
||||||
* Ensure your firewall (Windows Firewall) allows YTM Desktop app to access local networks.
|
* Ensure your firewall (Windows Firewall) allows YTM Desktop app to access local networks.
|
||||||
|
|
||||||
|
-----------------------------------------------------------------------------------
|
||||||
|
|
||||||
## Before Running the Display
|
## Before Running the Display
|
||||||
- To allow the script to properly access fonts, you need to set the correct permissions on your home directory:
|
- To allow the script to properly access fonts, you need to set the correct permissions on your home directory:
|
||||||
@@ -435,6 +439,10 @@ From the project root directory:
|
|||||||
```bash
|
```bash
|
||||||
sudo python3 display_controller.py
|
sudo python3 display_controller.py
|
||||||
```
|
```
|
||||||
|
This will start the display cycle but only stays active as long as your ssh session is active.
|
||||||
|
|
||||||
|
|
||||||
|
-----------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
## Run on Startup Automatically with Systemd Service Installation
|
## Run on Startup Automatically with Systemd Service Installation
|
||||||
@@ -502,10 +510,17 @@ sudo ./stop_display.sh
|
|||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Fonts
|
-----------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## Custom Fonts
|
||||||
You can add any font to the assets/fonts/ folder but they need to be .ttf or .btf(less support) and updated in display_manager.py
|
You can add any font to the assets/fonts/ folder but they need to be .ttf or .btf(less support) and updated in display_manager.py
|
||||||
|
|
||||||
### Running without Sudo (Optional and not recommended but can be useful for troubleshooting or overcoming write errors)
|
|
||||||
|
|
||||||
|
-----------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
### Running the display without Sudo (Not recommended but can be useful for troubleshooting or overcoming write errors)
|
||||||
|
|
||||||
To run the display script without `sudo`, the user executing the script needs access to GPIO pins. Add the user to the `gpio` group:
|
To run the display script without `sudo`, the user executing the script needs access to GPIO pins. Add the user to the `gpio` group:
|
||||||
|
|
||||||
@@ -526,6 +541,40 @@ python3 display_controller.py
|
|||||||
```
|
```
|
||||||
-----------------------------------------------------------------------------------
|
-----------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## 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/...
|
||||||
|
|
||||||
|
```bash
|
||||||
|
Example: NHL Configuration"nhl_scoreboard": {
|
||||||
|
"enabled": true,
|
||||||
|
"test_mode": false,
|
||||||
|
"update_interval_seconds": 300,
|
||||||
|
"live_update_interval": 15,
|
||||||
|
"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
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
@@ -632,3 +681,19 @@ The LEDMatrix system includes a robust caching mechanism to optimize API calls a
|
|||||||
- Cache directory is created with proper permissions on first run
|
- Cache directory is created with proper permissions on first run
|
||||||
- Temporary files are used for safe updates
|
- Temporary files are used for safe updates
|
||||||
- JSON serialization handles all data types including timestamps
|
- JSON serialization handles all data types including timestamps
|
||||||
|
|
||||||
|
## Final Notes
|
||||||
|
- Most configuration is done via config/config.json
|
||||||
|
- Refresh intervals for sports/weather/stocks are customizable
|
||||||
|
- A caching system reduces API strain and helps ensure the display doesn’t hammer external services (and ruin it for everyone)
|
||||||
|
- Font files should be placed in assets/fonts/
|
||||||
|
- You can test each module individually for debugging
|
||||||
|
|
||||||
|
|
||||||
|
##What's Next?
|
||||||
|
- Adding MQTT/HomeAssistant integration
|
||||||
|
- Gambling odds?
|
||||||
|
- Building a user-friendly UI for easier configuration
|
||||||
|
|
||||||
|
|
||||||
|
### If you’ve read this far — thanks!
|
||||||
|
|||||||
Reference in New Issue
Block a user