LEDMatrix/docs/PLUGIN_STORE_GUIDE.md

Plugin Store Guide

Overview

The LEDMatrix Plugin Store allows you to discover, install, and manage display plugins for your LED matrix. Install curated plugins from the official registry or add custom plugins directly from any GitHub repository.

In the web interface, the Plugin Store is a section of the Plugin Manager tab (below the installed plugins), followed by an Install from GitHub section.

The Python examples below pass plugins_dir="plugin-repos": PluginStoreManager() defaults to plugins, but the web interface and the plugin loader use plugin_system.plugins_directory from config.json (plugin-repos by default).

---

Quick Reference

Install from Store

# Web UI: Plugin Manager → Plugin Store section → Search → Click Install
# API:
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'

Install from GitHub URL

# Web UI: Plugin Manager → Install from GitHub → "Install Single Plugin" → Paste URL
# API:
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install-from-url \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/user/ledmatrix-plugin"}'

Manage Plugins

# List installed
curl "http://your-pi-ip:5000/api/v3/plugins/installed"

# Enable/disable
curl -X POST http://your-pi-ip:5000/api/v3/plugins/toggle \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple", "enabled": true}'

# Update
curl -X POST http://your-pi-ip:5000/api/v3/plugins/update \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'

# Uninstall
curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'

---

Installation Methods

Method 1: From Official Plugin Store (Recommended)

The official plugin store contains curated, verified plugins that have been reviewed by maintainers.

Via Web Interface:

1. Open the web interface at http://your-pi-ip:5000
2. Navigate to the "Plugin Manager" tab and scroll to the "Plugin Store" section
3. Browse or search for plugins
4. Click "Install" on the desired plugin
5. Wait for installation to complete
6. Restart the display to activate the plugin

Via REST API:

curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'

Via Python:

from src.plugin_system.store_manager import PluginStoreManager

store = PluginStoreManager(plugins_dir="plugin-repos")
success = store.install_plugin('clock-simple')
if success:
    print("Plugin installed!")

Method 2: From Custom GitHub URL

Install any plugin directly from a GitHub repository, even if it's not in the official store. This method is useful for:

• Testing your own plugins during development
• Installing community plugins before they're in the official store
• Using private plugins
• Sharing plugins with specific users

Via Web Interface:

