diff --git a/docs/PLUGIN_CONFIGURATION_TABS.md b/docs/PLUGIN_CONFIGURATION_TABS.md index 76a680ee..9fd8cce7 100644 --- a/docs/PLUGIN_CONFIGURATION_TABS.md +++ b/docs/PLUGIN_CONFIGURATION_TABS.md @@ -29,10 +29,14 @@ Each installed plugin now gets its own dedicated configuration tab in the web in 3. Click **Save Configuration** 4. Restart the display service to apply changes -### Plugin Management vs Configuration +### Plugin Manager vs Per-Plugin Configuration -- **Plugins Tab**: Used for plugin management (install, enable/disable, update, uninstall) -- **Plugin-Specific Tabs**: Used for configuring plugin behavior and settings +- **Plugin Manager tab** (second nav row): used for browsing the + Plugin Store, installing plugins, toggling installed plugins on/off, + and updating/uninstalling them +- **Per-plugin tabs** (one per installed plugin, also in the second + nav row): used for configuring that specific plugin's behavior and + settings via a form auto-generated from its `config_schema.json` ## For Plugin Developers diff --git a/docs/PLUGIN_CONFIG_QUICK_START.md b/docs/PLUGIN_CONFIG_QUICK_START.md index c3108211..16113ccc 100644 --- a/docs/PLUGIN_CONFIG_QUICK_START.md +++ b/docs/PLUGIN_CONFIG_QUICK_START.md @@ -4,13 +4,14 @@ ### For Users -1. Open the web interface: `http://your-pi-ip:5001` -2. Go to the **Plugin Store** tab -3. Install a plugin (e.g., "Hello World") -4. Notice a new tab appears with the plugin's name -5. Click on the plugin's tab to configure it -6. Modify settings and click **Save Configuration** -7. Restart the display to see changes +1. Open the web interface: `http://your-pi-ip:5000` +2. Open the **Plugin Manager** tab +3. Find a plugin in the **Plugin Store** section (e.g., "Hello World") + and click **Install** +4. Notice a new tab appears in the second nav row with the plugin's name +5. Click that tab to configure the plugin +6. Modify settings and click **Save** +7. From **Overview**, click **Restart Display Service** to see changes That's it! Each installed plugin automatically gets its own configuration tab. @@ -171,9 +172,11 @@ User enters: `255, 0, 0` ### For Users 1. **Reset Anytime**: Use "Reset to Defaults" to restore original settings -2. **Navigate Back**: Click "Back to Plugin Management" to return to Plugins tab +2. **Navigate Back**: Switch to the **Plugin Manager** tab to see the + full list of installed plugins 3. **Check Help Text**: Each field has a description explaining what it does -4. **Restart Required**: Remember to restart the display after saving +4. **Restart Required**: Remember to restart the display service from + **Overview** after saving ### For Developers @@ -206,8 +209,10 @@ User enters: `255, 0, 0` ## 📚 Next Steps - Read the full documentation: [PLUGIN_CONFIGURATION_TABS.md](PLUGIN_CONFIGURATION_TABS.md) -- Check implementation details: [PLUGIN_CONFIG_TABS_SUMMARY.md](PLUGIN_CONFIG_TABS_SUMMARY.md) -- Browse example plugins: `plugins/hello-world/`, `plugins/clock-simple/` +- Check the configuration architecture: [PLUGIN_CONFIG_ARCHITECTURE.md](PLUGIN_CONFIG_ARCHITECTURE.md) +- Browse example plugins in the + [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins) + repo, especially `plugins/hello-world/` and `plugins/clock-simple/` - Join the community for help and suggestions ## 🎉 That's It! diff --git a/docs/PLUGIN_DEPENDENCY_GUIDE.md b/docs/PLUGIN_DEPENDENCY_GUIDE.md index 0904ef0a..1388a6fc 100644 --- a/docs/PLUGIN_DEPENDENCY_GUIDE.md +++ b/docs/PLUGIN_DEPENDENCY_GUIDE.md @@ -37,7 +37,7 @@ sudo systemctl start ledmatrix-web ### ✅ Scenario 2: Web Interface Plugin Installation -**What:** Installing/enabling plugins via web interface at `http://pi-ip:5001` +**What:** Installing/enabling plugins via web interface at `http://pi-ip:5000` - **Web service runs as:** root (ledmatrix-web.service) - **Installs to:** System-wide diff --git a/docs/PLUGIN_DEPENDENCY_TROUBLESHOOTING.md b/docs/PLUGIN_DEPENDENCY_TROUBLESHOOTING.md index 1e3ef8d1..755760c9 100644 --- a/docs/PLUGIN_DEPENDENCY_TROUBLESHOOTING.md +++ b/docs/PLUGIN_DEPENDENCY_TROUBLESHOOTING.md @@ -77,10 +77,12 @@ sudo chmod -R 755 /root/.cache The web interface handles dependency installation correctly in the service context: -1. Access the web interface (usually http://ledpi:8080) -2. Navigate to Plugin Store or Plugin Management -3. Install plugins through the web UI -4. The system will automatically handle dependencies +1. Access the web interface (`http://ledpi:5000` or `http://your-pi-ip:5000`) +2. Open the **Plugin Manager** tab (use the **Plugin Store** section to + find the plugin, or **Install from GitHub**) +3. Install the plugin through the web UI +4. The system automatically handles dependency installation in the + service context (which has the right permissions) ## Prevention diff --git a/docs/PLUGIN_QUICK_REFERENCE.md b/docs/PLUGIN_QUICK_REFERENCE.md index 0825a8eb..7f8c0bf0 100644 --- a/docs/PLUGIN_QUICK_REFERENCE.md +++ b/docs/PLUGIN_QUICK_REFERENCE.md @@ -2,14 +2,20 @@ ## Overview -Transform LEDMatrix into a modular, plugin-based system where users can create, share, and install custom displays via a GitHub-based store (similar to HACS for Home Assistant). +LEDMatrix is a modular, plugin-based system where users create, share, +and install custom displays via a GitHub-based store (similar in spirit +to HACS for Home Assistant). This page is a quick reference; for the +full design see [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) +and [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md). ## Key Decisions -✅ **Gradual Migration**: Existing managers stay, plugins added alongside -✅ **Migration Required**: Breaking changes in v3.0, tools provided -✅ **GitHub Store**: Simple discovery, packages from repos -✅ **Plugin Location**: `./plugins/` directory +✅ **Plugin-First**: All display features (calendar excepted) are now plugins +✅ **GitHub Store**: Discovery from `ledmatrix-plugins` registry plus + any GitHub URL +✅ **Plugin Location**: configured by `plugin_system.plugins_directory` + in `config.json` (default `plugin-repos/`; the loader also searches + `plugins/` as a fallback) ## File Structure @@ -19,15 +25,16 @@ LEDMatrix/ │ └── plugin_system/ │ ├── base_plugin.py # Plugin interface │ ├── plugin_manager.py # Load/unload plugins +│ ├── plugin_loader.py # Discovery + dynamic import │ └── store_manager.py # Install from GitHub -├── plugins/ +├── plugin-repos/ # Default plugin install location │ ├── clock-simple/ │ │ ├── manifest.json # Metadata │ │ ├── manager.py # Main plugin class │ │ ├── requirements.txt # Dependencies │ │ ├── config_schema.json # Validation │ │ └── README.md -│ └── nhl-scores/ +│ └── hockey-scoreboard/ │ └── ... (same structure) └── config/config.json # Plugin configs ``` @@ -109,100 +116,45 @@ git push origin v1.0.0 ### Web UI -1. **Browse Store**: Plugin Store tab → Search/filter -2. **Install**: Click "Install" button -3. **Configure**: Plugin Manager → Click ⚙️ Configure -4. **Enable/Disable**: Toggle switch -5. **Reorder**: Drag and drop in rotation list +1. **Browse Store**: Plugin Manager tab → Plugin Store section → Search/filter +2. **Install**: Click **Install** in the plugin's row +3. **Configure**: open the plugin's tab in the second nav row +4. **Enable/Disable**: toggle switch in the **Installed Plugins** list +5. **Reorder**: order is set by the position in `display_modes` / + plugin order; rearranging via drag-and-drop is not yet supported -### API +### REST API -```python -# Install plugin -POST /api/plugins/install -{"plugin_id": "my-plugin"} - -# Install from custom URL -POST /api/plugins/install-from-url -{"repo_url": "https://github.com/User/plugin"} - -# List installed -GET /api/plugins/installed - -# Toggle -POST /api/plugins/toggle -{"plugin_id": "my-plugin", "enabled": true} -``` - -### Command Line - -```python -from src.plugin_system.store_manager import PluginStoreManager - -store = PluginStoreManager() - -# Install -store.install_plugin('nhl-scores') - -# Install from URL -store.install_from_url('https://github.com/User/plugin') - -# Update -store.update_plugin('nhl-scores') - -# Uninstall -store.uninstall_plugin('nhl-scores') -``` - -## Migration Path - -### Phase 1: v2.0.0 (Plugin Infrastructure) -- Plugin system alongside existing managers -- 100% backward compatible -- Web UI shows plugin store - -### Phase 2: v2.1.0 (Example Plugins) -- Reference plugins created -- Migration examples -- Developer docs - -### Phase 3: v2.2.0 (Migration Tools) -- Auto-migration script -- Config converter -- Testing tools - -### Phase 4: v2.5.0 (Deprecation) -- Warnings on legacy managers -- Migration guide -- 95% backward compatible - -### Phase 5: v3.0.0 (Plugin-Only) -- Legacy managers removed from core -- Packaged as official plugins -- **Breaking change - migration required** - -## Quick Migration +The API is mounted at `/api/v3` (`web_interface/app.py:144`). ```bash -# 1. Backup -cp config/config.json config/config.json.backup +# Install plugin from the registry +curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \ + -H "Content-Type: application/json" \ + -d '{"plugin_id": "hockey-scoreboard"}' -# 2. Run migration -python3 scripts/migrate_to_plugins.py +# Install from custom URL +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/plugin"}' -# 3. Review -cat config/config.json.migrated +# List installed +curl http://your-pi-ip:5000/api/v3/plugins/installed -# 4. Apply -mv config/config.json.migrated config/config.json - -# 5. Restart -sudo systemctl restart ledmatrix +# Toggle +curl -X POST http://your-pi-ip:5000/api/v3/plugins/toggle \ + -H "Content-Type: application/json" \ + -d '{"plugin_id": "hockey-scoreboard", "enabled": true}' ``` +See [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for the full list. + ## Plugin Registry Structure -**ChuckBuilds/ledmatrix-plugin-registry/plugins.json**: +The official registry lives at +[`ChuckBuilds/ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins). +The Plugin Store reads `plugins.json` at the root of that repo, which +follows this shape: ```json { "plugins": [ @@ -245,42 +197,30 @@ sudo systemctl restart ledmatrix - ✅ Community handles custom displays - ✅ Easier to review changes -## What's Missing? +## Known Limitations -This specification covers the technical architecture. Additional considerations: +The plugin system is shipped and stable, but some things are still +intentionally simple: -1. **Sandboxing**: Current design has no isolation (future enhancement) -2. **Resource Limits**: No CPU/memory limits per plugin (future) -3. **Plugin Ratings**: Registry needs rating/review system -4. **Auto-Updates**: Manual update only (could add auto-update) -5. **Dependency Conflicts**: No automatic resolution -6. **Version Pinning**: Limited version constraint checking -7. **Plugin Testing**: No automated testing framework -8. **Marketplace**: No paid plugins (all free/open source) - -## Next Steps - -1. ✅ Review this specification -2. Start Phase 1 implementation -3. Create first 3-4 example plugins -4. Set up plugin registry repo -5. Build web UI components -6. Test on Pi hardware -7. Release v2.0.0 alpha - -## Questions to Resolve - -Before implementing, consider: - -1. Should we support plugin dependencies (plugin A requires plugin B)? -2. How to handle breaking changes in core display_manager API? -3. Should plugins be able to add new web UI pages? -4. What about plugins that need hardware beyond LED matrix? -5. How to prevent malicious plugins? -6. Should there be plugin quotas (max API calls, etc.)? -7. How to handle plugin conflicts (two clocks competing)? +1. **Sandboxing**: plugins run in the same process as the display loop; + there is no isolation. Review code before installing third-party + plugins. +2. **Resource limits**: there's a resource monitor that warns about + slow plugins, but no hard CPU/memory caps. +3. **Plugin ratings**: not yet — the Plugin Store shows version, + author, and category but no community rating system. +4. **Auto-updates**: manual via the Plugin Manager tab; no automatic + background updates. +5. **Dependency conflicts**: each plugin's `requirements.txt` is + installed via pip; conflicting versions across plugins are not + resolved automatically. +6. **Plugin testing framework**: see + [HOW_TO_RUN_TESTS.md](HOW_TO_RUN_TESTS.md) and + [DEV_PREVIEW.md](DEV_PREVIEW.md) — there are tools, but no + mandatory test gate. --- -**See PLUGIN_ARCHITECTURE_SPEC.md for full details** +**See [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) for the +full architectural specification.** diff --git a/docs/PLUGIN_REGISTRY_SETUP_GUIDE.md b/docs/PLUGIN_REGISTRY_SETUP_GUIDE.md index 796cb422..7c1569b8 100644 --- a/docs/PLUGIN_REGISTRY_SETUP_GUIDE.md +++ b/docs/PLUGIN_REGISTRY_SETUP_GUIDE.md @@ -95,14 +95,14 @@ Official plugin registry for [LEDMatrix](https://github.com/ChuckBuilds/LEDMatri All plugins can be installed through the LEDMatrix web interface: -1. Open web interface (http://your-pi-ip:5050) -2. Go to Plugin Store tab -3. Browse or search for plugins -4. Click Install +1. Open web interface (http://your-pi-ip:5000) +2. Open the **Plugin Manager** tab +3. Browse or search the **Plugin Store** section +4. Click **Install** Or via API: ```bash -curl -X POST http://your-pi-ip:5050/api/plugins/install \ +curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \ -d '{"plugin_id": "clock-simple"}' ``` @@ -152,7 +152,7 @@ Before submitting, ensure your plugin: 1. **Test Your Plugin** ```bash # Install via URL on your Pi - curl -X POST http://your-pi:5050/api/plugins/install-from-url \ + curl -X POST http://your-pi:5000/api/v3/plugins/install-from-url \ -d '{"repo_url": "https://github.com/you/ledmatrix-your-plugin"}' ``` @@ -311,7 +311,7 @@ git push # 1. Receive PR on ledmatrix-plugins repo # 2. Review using VERIFICATION.md checklist # 3. Test installation: -curl -X POST http://pi:5050/api/plugins/install-from-url \ +curl -X POST http://pi:5000/api/v3/plugins/install-from-url \ -d '{"repo_url": "https://github.com/contributor/plugin"}' # 4. If approved, merge PR diff --git a/docs/PLUGIN_STORE_GUIDE.md b/docs/PLUGIN_STORE_GUIDE.md index da926af4..4482d5b9 100644 --- a/docs/PLUGIN_STORE_GUIDE.md +++ b/docs/PLUGIN_STORE_GUIDE.md @@ -12,7 +12,7 @@ The LEDMatrix Plugin Store allows you to discover, install, and manage display p ```bash # Web UI: Plugin Store → Search → Click Install # API: -curl -X POST http://your-pi-ip:5050/api/plugins/install \ +curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \ -H "Content-Type: application/json" \ -d '{"plugin_id": "clock-simple"}' ``` @@ -21,7 +21,7 @@ curl -X POST http://your-pi-ip:5050/api/plugins/install \ ```bash # Web UI: Plugin Store → "Install from URL" → Paste URL # API: -curl -X POST http://your-pi-ip:5050/api/plugins/install-from-url \ +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"}' ``` @@ -29,20 +29,20 @@ curl -X POST http://your-pi-ip:5050/api/plugins/install-from-url \ ### Manage Plugins ```bash # List installed -curl "http://your-pi-ip:5050/api/plugins/installed" +curl "http://your-pi-ip:5000/api/v3/plugins/installed" # Enable/disable -curl -X POST http://your-pi-ip:5050/api/plugins/toggle \ +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:5050/api/plugins/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:5050/api/plugins/uninstall \ +curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \ -H "Content-Type: application/json" \ -d '{"plugin_id": "clock-simple"}' ``` @@ -56,7 +56,7 @@ curl -X POST http://your-pi-ip:5050/api/plugins/uninstall \ 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:5050 +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 @@ -65,7 +65,7 @@ The official plugin store contains curated, verified plugins that have been revi **Via REST API:** ```bash -curl -X POST http://your-pi-ip:5050/api/plugins/install \ +curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \ -H "Content-Type: application/json" \ -d '{"plugin_id": "clock-simple"}' ``` @@ -101,7 +101,7 @@ Install any plugin directly from a GitHub repository, even if it's not in the of **Via REST API:** ```bash -curl -X POST http://your-pi-ip:5050/api/plugins/install-from-url \ +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"}' ``` @@ -131,13 +131,13 @@ else: **Via REST API:** ```bash # Search by query -curl "http://your-pi-ip:5050/api/plugins/store/search?q=hockey" +curl "http://your-pi-ip:5000/api/v3/plugins/store/search?q=hockey" # Filter by category -curl "http://your-pi-ip:5050/api/plugins/store/search?category=sports" +curl "http://your-pi-ip:5000/api/v3/plugins/store/search?category=sports" # Filter by tags -curl "http://your-pi-ip:5050/api/plugins/store/search?tags=nhl&tags=hockey" +curl "http://your-pi-ip:5000/api/v3/plugins/store/search?tags=nhl&tags=hockey" ``` **Via Python:** @@ -168,7 +168,7 @@ results = store.search_plugins(tags=["nhl", "hockey"]) **Via REST API:** ```bash -curl "http://your-pi-ip:5050/api/plugins/installed" +curl "http://your-pi-ip:5000/api/v3/plugins/installed" ``` **Via Python:** @@ -192,7 +192,7 @@ for plugin_id in installed: **Via REST API:** ```bash -curl -X POST http://your-pi-ip:5050/api/plugins/toggle \ +curl -X POST http://your-pi-ip:5000/api/v3/plugins/toggle \ -H "Content-Type: application/json" \ -d '{"plugin_id": "clock-simple", "enabled": true}' ``` @@ -207,7 +207,7 @@ curl -X POST http://your-pi-ip:5050/api/plugins/toggle \ **Via REST API:** ```bash -curl -X POST http://your-pi-ip:5050/api/plugins/update \ +curl -X POST http://your-pi-ip:5000/api/v3/plugins/update \ -H "Content-Type: application/json" \ -d '{"plugin_id": "clock-simple"}' ``` @@ -230,7 +230,7 @@ success = store.update_plugin('clock-simple') **Via REST API:** ```bash -curl -X POST http://your-pi-ip:5050/api/plugins/uninstall \ +curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \ -H "Content-Type: application/json" \ -d '{"plugin_id": "clock-simple"}' ``` @@ -351,15 +351,15 @@ All API endpoints return JSON with this structure: | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/api/plugins/store/list` | List all plugins in store | -| GET | `/api/plugins/store/search` | Search for plugins | -| GET | `/api/plugins/installed` | List installed plugins | -| POST | `/api/plugins/install` | Install from registry | -| POST | `/api/plugins/install-from-url` | Install from GitHub URL | -| POST | `/api/plugins/uninstall` | Uninstall plugin | -| POST | `/api/plugins/update` | Update plugin | -| POST | `/api/plugins/toggle` | Enable/disable plugin | -| POST | `/api/plugins/config` | Update plugin config | +| 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 | --- @@ -369,7 +369,7 @@ All API endpoints return JSON with this structure: ```bash # Install -curl -X POST http://192.168.1.100:5050/api/plugins/install \ +curl -X POST http://192.168.1.100:5000/api/v3/plugins/install \ -H "Content-Type: application/json" \ -d '{"plugin_id": "clock-simple"}' @@ -390,12 +390,12 @@ sudo systemctl restart ledmatrix ```bash # Install your own plugin during development -curl -X POST http://192.168.1.100:5050/api/plugins/install-from-url \ +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:5050/api/plugins/toggle \ +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}'