mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-10 13:02:59 +00:00
6812dfe7a6
* docs: refresh and correct stale documentation across repo
Walked the README and docs/ tree against current code and fixed several
real bugs and many stale references. Highlights:
User-facing
- README.md: web interface install instructions referenced
install_web_service.sh at the repo root, but it actually lives at
scripts/install/install_web_service.sh.
- docs/GETTING_STARTED.md: every web UI port reference said 5050, but
the real server in web_interface/start.py:123 binds 5000. Same bug
was duplicated in docs/TROUBLESHOOTING.md (17 occurrences). Fixed
both.
- docs/GETTING_STARTED.md: rewrote tab-by-tab instructions. The doc
referenced "Plugin Store", "Plugin Management", "Sports Configuration",
"Durations", and "Font Management" tabs - none of which exist. Real
tabs (verified in web_interface/templates/v3/base.html) are: Overview,
General, WiFi, Schedule, Display, Config Editor, Fonts, Logs, Cache,
Operation History, Plugin Manager (+ per-plugin tabs).
- docs/GETTING_STARTED.md: removed references to a "Test Display"
button (doesn't exist) and "Show Now" / "Stop" plugin buttons. Real
controls are "Run On-Demand" / "Stop On-Demand" inside each plugin's
tab (partials/plugin_config.html:792).
- docs/TROUBLESHOOTING.md: removed dead reference to
troubleshoot_weather.sh (doesn't exist anywhere in the repo); weather
is now a plugin in ledmatrix-plugins.
Developer-facing
- docs/PLUGIN_API_REFERENCE.md: documented draw_image() doesn't exist
on DisplayManager. Real plugins paste onto display_manager.image
directly (verified in src/base_classes/{baseball,basketball,football,
hockey}.py). Replaced with the canonical pattern.
- docs/PLUGIN_API_REFERENCE.md: documented cache_manager.delete() doesn't
exist. Real method is clear_cache(key=None). Updated the section.
- docs/PLUGIN_API_REFERENCE.md: added 10 missing BasePlugin methods that
the doc never mentioned: dynamic-duration hooks, live-priority hooks,
and the full Vegas-mode interface.
- docs/PLUGIN_DEVELOPMENT_GUIDE.md: same draw_image fix.
- docs/DEVELOPMENT.md: corrected the "Plugin Submodules" section. Plugins
are NOT git submodules - .gitmodules only contains
rpi-rgb-led-matrix-master. Plugins are installed at runtime into the
plugins directory configured by plugin_system.plugins_directory
(default plugin-repos/). Both internal links in this doc were also
broken (missing relative path adjustment).
- docs/HOW_TO_RUN_TESTS.md: removed pytest-timeout from install line
(not in requirements.txt) and corrected the test/integration/ path
(real integration tests are at test/web_interface/integration/).
Replaced the fictional file structure diagram with the real one.
- docs/EMULATOR_SETUP_GUIDE.md: clone URL was a placeholder; default
pixel_size was documented as 16 but emulator_config.json ships with 5.
Index
- docs/README.md: rewrote. Old index claimed "16-17 files after
consolidation" but docs/ actually has 38 .md files. Four were missing
from the index entirely (CONFIG_DEBUGGING, DEV_PREVIEW,
PLUGIN_ERROR_HANDLING, STARLARK_APPS_GUIDE). Trimmed the navel-gazing
consolidation/statistics sections.
Out of scope but worth flagging:
- src/plugin_system/resource_monitor.py:343 and src/common/api_helper.py:287
call cache_manager.delete(key) but no such method exists on
CacheManager. Both call sites would AttributeError at runtime if hit.
Not fixed in this docs PR - either add a delete() shim or convert
callers to clear_cache().
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix WEB_INTERFACE_GUIDE and WIFI_NETWORK_SETUP
WEB_INTERFACE_GUIDE.md
- Web UI port: 5050 -> 5000 (4 occurrences)
- Tab list was almost entirely fictional. Documented tabs:
General Settings, Display Settings, Durations, Sports Configuration,
Plugin Management, Plugin Store, Font Management. None of these
exist. Real tabs (verified in web_interface/templates/v3/base.html:
935-1000): Overview, General, WiFi, Schedule, Display, Config Editor,
Fonts, Logs, Cache, Operation History, plus Plugin Manager and
per-plugin tabs in the second nav row. Rewrote the navigation
section, the General/Display/Plugin sections, and the Common Tasks
walkthroughs to match.
- Quick Actions list referenced "Test Display" button (doesn't exist).
Replaced with the real button list verified in
partials/overview.html:88-152: Start/Stop Display, Restart Display
Service, Restart Web Service, Update Code, Reboot, Shutdown.
- API endpoints used /api/* paths. The api_v3 blueprint mounts at
/api/v3 (web_interface/app.py:144), so the real paths are
/api/v3/config/main, /api/v3/system/status, etc. Fixed.
- Removed bogus "Sports Configuration tab" walkthrough; sports
favorites live inside each scoreboard plugin's own tab now.
- Plugin directory listed as /plugins/. Real default is plugin-repos/
(verified in config/config.template.json:130 and
display_controller.py:132); plugins/ is a fallback.
- Removed "Swipe navigation between tabs" mobile claim (not implemented).
WIFI_NETWORK_SETUP.md
- 21 occurrences of port 5050 -> 5000.
- All /api/wifi/* curl examples used the wrong path. The real wifi
API routes are at /api/v3/wifi/* (api_v3.py:6367-6609). Fixed.
- ap_password default was documented as "" (empty/open network) but
config/wifi_config.json ships with "ledmatrix123". Updated the
Quick Start, Configuration table, AP Mode Settings section, and
Security Recommendations to match. Also clarified that setting
ap_password to "" is the way to make it an open network.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix ADVANCED_FEATURES and REST_API_REFERENCE
REST_API_REFERENCE.md
- Wrong path: /fonts/delete/<font_family> -> /fonts/<font_family>
(verified the real DELETE route in
web_interface/blueprints/api_v3.py).
- Diffed the documented routes against the real api_v3 blueprint
(92 routes vs the 71 documented). Added missing sections:
- Error tracking (/errors/summary, /errors/plugin/<id>, /errors/clear)
- Health (/health)
- Schedule dim/power (/config/dim-schedule GET/POST)
- Plugin-specific endpoints (calendar/list-calendars,
of-the-day/json/upload+delete, plugins/<id>/static/<path>)
- Starlark Apps (12 endpoints: status, install-pixlet, apps CRUD,
repository browse/install, upload)
- Font preview (/fonts/preview)
- Updated table of contents with the new sections.
- Added a footer note that the API blueprint mounts at /api/v3
(app.py:144) and that SSE stream endpoints are defined directly on
the Flask app at app.py:607-615.
ADVANCED_FEATURES.md
- Vegas Scroll Mode section was actually accurate (verified all
config keys match src/vegas_mode/config.py:15-30).
- On-Demand Display section had multiple bugs:
- 5 occurrences of port 5050 -> 5000
- All API paths missing /v3 (e.g. /api/display/on-demand/start
should be /api/v3/display/on-demand/start)
- "Settings -> Plugin Management -> Show Now Button" UI flow doesn't
exist. Real flow: open the plugin's tab in the second nav row,
click Run On-Demand / Stop On-Demand.
- "Python API Methods" section showed
controller.show_on_demand() / clear_on_demand() /
is_on_demand_active() / get_on_demand_info() — none of these
methods exist on DisplayController. The on-demand machinery is
all internal (_set_on_demand_*, _activate_on_demand, etc) and
is driven through the cache_manager. Replaced the section with
a note pointing to the REST API.
- All Use Case Examples used the same fictional Python calls.
Replaced with curl examples against the real API.
- Cache Management section claimed "On-demand display uses Redis cache
keys". LEDMatrix doesn't use Redis — verified with grep that
src/cache_manager.py has no redis import. The cache is file-based,
managed by CacheManager (file at /var/cache/ledmatrix/ or fallback
paths). Rewrote the manual recovery section:
- Removed redis-cli commands
- Replaced cache.delete() Python calls with cache.clear_cache()
(the real public method per the same bug already flagged in
PLUGIN_API_REFERENCE.md)
- Replaced "Settings -> Cache Management" with the real Cache tab
- Documented the actual cache directory candidates
- Background Data Service section:
- Used "nfl_scoreboard" as the plugin id in the example.
The real plugin is "football-scoreboard" (handles both NFL and
NCAA). Fixed.
- "Implementation Status: Phase 1 NFL only / Phase 2 planned"
section was severely outdated. The background service is now
used by all sports scoreboards (football, hockey, baseball,
basketball, soccer, lacrosse, F1, UFC), the odds ticker, and
the leaderboard plugin. Replaced with a current "Plugins using
the background service" note.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix plugin config + store + dependency docs
PLUGIN_STORE_GUIDE.md
- 19 occurrences of port 5050 -> 5000
- All API paths missing /v3 (e.g. /api/plugins/install ->
/api/v3/plugins/install). Bulk fix.
PLUGIN_REGISTRY_SETUP_GUIDE.md
- Same port + /api/v3 fixes (3 occurrences each)
- "Go to Plugin Store tab" -> "Open the Plugin Manager tab and scroll
to the Install from GitHub section" (the real flow for registry
setup is the GitHub install section, not the Plugin Store search)
PLUGIN_CONFIG_QUICK_START.md
- Port 5001 -> 5000 (5001 is the dev_server.py default, not the web UI)
- "Plugin Store tab" install flow -> real Plugin Manager + Plugin Store
section + per-plugin tab in second nav row
- Removed reference to PLUGIN_CONFIG_TABS_SUMMARY.md (archived doc)
PLUGIN_CONFIGURATION_TABS.md
- "Plugin Management vs Configuration" section confusingly described
a "Plugins Tab" that doesn't exist as a single thing. Rewrote to
describe the real two-piece structure: Plugin Manager tab (browse,
install, toggle) vs per-plugin tabs (configure individual plugins).
PLUGIN_DEPENDENCY_GUIDE.md
- Port 5001 -> 5000
PLUGIN_DEPENDENCY_TROUBLESHOOTING.md
- Wrong port (8080) and wrong UI nav ("Plugin Store or Plugin
Management"). Fixed to the real flow.
PLUGIN_QUICK_REFERENCE.md
- "Plugin Location: ./plugins/ directory" -> default is plugin-repos/
(verified in config/config.template.json:130 and
display_controller.py:132). plugins/ is a fallback.
- File structure diagram showed plugins/ -> plugin-repos/.
- Web UI install flow: "Plugin Store tab" -> "Plugin Manager tab ->
Plugin Store section". Also fixed Configure ⚙️ button (doesn't
exist) and "Drag and drop reorder" (not implemented).
- API examples: replaced ad-hoc Python pseudocode with real curl
examples against /api/v3/plugins/* endpoints. Pointed at
REST_API_REFERENCE.md for the full list.
- "Migration Path Phase 1-5" was a roadmap written before the plugin
system shipped. The plugin system is now stable and live. Removed
the migration phases as they're history, not a roadmap.
- "Quick Migration" section called scripts/migrate_to_plugins.py
which doesn't exist anywhere in the repo. Removed.
- "Plugin Registry Structure" referenced
ChuckBuilds/ledmatrix-plugin-registry which doesn't exist. The
real registry is ChuckBuilds/ledmatrix-plugins. Fixed.
- "Next Steps" / "Questions to Resolve" sections were
pre-implementation planning notes. Replaced with a "Known
Limitations" section that documents the actually-real gaps
(sandboxing, resource limits, ratings, auto-updates).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix misc remaining docs (architecture, dev quickref, sub-dir READMEs)
PLUGIN_ARCHITECTURE_SPEC.md
- Added a banner at the top noting this is a historical design doc
written before the plugin system shipped. The doc is ~1900 lines
with 13 stale /api/plugins/* paths (real is /api/v3/plugins/*),
references to web_interface_v2.py (current is app.py), and a
Migration Strategy / Implementation Roadmap that's now history.
Banner points readers at the current docs
(PLUGIN_DEVELOPMENT_GUIDE, PLUGIN_API_REFERENCE,
REST_API_REFERENCE) without needing to retrofit every section.
PLUGIN_CONFIG_ARCHITECTURE.md
- 10 occurrences of /api/plugins/* missing /v3 prefix. Bulk fixed.
DEVELOPER_QUICK_REFERENCE.md
- cache_manager.delete("key") -> cache_manager.clear_cache("key")
with comment noting delete() doesn't exist. Same bug already
documented in PLUGIN_API_REFERENCE.md.
SSH_UNAVAILABLE_AFTER_INSTALL.md
- 4 occurrences of port 5001 -> 5000 in AP-mode and Ethernet/WiFi
recovery instructions.
PLUGIN_CUSTOM_ICONS_FEATURE.md
- Port 5001 -> 5000.
CONFIG_DEBUGGING.md
- Documented /api/v3/config/plugin/<id> and /api/v3/config/validate
endpoints don't exist. Replaced with the real endpoints:
/api/v3/config/main, /api/v3/plugins/schema?plugin_id=,
/api/v3/plugins/config?plugin_id=. Added a note that validation
runs server-side automatically on POST.
STARLARK_APPS_GUIDE.md
- "Plugins -> Starlark Apps" UI navigation path doesn't exist (5
occurrences). Replaced with the real path: Plugin Manager tab,
then the per-plugin Starlark Apps tab in the second nav row.
- "Navigate to Plugins" install step -> Plugin Manager tab.
web_interface/README.md
- Documented several endpoints that don't exist in the api_v3
blueprint:
- GET /api/v3/plugins (list) -> /api/v3/plugins/installed
- GET /api/v3/plugins/<id> -> doesn't exist
- POST /api/v3/plugins/<id>/config -> POST /api/v3/plugins/config
- GET /api/v3/plugins/<id>/enable + /disable -> POST /api/v3/plugins/toggle
- GET /api/v3/store/plugins -> /api/v3/plugins/store/list
- POST /api/v3/store/install/<id> -> POST /api/v3/plugins/install
- POST /api/v3/store/uninstall/<id> -> POST /api/v3/plugins/uninstall
- POST /api/v3/store/update/<id> -> POST /api/v3/plugins/update
- POST /api/v3/display/start/stop/restart -> POST /api/v3/system/action
- GET /api/v3/display/status -> GET /api/v3/system/status
- Also fixed config/secrets.json -> config/config_secrets.json
- Replaced the per-section endpoint duplication with a current real
endpoint list and a pointer to docs/REST_API_REFERENCE.md.
- Documented that SSE stream endpoints are defined directly on the
Flask app at app.py:607-615, not in the api_v3 blueprint.
scripts/install/README.md
- Was missing 3 of the 9 install scripts in the directory:
one-shot-install.sh, configure_wifi_permissions.sh, and
debug_install.sh. Added them with brief descriptions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: clarify plugin paths and fix systemd manual install bug
PLUGIN_DEVELOPMENT_GUIDE.md
- Added a "Plugin directory note" callout near the top explaining
the plugins/ vs plugin-repos/ split:
- Dev workflow uses plugins/ (where dev_plugin_setup.sh creates
symlinks)
- Production / Plugin Store uses plugin-repos/ (the configurable
default per config.template.json:130)
- The plugin loader falls back to plugins/ so dev symlinks are
picked up automatically (schema_manager.py:77)
- User can set plugins_directory to "plugins" in the General tab
if they want both to share a directory
CLAUDE.md
- The Project Structure section had plugins/ and plugin-repos/
exactly reversed:
- Old: "plugins/ - Installed plugins directory (gitignored)"
"plugin-repos/ - Development symlinks to monorepo plugin dirs"
- Real: plugin-repos/ is the canonical Plugin Store install
location and is not gitignored. plugins/* IS gitignored
(verified in .gitignore) and is the legacy/dev location used by
scripts/dev/dev_plugin_setup.sh.
Reversed the descriptions and added line refs.
systemd/README.md
- "Manual Installation" section told users to copy the unit file
directly to /etc/systemd/system/. Verified the unit file in
systemd/ledmatrix.service contains __PROJECT_ROOT_DIR__
placeholders that the install scripts substitute at install time.
A user following the manual steps would get a service that fails
to start with "WorkingDirectory=__PROJECT_ROOT_DIR__" errors.
Added a clear warning and a sed snippet that substitutes the
placeholder before installing.
src/common/README.md
- Was missing 2 of the 11 utility modules in the directory
(verified with ls): permission_utils.py and cli.py. Added brief
descriptions for both.
Out-of-scope code bug found while auditing (flagged but not fixed):
- scripts/dev/dev_plugin_setup.sh:9 sets PROJECT_ROOT="$SCRIPT_DIR"
which resolves to scripts/dev/, not the project root. This means
the script's PLUGINS_DIR resolves to scripts/dev/plugins/ instead
of the project's plugins/ — confirmed by the existence of
scripts/dev/plugins/of-the-day/ from prior runs. Real fix is to
set PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)". Not fixing in
this docs PR.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: flag aspirational/regressed features in plugin docs
These docs describe features that exist as documented in the doc but
either never wired up or regressed when v3 shipped. Each gets a clear
status banner so plugin authors don't waste time chasing features that
don't actually work.
FONT_MANAGER.md
- The "For Plugin Developers / Plugin Font Registration" section
documents adding a "fonts" block to manifest.json that gets
registered via FontManager.register_plugin_fonts(). The method
exists at src/font_manager.py:150 but is **never called from
anywhere** in the codebase (verified: zero callers). A plugin
shipping a manifest "fonts" block has its fonts silently ignored.
Added a status warning and a note about how to actually ship plugin
fonts (regular files in the plugin dir, loaded directly).
PLUGIN_IMPLEMENTATION_SUMMARY.md
- Added a top-level status banner.
- Architecture diagram referenced src/plugin_system/registry_manager.py
(which doesn't exist) and listed plugins/ as the install location.
Replaced with the real file list (plugin_loader, schema_manager,
health_monitor, operation_queue, state_manager) and pointed at
plugin-repos/ as the default install location.
- "Dependency Management: Virtual Environments" — verified there's no
per-plugin venv. Removed the bullet and added a note that plugin
Python deps install into the system Python environment, with no
conflict resolution.
- "Permission System: File Access Control / Network Access /
Resource Limits / CPU and memory constraints" — none of these
exist. There's a resource_monitor.py and health_monitor.py for
metrics/warnings, but no hard caps or sandboxing. Replaced the
section with what's actually implemented and a clear note that
plugins run in the same process with full file/network access.
PLUGIN_CUSTOM_ICONS.md and PLUGIN_CUSTOM_ICONS_FEATURE.md
- The custom-icon feature was implemented in the v2 web interface
via a getPluginIcon() helper in templates/index_v2.html that read
the manifest "icon" field. When the v3 web interface was built,
that helper wasn't ported. Verified in
web_interface/templates/v3/base.html:515 and :774, plugin tab
icons are hardcoded to `fas fa-puzzle-piece`. The "icon" field in
plugin manifests is currently silently ignored (verified with grep
across web_interface/ and src/plugin_system/ — zero non-action-
related reads of plugin.icon or manifest.icon).
- Added a status banner to both docs noting the regression so plugin
authors don't think their custom icons are broken in their own
plugin code.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix .cursor/ helper docs
The .cursor/ directory holds the dev-side helper docs that Cursor and
contributors using AI tooling rely on to bootstrap plugin development.
Several of them had the same bug patterns as the user-facing docs.
.cursor/plugin_templates/QUICK_START.md
- "Adding Image Rendering" section showed
display_manager.draw_image(image, x=0, y=0). That method doesn't
exist on DisplayManager (same bug as PLUGIN_API_REFERENCE.md and
PLUGIN_DEVELOPMENT_GUIDE.md). Replaced with the canonical
display_manager.image.paste((x,y)) pattern, including the
transparency-mask form.
.cursor/plugins_guide.md
- 10 occurrences of ./dev_plugin_setup.sh — the script lives at
scripts/dev/dev_plugin_setup.sh, so anyone copy-pasting these
examples gets "command not found". Bulk fixed via sed.
- "Test with emulator: python run.py --emulator" — there's no
--emulator flag. Replaced with the real options:
EMULATOR=true python3 run.py for the full display, or
scripts/dev_server.py for the dev preview.
- Secrets management section showed a fictional
"config_secrets": { "api_key": "my-plugin.api_key" } reference
field. Verified in src/config_manager.py:162-172 that secrets are
loaded by deep-merging config_secrets.json into the main config.
There is no separate reference field — just put the secret under
the same plugin namespace and read it from the merged config.
Rewrote the section with the real pattern.
- "ssh pi@raspberrypi" -> "ssh ledpi@your-pi-ip" (consistent with
the rest of LEDMatrix docs which use ledpi as the default user)
.cursor/README.md
- Same ./dev_plugin_setup.sh -> ./scripts/dev/dev_plugin_setup.sh
fix (×6 occurrences via replace_all).
- Same "python run.py --emulator" -> "EMULATOR=true python3 run.py"
fix. Also added a pointer to scripts/dev_server.py for previewing
plugins without running the full display.
- "Example Plugins: plugins/hockey-scoreboard/" — the canonical
source is the ledmatrix-plugins repo. Installed copies land in
plugin-repos/ or plugins/. Updated the line to point at the
ledmatrix-plugins repo and explain both local locations.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix .cursorrules — the file Cursor auto-loads to learn the API
This is the file that Cursor reads to learn how plugin development
works. Stale entries here directly mislead AI-assisted plugin authors
on every new plugin. Several of the same bug patterns I've been
fixing in the user-facing docs were here too.
Display Manager section (highest impact)
- "draw_image(image, x, y): Draw PIL Image" — that method doesn't
exist on DisplayManager. Same bug already fixed in
PLUGIN_API_REFERENCE.md, PLUGIN_DEVELOPMENT_GUIDE.md,
ledmatrix-stocks/README.md, and .cursor/plugin_templates/QUICK_START.md.
Removed the bullet and replaced it with a paragraph explaining the
real pattern: paste onto display_manager.image directly, then
update_display(). Includes the transparency-mask form.
- Added the small_font/centered args to draw_text() since they're
the ones that matter most for new plugin authors
- Added draw_weather_icon since it's commonly used
Cache Manager section
- "delete(key): Remove cached value" — there's no delete() method
on CacheManager. The real method is clear_cache(key=None) (also
removes everything when called without args). Same bug as before.
- Added get_cached_data_with_strategy and get_background_cached_data
since contributors will hit these when working on sports plugins
Plugin System Overview
- "loaded from the plugins/ directory" — clarified that the default
is plugin-repos/ (per config.template.json:130) with plugins/ as
the dev fallback used by scripts/dev/dev_plugin_setup.sh
Plugin Development Workflow
- ./dev_plugin_setup.sh -> ./scripts/dev/dev_plugin_setup.sh (×2)
- Manual setup step "Create directory in plugins/<plugin-id>/" ->
plugin-repos/<plugin-id>/ as the canonical location
- "Use emulator: python run.py --emulator or ./run_emulator.sh"
— the --emulator flag doesn't exist; ./run_emulator.sh isn't at
root (it lives at scripts/dev/run_emulator.sh). Replaced with the
real options: scripts/dev_server.py for dev preview, or
EMULATOR=true python3 run.py for the full emulator path.
Configuration Management
- "Reference secrets via config_secrets key in main config" — this
is the same fictional reference syntax I just fixed in
.cursor/plugins_guide.md. Verified in src/config_manager.py:162-172
that secrets are deep-merged into the main config; there's no
separate reference field. Replaced with a clear explanation of
the deep-merge approach.
Code Organization
- "plugins/<plugin-id>/" -> the canonical location is
plugin-repos/<plugin-id>/ (or its dev-time symlink in plugins/)
- "see plugins/hockey-scoreboard/ as reference" — the canonical
source for example plugins is the ledmatrix-plugins repo. Updated
the pointer.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add LICENSE (GPL-3.0) and CONTRIBUTING.md
LICENSE
- The repository previously had no LICENSE file. The README and every
downstream plugin README already reference GPL-3.0 ("same as
LEDMatrix project"), but the canonical license text was missing —
contributors had no formal record of what they were contributing
under, and GitHub couldn't auto-detect the license for the repo
banner.
- Added the canonical GPL-3.0 text from
https://www.gnu.org/licenses/gpl-3.0.txt (verbatim, 674 lines).
- Compatibility verified: rpi-rgb-led-matrix is GPL-2.0-or-later
(per its COPYING file and README; the "or any later version" clause
in lib/*.h headers makes GPL-3.0 distribution legal).
CONTRIBUTING.md
- The repository had no CONTRIBUTING file. New contributors had to
reconstruct the dev setup from DEVELOPMENT.md, PLUGIN_DEVELOPMENT_GUIDE.md,
SUBMISSION.md, and the root README.
- Added a single page covering: dev environment setup (preview
server, emulator, hardware), running tests, PR submission flow,
commit message convention, plugin contribution pointer, and the
license terms contributors are agreeing to.
> Note for the maintainer: I (the AI assistant doing this audit) am
> selecting GPL-3.0 because every reference in the existing
> documentation already says GPL-3.0 — this commit just makes that
> declaration legally binding by adding the actual file. Please
> confirm during PR review that GPL-3.0 is what you want; if you
> prefer a different license, revert this commit before merging.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add CODE_OF_CONDUCT, SECURITY, PR template; link them from README
Tier 1 organizational files that any open-source project at
LEDMatrix's maturity is expected to have. None of these existed
before. They're additive — no existing content was rewritten.
CODE_OF_CONDUCT.md
- Contributor Covenant 2.1 (the de facto standard for open-source
projects). Mentions both the Discord and the GitHub Security
Advisories channel for reporting violations.
SECURITY.md
- Private vulnerability disclosure flow with two channels: GitHub
Security Advisories (preferred) and Discord DM.
- Documents the project's known security model as intentional
rather than vulnerabilities: no web UI auth, plugins run
unsandboxed, display service runs as root for GPIO access,
config_secrets.json is plaintext. These match the limitations
already called out in PLUGIN_QUICK_REFERENCE.md and the audit
flagging from earlier in this PR.
- Out-of-scope section points users at upstream
(rpi-rgb-led-matrix, third-party plugins) so reports land in the
right place.
.github/PULL_REQUEST_TEMPLATE.md
- 10-line checklist that prompts for the things that would have
caught the bugs in this very PR: did you load the changed plugin
once, did you update docs alongside code, are there any plugin
compatibility implications.
- Linked from CONTRIBUTING.md for the full flow.
README.md
- Added a License section near the bottom (the README previously
said nothing about the license despite the project being GPL-3.0).
- Added a Contributing section pointing at CONTRIBUTING.md and
SECURITY.md.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Customize bug report template for LEDMatrix hardware
The bug_report.md template was the GitHub default and asked
"Desktop (OS/Browser/Version)" and "Smartphone (Device/OS)" — neither
of which is relevant for a project that runs on a Raspberry Pi with
hardware LED panels. A user filing a bug under the old template was
giving us none of the information we'd actually need to triage it.
Replaced with a LEDMatrix-aware template that prompts for:
- Pi model, OS/kernel, panel type, HAT/Bonnet, PWM jumper status,
display chain dimensions
- LEDMatrix git commit / release tag
- Plugin id and version (if the bug is plugin-related)
- Relevant config snippet (with redaction reminder for API keys)
- journalctl log excerpt with the exact command to capture it
- Optional photo of the actual display for visual issues
Kept feature_request.md as-is — generic content there is fine.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix bare /api/plugins paths in PLUGIN_CONFIGURATION_TABS
Found 5 more bare /api/plugins/* paths in PLUGIN_CONFIGURATION_TABS.md
that I missed in the round 2 sweep — they're inside data flow diagrams
and prose ("loaded via /api/plugins/installed", etc.) so the earlier
grep over Markdown code blocks didn't catch them. Fixed all 5 to use
/api/v3/plugins/* (the api_v3 blueprint mount path verified at
web_interface/app.py:144).
Also added a status banner noting that the "Implementation Details"
section references the pre-v3 file layout (web_interface_v2.py,
templates/index_v2.html) which no longer exists. The current
implementation is in web_interface/app.py, blueprints/api_v3.py, and
templates/v3/. Same kind of historical drift I flagged in
PLUGIN_ARCHITECTURE_SPEC.md and the PLUGIN_CUSTOM_ICONS_FEATURE doc.
The user-facing parts of the doc (Overview, Features, Form Generation
Process) are still accurate.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(widgets): list the 20 undocumented built-in widgets
The widget registry README documented 3 widgets (file-upload,
checkbox-group, custom-feeds) but the directory contains 23 registered
widgets total. A plugin author reading this doc would think those 3
were the only built-in options and either reach for a custom widget
unnecessarily or settle for a generic text input.
Verified the actual list with:
grep -h "register('" web_interface/static/v3/js/widgets/*.js \
| sed -E "s|.*register\\('([^']+)'.*|\\1|" | sort -u
Added an "Other Built-in Widgets" section after the 3 detailed
sections, listing the remaining 20 with one-line descriptions
organized by category:
- Inputs (6): text-input, textarea, number-input, email-input,
url-input, password-input
- Selectors (7): select-dropdown, radio-group, toggle-switch,
slider, color-picker, font-selector, timezone-selector
- Date/time/scheduling (4): date-picker, day-selector, time-range,
schedule-picker
- Composite/data-source (2): array-table, google-calendar-picker
- Internal (2): notification, base-widget
Pointed at the .js source files as the canonical source for each
widget's exact schema and options — keeps this list low-maintenance
since I'm not duplicating each widget's full options table.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix README_NBA_LOGOS and PLUGIN_CONFIGURATION_GUIDE
scripts/README_NBA_LOGOS.md
- "python download_nba_logos.py" — wrong on two counts. The script
is at scripts/download_nba_logos.py (not the project root), and
"python" is Python 2 on most systems. Replaced all 4 occurrences
with "python3 scripts/download_nba_logos.py".
- The doc framed itself as the way to set up "the NBA leaderboard".
The basketball/leaderboard functionality is now in the
basketball-scoreboard and ledmatrix-leaderboard plugins (in the
ledmatrix-plugins repo), which auto-download logos on first run.
Reframed the script as a pre-population utility for offline / dev
use cases.
- Bumped the documented Python minimum from 3.7 to 3.9 to match
the rest of the project.
docs/PLUGIN_CONFIGURATION_GUIDE.md
- The "Plugin Manifest" example was missing 3 fields the plugin
loader actually requires: id, entry_point, and class_name. A
contributor copying this manifest verbatim would get
PluginError("No class_name in manifest") at load time — the same
loader bug already found in stock-news. Added all three.
- The same example showed config_schema as an inline object. The
loader expects config_schema to be a file path string (e.g.
"config_schema.json") with the actual schema in a separate JSON
file — verified earlier in this audit. Fixed.
- Added a paragraph explaining the loader's required fields and
the case-sensitivity rule on class_name (the bug that broke
hello-world's manifest before this PR fixed it).
- "Plugin Manager Class" example had the wrong constructor
signature: (config, display_manager, cache_manager, font_manager).
The real BasePlugin.__init__ at base_plugin.py:53-60 takes
(plugin_id, config, display_manager, cache_manager, plugin_manager).
A copy-pasted example would TypeError on instantiation. Fixed,
including a comment noting which attributes BasePlugin sets up.
- Renamed the example class from MyPluginManager to MyPlugin to
match the project convention (XxxPlugin / XxxScoreboardPlugin
in actual plugins).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(requirements): document optional dependencies (scipy, psutil, Flask-Limiter)
A doc-vs-code crosscheck of every Python import in src/ and
web_interface/ against requirements.txt found 3 packages that the
code uses but requirements.txt doesn't list. Verified with grep that
all 3 are wrapped in try/except blocks with documented fallback
paths, so they're optional features rather than missing required
deps:
- scipy src/common/scroll_helper.py:26
→ from scipy.ndimage import shift; HAS_SCIPY flag.
Used for sub-pixel interpolation in scrolling.
Falls back to a simpler shift algorithm without it.
- psutil src/plugin_system/resource_monitor.py:15
→ import psutil; PSUTIL_AVAILABLE flag. Used for
per-plugin CPU/memory monitoring. Silently no-ops
without it.
- flask-limiter web_interface/app.py:42-43
→ from flask_limiter import Limiter; wrapped at the
caller. Used for accidental-abuse rate limiting on
the web interface (not security). Web interface
starts without rate limiting when missing.
These were latent in two ways:
1. A user reading requirements.txt thinks they have the full feature
set after `pip install -r requirements.txt`, but they don't get
smoother scrolling, plugin resource monitoring, or rate limiting.
2. A contributor who deletes one of the packages from their dev env
wouldn't know which feature they just lost — the fallbacks are
silent.
Added an "Optional dependencies" section at the bottom of
requirements.txt with the version constraint, the file:line where
each is used, the feature it enables, and the install command. The
comment-only format means `pip install -r requirements.txt` still
gives the minimal-feature install (preserving current behavior),
while users who want the full feature set can copy the explicit
pip install commands.
Other findings from the same scan that came back as false positives
or known issues:
- web_interface_v2: dead pattern flagged in earlier iteration
(still no real implementation; affects 11+ plugins via the same
try/except dead-fallback pattern)
- urllib3: comes with `requests` transitively
- All 'src.', 'web_interface.', 'rgbmatrix', 'RGBMatrixEmulator'
imports: internal modules
- base_plugin / plugin_manager / store_manager / mocks /
visual_display_manager: relative imports to local modules
- freetype: false positive (freetype-py is in requirements.txt
under the package name)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: fix broken file references found by path-existence crosscheck
Ran a doc-vs-filesystem crosscheck: extracted every backtick-quoted
path with a file extension or known directory prefix from docs/*.md
and verified each exists. After filtering false positives
(placeholder paths, config keys mistaken for paths, paths inside
docs that already have historical-status banners), found 4 real
broken references — 3 fixed in docs, 1 fixed by creating the missing
file:
docs/HOW_TO_RUN_TESTS.md:339
- Claimed ".github/workflows/tests.yml" exists and runs pytest on
multiple Python versions in CI. There is no such workflow.
The only GitHub Actions file is security-audit.yml (bandit + semgrep).
- Pytest runs locally but is NOT gated on PRs.
- Replaced the fictional CI section with the actual state and a
note explaining how someone could contribute a real test workflow.
docs/MIGRATION_GUIDE.md:92
- Referenced scripts/fix_perms/README.md "(if exists)" — the
hedge betrays that the writer wasn't sure. The README didn't
exist. The 6 scripts in scripts/fix_perms/ were never documented.
- Created the missing scripts/fix_perms/README.md from scratch
with one-line descriptions of all 6 scripts (fix_assets,
fix_cache, fix_plugin, fix_web, fix_nhl_cache, safe_plugin_rm)
+ when-to-use-each guidance + usage examples.
- Updated MIGRATION_GUIDE link to drop the "(if exists)" hedge
since the file now exists.
docs/FONT_MANAGER.md:376
- "See test/font_manager_example.py for a complete working example"
— that file does not exist. Verified by listing test/ directory.
- Replaced with a pointer to src/font_manager.py itself and the
existing scoreboard base classes in src/base_classes/ that
actually use the font manager API in production.
Path-existence check methodology:
- Walked docs/ recursively, regex-extracted backtick-quoted paths
matching either /\.(py|sh|json|yml|yaml|md|txt|service|html|js|css|ttf|bdf|png)/
or paths starting with known directory prefixes (scripts/, src/,
config/, web_interface/, systemd/, assets/, docs/, test/, etc.)
- Filtered out URLs, absolute paths (placeholders), and paths
without slashes (likely not relative refs).
- Checked existence relative to project root.
- Out of 80 unique relative paths in docs/, 32 didn't exist on
disk. Most were false positives (configkeys mistaken for paths,
example placeholders like 'assets/myfont.ttf', historical
references inside docs that already have status banners). The 4
above were genuine broken refs.
This pattern is reusable for future iterations and worth wiring
into CI (link checker like lychee, scoped to fenced code paths
rather than just markdown links, would catch the same class).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: address CodeRabbit review comments on #306
Reviewed all 12 CodeRabbit comments on PR #306, verified each against
the current code, and fixed the 11 valid ones. The 12th finding is a
real code bug (cache_manager.delete() calls in api_helper.py and
resource_monitor.py) that's already in the planned follow-up code-fix
PR, so it stays out of this docs PR.
Fixed:
.cursor/plugins_guide.md, .cursor/README.md, .cursorrules
- I claimed "there is no --emulator flag" in 3 places. Verified in
run.py:19-20 that the -e/--emulator flag is defined and functional
(it sets os.environ["EMULATOR"]="true" before the display imports).
Other docs I didn't touch (.cursor/plugin_templates/QUICK_START.md,
docs/PLUGIN_DEVELOPMENT_GUIDE.md) already use the flag correctly.
Replaced all 3 wrong statements with accurate guidance that
both forms work and explains the CLI flag's relationship to the
env var.
.cursorrules, docs/GETTING_STARTED.md, docs/WEB_INTERFACE_GUIDE.md,
docs/PLUGIN_DEVELOPMENT_GUIDE.md
- Four places claimed "the plugin loader also falls back to plugins/".
Verified that PluginManager.discover_plugins()
(src/plugin_system/plugin_manager.py:154) only scans the
configured directory — no fallback. The fallback to plugins/
exists only in two narrower places: store_manager.py:1700-1718
(store install/update/uninstall operations) and
schema_manager.py:70-80 (schema lookup for the web UI form
generator). Rewrote all four mentions with the precise scope.
Added a recommendation to set plugin_system.plugins_directory
to "plugins" for the smoothest dev workflow with
dev_plugin_setup.sh symlinks.
docs/FONT_MANAGER.md
- The "Status" warning told plugin authors to use
display_manager.font_manager.resolve_font(...) as a workaround for
loading plugin fonts. Verified in src/font_manager.py that
resolve_font() takes a family name, not a file path — so the
workaround as written doesn't actually work. Rewrote to tell
authors to load the font directly with PIL or freetype-py in their
plugin.
- The same section said "the user-facing font override system in the
Fonts tab still works for any element that's been registered via
register_manager_font()". Verified in
web_interface/blueprints/api_v3.py:5404-5428 that
/api/v3/fonts/overrides is a placeholder implementation that
returns empty arrays and contains "would integrate with the actual
font system" comments — the Fonts tab does not have functional
integration with register_manager_font() or the override system.
Removed the false claim and added an explicit note that the tab
is a placeholder.
docs/ADVANCED_FEATURES.md:523
- The on-demand section said REST/UI calls write a request "into the
cache manager (display_on_demand_config key)". Wrong — verified
via grep that api_v3.py:1622 and :1687 write to
display_on_demand_request, and display_on_demand_config is only
written by the controller during activation
(display_controller.py:1195, cleared at :1221). Corrected the key
name and added controller file:line references so future readers
can verify.
docs/ADVANCED_FEATURES.md:803
- "Plugins using the background service" paragraph listed all
scoreboard plugins but an orphaned "⏳ MLB (baseball)" bullet
remained below from the old version of the section. Removed the
orphan and added "baseball/MLB" to the inline list for clarity.
web_interface/README.md
- The POST /api/v3/system/action action list was incomplete. Verified
in web_interface/app.py:1383,1386 that enable_autostart and
disable_autostart are valid actions. Added both.
- The Plugin Store section was missing
GET /api/v3/plugins/store/github-status (verified at
api_v3.py:3296). Added it.
- The SSE line-range reference was app.py:607-615 but line 619
contains the "Exempt SSE streams from CSRF and add rate limiting"
block that's semantically part of the same feature. Extended the
range to 607-619.
docs/GETTING_STARTED.md
- Rows/Columns step said "Columns: 64 or 96 (match your hardware)".
The web UI's validation accepts any integer in 16-128. Clarified
that 64 and 96 are the common bundled-hardware values but the
valid range is wider.
Not addressed (out of scope for docs PR):
- .cursorrules:184 CodeRabbit comment flagged the non-existent
cache_manager.delete() calls in src/common/api_helper.py:287 and
src/plugin_system/resource_monitor.py:343. These are real CODE
bugs, not doc bugs, and they're the first item in the planned
post-docs-refresh code-cleanup PR (see
/home/chuck/.claude/plans/warm-imagining-river.md). The docs in
this PR correctly state that delete() doesn't exist on
CacheManager — the fix belongs in the follow-up code PR that
either adds a delete() shim or updates the two callers.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Chuck <chuck@example.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
905 lines
37 KiB
Markdown
905 lines
37 KiB
Markdown
# 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:
|
||
[](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>
|
||
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)
|
||
<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 and the Pi 5 is unsupported due to new GPIO output.
|
||
- **Raspberry Pi 3B or 4 (NOT RPi 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)
|
||
|
||
|
||
### 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)
|
||
- [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!)*
|
||
> Amazon Affiliate Link – 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, 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.
|
||
|
||
|
||
|
||
|
||
<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.
|
||
|
||
</details>
|
||
|
||
</details>
|
||
|
||
|
||
## Configuration
|
||
|
||
<details>
|
||
|
||
<summary>Configuration</summary>
|
||
|
||
## 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:
|
||
<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 (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](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.
|
||
|
||
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 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 `-pwm` from 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 `true` only 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 `true` only if colors appear inverted
|
||
|
||
- **`show_refresh_rate`** (boolean, default: false)
|
||
- Displays the current refresh rate on the matrix (for debugging)
|
||
- Set to `true` to 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 5 (or higher if needed)
|
||
- **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": 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 (typically 90 seconds)
|
||
|
||
### 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
|
||
|
||
**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).
|