1. Open the web interface
2. Navigate to the "Plugin Manager" tab
3. Find "Install Single Plugin" in the "Install from GitHub" section
4. Paste the GitHub repository URL (e.g., https://github.com/user/ledmatrix-my-plugin) and optionally a branch
5. Click "Install"
6. Review the warning about unverified plugins
7. Confirm installation
8. Wait for installation to complete
9. Restart the display

Via REST API:

curl -X POST http://your-pi-ip:5000/api/v3/plugins/install-from-url \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/user/ledmatrix-my-plugin"}'

Via Python:

from src.plugin_system.store_manager import PluginStoreManager

store = PluginStoreManager(plugins_dir="plugin-repos")
result = store.install_from_url('https://github.com/user/ledmatrix-my-plugin')

if result['success']:
    print(f"Installed: {result['plugin_id']}")
else:
    print(f"Error: {result['error']}")

---

Searching for Plugins

Via Web Interface:

• Use the search bar to search by name, description, or author
• Filter by category (sports, weather, time, finance, etc.)
• Click on tags to filter by specific tags

Via REST API:

# Search by query
curl "http://your-pi-ip:5000/api/v3/plugins/store/list?query=hockey"

# Filter by category
curl "http://your-pi-ip:5000/api/v3/plugins/store/list?category=sports"

# Filter by tags
curl "http://your-pi-ip:5000/api/v3/plugins/store/list?tags=nhl&tags=hockey"

Via Python:

from src.plugin_system.store_manager import PluginStoreManager

store = PluginStoreManager(plugins_dir="plugin-repos")

# Search by query
results = store.search_plugins(query="hockey")

# Filter by category
results = store.search_plugins(category="sports")

# Filter by tags
results = store.search_plugins(tags=["nhl", "hockey"])

---

Managing Installed Plugins

List Installed Plugins

Via Web Interface:

• Navigate to the "Plugin Manager" tab
• View all installed plugins with their status

Via REST API:

curl "http://your-pi-ip:5000/api/v3/plugins/installed"

Via Python:

from src.plugin_system.store_manager import PluginStoreManager

store = PluginStoreManager(plugins_dir="plugin-repos")
for plugin_id in store.list_installed_plugins():
    print(plugin_id)

Enable/Disable Plugins

Via Web Interface:

1. Navigate to the "Plugin Manager" tab
2. Use the toggle switch next to each plugin
3. Restart the display to apply changes

Via REST API:

curl -X POST http://your-pi-ip:5000/api/v3/plugins/toggle \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple", "enabled": true}'

Update Plugins

Via Web Interface:

1. Navigate to the "Plugin Manager" tab
2. Click the "Update" button next to the plugin
3. Wait for the update to complete
4. Restart the display

Via REST API:

curl -X POST http://your-pi-ip:5000/api/v3/plugins/update \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'

Via Python:

from src.plugin_system.store_manager import PluginStoreManager

store = PluginStoreManager(plugins_dir="plugin-repos")
success = store.update_plugin('clock-simple')

Uninstall Plugins

Via Web Interface:

1. Navigate to the "Plugin Manager" tab
2. Click the "Uninstall" button next to the plugin
3. Confirm removal
4. Restart the display

Via REST API:

curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'

Via Python:

from src.plugin_system.store_manager import PluginStoreManager

store = PluginStoreManager(plugins_dir="plugin-repos")
success = store.uninstall_plugin('clock-simple')

---

Configuring Plugins

Each plugin can have its own configuration in config/config.json:

{
  "clock-simple": {
    "enabled": true,
    "display_duration": 15,
    "color": [255, 255, 255],
    "time_format": "12h"
  },
  "nhl-scores": {
    "enabled": true,
    "favorite_teams": ["TBL", "FLA"],
    "show_favorite_teams_only": true
  }
}

Via Web Interface:

1. Navigate to the "Plugin Manager" tab
2. Click the Configure (⚙️) button next to the plugin
3. Edit the configuration in the form
4. Save changes
5. Restart the display to apply changes

---

Safety and Security

Verified vs Unverified Plugins

• Verified Plugins: Reviewed by maintainers, follow best practices, no known security issues
• Unverified Plugins: User-contributed, not reviewed, install at your own risk

When installing from a custom GitHub URL, you'll see a warning about installing an unverified plugin. The plugin will have access to your display manager, cache manager, configuration files, and network access.

Best Practices

1. Only install plugins from trusted sources
2. Review plugin code before installing (click "View on GitHub")
3. Keep plugins updated for security patches
4. Report suspicious plugins to maintainers

---

Troubleshooting

Plugin Won't Install

Problem: Installation fails

Solutions:

• Plugins from the official registry live in the ledmatrix-plugins monorepo and are downloaded, not cloned: the store fetches the plugin's directory through the GitHub API and falls back to extracting it from the repository ZIP, so git is not involved (the installed copy has no .git)
• A plugin installed by URL from its own repository is cloned with git, falling back to an archive download; check which git if that fails
• Verify the GitHub URL is correct
• Check your internet connection

Plugin Won't Load

Problem: Plugin installed but doesn't appear in rotation

Solutions:

1. Check that the plugin is enabled in config: "enabled": true
2. Verify manifest.json exists and is valid
3. Check logs for errors: sudo journalctl -u ledmatrix -f
4. Restart the display service: sudo systemctl restart ledmatrix

Dependencies Failed

Problem: "Error installing dependencies" message

Solutions:

• Check that pip3 is installed
• Manually install: pip3 install --break-system-packages -r plugins/plugin-id/requirements.txt
• Check for conflicting package versions

Plugin Shows Errors

Problem: Plugin loads but shows error message on display

Solutions:

1. Check that the plugin configuration is correct
2. Verify API keys are set (if the plugin requires them)
3. Check plugin logs: sudo journalctl -u ledmatrix -f | grep plugin-id
4. Report the issue to the plugin developer on GitHub

---

API Reference

All API endpoints return JSON with this structure:

{
  "status": "success" | "error",
  "message": "Human-readable message",
  "data": { ... }
}

Endpoints

Method	Endpoint	Description
GET	/api/v3/plugins/store/list	List plugins in store; ?query=, ?category=, ?tags= search and filter
GET	/api/v3/plugins/installed	List installed plugins
POST	/api/v3/plugins/install	Install from registry
POST	/api/v3/plugins/install-from-url	Install from GitHub URL
POST	/api/v3/plugins/uninstall	Uninstall plugin
POST	/api/v3/plugins/update	Update plugin
POST	/api/v3/plugins/toggle	Enable/disable plugin
POST	/api/v3/plugins/config	Update plugin config

---

Examples

Example 1: Install Clock Plugin

# Install
curl -X POST http://192.168.1.100:5000/api/v3/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'

# Configure in config/config.json
{
  "clock-simple": {
    "enabled": true,
    "display_duration": 20,
    "time_format": "24h"
  }
}

# Restart display
sudo systemctl restart ledmatrix

Example 2: Install Custom Plugin from GitHub

# Install your own plugin during development
curl -X POST http://192.168.1.100:5000/api/v3/plugins/install-from-url \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/myusername/ledmatrix-my-custom-plugin"}'

# Enable it
curl -X POST http://192.168.1.100:5000/api/v3/plugins/toggle \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "my-custom-plugin", "enabled": true}'

# Restart
sudo systemctl restart ledmatrix

Example 3: Share Plugin with Others

As a plugin developer, you can share your plugin with others even before it's in the official store:

1. Push your plugin to GitHub: https://github.com/yourusername/ledmatrix-awesome-plugin
2. Share the URL with users
3. Users install via:
   • Open the LEDMatrix web interface
   • Open the "Plugin Manager" tab
   • Scroll to "Install from GitHub" → "Install Single Plugin"
   • Paste the URL
   • Click "Install"

---

Command-Line Usage

For advanced users, manage plugins via command line:

# Install from registry
python3 -c "
from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager(plugins_dir='plugin-repos')
store.install_plugin('clock-simple')
"

# Install from URL
python3 -c "
from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager(plugins_dir='plugin-repos')
result = store.install_from_url('https://github.com/user/plugin')
print(result)
"

# List installed
python3 -c "
from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager(plugins_dir='plugin-repos')
for plugin_id in store.list_installed_plugins():
    print(plugin_id)
"

# Uninstall
python3 -c "
from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager(plugins_dir='plugin-repos')
store.uninstall_plugin('clock-simple')
"

---

FAQ

Q: Do I need to restart the display after installing a plugin? A: Yes, plugins are loaded when the display controller starts.

Q: Can I install plugins while the display is running? A: Yes, you can install anytime, but you must restart the display to load them.

Q: What happens if I install a plugin with the same ID as an existing one? A: The existing copy will be replaced with the latest code from the repository.

Q: Can I install multiple versions of the same plugin? A: No, each plugin ID maps to a single installed copy.

Q: How do I update all plugins at once? A: Click Check & Update All at the top of the Plugin Manager tab. You can also turn on weekly automatic updates (off by default) in the General tab; they update LEDMatrix itself and then the installed plugins (web_interface/auto_update.py).

Q: How does the store know an update is available? A: For registry plugins it compares the installed manifest's version with the registry's latest_version; git tags and releases are not consulted.

Q: Can plugins access my API keys from config_secrets.json? A: Yes, if a plugin needs API keys, it can access them like core managers do.

Q: How much disk space do plugins use? A: Most plugins are small (1-5MB). Check individual plugin documentation for specific requirements.

Q: Can I create my own plugin? A: Yes! See PLUGIN_DEVELOPMENT_GUIDE.md for instructions.

---

Related Documentation

• PLUGIN_DEVELOPMENT_GUIDE.md - Create your own plugins
• PLUGIN_API_REFERENCE.md - Plugin API documentation
• PLUGIN_ARCHITECTURE_SPEC.md - Plugin system architecture (historical)
• REST_API_REFERENCE.md - Complete REST API reference