mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-04 14:25:08 +00:00
ChuckandClaude Opus 5.5
61e462c635
* refactor: remove the skin system Skins never rendered with the current scoreboard plugins: the only hook was SportsCore._render_game in src/base_classes, which no plugin builds on, so the UI and store already treated them as unsupported. The owner decided on 2026-09-23 to remove them outright. Removed src/skin_system/ (runtime, base class, fixtures), skins/, scripts/validate_skin.py and their tests; the store's "type": "skin" installer, uninstaller and hide/refuse filters (the official registry lists no skins); SchemaManager.inject_skin_selector; and GET /api/v3/skins. Stored skin/skin_options config values are handled in the next commit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(config): drop retired skin/skin_options keys instead of validating them A config.json written while the skin system existed can carry skin and skin_options in any plugin section, and most plugin schemas set additionalProperties: false. They are no longer core plugin properties; RETIRED_PLUGIN_KEYS in schema_manager lists them and drop_retired_plugin_keys removes them (unless the plugin's own schema declares the name) in prepare_plugin_config, which loading, hot reload, GET /plugins/config and both web saves already share, and in validate_config_against_schema for callers that validate a raw section. POST /plugins/config and /config/main also drop them from the stored section they merge into, so they leave config.json on the next save. Tests cover the load path (real PluginManager.load_plugin: no schema warning, not degraded), raw and prepared validation, validate_all_plugin_configs, and the JSON, form and /config/main saves. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor: remove the unused src/base_classes package No scoreboard plugin builds on src.base_classes: the nine monorepo scoreboards ship their own sports.py and share code through src/common (docs/SPORTS_UNIFICATION.md), and none of the third-party registry plugins imports it. The one import anywhere, baseball-scoreboard's rankings_manager.py, is a lazy import of ESPNDataSource in a class nothing instantiates. Removed the package and the eight test files that only tested it (test_api_extractors, test_data_sources, test_sports_base_characterization, test_sports_capabilities, test_sports_core_promotions, test_sports_logo_cache_bounded, test_sports_modes_promotions, test_sports_odds_fanout). test_common_is_hardware_free no longer lists src.base_classes as a forbidden import, and comments in sports_helpers.py and base_odds_manager.py stop pointing at it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: drop the skin system and src/base_classes from the docs Deletes docs/SKIN_SYSTEM.md and docs/CREATING_SKINS.md and every link to them (docs/README.md, README.md, PLUGIN_DEVELOPMENT_GUIDE.md, the /skins section of REST_API_REFERENCE.md), the skin section of CLAUDE.md and the term in PRODUCT.md. SPORTS_UNIFICATION.md now says src/base_classes was removed and shared code lives in src/common, in the Layering section and the view-model-contract rule. Other docs stop pointing at the removed package. CHANGELOG records both removals under Unreleased. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(store): hide and refuse registry entries that aren't plugins The skin filters went with the skin system, but a custom registry can still list "type": "skin" entries, and installing one as a plugin would unpack it into the plugins directory. PluginStoreManager.is_plugin_entry() (a missing type means plugin) now hides non-plugin entries from the store and custom-registry listings, and install refuses them, in the route with a clear 400 and in _install_plugin_impl for any other caller. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
56 lines
4.5 KiB
Markdown
56 lines
4.5 KiB
Markdown
# LEDMatrix
|
|
|
|
## Project Structure
|
|
- `src/plugin_system/` — Plugin loader, manager, store manager, base plugin class
|
|
- `web_interface/` — Flask web UI (blueprints, templates, static JS)
|
|
- `config/config.json` — User plugin configuration (persists across plugin reinstalls)
|
|
- `plugin-repos/` — **Default** plugin install directory used by the
|
|
Plugin Store, set by `plugin_system.plugins_directory` in
|
|
`config.json` (default per `config/config.template.json`).
|
|
Not gitignored.
|
|
- `plugins/` — Legacy/dev plugin location. Gitignored (`plugins/*`).
|
|
Used by `scripts/dev/dev_plugin_setup.sh` for symlinks. The plugin
|
|
loader does NOT fall back to it — `PluginManager.discover_plugins()`
|
|
(`src/plugin_system/plugin_manager.py`) scans only the configured
|
|
directory. Fallbacks exist in two narrower places: store operations
|
|
(`StoreManager._find_plugin_path()` in `store_manager.py`) and schema
|
|
lookup (`SchemaManager.get_schema_path()` in `schema_manager.py`,
|
|
which probes `plugins/` *before* `plugin-repos/`).
|
|
|
|
## Plugin System
|
|
- Plugins inherit from `BasePlugin` in `src/plugin_system/base_plugin.py`
|
|
- Required abstract methods: `update()`, `display(force_clear=False)`
|
|
- Each plugin needs: `manifest.json`, `config_schema.json`, `manager.py`, `requirements.txt`
|
|
- Plugin instantiation args: `plugin_id, config, display_manager, cache_manager, plugin_manager`
|
|
- Config schemas use JSON Schema Draft-7
|
|
- Display dimensions: always read dynamically from `self.display_manager.width/height` — not `display_manager.matrix.width/height`, because `matrix` is `None` when hardware init fails (the properties fall back to the canvas size)
|
|
- Secrets: namespaced by plugin id in `config/config_secrets.json`, declared
|
|
via `"x-secret": true` in the plugin's config schema, and deep-merged into
|
|
the plugin's config dict at load time — plugins read them with plain
|
|
`config.get(...)`, never a separate accessor
|
|
|
|
## Dev Workflow
|
|
- Link a plugin for development: `./scripts/dev/dev_plugin_setup.sh link-github <name>` clones the `ledmatrix-plugins` monorepo into `~/.ledmatrix-dev-plugins/` and links its `plugins/<name>` under the manifest id (add a repo URL for a plugin with its own repo; or `link <name> <path>`); symlinks land in `plugins/` — set `plugin_system.plugins_directory` to `plugins` so discovery picks them up. Fork/location overrides: `dev_plugins.json` (from `dev_plugins.json.example`)
|
|
- Browser preview without the display loop: `python3 scripts/dev_server.py` → http://localhost:5001
|
|
- Full display in emulator mode: `python3 run.py -e` (or `EMULATOR=true python3 run.py`)
|
|
- Validate one plugin headlessly: `python3 scripts/check_plugin.py --plugin <id>`
|
|
|
|
## Plugin Store Architecture
|
|
- Official plugins live in the `ledmatrix-plugins` monorepo (not individual repos)
|
|
- Plugin repo naming convention: `ledmatrix-<plugin-id>` (e.g., `ledmatrix-football-scoreboard`)
|
|
- `plugins.json` registry at `https://raw.githubusercontent.com/ChuckBuilds/ledmatrix-plugins/main/plugins.json`
|
|
- Store manager (`src/plugin_system/store_manager.py`) handles install/update/uninstall
|
|
- Monorepo plugins are installed via ZIP extraction (no `.git` directory)
|
|
- Update detection for monorepo plugins uses version comparison (manifest version vs registry latest_version)
|
|
- Plugin configs stored in `config/config.json`, NOT in plugin directories — safe across reinstalls
|
|
- Third-party plugins can use their own repo URL with empty `plugin_path`
|
|
|
|
## Common Pitfalls
|
|
- paho-mqtt 2.x needs `callback_api_version=mqtt.CallbackAPIVersion.VERSION1` for v1 compat
|
|
- BasePlugin uses `get_logger()` from `src.logging_config`, not standard `logging.getLogger()`
|
|
- `DisplayManager` has no `draw_image()` — paste onto the PIL image directly:
|
|
`self.display_manager.image.paste(img, (x, y))` then `update_display()`
|
|
(use a mask for transparency: `image.paste(rgba, (x, y), rgba)`)
|
|
- When modifying a plugin in the monorepo, you MUST bump `version` in its `manifest.json` and run `python update_registry.py` — otherwise users won't receive the update
|
|
- `src/pi5_matrix_support.py` hardcodes what the pinned `rpi-rgb-led-matrix-master` can drive on a Raspberry Pi 5 (`Rp1PioConfigSupported()` in `lib/rp1/rp1_pio_backend.cc`). Re-check it whenever the submodule is bumped: a stale rule blocks Pi 5 settings the new library supports, and a missing one lets the display service crash-loop. `src/matrix_support.py` holds the same kind of rules for every board (rows, chain length, mapping names, parallel per mapping) and needs the same re-check
|