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.

---

Quick Reference

Install from Store

# Web UI: Plugin Store → 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 Store → "Install from URL" → 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 Store" tab
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()
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 Store" tab
3. Find the "Install from URL" section
4. Paste the GitHub repository URL (e.g., https://github.com/user/ledmatrix-my-plugin)
5. Click "Install from URL"
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()
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/search?q=hockey"

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

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

Via Python:

from src.plugin_system.store_manager import PluginStoreManager

store = PluginStoreManager()

# 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()
installed = store.list_installed_plugins()

for plugin_id in installed:
    info = store.get_installed_plugin_info(plugin_id)
    print(f"{info['name']} (Last updated: {info.get('last_updated', 'unknown')})")

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()
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()
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 with "Failed to clone or download repository"

Solutions:

• Check that git is installed: which git
• Verify the GitHub URL is correct
• Check your internet connection
• The system will automatically try ZIP download as fallback

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 all plugins in store
GET	/api/v3/plugins/store/search	Search for plugins
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
   • Click "Plugin Store" tab
   • Scroll to "Install from URL"
   • Paste the URL
   • Click "Install from URL"

---

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()
store.install_plugin('clock-simple')
"

# Install from URL
python3 -c "
from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager()
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()
for plugin_id in store.list_installed_plugins():
    info = store.get_installed_plugin_info(plugin_id)
    print(f'{plugin_id}: {info[\"name\"]} (Last updated: {info.get(\"last_updated\", \"unknown\")})')
"

# Uninstall
python3 -c "
from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager()
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 checkout of the repository's default branch.

Q: How do I update all plugins at once? A: Currently, you need to update each plugin individually. Bulk update is planned for a future release.

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