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.matrix.width/height) rather than hardcoding one panel. 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

1. Link a Plugin from GitHub

The easiest way to link a plugin that's already on GitHub:

./scripts/dev/dev_plugin_setup.sh link-github music

This will:

• Clone https://github.com/ChuckBuilds/ledmatrix-music.git to ~/.ledmatrix-dev-plugins/ledmatrix-music
• Create a symbolic link from plugins/music to the cloned repository
• Validate that the plugin has a proper manifest.json

2. Link a Local Plugin Repository

If you already have a plugin repository cloned locally:

./scripts/dev/dev_plugin_setup.sh link music ../ledmatrix-music

This creates a symlink from plugins/music to your local repository path.

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/music  # Actually editing the linked repository
# Make your changes
git add .
git commit -m "feat: add new feature"
git push origin main

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-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: The name of the plugin (will be the directory name in plugins/)
• repo-url: (Optional) Full GitHub repository URL. If omitted, constructs from pattern: https://github.com/ChuckBuilds/ledmatrix-<plugin-name>.git

Examples:

# Auto-construct URL from plugin name
./scripts/dev/dev_plugin_setup.sh link-github music

# Use explicit URL
./scripts/dev/dev_plugin_setup.sh link-github stocks https://github.com/ChuckBuilds/ledmatrix-stocks.git

# Link from a different GitHub user
./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)
• 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/. You can customize this by creating a dev_plugins.json file:

{
  "dev_plugins_dir": "/path/to/your/dev/plugins",
  "github_user": "ChuckBuilds",
  "github_pattern": "ledmatrix-",
  "plugins": {
    "music": {
      "source": "github",
      "url": "https://github.com/ChuckBuilds/ledmatrix-music.git",
      "branch": "main"
    }
  }
}

Configuration options:

• dev_plugins_dir: Where to clone GitHub repositories (default: ~/.ledmatrix-dev-plugins)
• github_user: Default GitHub username for auto-constructing URLs
• github_pattern: Pattern for repository names (default: ledmatrix-)
• plugins: Plugin definitions (optional, for future auto-discovery features)

Note: Copy dev_plugins.json.example to dev_plugins.json and customize it. The dev_plugins.json file is git-ignored.

Development Workflow

Typical Development Session

1. Link your plugin for development:

   ./scripts/dev/dev_plugin_setup.sh link-github music
   

2. Test in LEDMatrix:

   # Run LEDMatrix with your plugin
   python run.py
   

3. Make changes:

   cd plugins/music
   # Edit files...
   # Test changes...
   

4. Commit to plugin repository:

   cd plugins/music  # This is actually your repo
   git add .
   git commit -m "feat: add new feature"
   git push origin main
   

5. Update from remote (if needed):

   ./scripts/dev/dev_plugin_setup.sh update music
   

6. When done developing:

   ./scripts/dev/dev_plugin_setup.sh unlink music
   

Working with Multiple Plugins

You can have multiple plugins linked simultaneously:

./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
./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-music
   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 to plugins/ as regular directories
• Development Setup: Links plugin repositories as symlinks

If you install a plugin via the store, you can still link it for development:

# Store installs to plugins/music (regular directory)
# Link for development (will prompt to replace)
./scripts/dev/dev_plugin_setup.sh link-github music

When you unlink, the directory is removed. If you want to switch back to the store version, re-install it via the plugin 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)
• Automatic version bumping: Use the pre-push git hook for automatic patch version bumps
• Manual versioning: Only needed for major/minor bumps or special cases
• GitHub as source of truth: Plugin store fetches versions from GitHub releases/tags/manifest

See the Git Workflow rules for version management details.

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. Create GitHub repository:

   • Repository name: ledmatrix-<plugin-name>
   • Public repository
   • Proper README.md with installation instructions

3. Contact maintainers:

   • 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
• Releases or tags: Recommended for version tracking
• 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
   • Automatic updates
   • 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 User Guide - Using the plugin store