mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-05 06:45:09 +00:00
ChuckandClaude Opus 5.5
11a7ca9671
The identical sweep: method families every scoreboard carrying them has as an identical copy (executable AST, docstrings stripped, decorators compared), re-measured at ledmatrix-plugins 56c4f15. Four new hardware-free modules; the bodies are the plugins', with type annotations and type comments for the mypy ratchet. - src/common/sports_plugin_host.py: SportsPluginHostMixin, ten helpers of the scoreboard plugin class (manager.py) identical in all nine: _dispatch_switch_refresh (with _SWITCH_REFRESH_MIN_GAP_SECONDS), get_vegas_priority_weight, _favorite_team_is_live, _favorite_scan_targets, _favorite_scan_games, _game_involves, get_vegas_content_type, _dynamic_feature_enabled, _get_total_games_for_manager, _build_manager_key. Listed before BasePlugin, whose defaults two of them override. - src/common/sports_live_scroll.py: SportsLiveScrollMixin, the eight manager.py methods that rebuild a live scroll strip mid-cycle (all eight scoreboards with a strip; ufc has none), with the two rebuild-rate constants. LIVE_VOLATILE_FIELDS differs (afl/nrl/soccer add period_text) and stays in each plugin as host contract. - src/common/sports_display_rules.py: SportsCardOptionsMixin (_card_option, _recent_date_text; the eight team scoreboards; must precede SportsCoreSharedMixin, whose _card_option it wraps) and SportsGameRulesMixin (_filtered_or_all, all but football; _effective_live_duration, all but ufc). Split by carrier so ufc does not gain a _card_option override it never had. - src/common/sports_font_path.py: resolve_font_path, what the 17 _resolve_font_path copies (nine sports.py, eight game_renderer.py) return on a core that ships it: the cwd first, then resolve_asset_path. Not resolve_asset_path alone, which skips the cwd. Left in the plugins: _get_timezone, _extract_game_details and _fetch_data (per-plugin import, abstract contract), _schema_font_size and _resolve_font_size (each plugin's _SCHEMA_PATH), and the families carried by seven plugins or fewer. Tests: behaviour ported from the plugins' own tests against stub hosts with exactly the documented contract, a host-contract test per mixin, and test_sports_stage4_parity.py, which with LEDMATRIX_PLUGINS set compares every promoted method and constant with every plugin copy using scripts/sports_drift_report.py's normalisation plus decorators and values (27 pass against 56c4f15; mutation-checked: a changed body, a swapped decorator, a changed constant, a dropped @contextmanager and an unlisted new method each fail it). test_sports_font_path.py runs both on the same paths from a temporary cwd. All four modules are on the mypy ratchet, in src/common/README.md, the CHANGELOG's Unreleased section (module entries for the sunset floor; the version is not bumped) and SPORTS_UNIFICATION. Nothing in core uses them yet. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LEDMatrix Documentation
This directory contains guides, references, and architectural notes for the LEDMatrix project. If you are setting up a Pi for the first time, start with the project root README — it covers hardware, OS imaging, and the one-shot installer. The pages here go deeper.
I'm a new user
- GETTING_STARTED.md — first-time setup walkthrough
- WEB_INTERFACE_GUIDE.md — using the web UI
- PLUGIN_STORE_GUIDE.md — installing and managing plugins
- WIFI_NETWORK_SETUP.md — WiFi and AP-mode setup
- TROUBLESHOOTING.md — common issues and fixes (PERMISSIONS.md for "Permission denied")
- SSH_UNAVAILABLE_AFTER_INSTALL.md — recovering SSH after install
- CONFIG_DEBUGGING.md — diagnosing config problems
- LOW_MEMORY_BOARDS.md — Pi Zero 2 W / 3B+ / 1GB Pi 4 memory limits
I want to write a plugin
Start here:
- PLUGIN_DEVELOPMENT_GUIDE.md — end-to-end workflow
- PLUGIN_QUICK_REFERENCE.md — cheat sheet
- PLUGIN_API_REFERENCE.md — display, cache, and plugin-manager APIs
- PLUGIN_ERROR_HANDLING.md — error-handling patterns
- DEV_PREVIEW.md — preview plugins on your dev machine without a Pi
- EMULATOR_SETUP_GUIDE.md — running the matrix emulator
Going deeper:
- ADVANCED_PLUGIN_DEVELOPMENT.md — advanced patterns
- PLUGIN_ARCHITECTURE_SPEC.md — original plugin-system design spec (historical; see its banner for what has drifted)
- PLUGIN_DEPENDENCY_GUIDE.md / PLUGIN_DEPENDENCY_TROUBLESHOOTING.md
- PLUGIN_WEB_UI_ACTIONS.md (+ example JSON)
- PLUGIN_CUSTOM_ICONS.md
- PLUGIN_REGISTRY_SETUP_GUIDE.md (+ registry template)
- STARLARK_APPS_GUIDE.md — Starlark-based mini-apps
- Widget guide — built-in
x-widgets and custom widgets - ADAPTIVE_LAYOUT.md — render legibly on any panel size (opt-in font/layout scaling)
- plugin-safety-harness.md — test a plugin across every screen and matrix size
Configuring plugins
- PLUGIN_CONFIG_QUICK_START.md — minimal config you need
- PLUGIN_CONFIGURATION_GUIDE.md — schema design
- PLUGIN_ELEMENT_STYLING.md — let users restyle, move, hide and scale individual elements (per display mode, if you have them)
- PLUGIN_CONFIGURATION_TABS.md — multi-tab UI configs
- PLUGIN_CONFIG_ARCHITECTURE.md — how the config system works
- PLUGIN_CONFIG_CORE_PROPERTIES.md — properties every plugin honors
Advanced features
- ADVANCED_FEATURES.md — Vegas scroll, on-demand display, cache management, background services, permissions
- FONT_MANAGER.md — font system
- SCROLL_PERFORMANCE.md — how scrolling is paced, and how to make a plugin's marquee smooth
- OFFSCREEN_RENDERING.md — rendering plugin content off the render thread
- PERMISSIONS.md — file ownership, sudo rules, repair scripts
- MQTT bridge — control the display from Home Assistant over MQTT
Reference
- CONFIG_REFERENCE.md — every key in config.json and config_secrets.json
- REST_API_REFERENCE.md — all web-interface HTTP endpoints
- PLUGIN_API_REFERENCE.md — Python APIs available to plugins
- src/common/README.md — shared helper modules plugins can import
- DEVELOPER_QUICK_REFERENCE.md — common dev tasks
Contributing to LEDMatrix itself
- ARCHITECTURE.md — processes, display loop, plugin system, web UI; where to start reading
- DEVELOPMENT.md — environment setup
- HOW_TO_RUN_TESTS.md — running the test suite
- MULTI_ROOT_WORKSPACE_SETUP.md — multi-repo workspace
- MIGRATION_GUIDE.md — breaking changes between releases
- SPORTS_UNIFICATION.md — how shared sports scoreboard code moves into
src/common
Audits
- audits/WEB_UI_AUDIT_2026-09.md — web UI audit (September 2026)
Contributing to the docs
- Markdown only, professional tone, minimal emoji.
- Prefer adding to an existing page over creating a new one. If you add a new page, link it from this index in the section it belongs to.
- If a page becomes obsolete, delete it (it stays in the repository
history) and fix the links to it;
test/test_doc_links.pyfails on broken relative links. - Keep examples runnable — paths, commands, and config keys here should match what's actually in the repo.