mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-04 14:25:08 +00:00
ChuckandClaude Opus 5.5
a12be7c3c5
* perf(timing): say which render-thread work a late frame followed The soak already says how often a moving frame reached the panel late, but not what the render thread was doing just before it. Vegas does two kinds of work there between frames -- building its strip (compose, extend) and, with live elements, patching changed pixels into it -- and deciding whether either is affordable needs their own numbers. - FrameTimingRecorder.note_op(kind, nbytes) tags the next presented frame. Totals gain op_frames, late_op_frames, op_freezes and op_bytes per kind; aggregate() still takes frames without ops. The file schema is unchanged. - Vegas tags compose and every strip extension (with the bytes it copied). - frame_soak prints an "after work" table: frames, late %, freezes and MB moved per kind, only when something tagged its work. - render_bench gains --strip-screens (Vegas-sized strips), --patch-bytes / --patch-every / --patch-where (in-place column writes, as a live element update does) and --extend-every-screens / --extend-width (append + trim on a fixed cadence that holds the strip's width). No runtime behaviour changes: this is the measurement gate for live Vegas elements. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(changelog): note the frame-op attribution and bench modes Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * perf(scroll): build the strip's PIL image only when something reads it Every Vegas strip extension rebuilt ScrollHelper.cached_image from cached_array in full, twice (append, then trim), on the render thread: Image.fromarray is 1.7ms for an 8,000px strip and 3.8ms for 20,000px on a Pi 4 (measured on ledpi), about two thirds of an extension's render-thread cost. Nothing on the frame path reads the image's pixels; every frame is cut from the array. cached_image is now a property. append_content and drop_scrolled_prefix defer it; the first read builds it from the array it started with and keeps it only if the strip has not changed meanwhile, so a sync push racing an extension cannot leave a stale image cached. Assigning cached_image stores exactly what was assigned, as before. has_strip() says whether there is a strip without building its image; the helper's frame path, Vegas and the adapter's scroll-cache invalidation use it. The strip is also no longer held in memory twice. In Vegas the image is now built only by a multi-display sync push. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(vegas): live elements -- a plugin API for content that changes while it scrolls Vegas bakes each plugin's pictures into one strip, so a card already on its way across the panel keeps what it showed when it was drawn. This adds the API and bookkeeping for content that can be updated in place; the worker that redraws and swaps it follows separately. No shipped plugin implements the hook yet, so nothing changes for users. Plugin API (core 3.8.0), all no-ops by default: - BasePlugin.get_vegas_elements() -> [VegasElement(key, image, version, live, refresh_hz)]: named, fixed-width pieces of Vegas content. - BasePlugin.redraw_vegas_element(key, width, height, at): a lock-free redraw for content that changes with time. - BasePlugin.notify_vegas_data_changed(): data that lands outside update(). - src/plugin_system/vegas_elements.py (VegasElement, re-exported from base_plugin). Core: - PluginAdapter asks a plugin that implements the hook for elements on the background fetch only (under its lock, on its own canvas); every other path keeps get_vegas_content(). Live elements are pinned (padded with content_padding, never trimmed), tagged with their key, digest and data epoch in Image.info so the existing cache and group plumbing carry them unchanged, and untagged if a width budget crops them. - RenderPipeline records where each live element lands (ElementRecord), in absolute strip columns a trim does not move; the block-start arithmetic is shared with the STATIC markers. - PluginManager update listeners (add/remove_update_listener, notify_data_changed): told the moment update() completes, not at the next ~4s Vegas poll. The coordinator uses one to move each plugin's data epoch on. - vegas_scroll.live_refresh (kill switch), live_max_hz, live_min_interval, live_lead_screens; per-plugin core-owned vegas_live. Live elements are off under multi-display sync, in swap mode and with offscreen_prefetch off. - scripts/check_plugin.py checks the element contract (src/plugin_system/testing/vegas.py); test/fixtures/plugins/vegas-live-stub is a working example. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(vegas): live elements update in place while they scroll One background worker (src/vegas_mode/live_worker.py) redraws a plugin's live elements when its data epoch moves on (update listener) or on their refresh_hz, nearest the screen first, and hands changed pixels lock-free to the render thread, which copies them into the strip between frames (RenderPipeline.apply_live_patches, ScrollHelper.patch_columns): at most four patches or two screens of bytes a frame, no drawing or locks there. The worker takes over group prefetch once a live element is placed, runs inside the render gate, and is supervised. Update tick 1s while live elements exist. Web UI switch for live_refresh. OFFSCREEN_RENDERING.md describes what was built and why SegmentStrip was not needed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(sports): live Vegas cards for the scoreboards (shared layer) One live element per game, drawn only when what the card shows changes, so a score changes on a card already crossing the panel. The shared part, so each scoreboard adopts it in a few lines: - src/common/sports_vegas.py: game_key, game_fingerprint (the whole game dict, frozen: no drawn field can be missed), dedupe_games, VegasCardCache, StickyOdds (odds a live poll left out stay drawn), finished_games / with_finished_games (a game that just went final keeps its card, after its league's live games; one a heuristic only judged over keeps its live state, so a tied end of regulation never shows FINAL early). - SportsScrollDisplay.make_vegas_renderer() is the override point; build_vegas_elements() and SportsScrollDisplayManager .get_vegas_elements_for() do the rest. A card's version includes its teams' ranks, which the renderer draws from the rankings cache. - SportsLiveSharedMixin._record_finished_game() / finished_games_snapshot(): held for FINISHED_GAME_TTL after it leaves the live list. A sport that does not implement make_vegas_renderer keeps its ordinary Vegas content, so no scoreboard changes until it opts in. scripts/render_plugin.py --vegas renders a plugin's Vegas block as the ticker lays it out, and --timeline stacks it at successive moments as the ticker would update it in place; the join is now render_pipeline.join_plugin_rows(). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(sports): a default _determine_game_type on SportsScrollDisplay render_vegas_card looked the method up with getattr and a None default, which static analysis (Codacy) reports as calling something that may not be callable. The base class now has the default -- the card type from the game's state -- and the plugins that define their own override it as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix: review follow-ups on the shared live-card layer - The reused Vegas renderer always gets the current rankings, empty included, so ranks cleared since are not kept drawn. - render_plugin.py: --timeline refuses --no-live (a timeline shows live elements changing), --timeline/--no-live need --vegas, and the Vegas paths create the output's directory like the display path does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Scripts
Helper scripts for installing, repairing, diagnosing and developing LEDMatrix. Most users only ever run the one-shot installer (see the project README); everything else here is for troubleshooting or development.
Status key: keep — part of install/runtime or referenced by docs, CI, tests or code; dev-only — for plugin/core development, not needed on a display; diagnostic — run by hand on a Pi when something is wrong.
Directories
| Directory | Status | What it holds |
|---|---|---|
install/ |
keep | The installers: one-shot, services, sudoers/WiFi permissions, cache setup, and the shared lib_*.sh helpers first_time_install.sh sources |
fix_perms/ |
keep | Permission repair scripts, plus the two root helpers the web interface runs through sudo (safe_plugin_rm.sh, safe_pip_install.sh) |
utils/ |
keep | Scripts run by systemd units or the web interface (conditional web start, WiFi monitor, update verify, DNS fix, Pixlet config editor, cache clearing) |
dev/ |
dev-only | Plugin linking, emulator runner, Vegas density audit, Pillow smoke test |
templates/ |
dev-only | dev_preview.html, the page dev_server.py serves |
Top-level scripts
| Script | Status | What it does |
|---|---|---|
build_rgbmatrix_nogil.sh |
keep | Rebuilds the rgbmatrix Python binding so SwapOnVSync releases the GIL (docs/SCROLL_PERFORMANCE.md) |
check_plugin.py |
dev-only | Renders a plugin across every mode and matrix size and fails on crashes, overflow or golden-image drift |
check_release_version.py |
keep | Checks a release tag, CHANGELOG and src.__version__ agree (release-version-check workflow) |
check_system_compatibility.sh |
diagnostic | Pre-install check of hardware, OS (Trixie only), kernel, Python, packages, disk and network |
dev_server.py |
dev-only | Browser preview server for plugins without the display loop (http://localhost:5001) |
diagnose_dependencies.sh |
diagnostic | Investigates pip installs stuck on "Preparing metadata" |
diagnose_web_interface.sh |
diagnostic | Checks why the web interface is not reachable |
download_pixlet.sh |
keep | Downloads the bundled Pixlet binaries for Starlark apps (also run from the web UI) |
emergency_reconnect.sh |
diagnostic | Reconnects to your WiFi network if captive-portal testing leaves the Pi offline |
frame_soak.py |
diagnostic | Soaks a running display and reports how often frames reached the panel late (docs/SCROLL_PERFORMANCE.md) |
install_dependencies_apt.py |
keep | Dependency installer that tries apt packages first, then pip (installer Step 7, plugin loader) |
install_plugin_dependencies.sh |
diagnostic | Installs plugin requirements by hand when the automatic install fails |
plugin_api_usage.py |
dev-only | Scans core, the plugin monorepo and the registry's third-party plugins for callers of every @deprecated core method; its output is docs/DEPRECATIONS_3.8.md |
prove_security.py |
keep | Security property checks run by pre-commit |
render_bench.py |
diagnostic | Benchmarks the render loop against the panel's real refresh rate on a synthetic strip |
render_plugin.py |
dev-only | Runs a plugin's update() + display() and saves the frame as a PNG |
reset_web_password.py |
keep | Turns the optional web login off when the password is lost (sudo python3 scripts/reset_web_password.py; docs/WEB_INTERFACE_GUIDE.md) |
run_plugin_tests.py |
dev-only | Discovers and runs plugin test suites |
scroll_speeds.py |
keep | Shows and tries the scroll speeds your panel can display cleanly |
sports_drift_report.py |
keep | Counts the different bodies of each method across the nine scoreboards in a ledmatrix-plugins checkout (report-only CI job; docs/SPORTS_UNIFICATION.md) |
troubleshoot_captive_portal.sh |
diagnostic | Troubleshoots captive-portal WiFi setup after you can SSH back in |
update_plugin_repos.py |
dev-only | Pulls the latest ledmatrix-plugins monorepo |
verify_installation.sh |
diagnostic | Checks that an installation completed correctly |
verify_wifi_setup.sh |
diagnostic | Health check of the WiFi management setup |
Candidates for removal
Nothing in the repo (docs, CI, tests, other scripts or code) refers to these. They are kept for now; each one needs an owner decision before it goes.
| Script | What it does |
|---|---|
add_defaults_to_schemas.py |
One-off: adds missing default values to plugin config schemas |
analyze_plugin_schemas.py |
One-off: reports duplicate/inconsistent fields across plugin schemas |
audit_plugins.py |
AST security audit of plugin code; says it is "designed to run in CI" but no workflow runs it |
audit_render_path.py |
Finds blocking calls reachable from a plugin's display() |
sports_scroll_check.py |
Drives a sports scoreboard scroll on the panel and reports its pacing |
test_captive_portal.sh |
Tests the captive portal from a device connected to the AP |
verify_wifi_before_testing.sh |
Pre-flight check before unplugging Ethernet to test WiFi |
dev/test_pillow_compat.py |
Pillow API smoke test to run after upgrading Pillow |