mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-08-01 08:48:05 +00:00
5b45f35888
* Vegas mode: reclaim dead space and pace the rotation On a wide panel Vegas mode spent much of its time showing black. At 50px/s on a 512px display, one display width of blank is 10.2 seconds, which makes several long-standing behaviours expensive: - ScrollHelper prepended a full display width of black as an "initial gap", charged once per cycle — 10.2s of black at the start of every rotation. - Plugins without get_vegas_content() are captured off a full-display canvas, so their blank margins entered the ticker too. Measured: of-the-day drew 35px of "No Data" on a 512px canvas (92% blank), youtube-stats 142px of content with 185px of black either side. Only the scroll_helper path had any trimming. - Cycle transitions deliberately pushed a blank frame and then recomposed synchronously: 84ms at best, 4.8s at worst, every millisecond of it black. - buffer_ahead doubled as the cycle size, so a 21-plugin install showed 3 plugins per cycle and took ~7 cycles to come around. - separator_width was applied between every image rather than at plugin boundaries, so a per-row ticker like the F1 scoreboard (116 images, which it renders 4px apart internally) got a 32px chasm between each row — and the width budget didn't count those gaps, so the plugin quietly occupied far more of the panel than intended. Changes: - src/vegas_mode/geometry.py: numpy column-ink primitives shared by the trimmer and the audit tool, so the number reported is the number acted on. A Python per-column loop over a 17,000px strip is far too slow for the render path. - PluginAdapter trims every content path, not just scroll_helper. Only outer edges are cropped: interior blank columns are the plugin's own layout (logo left, score right) and closing them would corrupt the design. A plugin on a non-black background is inherently unaffected. - ScrollHelper.create_scrolling_image takes an explicit lead_gap, still defaulting to display_width so the many standalone-ticker callers are unchanged. Vegas passes lead_in_width (default 0). - Cycle end holds the last rendered frame instead of blanking, turning the recompose into a brief freeze rather than the panel switching off. - plugins_per_cycle (default 6) is split from buffer_ahead, which goes back to being only a prefetch low-water mark. - max_plugin_width_ratio (default 3x display width) caps one plugin's share of a cycle. Overflow is deferred, not discarded: a rotation offset advances each fetch so later rows appear on subsequent cycles. Single oversized images are cropped at a blank column so the cut misses glyphs. - Composition groups images by plugin: rows are joined by intra_plugin_gap (default 8) and separator_width applies only between plugins. The width budget now counts those gaps. - Plugin data updates no longer run on the Vegas render path. All new settings are user-configurable in Display -> Vegas Scroll, including min/max cycle duration and dynamic duration, which previously existed in code but were reachable only by hand-editing config.json. Measured with scripts/dev/vegas_audit.py on a 512x64 panel: mean ink coverage 42.7% -> 69.4% fully blank 5.9% -> 0% reads as empty 13.6% -> 0% worst blank stretch 4.8s -> 0s full rotation 414s -> 123s plugins per cycle 3 -> 6 Note the metric choice: a "fully blank" scan (>=95% black viewport) reported only 0.4% and badly understated the problem, because two full-width segments with mid-canvas content never fully blank the viewport — they hold it at ~28%. window_coverage_stats grades every viewport position by how much ink it carries, which is what tracks perceived dead time. Known remaining: cycle transitions still freeze ~3.5s while the next cycle is fetched. Fixing that needs background prefetch, which is deferred because the fallback-capture path mutates the shared display_manager.image and racing it against the render loop risks torn frames. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Drop unused Optional import from the vegas audit script Flagged by Codacy (F401). Any, Dict and List are all still used. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Align Vegas API bounds with validate(), fix audit config plumbing Both from review feedback on #423. The web API's accepted ranges disagreed with VegasModeConfig.validate(), which is what actually gates Vegas starting: scroll_speed 1-100 -> 1-200 (a slider value of 150 returned 400) separator_width 0-500 -> 0-128 target_fps 1-200 -> 30-200 buffer_ahead 1-20 -> 1-5 The three loose ones were the dangerous direction: the value saved with a 200, then VegasModeCoordinator.start() failed validation with only a log line, so the ticker silently never ran. The UI already matched validate() in all four cases, so the API was the odd one out. test_vegas_api_bounds_match_validate parses the numeric_fields map out of api_v3 and asserts every bound against validate(), plus that validate() accepts both endpoints and rejects just outside them, so these cannot drift apart again. That test immediately caught a missing upper bound on min_plugin_width, now added — unbounded it would drop every segment and leave a blank ticker. Separately, vegas_audit.py constructed PluginAdapter without the config, so it fell back to VegasModeConfig() defaults and would report trimming and width-budget behaviour that differed from the user's config.json. It now passes the loaded config exactly as the coordinator does. This is the same class of drift the explicit lead_gap and grouping arguments already guard against. Output is unchanged on a rig whose config matches the defaults. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Vegas mode: render plugins narrower, space rows by measured separation Trimming reclaims blank margins but cannot compact a layout that genuinely spans the display — a five-column forecast, a progress bar drawn at 100% width, a stat block with the panel's whole width between its elements. Those need the plugin to make different layout decisions, which means telling it the screen is narrower while it renders. DisplayManager.render_size() presents a smaller logical canvas for the duration of a Vegas content fetch, reusing the same _LogicalMatrix indirection double-sided mode already relies on so plugins see a consistent size from every accessor. Plugins that size themselves from matrix.width need no changes at all; one that wants to be explicit can read the new BasePlugin.get_vegas_render_width(). Width is a percentage so a single setting travels across panel sizes: vegas_scroll.render_width_pct globally, or vegas_width_pct in an individual plugin's config. Measured on a 512x64 panel with real data: ledmatrix-weather 1536px -> 576px (forecast becomes narrow cards) youtube-stats 353px -> 199px (2% blank left, so genuinely compact) geochron 453px -> 153px (ink density rises to 100%) ledmatrix-flights 950px -> 740px The youtube-stats figure is the clearest evidence the layout itself changed rather than being cropped: at full width the content had to be trimmed from 512px to 353px, whereas at 40% it arrives with almost no blank to reclaim. Row spacing is now measured rather than added. A flat gap gets it wrong in both directions at once — content drawn flush to its own edges ends up nearly touching (reported for recent sports scores, which sat 8px apart), while content already carrying wide margins gets pushed even further out. separation_gap() measures the blank each pair already has and adds only the shortfall, up to min_content_separation (default 24). intra_plugin_gap stays as a floor applied regardless. Two tests shipped in the previous commit encoded the old flat-gap arithmetic and are updated to the measured semantics, including one renamed to reflect that zero intra_plugin_gap alone no longer butts rows together. Also fixes a real bug found while testing: the harness display manager had no render_size(), and because the adapter catches broadly that surfaced as "no content" rather than an error, silently dropping five plugins. Added the context to VisualTestDisplayManager for parity, and _render_at() now degrades to a no-op on any display manager lacking it, so a third-party or older harness loses the narrowing rather than the content. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Vegas mode: end cycles before the wrap, keep the width budget honest Three fixes, the first a regression from lead_in_width defaulting to 0. get_visible_portion wraps: once scroll_position + display_width passes the end of the strip it fills the right of the frame from the *head* of the same strip. So the final display_width of travel showed the cycle's first plugin re-entering on the right while its last plugin exited on the left, and the recompose that followed replaced both at once. On a 512px panel at 50px/s that was 10.2s of two plugins on screen at once, ending in a hard cut — reported as the ticker "switching mid-scroll" from F1 to news. That used to be invisible because the strip began with a full display_width of blank, so the wrapped-in region was black. Removing that blank (it was 10s of dead panel per cycle) exposed the wrap. Cycles now end one display width earlier, before any wrapped content appears, clamped for strips no wider than the display so they don't complete instantly and spin the recompose loop. Verified on hardware: a 3936px strip now completes at 68.5s, exactly (3936 - 512) / 50. Second, auto_trim=False also skipped the width budget, which is an unrelated concern — turning off margin cropping should not let one plugin hold the panel for minutes. Seen in the field: the F1 scoreboard contributed 116 images and 14,848px untouched, giving a 33,821px cycle (11 minutes of content). The budget now applies regardless of trimming; with it restored that cycle is 6,362px. Third, the budget accounted for row gaps using the flat intra_plugin_gap while the compositor had moved to measured separation, so it under-counted by up to (min_content_separation - intra_plugin_gap) per row and a many-row plugin overran its cap. Both now use the same separation_gap() rule, and a test asserts the composed block fits the budget end to end rather than trusting the two paths to agree. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Fix IndexError in find_blank_cut when the cut lands on the image edge A cut position after the last column is legitimate — _crop_to_budget asks for min(start + budget, img.width), which equals the width whenever the remaining strip is shorter than the budget. find_blank_cut clamped target to width but then walked leftwards starting at target itself, so ink[width] raised IndexError. Caught on hardware: it killed the ledmatrix-stocks fetch, and because _fetch_plugin_content catches broadly that surfaced as the plugin silently contributing nothing for the cycle. Only reachable on the second or later pass of the rotating window over a single oversized image, which is why the existing tests missed it — they all exercised the first pass, where start is 0 and start + budget is comfortably inside the image. Added TestRotationAcrossMultipleCycles, which walks the window round several times and asserts content is never lost, plus direct coverage of find_blank_cut at and beyond the image edge. Both bounds now stop at width - 1 so neither direction can index past the end. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Only cut oversized segments at real gaps between items The width-budget crop snapped to the nearest blank column, and in rendered text the gap between two characters is a single column. So a cut routinely landed inside a word: the cycle showed "Wednesda" and the orphaned "y" turned up as a lone floating letter in the next cycle, positioned after whatever plugin happened to precede it. Measured on the clock-simple segment to confirm: its blank runs are [1, 1, 1, 1, 1, 8, 8] — five single-column letter gaps, every one of which find_blank_cut would happily have chosen. Cuts now only land in a run of at least min_cut_gap blank columns (default 6), which excludes letter spacing while still finding the gaps plugins put between items (the stocks ticker uses 32px, baseball 48px). Where no boundary falls inside the budget the cut waits for the next one and overruns, because splitting an item is worse than a slightly long segment. Continuous content is treated differently on purpose: an image with no internal gaps is a map or a chart, where any column is as good as another, so it is still cut to the budget exactly. The gap rule protects discrete items; letting a solid image escape the cap in its name would be wrong. blank_runs() is vectorised — 48ms for a 17,000px strip, against seconds for a per-column Python loop. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Hold capture_mode for every plugin render, not just narrowed ones The native content path only entered capture_mode when it was also narrowing the canvas, so at full width — which is every plugin without a vegas_width_pct override, i.e. most of them — a plugin calling update_display() while building its Vegas content wrote straight to the hardware. That is a visible flash mid-scroll, and it lines up with the flash reported at cycle transitions, when several plugins are fetched back to back. Suppression is now unconditional; the narrowing context stays separate because it is already a no-op at full width. Both contexts are reached through helpers that degrade to nullcontext when the display manager lacks them. That matters more than it looks: the adapter's handlers are deliberately broad, so an AttributeError from a missing context does not surface as an error — it surfaces as the plugin contributing nothing. Making the call unconditional without this turned 44 tests red for exactly that reason, all of them reporting lost content rather than the real cause. The test double now provides capture_mode and render_size too, so tests exercise the real contexts instead of silently taking the degraded path. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Vegas mode: one continuous strip instead of swapping cycles A cycle used to be a discrete strip that got replaced: motion stopped, every pixel was substituted at once, and the next group started with the viewport already full. That is the freeze, the flash and the jump. The strip is now extended rather than replaced. ScrollHelper gains append_content(), which adds items on the right without touching scroll_position or total_distance_scrolled, so motion continues and the next group simply arrives from the right. Because completion is measured against total_scroll_width, extending also defers completion — there is no longer a cycle boundary to see. drop_scrolled_prefix() reclaims what has gone past, keeping the strip bounded however long Vegas runs (observed 5,000-11,000px against an unbounded strip otherwise). It shifts total_distance_scrolled and total_scroll_width together so the completion arithmetic is unchanged, and refuses to run while the viewport is wrapping: wrapping reads the head of the strip into the right of the frame, so trimming the head there would visibly change the picture. A test caught that. Groups are prepared off the render thread. The constraint is that the canvas and the matrix proxy are process-wide mutable state, so narrowing or capturing through them from another thread would corrupt the frame the render loop is pushing. get_content() therefore takes offscreen_only: the background thread uses only paths that avoid the canvas, and anything needing it is marked and picked up on the render thread. That puts the expensive work (native renders of leaderboard and baseball cards, seconds each) in the background and leaves the cheap work (display capture, 40-600ms) in the foreground. DisplayManager's capture flag is now thread-local. As a shared flag, a background capture would have suppressed the render loop's own frame pushes for its duration, freezing the panel precisely when the point was to avoid a freeze. Canvas-bound plugins are drained one at a time rather than as a batch: six at once held the render thread for 1.75s. Drains are also spaced by two seconds while the lookahead is healthy, since taking them back to back turns one long stall into a run of short ones. When the strip is genuinely running short the throttle is ignored, because content matters more than smoothness there. Measured on hardware: zero cycle-complete swaps, drains landing 2-4s apart, lookahead holding at 1,200-3,500px, no errors. Set continuous_scroll false to restore the swap behaviour; the old path is intact. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Pace the Vegas frame loop adaptively: 31.5 -> 78.7 fps The loop slept a fixed frame_interval on top of however long the frame took, so at a measured 31.6ms per frame a flat 8ms of that was pure idle — a quarter of the budget spent not rendering. It now sleeps only the remainder of the budget. Measured on hardware: 31.5 fps to 78.7 fps sustained, with CPU going *down* from 150% to 127%. Scroll speed is unchanged at 49.9px/s against a configured 50, because motion is derived from elapsed time rather than frame count — this buys smoothness, not speed. Worth recording what the bottleneck was not: the per-frame render path measures 0.34ms in total (0.18ms for the numpy slice, 0.17ms for the dirty-tracking digest), which is a theoretical 2900 fps. Optimising any of that would have been wasted effort. The frame was idle, not busy. Also nices the prefetch thread. Its work is PIL and numpy that releases the GIL, so the scheduler can act on the priority, and without it the prefetch competes for the same cores as the render loop. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Sub-pixel scrolling: motion at the frame rate, not the pixel rate With integer positioning the number of distinct frames per second equals the scroll speed in px/s, however fast the loop renders. Measured at 50px/s and 78.7fps, 36% of frames were byte-identical: the extra frames cost work and bought no motion, and what was left was 50 discrete 1px steps a second. Two things were wrong with the pre-existing sub-pixel support. get_visible_portion never consulted sub_pixel_scrolling — it always took the integer path, so the flag and _get_visible_portion_subpixel were dead code. And that implementation needed scipy.ndimage.shift, which is not installed on the target devices (HAS_SCIPY is False there), so it would not have interpolated even if reached. Verified both: positions 1000.0 and 1000.5 produced identical frames either way. Blending is now wired up and implemented with numpy. Two details make it affordable: slice cached_array directly instead of building two PIL images only to convert them straight back (the naive version measured 15x the integer path), and use fixed-point uint16 multiply-add rather than float32, which suits the Pi's cores and gives finer weighting than the panel can resolve. Result 0.939ms against 0.237ms — 0.70ms added per frame, a 1065fps ceiling. Measured on hardware: 81.2 fps with blending on, against 78.7 with it off, so no cost within noise — and every frame is now a distinct position rather than one in three being a repeat. The trade is a slight horizontal softening of text, since each frame blends two positions. Set smooth_scroll false for maximum crispness. Also benchmarked and cleared as non-issues: extending the strip costs 9.4ms on an 11,000px strip and trimming 2.5ms, both under one frame at this rate. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Add overflow handling: keep ordered content whole instead of rotating a window The width budget split any oversized plugin by advancing a window each cycle. That is right for interchangeable items — news headlines, odds, stock prices — but wrong for ordered content: a league table showed ranks 1-6, then resumed at 7 two rotations later, which reads as out of order and out of context. Nobody needs rank 23 in a ticker; they need the top of the table, every time. overflow_mode chooses between them: rotate — advance a window each cycle so everything is seen eventually (unchanged default) truncate — always show the start and drop the rest, keeping ordered content coherent. Records no window state, so every pass starts at the top. Per-plugin vegas_overflow overrides the global setting, since one install has both kinds of plugin. Also adds per-plugin vegas_max_width_screens, so content that must stay whole can be given more room — or uncapped with 0 — without lifting the cap on every ticker. Applied on the test rig: f1-scoreboard and ledmatrix-leaderboard set to truncate, and baseball given 4.5 screens because it was showing 8 of 9 games when the whole slate needed only a little more room. Verified: F1 now reports "the first 10 of 116 ... the rest are not shown", baseball has dropped out of the budget log entirely, and stocks, odds-ticker and stock-news still rotate. Also corrects the crop log, which claimed "window advances next cycle" unconditionally and so misreported truncated crops. A test now pins the behaviour behind the message: truncate must leave no offset recorded. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Stop Vegas mode showing last night's games as if they were live A game that was live in the evening was still being drawn as live the next morning. Two faults combined to freeze plugin visuals indefinitely. PR #291 added a call to plugin_adapter.invalidate_plugin_scroll_cache() so a plugin's own cached scroll image would be rebuilt from fresh data. That method was never implemented. hot_swap_content() wraps the call in a broad except, so every hot swap has raised AttributeError and been swallowed silently ever since — which is why the visuals it was meant to keep fresh never were. Continuous scrolling then removed the only path that reached it at all: should_recompose() and hot_swap_content() are called from the non-continuous branch of run_frame(), and continuous_scroll defaults to True. So on a default install the pending-update flags were set by the update tick, never consumed, and grew without bound. Together these froze content completely, because refetching is not enough on its own: the sports plugins' get_vegas_content() regenerates only "if the cache is empty", so take_next_group() kept receiving the same picture however often it asked. Fixed by: - Implementing invalidate_plugin_scroll_cache(). It covers both layouts — a helper directly on the plugin (stocks, news, odds-ticker) and one owned by a scroll-display manager (the sports scoreboards, which is the shape that produced this bug) — and clears cached_image and cached_array together, since the array is the image's numpy mirror. - Adding StreamManager.invalidate_pending_updates() and calling it from the continuous branch. It only drops the caches; the plugin recomposes when it next comes round in the rotation. process_updates() is wrong here: it refetches synchronously and merges into the active buffer that continuous mode bypasses, and hot_swap_content() rebuilds and repositions the whole strip, which is the freeze-and-jump this mode exists to avoid. Tests assert the fix rather than the implementation: 14 of the 17 new tests fail without it. Includes the wiring itself, since the regression was a call that was simply absent, and a check that the scroll position is untouched so this cannot regress into the swap's visible jump. All Vegas suites pass (355 tests). test_display_controller_vegas_tick.py still cannot be collected off-device for want of rgbmatrix, identically with and without this change. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ * Fix two CodeRabbit-flagged test assertions in vegas density tests test_prepared_group_is_used_without_refetching had a tautological final assertion; now checks stream.calls directly. test_no_partial_letter_at_either_edge required both crop edges to be blank, but the left edge here is always the crop's start position with no lead-in gap in word_strip, so it legitimately carries ink — only the right edge is an actual cut and needs the check. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ --------- Co-authored-by: Claude <noreply@anthropic.com>
LEDMatrix
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:
Setup video and feature walkthrough on Youtube (Outdated but still useful) :
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
- Feeling Generous? Consider sponsoring this project or sending a donation (these AI credits aren't cheap!)
Special Thanks to:
- Hzeller for his groundwork on controlling an LED Matrix from the Raspberry Pi
- Cursor for making this project possible
- CodeRabbit for fixing my PR's
- Everyone involved in this project for their patience, input, and support
Core Features
Core Features
The following plugins are available inside of the LEDMatrix project. These modular, rotating Displays that can be individually enabled or disabled per the user's needs with some configuration around display durations, teams, stocks, weather, timezones, and more. Displays 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)
-
NCAA Football (2x 96x48 Displays 2.5mm Pixel Pitch)
-
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)
Hardware
Hardware Requirements
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
Amazon Affiliate Link – Raspberry Pi 4 8GB RAM
- Pi 5 users: the installer automatically detects Pi 5 and builds the
rpi-rgb-led-matrixlibrary with RP1 support. If you previously installed on a Pi 4 and migrated the SD card, or if you seemmaperrors in the logs, force a fresh library build:sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh - Pi 5 config: leave
rp1_rioat0(PIO mode, default) and setgpio_slowdownto1or2.
- Pi 5 users: the installer automatically detects Pi 5 and builds the
RGB Matrix Bonnet / HAT
- Adafruit RGB Matrix Bonnet/HAT – supports one “chain” of horizontally connected displays
- Adafruit Triple LED Matrix Bonnet – supports up to 3 vertical “chains” of horizontally connected displays (use
regular-pi1as hardware mapping) - Electrodragon RGB HAT – supports up to 3 vertical “chains”
- Seengreat Matrix Adapter Board – single-chain LED Matrix (use
regularas hardware mapping)
LED Matrix Panels
(2x in a horizontal chain is recommended)
- Adafruit 64×32 – designed for 128×32 but works with dynamic scaling on many displays (pixel pitch is user preference)
- Waveshare 64×32 - Does not require E addressable pad
- Waveshare 96×48 – higher resolution, requires soldering the E addressable pad on the Adafruit RGB Bonnet to “8” OR toggling the DIP switch on the Adafruit Triple LED Matrix Bonnet (no soldering required!)
Amazon Affiliate Link – ChuckBuilds receives a small commission on purchases
Power Supply
- 5V 4A DC Power Supply (good for 2 -3 displays, depending on brightness and pixel density, you'll need higher amperage for more)
- 5V 10A DC Power Supply (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 does NOT require the E addressable line, however the 96x48 Waveshare display 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.
or
or
How to set addressable E line on various HATs:
-
Adafruit Single Chain HATs
or
-
Adafruit Triple Chain HAT
-
ElectroDragon RGB LED Matrix Panel Drive Board
2 Matrix display with Rpi connected to Adafruit Single Chain HAT.
Mount / Stand options
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)
Installation Steps
Preparing the Raspberry Pi
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. |
-
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
-
Choose your Raspberry Pi (3B+ in my case)
- For Operating System (OS), choose "Other"
- Then choose Raspbian OS (64-bit) Lite (Trixie)
- For Storage, choose your micro-sd card
| ⚠️ IMPORTANT |
|---|
| Make sure it's the correct drive! Data will be erased! |
- 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".
- Choose your timezone and keyboard layout.
- 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.
- (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.
- 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.
- 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.
- Double check your settings then confirm by clicking "Write".
- 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.
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.
System Setup & Installation
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.
- SSH into your Raspberry Pi:
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 Ctrl+Shift+V on Windows or Shift+Command+V on Mac.
Tip
Terminal can be funky about pasting with just Ctrl+V, by right click -> paste or using Ctrl+Shift+V you will be able to paste without additional unwanted characters.
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, 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. All errors are reported explicitly with actionable fixes.
Note: The script is safe to run multiple times and will handle existing installations gracefully.
Manual Installation (Alternative)
If you prefer to install manually or the one-shot installer doesn't work for your setup:
- SSH into your Raspberry Pi:
ssh ledpi@ledpi
- Update repositories, upgrade Raspberry Pi OS, and install prerequisites:
sudo apt update && sudo apt upgrade -y
sudo apt install -y git python3-pip cython3 build-essential python3-dev python3-pillow scons
- Clone this repository:
git clone https://github.com/ChuckBuilds/LEDMatrix.git
cd LEDMatrix
- Run the first-time installation script:
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.
Configuration
Configuration
Configuration
Initial Setup
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:
Manual Config.json editing
-
First-time setup: The previous "First_time_install.sh" script should've already copied the template to create your config.json:
-
Edit your configuration:
sudo nano config/config.json
Automatic Configuration Migration
The system automatically handles configuration updates:
- New installations: Creates
config.jsonfrom 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.
Running the Display
Recommended: Use Web UI Quick Actions
I recommend using the web-ui "Quick Actions" to control the Display.
Plugins
LEDMatrix uses a plugin-based architecture where all display functionality (except the core calendar) 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 for detailed installation instructions.
The easiest way to discover and install plugins is through the Plugin Store in the LEDMatrix web interface:
- Open the web interface (
http://your-pi-ip:5000) - Navigate to the Plugin Manager tab
- Browse available plugins in the Plugin Store
- Click Install on any plugin you want
- 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 for detailed installation instructions.
For plugin development, check out the Hello World Plugin repository as a starter template.
Visual Skins for Scoreboards
Want a different look for a sports scoreboard without forking the plugin?
Skins restyle the live/recent/upcoming screens while the plugin keeps
handling data, scheduling, caching, and vegas mode. Install one with
git clone <skin repo> skins/<skin-id>, select it in the plugin's config,
and you're done — see docs/SKIN_SYSTEM.md (how it
works) and docs/CREATING_SKINS.md (build your own,
including a ready-made Claude Code prompt).
- 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.
Detailed Information
Display Settings from RGBLEDMatrix Library
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 match your physical panel configuration
-
cols(integer, default: 64)- Number of LED columns (horizontal pixels) in each panel
- Common values: 32, 64, 96, 128
- Must match your physical panel configuration
-
chain_length(integer, default: 2)- Number of LED panels chained together horizontally
- 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
- Total display height =
rows × parallel
Brightness and Visual Settings
brightness(integer, 0-100, default: 90)- Display brightness level
- Lower values (0-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-pwmfrom the value if you did not solder the jumper."regular": Standard GPIO pin mapping for direct GPIO connections (Generic)"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.
PWM (Pulse Width Modulation) Settings
These settings affect color fidelity and smoothness of color transitions:
-
pwm_bits(integer, default: 9)- Number of bits used for PWM (affects color depth)
- Higher values (9-11) = more color levels, smoother gradients
- Lower values (7-8) = fewer color levels, but may improve stability on some hardware
- Range: 1-11, recommended: 9-10
-
pwm_dither_bits(integer, default: 1)- Additional dithering bits for smoother color transitions
- Helps reduce color banding in gradients
- Higher values (1-2) = smoother gradients but may impact performance
- Range: 0-2, recommended: 1
-
pwm_lsb_nanoseconds(integer, default: 130)- Least significant bit timing in nanoseconds
- Controls the base timing for PWM signals
- Lower values = faster PWM, higher values = slower PWM
- Typical range: 100-300 nanoseconds
- May need adjustment if you see flickering or color issues
Advanced Hardware Settings
-
scan_mode(integer, default: 0)- Panel scan mode (how rows are addressed)
- Common values: 0 (progressive), 1 (interlaced)
- Most panels use 0, but some require 1
- Check your panel datasheet if colors appear incorrect
-
limit_refresh_rate_hz(integer, default: 100)- Maximum refresh rate in Hz (frames per second)
- Caps the refresh rate for better stability
- Lower values (60-80) = more stable, less CPU usage
- Higher values (100-120) = smoother animations, more CPU usage
- Recommended: 80-100 for most setups
-
disable_hardware_pulsing(boolean, default: false)- Disables hardware pulsing (usually leave as false)
- Set to
trueonly if you experience timing issues - Most users should leave this as
false
-
inverse_colors(boolean, default: false)- Inverts all colors (red becomes cyan, etc.)
- Useful if your panel has inverted color channels
- Set to
trueonly if colors appear inverted
-
show_refresh_rate(boolean, default: false)- Displays the current refresh rate on the matrix (for debugging)
- Set to
trueto see FPS on the display - Useful for troubleshooting performance issues
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
- 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
-
row_address_type(integer, default: 0)- How rows are addressed on the panel
- Most panels use 0 (direct addressing)
- Some panels require 1 (AB addressing) or 2 (ABC addressing)
- Check your panel datasheet if display appears corrupted
-
multiplexing(integer, default: 0)- Panel multiplexing type
- 0 = no multiplexing (standard panels)
- Higher values for panels with different multiplexing schemes
- Check your panel datasheet for the correct value
Runtime Configuration (display.runtime)
These settings control runtime behavior and GPIO timing:
gpio_slowdown(integer, default: 3)- GPIO timing slowdown factor
- Critical setting: Must match your Raspberry Pi model for stability
- Raspberry Pi 3: Use 3
- Raspberry Pi 4: Use 4
- Raspberry Pi 5: Use 1–2 in PIO mode (
rp1_rio: 0, the default); start with1and increase if you see flickering - Raspberry Pi Zero/1: Use 1-2
- Incorrect values can cause display corruption, flickering, or system instability
- If you experience issues, try adjusting this value up or down by 1
Display Durations (display.display_durations)
Controls how long each display module stays visible in seconds before switching to the next one.
-
calendar(integer, default: 30)- Duration in seconds for the calendar display
- Increase for more time to read dates/events
- Decrease to cycle through other displays faster
-
Plugin-specific durations
- Each plugin can have its own duration setting
- Format:
"<plugin-id>": <seconds> - Example:
"hockey-scoreboard": 45shows hockey scores for 45 seconds - Example:
"weather": 20shows 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_durationin 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
falsefor longer, more readable dates - Set to
trueto 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 (typically 90 seconds)
Example Configuration
{
"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, andparallelmatch your physical setup - Verify
hardware_mappingmatches your HAT/connection type - Try adjusting
gpio_slowdown - Ensure your display doesn't need the E-Addressable line
Colors are wrong or inverted:
- Check
led_rgb_sequence(try "GRB" if "RGB" doesn't work) - Try setting
inverse_colorstotrue - Verify
hardware_mappingis correct for your hardware
Display flickers or is unstable:
- Increase
gpio_slowdownby 1-2 - Lower
limit_refresh_rate_hzto 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_bitsto 8 - Set
pwm_dither_bitsto 0
Manual SSH Commands (for reference)
The quick actions essentially just execute the following commands on the Pi.
From the project root directory (ex: /home/ledpi/LEDMatrix):
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 servicestop_display.sh- Stops the LED matrix display service
Make them executable with:
chmod +x start_display.sh stop_display.sh
Then use them to control the service:
sudo ./start_display.sh
sudo ./stop_display.sh
Service Installation Details
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)
- Make the install script executable:
chmod +x scripts/install/install_service.sh
- Run the install script with sudo:
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:
# 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
Web Interface Installation Details
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.
- Make the install script executable:
chmod +x scripts/install/install_web_service.sh
- Run the install script with sudo:
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:
- In
config/config.json, ensure the web interface autostart is enabled:
{
"web_display_autostart": true
}
- The web interface will now start automatically when:
- The system boots
- The
web_display_autostartsetting istruein 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
# 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:
- Check if the web service is running:
sudo systemctl status ledmatrix-web.service - Verify the service is enabled:
sudo systemctl is-enabled ledmatrix-web.service - Check logs for errors:
journalctl -u ledmatrix-web.service -f - Ensure
web_display_autostartis set totrueinconfig/config.json
Port 5000 Not Accessible:
- Check if the service is running on the correct port
- Verify firewall settings allow access to port 5000
- Check if another service is using port 5000
Service Fails to Start:
- Check Python dependencies are installed
- Verify the virtual environment is set up correctly
- Check file permissions and ownership
If you've read this far — thanks!
License
LEDMatrix is licensed under the GNU General Public License v3.0 or later.
LEDMatrix builds on
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
are also GPL-3.0-or-later unless individual plugins specify otherwise.
Contributing
See CONTRIBUTING.md for development setup, the PR flow, and how to add a plugin. Bug reports and feature requests go in the issue tracker. Security issues should be reported privately per SECURITY.md.