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
```bash
# 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
```bash
# 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
```bash
# 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:**
```bash
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'
```

**Via Python:**
```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:**
```bash
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:**
```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:**
```bash
# 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:**
```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:**
```bash
curl "http://your-pi-ip:5000/api/v3/plugins/installed"
```

**Via Python:**
```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:**
```bash
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:**
```bash
curl -X POST http://your-pi-ip:5000/api/v3/plugins/update \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'
```

**Via Python:**
```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:**
```bash
curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \
  -H "Content-Type: application/json" \
  -d '{"plugin_id": "clock-simple"}'
```

**Via Python:**
```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`:

```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:

```json
{
  "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

```bash
# 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

```bash
# 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:

```bash
# 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](PLUGIN_DEVELOPMENT_GUIDE.md) for instructions.

---

## Related Documentation

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