LEDMatrix/docs/PLUGIN_DEVELOPMENT_GUIDE.md

LEDMatrix Plugin Development Guide

This guide explains how to set up a development workflow for plugins that are maintained in separate Git repositories while still being able to test them within the LEDMatrix project.

Rendering guidance: plugins should read the display size dynamically (self.display_manager.width/height) rather than hardcoding one panel. Don't read display_manager.matrix.width/height: matrix is None when hardware init fails, while the width/height properties fall back to the canvas size. For plugins that want to scale their layout to any panel, the opt-in adaptive layout system (ADAPTIVE_LAYOUT.md) provides the shared helpers — fonts, images, and composite layouts that scale. Existing plugins keep their classic rendering unless they adopt those APIs; nothing migrates automatically.

Overview

When developing plugins in separate repositories, you need a way to:

• Test plugins within the LEDMatrix project
• Make changes and commit them back to the plugin repository
• Avoid git conflicts between LEDMatrix and plugin repositories
• Easily switch between development and production modes

The solution uses symbolic links to connect plugin repositories to the plugins/ directory, combined with a helper script to manage the linking process.

Plugin directory note: the dev workflow described here puts symlinks in plugins/. The plugin loader's production default is plugin-repos/ (set by plugin_system.plugins_directory in config.json). Importantly, the main discovery path (PluginManager.discover_plugins()) only scans the configured directory — it does not fall back to plugins/. Two narrower paths do: the Plugin Store install/update logic in store_manager.py, and schema_manager.get_schema_path() (which the web UI form generator uses to find config_schema.json). That's why plugins installed via the Plugin Store still work even with symlinks in plugins/, but your own dev plugin won't appear in the rotation until you either move it to plugin-repos/ or change plugin_system.plugins_directory to plugins in the General tab of the web UI. The latter is the smoother dev setup.

Quick Start

Official plugins all live in one repository, ledmatrix-plugins, with one directory per plugin under plugins/ (there are no per-plugin ledmatrix-<name> repositories). The helper script links a plugin directory from a checkout of that monorepo into LEDMatrix's plugins/ directory.

1. Link an Official Plugin

./scripts/dev/dev_plugin_setup.sh link-github football-scoreboard

This will:

• Clone https://github.com/ChuckBuilds/ledmatrix-plugins.git to ~/.ledmatrix-dev-plugins/ledmatrix-plugins (or git pull it if it is already there)
• Find plugins/football-scoreboard in it (also accepted: plugins/ledmatrix-<name>, or a plugin whose manifest id is the name)
• Validate that it has a manifest.json
• Create a symbolic link named after the plugin's manifest id, e.g. plugins/football-scoreboard → ~/.ledmatrix-dev-plugins/ledmatrix-plugins/plugins/football-scoreboard

link-github music finds the monorepo's plugins/ledmatrix-music directory and links it into LEDMatrix as plugins/ledmatrix-music, because ledmatrix-music is that plugin's manifest id.

To work from your fork of the monorepo, set github_user in dev_plugins.json (see Configuration).

2. Link a Local Plugin Directory

If you already have the monorepo (or a third-party plugin repository) cloned locally:

./scripts/dev/dev_plugin_setup.sh link hello-world ../ledmatrix-plugins/plugins/hello-world

This creates a symlink from plugins/hello-world to that directory.

3. Check Status

See which plugins are linked and their git status:

./scripts/dev/dev_plugin_setup.sh status

4. Work on Your Plugin

cd plugins/football-scoreboard  # Actually editing the monorepo checkout
# Make your changes, then bump "version" in manifest.json
git add .
git commit -m "feat(football-scoreboard): add new feature"
git push   # to your fork, then open a PR against ledmatrix-plugins

In the monorepo, every plugin change must bump version in the plugin's manifest.json and run python update_registry.py, or users won't receive the update.

5. Update Plugins

Pull latest changes from remote:

# Update all linked plugins
./scripts/dev/dev_plugin_setup.sh update

