mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-08-06 19:28:06 +00:00

Files

T

ChuckBuildsandClaude Opus 5 ffd706a454 fix(backup): make a restored device match the one that was backed up

Found by wiping a working device and reinstalling from scratch. Every
problem here is invisible until you actually do that, which is why a
green test suite and eleven hours of uptime had not surfaced any of them.

**Four enabled plugins vanished on restore.** Weather, stocks, music and
leaderboard have a registry `id` that differs from the `id` in their own
manifest: the registry calls them `weather`, everything else calls them
`ledmatrix-weather`. Installation already prefers the manifest id for the
directory name and warns when the two disagree, so on disk, in
config.json and in a backup they are `ledmatrix-weather` -- but nothing
resolved that in reverse. Restore asked the store for `ledmatrix-weather`
and got "Plugin not found in registry", four times, and the device came
back missing four plugins the user had enabled.

Registry lookup now falls back to matching `plugin_path`, which already
records `plugins/ledmatrix-weather`. Renaming the published ids would
have orphaned `plugin_state.json` entries keyed on the old ones. Exact id
still wins, so a path that collides with another entry's id cannot
shadow it. Against the live registry and a real 28-plugin install this
takes unresolvable directories from five to one -- the one being
starlark-apps, which is genuinely not in the registry.

**Secrets could not be restored at all.** A fresh install left
config_secrets.json group-readable but not group-writable, and the web
interface -- which is what performs a restore -- does not necessarily run
as the owner. Every other file in the backup restored; secrets failed
with EACCES. Now group-writable, so the account running the web UI can
put them back.

**A partial restore reported "Restore had errors" and nothing else.**
That is the same message whether the whole thing failed or it quietly
dropped your API keys. It now names what was restored, what failed, and
which plugins were not reinstalled.

**ytm_auth.json was never in the backup.** It sits in config/ beside the
three files that are, and is pure device-local auth: losing it silently
signs the user out of YouTube Music. Backed up and restored with the
wifi config, which it resembles.

**Backups were written inside the directory a reinstall deletes.**
config/backups/exports is destroyed by the reinstall the user was told to
make it before. Exports now go beside the install, falling back to the
old path when that is not writable.

**The installer reboots without asking in non-interactive mode**, which
the README did not mention -- easy to hit when piping the install, and
alarming when a device you are installing onto disappears. Documented,
with --no-reboot-prompt. Its log also claimed root:ledmatrix while
printing a hardcoded group name rather than the one it used.

Tests: registry resolution gets its own suite, including the collision
case and third-party entries with an empty plugin_path. The existing
round-trip test passed throughout this because its fixture plugin has a
directory name equal to its id -- the one shape that cannot fail -- so it
now carries ytm_auth too.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Udr6MfaFLUPhX5Fgo67Jf5

2026-08-06 13:07:55 -04:00

blueprints

fix(backup): make a restored device match the one that was backed up

2026-08-06 13:07:55 -04:00

static/v3

