mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-04 22:35:08 +00:00
ChuckandClaude Opus 5
f9b3d6ae52
* fix(web): accept every panel size and row address type the rgbmatrix library does The Display form capped columns at 128 and chain length at 24, and its submit handler (fixInvalidNumberInputs) rewrote anything larger to the cap, so wide panels and long chains silently saved as the wrong size. The config API checked none of the hardware numbers, so values the library rejects (odd rows, parallel 4, PWM dither bits 3) saved and the matrix then refused to start. - Form limits now match the pinned library: rows even 8-64, cols >= 16 and chain_length >= 1 with no upper bound, parallel 1-3, PWM dither bits 0-2, PWM LSB nanoseconds 50-3000. - save_main_config rejects out-of-range rows, cols, chain_length, parallel, brightness, scan_mode, pwm_bits, pwm_dither_bits, pwm_lsb_nanoseconds and gpio_slowdown with a 400. - A stored gpio_slowdown or pwm_dither_bits of 0 renders as 0 instead of the default, so saving the tab no longer overwrites it. - Row Address Type offers 5 (SM5368 / B707 row shift register). Verified on a Waveshare 96x48 V2 (24S-A1) on a Pi 4 with the Adafruit Triple LED Matrix Bonnet: rows 48, cols 96, row address type 5, BGR, GPIO slowdown 8. - Help text and docs: FM6124-family panels use Panel Type Standard; on a Pi 5 the library supports only row address types 0 and 2. No change to the rpi-rgb-led-matrix submodule. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(web): drop the rows cap and document every display setting accurately Rows: no upper limit in the form or the API. Still even and at least 8. The current rgbmatrix library rejects more than 64 per panel, so a larger value saves but the matrix won't start; the help tip, README, config reference and troubleshooting section all say so, and nothing here needs changing if the library lifts the limit. limit_refresh_rate_hz: the form accepts 0 (the library's "no cap"), a stored 0 no longer renders and re-saves as 120, and the API rejects negatives. pwm_dither_bits stays 0-2: the library rejects 3 and 4, so the old form's 0-4 only ever let users save a config the display couldn't start with. Docs and help tips, checked against the pinned library and its README: - panel_type and rp1_rio get README entries - show_refresh_rate prints to stdout; it never drew on the panel - dither bits raise the refresh rate; the tip said they lowered it - scan_mode is about interlacing at low refresh, not wrong colours - disable_hardware_pulsing: hardware pulsing needs OE on GPIO 18 and the onboard sound driver off; software timing makes rows flash brighter - gpio_slowdown guidance agrees between the README and the UI - all 22 multiplexing values listed; every numeric setting states its range - troubleshooting for a blank panel after a settings change, jumping rows and brightness flashes Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(web): reject true and 5.5 for row_address_type and multiplexing Both still went straight through int(), so a JSON true saved as 1 and 5.5 as 5. They now use the shared hardware range check like the other panel fields. Review feedback on #586. Also: the RP1 Backend tooltip said it is ignored on Pi 3/4 (it is ignored on every model but the Pi 5), and the README gave the dynamic-duration default cap as 90s; the code default is 180s. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat: refuse matrix settings a Raspberry Pi 5 can't drive On a Pi 5 the pinned rgbmatrix library drives the panel through the RP1 chip, and that path supports only row address types 0 and 2, parallel 1-3 and the regular / regular-pi1 / classic / adafruit-hat(-pwm) mappings (Rp1PioConfigSupported in lib/rp1/rp1_pio_backend.cc). For anything else CreateFromOptions returns NULL; the Python binding doesn't check, so the display process crashed on its first call into the matrix and systemd restarted it into the same crash every 10 seconds. - src/pi5_matrix_support.py: the rule and Pi 5 detection, matching the library's /proc/device-tree/model check - DisplayManager raises before creating the matrix, so it is a logged init failure (reported by /api/v3/hardware/status) and fallback mode - the config API rejects those settings on a Pi 5 when a request sets row_address_type, parallel or hardware_mapping - the Display form offers only row address types 0 and 2 on a Pi 5, and warns when a stored value can't be used - CLAUDE.md: re-check the rule whenever the submodule is bumped Review feedback on #586. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
995 lines
46 KiB
Markdown
995 lines
46 KiB
Markdown
# LEDMatrix
|
||
[](LICENSE)
|
||
[](https://discord.gg/RdrC37rEag)
|
||
[](https://github.com/ChuckBuilds/ledmatrix)
|
||
[](https://app.codacy.com/gh/ChuckBuilds/LEDMatrix/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
|
||
|
||
|
||
## Welcome to LEDMatrix!
|
||
Welcome to the LEDMatrix Project! This open-source project enables you to run an information-rich display on a Raspberry Pi connected to an LED RGB Matrix panel. Whether you want to see your calendar, weather forecasts, sports scores, stock prices, or any other information at a glance, LEDMatrix brings it all together.
|
||
|
||
### About This Project
|
||
|
||
LEDMatrix is a constantly evolving project that I'm building to create a customizable information display. The project is designed to be modular and extensible, with a plugin-based architecture that makes it easy to add new features and displays.
|
||
|
||
**This project is open source and supports third-party plugin development.** I believe that great projects get better when more people are involved, and I'm excited to see what the community can build together. Whether you want to contribute to the core project, develop your own plugins, or just use and enjoy LEDMatrix, you're welcome here!
|
||
|
||
### A Note from the ChuckBuilds
|
||
I'm very new to all of this and am *heavily* relying on AI development tools to create this project. This means I'm learning as I go, and I'm grateful for your patience and feedback as the project continues to evolve and improve.
|
||
|
||
I'm trying to be open to constructive criticism and support, as long as it's a realistic ask and aligns with my priorities on this project. If you have ideas for improvements, find bugs, or want to add features to the base project, please don't hesitate to reach out on Discord or submit a pull request. Similarly, if you want to develop a plugin of your own, please do so! I'd love to see what you create.
|
||
|
||
|
||
### Installing the LEDMatrix project on a pi video:
|
||
[](https://www.youtube.com/watch?v=bkT0f1tZI0Y)
|
||
|
||
### Setup video and feature walkthrough on Youtube (Outdated but still useful) :
|
||
[](https://www.youtube.com/watch?v=_HaqfJy1Y54)
|
||
|
||
|
||
-----------------------------------------------------------------------------------
|
||
### Connect with ChuckBuilds
|
||
|
||
- Show support on Youtube: https://www.youtube.com/@ChuckBuilds
|
||
- Check out the write-up on my website: https://www.chuck-builds.com/led-matrix/
|
||
- Stay in touch on Instagram: https://www.instagram.com/ChuckBuilds/
|
||
- Want to chat? Reach out on the LEDMatrix Discord: [https://discord.com/invite/uW36dVAtcT](https://discord.gg/dfFwsasa6W)
|
||
- Feeling Generous? Consider sponsoring this project or sending a donation (these AI credits aren't cheap!)
|
||
|
||
-----------------------------------------------------------------------------------
|
||
|
||
### Special Thanks to:
|
||
- [Hzeller](https://github.com/hzeller/rpi-rgb-led-matrix) for his groundwork on controlling an LED Matrix from the Raspberry Pi
|
||
- [Cursor](https://cursor.com/home) for making this project possible
|
||
- [CodeRabbit](https://github.com/coderabbitai) for fixing my PR's
|
||
- Everyone involved in this project for their patience, input, and support
|
||
|
||
-----------------------------------------------------------------------------------
|
||
|
||
## Core Features
|
||
|
||
<details>
|
||
<summary>Core Features</summary>
|
||
LEDMatrix is a plugin platform: the displays below are plugins installed
|
||
from the built-in Plugin Store (web interface → Plugins), where each can be
|
||
individually enabled, ordered, and configured — display durations, teams,
|
||
stocks, weather, timezones, and more. The core repo ships with just two
|
||
bundled plugins (`starlark-apps` and `web-ui-info`); the official plugins
|
||
live in the [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
||
monorepo and install with one click, and third-party plugins can be
|
||
installed from their own GitHub repositories. Displays available in the
|
||
store include:
|
||
|
||
### Time and Weather
|
||
- Real-time clock display (2x 64x32 Displays 4mm Pixel Pitch)
|
||
|
||
|
||
|
||
- Current Weather, Daily Weather, and Hourly Weather Forecasts (2x 64x32 Displays 4mm Pixel Pitch)
|
||
|
||
|
||
|
||
|
||
|
||
- Google Calendar event display (2x 64x32 Displays 4mm Pixel Pitch)
|
||
|
||
|
||
|
||
|
||
### Sports Information
|
||
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)
|
||
|
||
|
||
### Financial Information
|
||
- Near real-time stock & crypto price updates
|
||
- Stock news headlines
|
||
- Customizable stock & crypto watchlists (2x 64x32 Displays 4mm Pixel Pitch)
|
||
|
||
|
||
|
||
|
||
|
||
### Entertainment
|
||
- Music playback information from multiple sources:
|
||
- Spotify integration
|
||
- YouTube Music integration
|
||
- Album art display
|
||
- Now playing information with scrolling text (2x 64x32 Displays 4mm Pixel Pitch)
|
||
|
||
|
||
|
||
|
||
|
||
### Custom Display Features
|
||
- Custom Text display (2x 64x32 Displays 4mm Pixel Pitch)
|
||
|
||
|
||
- Youtube Subscriber Count Display (2x 64x32 Displays 4mm Pixel Pitch)
|
||
|
||
|
||
</details>
|
||
|
||
-----------------------------------------------------------------------------------
|
||
## Hardware
|
||
|
||
<details>
|
||
<summary>Hardware Requirements</summary>
|
||
|
||
## Hardware Requirements
|
||
|
||
| ⚠️ IMPORTANT |
|
||
| :--- |
|
||
| This project can be finnicky! RGB LED Matrix displays are not built the same or to a high-quality standard. We have seen many displays arrive dead or partially working in our discord. Please purchase from a reputable vendor. |
|
||
|
||
### Raspberry Pi
|
||
- Raspberry Pi Zero's don't have enough processing power for this project.
|
||
- **Raspberry Pi 3B, 4, or 5**
|
||
[Amazon Affiliate Link – Raspberry Pi 4 4GB RAM](https://amzn.to/4dJixuX)
|
||
[Amazon Affiliate Link – Raspberry Pi 4 8GB RAM](https://amzn.to/4qbqY7F)
|
||
- **Pi 5 users**: the installer automatically detects Pi 5 and builds the `rpi-rgb-led-matrix` library with RP1 support. If you previously installed on a Pi 4 and migrated the SD card, or if you see `mmap` errors in the logs, force a fresh library build:
|
||
```bash
|
||
sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh
|
||
```
|
||
- Pi 5 config: leave `rp1_rio` at `0` (PIO mode, default) and set `gpio_slowdown` to `1` or `2`.
|
||
- **1GB models (Pi 3B / 3B+) and other low-memory boards**: supported, but the `rpi-rgb-led-matrix` C++ build needs more memory than the Pi has. The installer detects this automatically, compiles with fewer parallel jobs, and adds a temporary swapfile for the build which it removes afterwards. Expect that step to take 15-25 minutes instead of 2-5, and leave at least **3GB free** on the SD card. If you manage swap yourself, opt out with `--skip-swap`. To pin the compiler down further, use `--build-jobs 1`.
|
||
|
||
|
||
### RGB Matrix Bonnet / HAT
|
||
- [Adafruit RGB Matrix Bonnet/HAT](https://www.adafruit.com/product/3211) – supports one “chain” of horizontally connected displays
|
||
- [Adafruit Triple LED Matrix Bonnet](https://www.adafruit.com/product/6358) – supports up to 3 vertical “chains” of horizontally connected displays *(use `regular-pi1` as hardware mapping)*
|
||
- [Electrodragon RGB HAT](https://www.electrodragon.com/product/rgb-matrix-panel-drive-board-raspberry-pi/) – supports up to 3 vertical “chains”
|
||
- [Seengreat Matrix Adapter Board](https://amzn.to/3KsnT3j) – single-chain LED Matrix *(use `regular` as hardware mapping)*
|
||
|
||
### LED Matrix Panels
|
||
(2x in a horizontal chain is recommended)
|
||
- [Adafruit 64×32](https://www.adafruit.com/product/2278) – designed for 128×32 but works with dynamic scaling on many displays (pixel pitch is user preference)
|
||
**Warning: Lately the Waveshare Panels have had different variations - only some are compatible with this project. I hope to identify what is different to fix it but so far there is a decent chance you get a mis-matched set of panels if you don't buy them all at once! **
|
||
- [Waveshare 64×32](https://amzn.to/3Kw55jK) - Does not require E addressable pad
|
||
- [Waveshare 96×48](https://amzn.to/4bydNcv) – higher resolution, requires soldering the **E addressable pad** on the [Adafruit RGB Bonnet](https://www.adafruit.com/product/3211) to “8” **OR** toggling the DIP switch on the Adafruit Triple LED Matrix Bonnet *(no soldering required!)*
|
||
- There are some Panels on Aliexpress that have worked fine for me, shop around! I think Adafruit is probably the "safest" but they do have some limitation on resolution and layout.
|
||
> Amazon Affiliate Links – ChuckBuilds receives a small commission on purchases
|
||
|
||
### Power Supply
|
||
- [5V 4A DC Power Supply](https://www.adafruit.com/product/658) (good for 2 -3 displays, depending on brightness and pixel density, you'll need higher amperage for more)
|
||
- [5V 10A DC Power Supply](https://amzn.to/3IKlYqe) (good for 6-8 displays, depending on brightness and pixel density)
|
||
|
||
## 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.
|
||
- 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
|
||
|
||
|
||
## Possibly required depending on the display you are using.
|
||
- Some LED Matrix displays require an "E" addressable line to draw the display properly. The [64x32 Adafruit display](https://www.adafruit.com/product/2278) does NOT require the E addressable line, however the [96x48 Waveshare display](https://amzn.to/4pQdezE) DOES require the "E" Addressable line.
|
||
- Various ways to enable this depending on your Bonnet / HAT.
|
||
|
||
Your display will look like it is "sort of" working but still messed up.
|
||
<img width="841" height="355" alt="image" src="https://github.com/user-attachments/assets/7b8cfa98-270c-4c41-9cdc-146535eec32f" />
|
||
or
|
||
<img width="924" height="316" alt="image" src="https://github.com/user-attachments/assets/fda59057-faca-401b-8d55-f0e360cadbdf" />
|
||
or
|
||
<img width="1363" height="703" alt="image" src="https://github.com/user-attachments/assets/0e833721-1690-4446-a6a9-7c48eed7a633" />
|
||
|
||
How to set addressable E line on various HATs:
|
||
|
||
- Adafruit Single Chain HATs
|
||
<img width="719" height="958" alt="IMG_5228" src="https://github.com/user-attachments/assets/b30e839c-6fc9-4129-a99c-0f4eaf62c89d" />
|
||
or
|
||
<img width="349" height="302" alt="image" src="https://github.com/user-attachments/assets/2175fa40-98a8-4da7-bcd3-d6b1714e33d2" />
|
||
|
||
- Adafruit Triple Chain HAT
|
||
|
||
|
||
- ElectroDragon RGB LED Matrix Panel Drive Board
|
||
|
||
|
||
|
||
|
||
|
||
|
||
2 Matrix display with Rpi connected to Adafruit Single Chain HAT.
|
||
|
||
|
||
|
||
</details>
|
||
|
||
<details>
|
||
|
||
<summary>Mount / Stand options</summary>
|
||
|
||
|
||
## 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.
|
||
|
||
Special Thanks for Rmatze for making:
|
||
- 3mm Pixel Pitch RGB Stand for 32x64 Display : https://www.thingiverse.com/thing:7149818
|
||
- 4mm Pixel Pitch RGB Stand for 32x64 Display : https://www.thingiverse.com/thing:7165993
|
||
|
||
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)
|
||
|
||
</details>
|
||
|
||
-----------------------------------------------------------------------------------
|
||
## Installation Steps
|
||
|
||
<details>
|
||
|
||
<summary>Preparing the Raspberry Pi</summary>
|
||
|
||
# Preparing the Raspberry Pi
|
||
|
||
| ⚠️ IMPORTANT |
|
||
| :--- |
|
||
| It is required to use the **NEW** Raspberry Pi Imager tool. If your tool doesn't look like my screenshots, be sure to update it. |
|
||
|
||
1. Create RPI Image on a Micro-SD card (I use whatever I have laying around, size is not too important but I would use 8gb or more) using [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
|
||
|
||
2. Choose your Raspberry Pi (3B+ in my case)
|
||
|
||
<img width="512" height="361" alt="Step 1 rpi" src="https://github.com/user-attachments/assets/4d42961c-97f3-46d6-8e3f-b4ac04615ec7" />
|
||
|
||
3. For Operating System (OS), choose "Other"
|
||
|
||
<img width="512" height="361" alt="Step 2 Other " src="https://github.com/user-attachments/assets/166a22e8-8067-48df-9f80-50c91f573356" />
|
||
|
||
5. Then choose Raspbian OS (64-bit) Lite (Trixie)
|
||
|
||
<img width="512" height="361" alt="Step 4 Trixie Lite 64" src="https://github.com/user-attachments/assets/3b8590ce-b810-4dfe-9253-26e0d4f8ed1e" />
|
||
|
||
6. For Storage, choose your micro-sd card
|
||
|
||
| ⚠️ IMPORTANT |
|
||
| :--- |
|
||
| Make sure it's the correct drive! Data will be erased! |
|
||
|
||
<img width="512" height="361" alt="Step 5 Select storage" src="https://github.com/user-attachments/assets/d2840c6b-2a07-45a4-bfd4-2a73ee790e87" />
|
||
|
||
7. Choose the hostname of the device. This will be often used to access the web-ui and will be the name of the device on your network. I recommend "ledpi".
|
||
|
||
<img width="512" height="361" alt="Step 6 name storage" src="https://github.com/user-attachments/assets/e782ef1e-49c6-4483-9791-96f34c27235d" />
|
||
|
||
8. Choose your timezone and keyboard layout.
|
||
|
||
<img width="512" height="361" alt="Step 7 Choose Timezone" src="https://github.com/user-attachments/assets/6cf38b5a-ec72-42af-93b8-e6f5b0874fa6" />
|
||
|
||
9. Set your username and password. This is your "root" password and is important, make sure you remember it! We will use it to access the Raspberry Pi via SSH.
|
||
|
||
<img width="512" height="361" alt="Step 8 set password for root" src="https://github.com/user-attachments/assets/5a3f9eb2-b2fd-4db3-8c51-490fff091fd4" />
|
||
|
||
10. (Optional) Choose your Wi-fi network and enter wifi password. This can be changed in the future. This is also optional if you are going to connect it via ethermet.
|
||
|
||
<img width="512" height="361" alt="Step 9 choose network" src="https://github.com/user-attachments/assets/0ac9c69b-d29c-454f-a6ed-ffdaa778729d" />
|
||
|
||
11. Enable SSH and opt for "Use Password Authentication". You can use public key auth if you know how but for the sake of new folks, let's use the password that we chose in Step 9.
|
||
|
||
<img width="512" height="361" alt="Step 10 enable Ssh and choose password authentication" src="https://github.com/user-attachments/assets/a2df9994-8be5-4785-9f4c-a2888edb5c78" />
|
||
|
||
12. Disable Raspberry Pi Connect. It's a VPN / Remote Connection tool built into Raspberry Pi, it seems like there might be a subscription? Not sure but I am not using it.
|
||
|
||
<img width="512" height="361" alt="step 11 disable RPI connect" src="https://github.com/user-attachments/assets/63808069-b620-49db-a102-76e2b75ad055" />
|
||
|
||
13. Double check your settings then confirm by clicking "Write".
|
||
|
||
<img width="512" height="361" alt="step 12 write to disk" src="https://github.com/user-attachments/assets/77a0d193-2953-4c52-971c-3069f55ac70e" />
|
||
|
||
14. Final warning to be SURE that you have the correct micro-sd card inserted and selected as all data on the drive will be erased.
|
||
|
||
<img width="512" height="361" alt="Step 13 be very sure you are using the right drive" src="https://github.com/user-attachments/assets/9a46447e-3be6-4838-9114-27415869a3c6" />
|
||
|
||
You're done with preparing the Operating System. Once the Raspberry Pi Imager has finished writing to the micro-sd card it will let you know it is safe to eject. Eject the micro-sd card and plug it into the Raspberry Pi and turn it on.
|
||
</details>
|
||
|
||
<details>
|
||
|
||
<summary>System Setup & Installation</summary>
|
||
|
||
# System Setup & Installation
|
||
|
||
Once your Raspberry Pi has turned on and connected to your wifi (check your router's dhcp leases) or just give it a few minutes after plugging it in. We will connect via ssh.
|
||
|
||
Secure Shell (SSH) is a way to connect to the device and execute commands. On Windows, I recommend using Powershell. On MacOS or Linux, I recommend using Terminal.
|
||
|
||
1. SSH into your Raspberry Pi:
|
||
```bash
|
||
ssh ledpi@ledpi
|
||
```
|
||
The format "username@hostname" is coincidentally the same for this project (which is fine) but if you changed the username, hostname, or your router's DNS doesn't recognize the hostname you would use "username@ipaddress". You can skip the username and just enter "ssh hostname" or "ssh ipaddress" and it will prompt you for a username.
|
||
|
||
## Quick Install (Recommended)
|
||
|
||
Paste this single command into SSH using <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>V</kbd> on Windows or <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>V</kbd> on Mac.
|
||
|
||
> [!TIP]
|
||
> Terminal can be funky about pasting with just <kbd>Ctrl</kbd>+<kbd>V</kbd>, by right click -> paste or using <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>V</kbd> you will be able to paste without additional unwanted characters.
|
||
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/ChuckBuilds/LEDMatrix/main/scripts/install/one-shot-install.sh | bash
|
||
```
|
||
|
||
This one-shot installer will automatically:
|
||
- Check system prerequisites (network, disk space, memory, sudo access)
|
||
- Install required system packages (git, python3, build tools, etc.)
|
||
- Clone or update the LEDMatrix repository
|
||
- Run the complete first-time installation script
|
||
|
||
The installation process typically takes 10-30 minutes depending on your internet connection and Pi model. Pi 3B/3B+ and other 1GB boards land at the top of that range, because the C++ library is compiled serially to stay within available memory. All errors are reported explicitly with actionable fixes.
|
||
|
||
**Note:** The script is safe to run multiple times and will handle existing installations gracefully.
|
||
|
||
|
||
|
||
|
||
<details>
|
||
<summary>Manual Installation (Alternative)</summary>
|
||
|
||
If you prefer to install manually or the one-shot installer doesn't work for your setup:
|
||
|
||
1. SSH into your Raspberry Pi:
|
||
```bash
|
||
ssh ledpi@ledpi
|
||
```
|
||
|
||
2. Update repositories, upgrade Raspberry Pi OS, and install prerequisites:
|
||
```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/ChuckBuilds/LEDMatrix.git
|
||
cd LEDMatrix
|
||
```
|
||
|
||
4. Run the first-time installation script:
|
||
```bash
|
||
chmod +x first_time_install.sh
|
||
sudo bash ./first_time_install.sh
|
||
```
|
||
|
||
This single script installs services, dependencies, configures permissions and sudoers, and validates the setup.
|
||
|
||
It finishes by asking whether to reboot. If you run it non-interactively — piped, over a script, or with `-y` — there is no one to ask, so **it reboots immediately without prompting**. Pass `--no-reboot-prompt` to install without rebooting:
|
||
|
||
```bash
|
||
sudo bash ./first_time_install.sh -y --no-reboot-prompt
|
||
```
|
||
|
||
</details>
|
||
|
||
</details>
|
||
|
||
|
||
## Configuration
|
||
|
||
<details>
|
||
|
||
<summary>Configuration</summary>
|
||
|
||
## Configuration
|
||
|
||
### Initial Setup
|
||
|
||
For a complete list of every key in `config.json` and
|
||
`config_secrets.json`, see
|
||
[docs/CONFIG_REFERENCE.md](docs/CONFIG_REFERENCE.md).
|
||
|
||
For most settings I recommend using the web interface:
|
||
Edit the project via the web interface at http://[IP ADDRESS or HOSTNAME]:5000 or http://ledpi:5000 .
|
||
|
||
If you need to manually edit your config file, you can follow the steps below:
|
||
<details>
|
||
<summary>Manual Config.json editing </summary>
|
||
|
||
1. **First-time setup**:
|
||
The previous "First_time_install.sh" script should've already copied the template to create your config.json:
|
||
|
||
2. **Edit your configuration**:
|
||
```bash
|
||
sudo nano config/config.json
|
||
```
|
||
</details>
|
||
|
||
|
||
### Automatic Configuration Migration
|
||
|
||
The system automatically handles configuration updates:
|
||
- **New installations**: Creates `config.json` from the template automatically
|
||
- **Existing installations**: Automatically adds new configuration options with default values when the system starts
|
||
- **Backup protection**: Creates a backup of your current config before applying updates
|
||
- **No conflicts**: Your custom settings are preserved while new options are added
|
||
|
||
Everything is configured via `config/config.json` and `config/config_secrets.json` and are not tracked by Git to prevent conflicts during updates.
|
||
|
||
</details>
|
||
|
||
|
||
## Running the Display
|
||
|
||
<details>
|
||
<summary>Recommended: Use Web UI Quick Actions</summary>
|
||
|
||
I recommend using the web-ui "Quick Actions" to control the Display.
|
||
|
||
<img width="2009" height="201" alt="image" src="https://github.com/user-attachments/assets/49e4db32-05f7-43b4-b7dd-7be7aa28994c" />
|
||
|
||
</details>
|
||
|
||
|
||
## Plugins
|
||
|
||
<details>
|
||
LEDMatrix uses a plugin-based architecture where all display functionality is implemented as plugins. All managers that were previously built into the core system are now available as plugins through the Plugin Store.
|
||
|
||
### Plugin Store
|
||
See the [Plugin Store documentation](https://github.com/ChuckBuilds/ledmatrix-plugins) for detailed installation instructions.
|
||
|
||
The easiest way to discover and install plugins is through the **Plugin Store** in the LEDMatrix web interface:
|
||
|
||
1. Open the web interface (`http://your-pi-ip:5000`)
|
||
2. Navigate to the **Plugin Manager** tab
|
||
3. Browse available plugins in the Plugin Store
|
||
4. Click **Install** on any plugin you want
|
||
5. Configure and enable plugins through the web UI
|
||
|
||
### Installing 3rd-Party Plugins
|
||
|
||
You can also install plugins directly from GitHub repositories:
|
||
|
||
- **Single Plugin**: Install from any GitHub repository URL
|
||
- **Registry/Monorepo**: Install multiple plugins from a single repository
|
||
|
||
See the [Plugin Store documentation](https://github.com/ChuckBuilds/ledmatrix-plugins) for detailed installation instructions.
|
||
|
||
For plugin development, check out the [Hello World Plugin](https://github.com/ChuckBuilds/ledmatrix-hello-world) repository as a starter template.
|
||
|
||
### Visual Skins for Scoreboards
|
||
|
||
**Not supported yet.** Skins are meant to restyle a sports scoreboard's
|
||
live/recent/upcoming screens without forking the plugin, but the current
|
||
scoreboard plugins don't render them: a selected skin has no effect. The web
|
||
UI doesn't offer skin install or selection for that reason. The skin system
|
||
and its docs stay in place for when scoreboards adopt it; see
|
||
[docs/SKIN_SYSTEM.md](docs/SKIN_SYSTEM.md) for why.
|
||
|
||
2. **Built-in Managers Deprecated**: The built-in managers (hockey, football, stocks, etc.) are now deprecated and have been moved to the plugin system. **You must install replacement plugins from the Plugin Store** in the web interface instead. The plugin system provides the same functionality with better maintainability and extensibility.
|
||
</details>
|
||
|
||
## Detailed Information
|
||
|
||
<details>
|
||
|
||
<summary>Display Settings from RGBLEDMatrix Library</summary>
|
||
|
||
## Display Settings
|
||
|
||
If you are copying my exact setup, you can likely leave the defaults alone. However, if you have different hardware or want to customize the display behavior, these settings allow you to fine-tune the LED matrix configuration.
|
||
|
||
The display settings are located in `config/config.json` under the `"display"` key and are organized into three main sections: `hardware`, `runtime`, and `display_durations`.
|
||
|
||
### Hardware Configuration (`display.hardware`)
|
||
|
||
These settings control the physical hardware configuration and how the matrix is driven.
|
||
|
||
#### Basic Panel Configuration
|
||
|
||
- **`rows`** (integer, default: 32)
|
||
- Number of LED rows (vertical pixels) in each panel
|
||
- Common values: 16, 32, 48, 64
|
||
- Must be an even number, at least 8. LEDMatrix sets no upper limit, but the
|
||
current rgbmatrix library rejects more than 64 rows per panel — the display
|
||
then won't start (see Troubleshooting Display Settings below)
|
||
- Must match your physical panel configuration
|
||
|
||
- **`cols`** (integer, default: 64)
|
||
- Number of LED columns (horizontal pixels) in each panel
|
||
- Common values: 32, 64, 96, 128
|
||
- At least 16, with no upper limit
|
||
- Must match your physical panel configuration
|
||
|
||
- **`chain_length`** (integer, default: 2)
|
||
- Number of LED panels chained together horizontally
|
||
- At least 1, with no upper limit; longer chains lower the refresh rate
|
||
- If you have 2 panels side-by-side, set to 2
|
||
- If you have 4 panels in a row, set to 4
|
||
- Total display width = `cols × chain_length`
|
||
|
||
- **`parallel`** (integer, default: 1)
|
||
- Number of parallel chains (panels stacked vertically)
|
||
- Use 1 for a single row of panels
|
||
- Use 2 if you have panels stacked in two rows
|
||
- 1–3 on a Raspberry Pi, and the HAT needs that many outputs
|
||
- Total display height = `rows × parallel`
|
||
|
||
#### Brightness and Visual Settings
|
||
|
||
- **`brightness`** (integer, 1-100, default: 90)
|
||
- Display brightness level
|
||
- Lower values (1-50) are dimmer, higher values (50-100) are brighter
|
||
- Recommended: 70-90 for indoor use, 90-100 for bright environments
|
||
- Very high brightness may cause distortion or require more power
|
||
|
||
#### Hardware Mapping
|
||
|
||
- **`hardware_mapping`** (string, default: "adafruit-hat-pwm")
|
||
- Specifies which GPIO pin mapping to use for your hardware
|
||
- **`"adafruit-hat-pwm"`**: Use this for Adafruit RGB Matrix Bonnet/HAT WITH the jumper mod (PWM enabled). This is the recommended setting for Adafruit hardware with the PWM jumper soldered.
|
||
- **`"adafruit-hat"`**: Use this for Adafruit RGB Matrix Bonnet/HAT WITHOUT the jumper mod (no PWM). Remove `-pwm` from the value if you did not solder the jumper.
|
||
- **`"regular"`**: Standard GPIO pin mapping for direct GPIO connections (Generic). Also the right choice for the Adafruit Triple LED Matrix Bonnet
|
||
- **`"regular-pi1"`**: Standard GPIO pin mapping for Raspberry Pi 1 (older hardware or non-standard hat mapping)
|
||
- Choose the option that matches your specific hardware setup, if aren't sure try them all.
|
||
- Hardware pulsing (see `disable_hardware_pulsing`) needs the panel's OE line on GPIO 18, which `adafruit-hat-pwm` and `regular` provide and `adafruit-hat` does not
|
||
|
||
#### PWM (Pulse Width Modulation) Settings
|
||
|
||
These settings affect color fidelity and smoothness of color transitions:
|
||
|
||
- **`pwm_bits`** (integer, 1-11, default: 9)
|
||
- Color depth per channel: how many brightness levels each LED gets
|
||
- Higher values (9-11) = more color levels, smoother gradients, lower refresh rate
|
||
- Lower values (7-8) = the subtlest shades are dropped for a higher refresh rate; `1` gives 8 colors
|
||
- Recommended: 9-10
|
||
|
||
- **`pwm_dither_bits`** (integer, 0-2, default: 1)
|
||
- Time-dithers the lowest color bits: their brightness comes from showing them on only some frames
|
||
- Raises the refresh rate; the cost is that dark shades can shimmer slightly
|
||
- `0` = steadiest dim colors, `2` = fastest
|
||
- The rgbmatrix library accepts only 0-2; a higher value stops the display starting
|
||
|
||
- **`pwm_lsb_nanoseconds`** (integer, 50-3000, default: 130)
|
||
- On-time of the least significant color bit; each higher bit doubles it
|
||
- Lower values = higher refresh rate, but can cost color accuracy or add ghosting on some panels
|
||
- Higher values = less ghosting (faint trails behind bright text on black), lower refresh rate
|
||
- Typical range: 100-300 nanoseconds
|
||
|
||
#### Advanced Hardware Settings
|
||
|
||
- **`scan_mode`** (integer, 0-1, default: 0)
|
||
- Order the rows are refreshed in: `0` = progressive, `1` = interlaced
|
||
- Interlaced can look a little smoother when the refresh rate is very low, but usually shows a comb effect on anything moving
|
||
- Leave at `0` unless you are tuning a slow setup
|
||
|
||
- **`limit_refresh_rate_hz`** (integer, default: 100)
|
||
- Caps the panel refresh rate in Hz; `0` = no cap
|
||
- A steady cap reduces flicker caused by other activity on the Pi, and in camera recordings
|
||
- Scroll speeds are worked out against this value (against 100 Hz when it is `0`), so a cap the panel can actually hold keeps scrolling even
|
||
- If the key is missing from the config, `DisplayManager` uses 90
|
||
- Recommended: 80-120. `sudo python3 scripts/scroll_speeds.py --measure` reports the rate your panel really achieves
|
||
|
||
- **`disable_hardware_pulsing`** (boolean, default: false)
|
||
- `false` = the Pi's hardware PWM times each brightness pulse; `true` = software timing
|
||
- Leave `false` where possible. Software timing is less exact, so a row, or the whole panel, can briefly flash brighter
|
||
- Hardware pulsing needs the panel's OE line on GPIO 18 (`adafruit-hat-pwm`, `regular`, the Adafruit Triple LED Matrix Bonnet). With `adafruit-hat` the library uses software timing anyway
|
||
- It also needs the Pi's onboard sound driver (`snd_bcm2835`) disabled, which `first_time_install.sh` does. Set `true` only if you need the Pi's own audio
|
||
|
||
- **`inverse_colors`** (boolean, default: false)
|
||
- Inverts all colors (red becomes cyan, etc.)
|
||
- Useful if your panel has inverted color channels
|
||
- Set to `true` only if colors appear inverted
|
||
|
||
- **`show_refresh_rate`** (boolean, default: false)
|
||
- Prints the live refresh rate to the console; nothing is drawn on the panel
|
||
- Readable when you stop the service and run `sudo python3 run.py` in a terminal; under the service the output is buffered
|
||
- `sudo python3 scripts/scroll_speeds.py --measure` is an easier way to see the real refresh rate
|
||
|
||
#### Advanced Panel Configuration (Advanced Users Only)
|
||
|
||
These settings are typically only needed for non-standard panels or custom configurations:
|
||
|
||
- **`led_rgb_sequence`** (string, default: "RGB")
|
||
- Color channel order for your LED panel
|
||
- Common values: "RGB", "RBG", "GRB", "GBR", "BRG", "BGR"
|
||
- Most panels use "RGB", but some use "GRB" or other orders
|
||
- If red shows as blue, try "BGR" (the Waveshare 96x48 V2 needs it)
|
||
- Check your panel datasheet if colors appear wrong
|
||
|
||
- **`pixel_mapper_config`** (string, default: "")
|
||
- Advanced pixel mapping configuration
|
||
- Used for custom panel layouts, rotations, or transformations
|
||
- Examples: "U-mapper", "Rotate:90", "Mirror:H"
|
||
- Leave empty unless you need custom mapping
|
||
- See rpi-rgb-led-matrix documentation for full options
|
||
|
||
- **`orientation`** (string, default: "normal")
|
||
- Rotates the rendered image to match how the panel is physically mounted
|
||
- Set to `"180"` (or use the "Upside Down" option in the web UI's Display
|
||
settings) if the panel is mounted upside down — useful for optimizing
|
||
where the Raspberry Pi and wiring sit relative to the mounting location
|
||
- Applied independently of `pixel_mapper_config` (appended as a trailing
|
||
`Rotate:180` mapper), so custom mapper configs keep working alongside it
|
||
|
||
- **`row_address_type`** (integer, default: 0)
|
||
- How rows are addressed on the panel
|
||
- Most panels use 0 (direct addressing)
|
||
- 1 = AB-addressed, 2 = direct row select, 3 = ABC-addressed,
|
||
4 = ABC shift + DE direct (SM5266), 5 = SM5368 / B707 row shift register
|
||
- ABC panels (no E line, e.g. many 128x64 FM6124 panels) use 3
|
||
- Panels with SM5368 row drivers use 5 with `led_rgb_sequence` `"BGR"` —
|
||
e.g. the Waveshare 96x48 V2 (back silkscreen `24S-A1`; the V1, `24S-A2.1`,
|
||
uses the defaults). This is what Waveshare's `96X48_1_24_SM5368` panel
|
||
type sets in their library fork.
|
||
- SM5368 row drivers are timing-sensitive: if rows jump up and down or the
|
||
bottom row shows a copy of other rows, raise `gpio_slowdown`. On a Pi 4
|
||
with an Adafruit Triple LED Matrix Bonnet, 4 left rows jumping; 6–8 gave a
|
||
stable image.
|
||
- On a Raspberry Pi 5 the rgbmatrix library currently supports only 0 and 2
|
||
(and `parallel` 1-3). Anything else would crash the display service, so on
|
||
a Pi 5 the web UI offers only 0 and 2, the config API refuses the others,
|
||
and if one is set in `config.json` anyway the display logs why and runs in
|
||
fallback mode
|
||
- Check your panel datasheet if display appears corrupted
|
||
|
||
- **`multiplexing`** (integer, 0-22, default: 0)
|
||
- How pixels are wired on outdoor/specialty panels (P10, P8, P4 and P3 outdoor modules and similar) whose LEDs aren't laid out in straight rows
|
||
- `0` = direct (standard indoor panels)
|
||
- `1` Stripe, `2` Checkered, `3` Spiral, `4` ZStripe, `5` ZnMirrorZStripe,
|
||
`6` Coreman, `7` Kaler2Scan, `8` ZStripeUneven, `9` P10-128x4-Z,
|
||
`10` QiangLiQ8, `11` InversedZStripe, `12`–`14` P10Outdoor1R1G1B v1–v3,
|
||
`15` P10CoremanMapper, `16` P8Outdoor1R1G1B, `17` FlippedStripe,
|
||
`18` P10-32x16-HalfScan, `19` P10-32x16-QuarterScan, `20` P3Outdoor-64x64,
|
||
`21` DoubleZMultiplex, `22` P4Outdoor-80x40
|
||
- If the image is scrambled in a repeating pattern, try the value named after your panel first
|
||
|
||
- **`panel_type`** (string, default: `""`)
|
||
- Sends a start-up initialization sequence to driver chips that need one
|
||
- `""` = Standard (no initialization) — right for most panels, including FM6124 / FM6124D / FM6124DJ
|
||
- `"FM6126A"` or `"FM6127"` for panels with those chips; try `"FM6126A"` if the panel stays dark or lights only the first pixel on Standard
|
||
|
||
### Runtime Configuration (`display.runtime`)
|
||
|
||
These settings control runtime behavior and GPIO timing:
|
||
|
||
- **`gpio_slowdown`** (integer, default: 3)
|
||
- GPIO timing slowdown factor (0-10): slows GPIO writes so the panel electronics keep up. Higher is more reliable but lowers the refresh rate
|
||
- **Critical setting**: depends on your Raspberry Pi model and your panel
|
||
- **Raspberry Pi Zero/1**: 0-1
|
||
- **Raspberry Pi 2/3**: 1-3
|
||
- **Raspberry Pi 4**: 2-4 (the config template ships 3)
|
||
- **Raspberry Pi 5**: 1–3 in PIO mode (`rp1_rio: 0`, the default); start with `1` and increase if you see flickering
|
||
- Panels on `row_address_type` 5 (SM5368 row drivers) can need 6-8 on a Pi 4
|
||
- Too low: garbage, flicker or rows jumping. Too high: a lower refresh rate
|
||
- If you experience issues, try adjusting this value up or down by 1
|
||
|
||
- **`rp1_rio`** (integer, 0 or 1, default: 0) — Raspberry Pi 5 only
|
||
- Which driver the Pi 5's RP1 chip uses: `0` = PIO (default, less CPU), `1` = RIO (registered I/O, can reach a higher refresh rate)
|
||
- In RIO mode the effect of `gpio_slowdown` is inverted: higher values may be faster
|
||
- Ignored on a Pi 0-4, and applied only if the installed rgbmatrix library supports it
|
||
|
||
### Display Durations (`display.display_durations`)
|
||
|
||
Controls how long each installed plugin stays visible in seconds before switching to the next one, keyed by plugin id.
|
||
|
||
- **Plugin-specific durations**
|
||
- Each plugin can have its own duration setting
|
||
- Format: `"<plugin-id>": <seconds>`
|
||
- Example: `"hockey-scoreboard": 45` shows hockey scores for 45 seconds
|
||
- Example: `"weather": 20` shows weather for 20 seconds
|
||
- If a plugin doesn't have a duration here, it uses its default (usually 15 seconds)
|
||
- You can also set `display_duration` in each plugin's individual configuration
|
||
|
||
**Tips for Display Durations:**
|
||
- Longer durations (30-60 seconds) = more time to read content, slower cycling
|
||
- Shorter durations (10-20 seconds) = faster cycling, less time per display
|
||
- Balance based on your preference and how much information each display shows
|
||
- For example, if you want more focus on stocks, increase the stock plugin's duration value
|
||
|
||
### Display Format Settings
|
||
|
||
- **`use_short_date_format`** (boolean, default: true)
|
||
- Use short date format (e.g., "Jan 15") instead of long format (e.g., "January 15th")
|
||
- Set to `false` for longer, more readable dates
|
||
- Set to `true` to save space and show more information
|
||
|
||
### Dynamic Duration Settings (`display.dynamic_duration`)
|
||
|
||
- **`max_duration_seconds`** (integer, optional)
|
||
- Maximum duration cap for plugins that use dynamic durations
|
||
- Some plugins can automatically adjust their display time based on content
|
||
- This setting limits how long they can extend (prevents one display from dominating)
|
||
- Example: If set to 60, a plugin can extend up to 60 seconds even if it requests longer
|
||
- Leave unset to use the default cap (180 seconds; the web UI accepts 30-1800)
|
||
|
||
### Example Configuration
|
||
|
||
```json
|
||
{
|
||
"display": {
|
||
"hardware": {
|
||
"rows": 32,
|
||
"cols": 64,
|
||
"chain_length": 2,
|
||
"parallel": 1,
|
||
"brightness": 90,
|
||
"hardware_mapping": "adafruit-hat-pwm",
|
||
"scan_mode": 0,
|
||
"pwm_bits": 9,
|
||
"pwm_dither_bits": 1,
|
||
"pwm_lsb_nanoseconds": 130,
|
||
"disable_hardware_pulsing": false,
|
||
"inverse_colors": false,
|
||
"show_refresh_rate": false,
|
||
"limit_refresh_rate_hz": 100
|
||
},
|
||
"runtime": {
|
||
"gpio_slowdown": 4
|
||
},
|
||
"display_durations": {
|
||
"calendar": 30,
|
||
"hockey-scoreboard": 45,
|
||
"weather": 20,
|
||
"stocks": 25
|
||
},
|
||
"use_short_date_format": true,
|
||
"dynamic_duration": {
|
||
"max_duration_seconds": 60
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Troubleshooting Display Settings
|
||
|
||
**Display is blank or shows garbage:**
|
||
- Check `rows`, `cols`, `chain_length`, and `parallel` match your physical setup
|
||
- Verify `hardware_mapping` matches your HAT/connection type
|
||
- Try adjusting `gpio_slowdown`
|
||
- Ensure your display doesn't need the E-Addressable line
|
||
- If it went blank right after a settings change, check `sudo journalctl -u ledmatrix` for `Failed to initialize RGB Matrix`: the rgbmatrix library refused a value (for example more than 64 `rows`, or `pwm_dither_bits` above 2) and the display fell back to no output. The library's own message nearby names the setting; on a Raspberry Pi 5, LEDMatrix's message names any unsupported `row_address_type`, `parallel` or `hardware_mapping`
|
||
- A repeating scramble points at `row_address_type` or `multiplexing`; a panel that stays dark, at `panel_type`
|
||
|
||
**Rows jump up and down, or the bottom row repeats other rows:**
|
||
- Raise `gpio_slowdown` a step at a time (SM5368 panels on `row_address_type` 5 can need 6-8 on a Pi 4)
|
||
|
||
**A row or the whole panel briefly flashes brighter:**
|
||
- Set `disable_hardware_pulsing` to `false` (needs the OE line on GPIO 18; see `hardware_mapping`)
|
||
|
||
**Colors are wrong or inverted:**
|
||
- Check `led_rgb_sequence` (try "GRB" if "RGB" doesn't work)
|
||
- Try setting `inverse_colors` to `true`
|
||
- Verify `hardware_mapping` is correct for your hardware
|
||
|
||
**Display flickers or is unstable:**
|
||
- Increase `gpio_slowdown` by 1-2
|
||
- Lower `limit_refresh_rate_hz` to 60-80
|
||
- Check power supply (LED matrices need adequate power)
|
||
|
||
**Display is too dim or too bright:**
|
||
- Adjust `brightness` (0-100)
|
||
- Very high brightness may require better power supply
|
||
|
||
**Performance issues:**
|
||
- Lower `limit_refresh_rate_hz`
|
||
- Reduce `pwm_bits` to 8
|
||
- Set `pwm_dither_bits` to 0
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Manual SSH Commands (for reference)</summary>
|
||
|
||
The quick actions essentially just execute the following commands on the Pi.
|
||
|
||
From the project root directory (ex: /home/ledpi/LEDMatrix):
|
||
|
||
```bash
|
||
sudo python3 display_controller.py
|
||
```
|
||
|
||
This will start the display cycle but only stays active as long as your ssh session is active.
|
||
|
||
### 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>
|
||
|
||
<details>
|
||
<summary>Service Installation Details</summary>
|
||
|
||
The first time install will handle this:
|
||
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 (this is included in the first_time_install.sh)
|
||
|
||
1. Make the install script executable:
|
||
```bash
|
||
chmod +x scripts/install/install_service.sh
|
||
```
|
||
|
||
2. Run the install script with sudo:
|
||
```bash
|
||
sudo ./scripts/install/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
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Web Interface Installation Details</summary>
|
||
|
||
The first time install will handle this:
|
||
The LEDMatrix system includes Web Interface that runs on port 5000 and provides real-time display preview, configuration management, and on-demand display controls.
|
||
|
||
### Installing the Web Interface Service
|
||
|
||
> The first-time installer (`first_time_install.sh`) already installs the
|
||
> web service. The steps below only apply if you need to (re)install it
|
||
> manually.
|
||
|
||
1. Make the install script executable:
|
||
```bash
|
||
chmod +x scripts/install/install_web_service.sh
|
||
```
|
||
|
||
2. Run the install script with sudo:
|
||
```bash
|
||
sudo ./scripts/install/install_web_service.sh
|
||
```
|
||
|
||
The script will:
|
||
- Copy the web service file to `/etc/systemd/system/`
|
||
- Enable the service to start on boot
|
||
- Start the service immediately
|
||
- Show the service status
|
||
|
||
### Web Interface Configuration
|
||
|
||
The web interface can be configured to start automatically with the main display service:
|
||
|
||
1. In `config/config.json`, ensure the web interface autostart is enabled:
|
||
```json
|
||
{
|
||
"web_display_autostart": true
|
||
}
|
||
```
|
||
|
||
2. The web interface will now start automatically when:
|
||
- The system boots
|
||
- The `web_display_autostart` setting is `true` in your config
|
||
|
||
### Accessing the Web Interface
|
||
|
||
Once installed, you can access the web interface at:
|
||
```
|
||
http://your-pi-ip:5000
|
||
```
|
||
|
||
### Managing the Web Interface Service
|
||
|
||
```bash
|
||
# Check service status
|
||
sudo systemctl status ledmatrix-web.service
|
||
|
||
# View logs
|
||
journalctl -u ledmatrix-web.service -f
|
||
|
||
# Stop the service
|
||
sudo systemctl stop ledmatrix-web.service
|
||
|
||
# Start the service
|
||
sudo systemctl start ledmatrix-web.service
|
||
|
||
# Disable autostart
|
||
sudo systemctl disable ledmatrix-web.service
|
||
|
||
# Enable autostart
|
||
sudo systemctl enable ledmatrix-web.service
|
||
```
|
||
|
||
### Web Interface Features
|
||
|
||
- **Real-time Display Preview**: See what's currently displayed on the LED matrix
|
||
- **Configuration Management**: Edit settings through a web interface
|
||
- **On-Demand Controls**: Start specific displays (weather, stocks, sports) on demand
|
||
- **Service Management**: Start/stop the main display service
|
||
- **System Controls**: Restart, update code, and manage the system
|
||
- **API Metrics**: Monitor API usage and system performance
|
||
- **Logs**: View system logs in real-time
|
||
|
||
### Troubleshooting Web Interface
|
||
|
||
**Web Interface Not Accessible After Restart:**
|
||
1. Check if the web service is running: `sudo systemctl status ledmatrix-web.service`
|
||
2. Verify the service is enabled: `sudo systemctl is-enabled ledmatrix-web.service`
|
||
3. Check logs for errors: `journalctl -u ledmatrix-web.service -f`
|
||
4. Ensure `web_display_autostart` is set to `true` in `config/config.json`
|
||
|
||
**Port 5000 Not Accessible:**
|
||
1. Check if the service is running on the correct port
|
||
2. Verify firewall settings allow access to port 5000
|
||
3. Check if another service is using port 5000
|
||
|
||
**Service Fails to Start:**
|
||
1. Check Python dependencies are installed
|
||
2. Verify the virtual environment is set up correctly
|
||
3. Check file permissions and ownership
|
||
|
||
</details>
|
||
|
||
|
||
### If you've read this far — thanks!
|
||
|
||
-----------------------------------------------------------------------------------
|
||
|
||
## License
|
||
|
||
LEDMatrix is licensed under the
|
||
[GNU General Public License v3.0 or later](LICENSE).
|
||
|
||
LEDMatrix builds on
|
||
[`rpi-rgb-led-matrix`](https://github.com/hzeller/rpi-rgb-led-matrix),
|
||
which is GPL-2.0-or-later. The "or later" clause makes it compatible
|
||
with GPL-3.0 distribution.
|
||
|
||
Plugin contributions in
|
||
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
||
are also GPL-3.0-or-later unless individual plugins specify otherwise.
|
||
|
||
## Contributing
|
||
|
||
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the PR
|
||
flow, and how to add a plugin. Bug reports and feature requests go in
|
||
the [issue tracker](https://github.com/ChuckBuilds/LEDMatrix/issues).
|
||
Security issues should be reported privately per
|
||
[SECURITY.md](SECURITY.md).
|