# Or update a specific plugin
./scripts/dev/dev_plugin_setup.sh update music

6. Unlink When Done

Remove the symlink (repository is preserved):

./scripts/dev/dev_plugin_setup.sh unlink music

Detailed Commands

link <plugin-name> <repo-path>

Links a local plugin repository to the plugins directory.

Arguments:

• plugin-name: The name of the plugin (will be the directory name in plugins/)
• repo-path: Path to the plugin repository (absolute or relative)

Example:

./scripts/dev/dev_plugin_setup.sh link football-scoreboard ../ledmatrix-plugins/plugins/football-scoreboard

Notes:

• The script validates that the repository contains a manifest.json file
• If a plugin directory already exists, you'll be prompted to replace it
• The repository path can be absolute or relative

link-github <plugin-name> [repo-url]

Clones a plugin from GitHub and links it.

Arguments:

• plugin-name: Without repo-url, the plugin to link from the monorepo: a directory under plugins/ (<name> or ledmatrix-<name>) or a manifest id. The link is named after the plugin's manifest id. With repo-url, the name of the link in plugins/.
• repo-url: (Optional) A plugin that has its own repository (e.g. a third-party plugin). The repository root is linked.

Examples:

# Official plugin, from the ledmatrix-plugins monorepo
./scripts/dev/dev_plugin_setup.sh link-github stocks

# Third-party plugin with its own repository
./scripts/dev/dev_plugin_setup.sh link-github custom-plugin https://github.com/OtherUser/custom-plugin.git

Notes:

• Repositories are cloned to ~/.ledmatrix-dev-plugins/ by default (configurable)
• The monorepo is cloned once and shared by every plugin you link from it
• If the repository already exists, it will be updated with git pull instead of re-cloning
• The cloned repository is preserved when you unlink the plugin

unlink <plugin-name>

Removes the symlink for a plugin.

Arguments:

• plugin-name: The name of the plugin to unlink

Example:

./scripts/dev/dev_plugin_setup.sh unlink music

Notes:

• Only removes the symlink, does NOT delete the repository
• Your work and git history are preserved in the repository location

list

Lists all plugins in the plugins/ directory and shows their status.

Example:

./scripts/dev/dev_plugin_setup.sh list

Output:

• ✓ Green checkmark: Plugin is symlinked (development mode)
• ○ Yellow circle: Plugin is a regular directory (production/installed mode)
• Shows the source path for symlinked plugins
• Shows git status (branch, clean/dirty) for linked repos

status

Shows detailed status of all linked plugins.

Example:

./scripts/dev/dev_plugin_setup.sh status

Shows:

• Link status (working/broken)
• Repository path
• Git branch
• Remote URL
• Git status (clean, uncommitted changes, ahead/behind remote)
• Summary of all plugins

update [plugin-name]

Updates plugin(s) by running git pull in their repositories.

Arguments:

• plugin-name: (Optional) Specific plugin to update. If omitted, updates all linked plugins.

Examples:

# Update all linked plugins
./scripts/dev/dev_plugin_setup.sh update

# Update specific plugin
./scripts/dev/dev_plugin_setup.sh update music

Configuration

Custom Development Directory

By default, GitHub repositories are cloned to ~/.ledmatrix-dev-plugins/ and official plugins come from ChuckBuilds/ledmatrix-plugins. To change either, copy dev_plugins.json.example (in the LEDMatrix root) to dev_plugins.json and edit it. dev_plugins.json is git-ignored.

{
  "dev_plugins_dir": "~/.ledmatrix-dev-plugins",
  "github_user": "your-github-user",
  "plugins_repo": "ledmatrix-plugins",
  "plugins_branch": "main"
}

Configuration options (all optional):

