LEDMatrix/docs/MULTI_ROOT_WORKSPACE_SETUP.md

Multi-Root Workspace Setup Guide

This document explains how to work on LEDMatrix and the official plugins side by side, with one editor workspace and the plugins loaded straight from your plugin checkout.

Overview

Official plugins live in a single repository, ledmatrix-plugins, with one directory per plugin under plugins/. There are no separate per-plugin repositories. For development you clone that monorepo next to LEDMatrix and symlink its plugin directories into LEDMatrix's plugin-repos/, which is where the plugin loader looks by default.

• ✅ Plugin code stays in the monorepo checkout, with its own git history
• ✅ LEDMatrix discovers the plugins through symlinks in plugin-repos/
• ✅ LEDMatrix.code-workspace opens both repositories in VS Code/Cursor

Directory Structure

~/Github/
├── LEDMatrix/                        # Main project
│   ├── plugin-repos/                 # Plugin directory the loader scans
│   │   ├── starlark-apps/            # Bundled with LEDMatrix (tracked in git)
│   │   ├── web-ui-info/              # Bundled with LEDMatrix (tracked in git)
│   │   ├── clock-simple -> ../../ledmatrix-plugins/plugins/clock-simple
│   │   ├── ledmatrix-weather -> ../../ledmatrix-plugins/plugins/ledmatrix-weather
│   │   └── ...
│   ├── LEDMatrix.code-workspace      # Opens LEDMatrix and ../ledmatrix-plugins
│   └── ...
└── ledmatrix-plugins/                # Plugin monorepo (git repo)
    ├── plugins/
    │   ├── clock-simple/
    │   ├── ledmatrix-weather/
    │   └── ...
    ├── plugins.json                  # Store registry
    └── update_registry.py

How It Works

1. The plugin monorepo

Clone ledmatrix-plugins into the same parent directory as LEDMatrix (the scripts below look for ../ledmatrix-plugins relative to the LEDMatrix root):

cd ~/Github
git clone https://github.com/ChuckBuilds/ledmatrix-plugins.git

2. Symlinks in plugin-repos/

scripts/setup_plugin_repos.py creates one symlink per plugin in LEDMatrix/plugin-repos/, named after the plugin's manifest id and pointing at ../ledmatrix-plugins/plugins/<dir>.

3. Multi-root workspace

LEDMatrix.code-workspace has two roots: LEDMatrix itself and ../ledmatrix-plugins.

Setup Scripts

Initial Setup

cd ~/Github/LEDMatrix
python3 scripts/setup_plugin_repos.py

This script:

• Reads each manifest.json under ../ledmatrix-plugins/plugins/
• Creates plugin-repos/<id> symlinks (relative) to those directories
• Leaves correct links alone, replaces links that point elsewhere, and skips (does not overwrite) a real directory of the same name — for example a plugin you installed from the Plugin Store. Remove that directory first if you want the linked copy.

Updating Plugins

cd ~/Github/LEDMatrix
python3 scripts/update_plugin_repos.py

This runs git pull in ../ledmatrix-plugins and prints the result. The symlinks pick up the new code; restart the display to load it.

Configuration

The loader reads plugins from plugin_system.plugins_directory in config/config.json. The default is already right for this setup:

{
  "plugin_system": {
    "plugins_directory": "plugin-repos"
  }
}

Workflow

Daily Development

1. Open Workspace: Open LEDMatrix.code-workspace in VS Code/Cursor
2. Edit Plugins: Edit code under ledmatrix-plugins/plugins/<plugin>/
3. Test: python3 run.py -e (emulator) or python3 scripts/check_plugin.py --plugin <id> from LEDMatrix
4. Ship: Bump version in the plugin's manifest.json, run python update_registry.py in ledmatrix-plugins, commit there

Adding New Plugins

1. Create plugins/<your-plugin-id>/ in the monorepo checkout
2. Run python3 scripts/setup_plugin_repos.py in LEDMatrix to link it

Troubleshooting

Plugins not discovered

cd ~/Github/LEDMatrix
ls -la plugin-repos/                  # links present and not broken?
python3 scripts/setup_plugin_repos.py # recreate them

Also check that plugin_system.plugins_directory is plugin-repos.

"Monorepo plugins directory not found"

setup_plugin_repos.py expects the monorepo at ../ledmatrix-plugins. Clone it there (or symlink it there).

Plugin updates not showing

1. Verify the link target: ls -la plugin-repos/<id>
2. Check that you're editing the monorepo checkout, not a store-installed copy
3. Restart the LEDMatrix service (or run.py)

Notes

• plugin-repos/ is tracked in git only for the bundled plugins (starlark-apps, web-ui-info). The symlinks you create are untracked files; don't commit them.
• For linking a single plugin into plugins/ instead (without a sibling checkout), see scripts/dev/dev_plugin_setup.sh in the Plugin Development Guide.
• When changing a plugin in the monorepo, bump its manifest version and run python update_registry.py, or users won't receive the update.