mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 13:02:59 +00:00

Files

Chuck b577668568 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>

2026-04-07 09:25:01 -04:00

2.3 KiB

Raw Blame History

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:130). Not gitignored.
plugins/ — Legacy/dev plugin location. Gitignored (plugins/*). Used by scripts/dev/dev_plugin_setup.sh for symlinks. The plugin loader falls back to it when something isn't found in plugin-repos/ (src/plugin_system/schema_manager.py:77).

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.matrix.width/height

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()
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

2.3 KiB Raw Blame History

LEDMatrix

Project Structure

Plugin System

Plugin Store Architecture

Common Pitfalls

2.3 KiB

Raw Blame History