Surface plugin update availability on the plugins page (#421 )

2026-07-21 08:06:36 -04:00

templates/v3

Give plugins access to device-wide config, and a global scroll frame rate (#424 )

2026-08-02 10:40:12 -04:00

__init__.py

fix(version): make the core version have exactly one answer (#428 )

2026-08-03 15:21:47 -04:00

app.py

Web UI: mobile navigation, guided onboarding, basic/advanced config tiering + performance (#417 )

2026-07-16 20:32:07 -04:00

cache.py

Plugins (#145 )

2025-12-27 14:15:49 -05:00

logging_config.py

fix: Codacy security fixes, CVE dependency bumps, and code quality cleanup (#331 )

2026-05-15 10:19:55 -04:00

README.md

docs: refresh and correct stale documentation across repo (#306 )

2026-04-07 21:04:25 -04:00

requirements.txt

Web UI: mobile navigation, guided onboarding, basic/advanced config tiering + performance (#417 )

2026-07-16 20:32:07 -04:00

run.sh

Plugins (#145 )

2025-12-27 14:15:49 -05:00

start.py

fix: Codacy round-2 — urllib3 CVEs, missed JS/Python issues (#336 )

2026-05-15 18:04:21 -04:00

README.md

LED Matrix Web Interface V3

Modern, production web interface for controlling the LED Matrix display.

Overview

This directory contains the active V3 web interface with the following features:

Real-time display preview via Server-Sent Events (SSE)
Plugin management and configuration
System monitoring and logs
Modern, responsive UI
RESTful API

Directory Structure

web_interface/
├── app.py                    # Main Flask application
├── start.py                  # Startup script
├── run.sh                    # Shell runner script
├── requirements.txt          # Python dependencies
├── blueprints/               # Flask blueprints
│   ├── api_v3.py            # API endpoints
│   └── pages_v3.py          # Page routes
├── templates/                # HTML templates
│   └── v3/
│       ├── base.html
│       ├── index.html
│       └── partials/
└── static/                   # CSS/JS assets
    └── v3/
        ├── app.css
        └── app.js

Running the Web Interface

Standalone (Development)

From the project root:

python3 web_interface/start.py

Or using the shell script:

./web_interface/run.sh

As a Service (Production)

The web interface can run as a systemd service that starts automatically based on the web_display_autostart configuration setting:

sudo systemctl start ledmatrix-web
sudo systemctl enable ledmatrix-web  # Start on boot

Accessing the Interface

Once running, access the web interface at:

Local: http://localhost:5000
Network: http://:5000

Configuration

The web interface reads configuration from:

config/config.json - Main configuration
config/config_secrets.json - API keys and secrets

API Documentation

The V3 API is mounted at /api/v3/ (app.py:144). For the complete list and request/response formats, see docs/REST_API_REFERENCE.md. Quick reference for the most common endpoints:

Configuration

GET /api/v3/config/main - Get main configuration
POST /api/v3/config/main - Save main configuration
GET /api/v3/config/secrets - Get secrets configuration
POST /api/v3/config/raw/main - Save raw main config (Config Editor)
POST /api/v3/config/raw/secrets - Save raw secrets

Display & System Control

GET /api/v3/system/status - System status
POST /api/v3/system/action - Control display (action body: start_display, stop_display, restart_display_service, restart_web_service, git_pull, reboot_system, shutdown_system, enable_autostart, disable_autostart)
GET /api/v3/display/current - Current display frame
GET /api/v3/display/on-demand/status - On-demand status
POST /api/v3/display/on-demand/start - Trigger on-demand display
POST /api/v3/display/on-demand/stop - Clear on-demand

Plugins

GET /api/v3/plugins/installed - List installed plugins
GET /api/v3/plugins/config?plugin_id=<id> - Get plugin config
POST /api/v3/plugins/config - Update plugin configuration
GET /api/v3/plugins/schema?plugin_id=<id> - Get plugin schema
POST /api/v3/plugins/toggle - Enable/disable plugin
POST /api/v3/plugins/install - Install from registry
POST /api/v3/plugins/install-from-url - Install from GitHub URL
POST /api/v3/plugins/uninstall - Uninstall plugin
POST /api/v3/plugins/update - Update plugin

Plugin Store

GET /api/v3/plugins/store/list - List available registry plugins
GET /api/v3/plugins/store/github-status - GitHub authentication status
POST /api/v3/plugins/store/refresh - Refresh registry from GitHub

Real-time Streams (SSE)

SSE stream endpoints are defined directly on the Flask app (app.py:607-619 — includes the CSRF exemption and rate-limit hookup alongside the three route definitions), not on the api_v3 blueprint:

GET /api/v3/stream/stats - System statistics stream
GET /api/v3/stream/display - Display preview stream
GET /api/v3/stream/logs - Service logs stream

Development

When making changes to the web interface:

Edit files in this directory
Test changes by running python3 web_interface/start.py
Restart the service if running: sudo systemctl restart ledmatrix-web

Notes

Templates and static files use the v3/ prefix to allow for future versions
The interface uses Flask blueprints for modular organization
SSE streams provide real-time updates without polling