• dev_plugins_dir: Where to clone GitHub repositories (default: ~/.ledmatrix-dev-plugins)
• github_user: Owner of the plugin monorepo that link-github <name> clones — set it to use your fork (default: ChuckBuilds)
• plugins_repo: Name of that monorepo (default: ledmatrix-plugins)
• plugins_branch: Branch to clone it at (default: the repository's default branch). Only applies when the clone is first made.

github_pattern from older versions of this guide is no longer used (the script warns if it is set).

Development Workflow

Typical Development Session

1. Link your plugin for development:

   ./scripts/dev/dev_plugin_setup.sh link-github clock-simple
   

2. Test in LEDMatrix:

   # Run LEDMatrix with your plugin (emulator shown)
   python3 run.py -e
   

3. Make changes:

   cd plugins/clock-simple
   # Edit files...
   # Test changes...
   

4. Commit to the plugin repository:

   cd plugins/clock-simple  # This is inside your monorepo checkout
   # bump "version" in manifest.json, then from the monorepo root:
   # python update_registry.py
   git add .
   git commit -m "feat(clock-simple): add new feature"
   git push
   

5. Update from remote (if needed):

   ./scripts/dev/dev_plugin_setup.sh update clock-simple
   

6. When done developing:

   ./scripts/dev/dev_plugin_setup.sh unlink clock-simple
   

Working with Multiple Plugins

You can have multiple plugins linked simultaneously. Plugins linked from the monorepo share one checkout:

./scripts/dev/dev_plugin_setup.sh link-github music
./scripts/dev/dev_plugin_setup.sh link-github stocks
./scripts/dev/dev_plugin_setup.sh link-github football-scoreboard

# Check status of all
./scripts/dev/dev_plugin_setup.sh status

# Update all at once (the shared monorepo checkout is pulled once)
./scripts/dev/dev_plugin_setup.sh update

Switching Between Development and Production

Development mode: Plugins are symlinked to your repositories

• Edit files directly in plugins/<name>
• Changes are in the plugin repository
• Git operations work normally

Production mode: Plugins are installed normally

• Plugins are regular directories (installed via plugin store or manually)
• Can't edit directly (would need to edit in place or re-install)
• Use unlink to remove symlink if you want to switch back to installed version

Best Practices

1. Keep Repositories Outside LEDMatrix

The script clones GitHub repositories to ~/.ledmatrix-dev-plugins/ by default, which is outside the LEDMatrix directory. This:

• Avoids git conflicts
• Keeps plugin repos separate from LEDMatrix repo
• Makes it easy to manage multiple plugin repositories

2. Use Descriptive Commit Messages

When committing changes in your plugin repository, use clear commit messages following the project's conventions:

git commit -m "feat(music): add album art support"
git commit -m "fix(stocks): resolve API timeout issue"

3. Test Before Committing

Always test your plugin changes in LEDMatrix before committing:

# Make changes
cd plugins/music
# ... edit files ...

# Test in LEDMatrix
cd ../..
python run.py

# If working, commit
cd plugins/music
git add .
git commit -m "feat: new feature"

4. Keep Plugins Updated

Regularly update your linked plugins to get the latest changes:

./scripts/dev/dev_plugin_setup.sh update

5. Check Status Regularly

Before starting work, check the status of your linked plugins:

./scripts/dev/dev_plugin_setup.sh status

This helps you:

• See if you have uncommitted changes
• Check if you're behind the remote
• Identify any broken symlinks

Troubleshooting

Plugin Not Discovered by LEDMatrix

If LEDMatrix doesn't discover your linked plugin:

1. Check the symlink exists:

   ls -la plugins/your-plugin-name
   

2. Verify manifest.json exists:

   ls plugins/your-plugin-name/manifest.json
   

3. Check PluginManager logs:

   • LEDMatrix logs should show plugin discovery
   • Look for errors related to the plugin

Broken Symlink

If a symlink is broken (target repository was moved or deleted):

1. Check status:

   ./scripts/dev/dev_plugin_setup.sh status
   

2. Unlink and re-link:

   ./scripts/dev/dev_plugin_setup.sh unlink plugin-name
   ./scripts/dev/dev_plugin_setup.sh link-github plugin-name
   

Git Conflicts

If you have conflicts when updating:

1. Manually resolve in the plugin repository:

   cd ~/.ledmatrix-dev-plugins/ledmatrix-plugins
   git pull
   # Resolve conflicts...
   git add .
   git commit
   

2. Or use the update command:

   ./scripts/dev/dev_plugin_setup.sh update music
   

Plugin Directory Already Exists

If you try to link a plugin but the directory already exists:

1. Check if it's already linked:

   ./scripts/dev/dev_plugin_setup.sh list
   

2. If it's a symlink to the same location, you're done

3. If it's a regular directory or different symlink:

   • The script will prompt you to replace it
   • Or manually backup: mv plugins/plugin-name plugins/plugin-name.backup

Advanced Usage

Linking Plugins from Different GitHub Users

./scripts/dev/dev_plugin_setup.sh link-github custom-plugin https://github.com/OtherUser/custom-plugin.git

Using a Custom Development Directory

Create dev_plugins.json:

{
  "dev_plugins_dir": "/home/user/my-dev-plugins"
}

Combining Local and GitHub Plugins

You can mix local and GitHub plugins:

# Link from GitHub
./scripts/dev/dev_plugin_setup.sh link-github music

# Link local repository
./scripts/dev/dev_plugin_setup.sh link custom-plugin ../my-custom-plugin

Integration with Plugin Store

The development workflow is separate from the plugin store installation:

• Plugin Store: Installs plugins as regular directories in the configured plugins directory (plugin-repos/ by default)
• Development Setup: Links plugin directories as symlinks in plugins/

The plugin loader scans only one directory, so while developing set plugin_system.plugins_directory to plugins (see the note at the top of this guide). If plugins/ already holds a regular directory of the same name, link/link-github offers to rename it to <name>.backup.<timestamp> before linking.

unlink removes only the symlink. To switch back to the store version, set plugins_directory back to plugin-repos (or reinstall the plugin from the store).

API Reference

When developing plugins, you'll need to use the APIs provided by the LEDMatrix system:

• Plugin API Reference - Complete reference for Display Manager, Cache Manager, and Plugin Manager methods
• Advanced Plugin Development - Advanced patterns, examples, and best practices
• Developer Quick Reference - Quick reference for common developer tasks

Key APIs for Plugin Developers

Display Manager (self.display_manager):

• clear(), update_display() - Core display operations
• draw_text() - Text rendering. For images, paste directly onto display_manager.image (a PIL Image) and call update_display(); there is no draw_image() helper method.
• draw_weather_icon(), draw_sun(), draw_cloud() - Weather icons
• get_text_width(), get_font_height() - Text utilities
• set_scrolling_state(), defer_update() - Scrolling state management

Cache Manager (self.cache_manager):

• get(), set(), delete() - Basic caching
• get_cached_data_with_strategy() - Advanced caching with strategies
• get_background_cached_data() - Background service caching

Plugin Manager (self.plugin_manager):

• get_plugin(), get_all_plugins() - Access other plugins
• get_plugin_info() - Get plugin information

See PLUGIN_API_REFERENCE.md for complete documentation.

3rd Party Plugin Development

Want to create and share your own plugin? Here's everything you need to know.

Getting Started

1. Review the documentation:

   • Plugin Architecture Spec - System architecture
   • Plugin API Reference - Available methods
   • Advanced Plugin Development - Patterns and examples

2. Start with a template:

   • Use the Hello World plugin as a starting point
   • Or fork an existing plugin and modify it

3. Follow the plugin structure:

   your-plugin/
   ├── manifest.json          # Required: Plugin metadata
   ├── manager.py             # Required: Plugin class
   ├── config_schema.json     # Recommended: Configuration schema
   ├── requirements.txt       # Optional: Python dependencies
   └── README.md              # Recommended: User documentation
   

Plugin Requirements

Your plugin must:

1. Inherit from BasePlugin:

   from src.plugin_system.base_plugin import BasePlugin
   
   class MyPlugin(BasePlugin):
       def update(self):
           # Fetch data
           pass
   
       def display(self, force_clear=False):
           # Render display
           pass
   

2. Include manifest.json with required fields:

   {
     "id": "my-plugin",
     "name": "My Plugin",
     "version": "1.0.0",
     "class_name": "MyPlugin",
     "entry_point": "manager.py",
     "display_modes": ["my_plugin"],
     "compatible_versions": [">=2.0.0"]
   }
   

3. Match class name: The class name in manager.py must match class_name in manifest

Testing Your Plugin

1. Test locally:

   # Link your plugin for development
   ./scripts/dev/dev_plugin_setup.sh link your-plugin /path/to/your-plugin
   
   # Run LEDMatrix with emulator
   python run.py --emulator
   

2. Test on hardware: Deploy to Raspberry Pi and test on actual LED matrix

3. Use mocks for unit testing: See Advanced Plugin Development

Versioning Best Practices

• Use semantic versioning: MAJOR.MINOR.PATCH (e.g., 1.2.3)
• Bump version in manifest.json by hand for every change you ship. There is no automatic version-bump hook or bump script.
• Official (monorepo) plugins: after bumping the manifest, run python update_registry.py in the ledmatrix-plugins checkout. It copies each manifest's version into plugins.json as latest_version, which is what the store compares installed versions against. Without it, users won't be offered the update.
• Plugins in their own repository: still bump the manifest version, so users can see which version they run; tagging releases (v1.2.3) to match is a good habit.

Submitting to Official Registry

To have your plugin added to the official plugin store:

1. Ensure quality:

   • Plugin works reliably
   • Well-documented (README.md)
   • Follows best practices
   • Tested on Raspberry Pi hardware

2. Choose where it lives (see SUBMISSION.md in ledmatrix-plugins):

   • In the monorepo (preferred): fork ledmatrix-plugins, add plugins/<your-plugin-id>/, and open a pull request
   • In your own public repository (conventionally ledmatrix-<plugin-name>), with a README that covers installation

3. Contact maintainers (own-repository plugins):

   • Open a GitHub issue in the ledmatrix-plugins repository
   • Or reach out on Discord: https://discord.gg/uW36dVAtcT
   • Include: Repository URL, plugin description, why it's useful

4. Review process:

   • Code review for quality and security
   • Testing on Raspberry Pi hardware
   • Documentation review
   • If approved, added to official registry

Plugin Store Integration Requirements

For your plugin to work well in the plugin store:

• GitHub repository: Must be publicly accessible on GitHub
• version in manifest.json: The store offers updates by comparing it with the registry's latest_version; releases and tags are not read
• README.md: Clear installation and configuration instructions
• config_schema.json: Recommended for web UI configuration
• manifest.json: Required with all required fields
• requirements.txt: If your plugin has Python dependencies

Distribution Options

1. Official Registry (Recommended):

   • Listed in default plugin store
   • Update offers in the Plugin Manager (and weekly automatic updates, if the user turns them on)
   • Verified badge
   • Requires approval

2. Custom Repository:

   • Host your own plugin repository
   • Users can install via "Install from GitHub" in web UI
   • Full control over distribution

3. Direct Installation:

   • Users can clone and install manually
   • Good for development/testing

Best Practices for 3rd Party Plugins

1. Documentation: Include comprehensive README.md
2. Configuration: Provide config_schema.json for web UI
3. Error handling: Graceful failures with clear error messages
4. Logging: Use plugin logger for debugging
5. Testing: Test on actual Raspberry Pi hardware
6. Versioning: Follow semantic versioning
7. Dependencies: Minimize external dependencies
8. Performance: Optimize for Pi's limited resources

See Also

• Plugin Architecture Specification - Complete system specification
• Plugin API Reference - Complete API documentation
• Advanced Plugin Development - Advanced patterns and examples
• Plugin Quick Reference - Quick development reference
• Plugin Configuration Guide - Configuration setup
• Plugin Store Guide - Using the plugin store