diff --git a/docs/PLUGIN_DEVELOPMENT_GUIDE.md b/docs/PLUGIN_DEVELOPMENT_GUIDE.md index 491bd8ad..14b96c87 100644 --- a/docs/PLUGIN_DEVELOPMENT_GUIDE.md +++ b/docs/PLUGIN_DEVELOPMENT_GUIDE.md @@ -660,7 +660,8 @@ To have your plugin added to the official plugin store: 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 +- **`version` in manifest.json**: The store offers updates by comparing it + with the registry's `latest_version`; releases and tags are not read - **README.md**: Clear installation and configuration instructions - **config_schema.json**: Recommended for web UI configuration - **manifest.json**: Required with all required fields @@ -670,7 +671,8 @@ For your plugin to work well in the plugin store: 1. **Official Registry** (Recommended): - Listed in default plugin store - - Automatic updates + - Update offers in the Plugin Manager (and weekly automatic updates, if + the user turns them on) - Verified badge - Requires approval diff --git a/docs/PLUGIN_QUICK_REFERENCE.md b/docs/PLUGIN_QUICK_REFERENCE.md index 09c54b76..8eb7f793 100644 --- a/docs/PLUGIN_QUICK_REFERENCE.md +++ b/docs/PLUGIN_QUICK_REFERENCE.md @@ -99,20 +99,13 @@ class MyPlugin(BasePlugin): ### 3. Publishing -```bash -# Create repo -git init -git add . -git commit -m "Initial commit" -git remote add origin https://github.com/YourName/ledmatrix-my-plugin -git push -u origin main - -# Tag release -git tag v1.0.0 -git push origin v1.0.0 - -# Submit to registry (PR to ChuckBuilds/ledmatrix-plugins) -``` +Official plugins live in the +[ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins) +monorepo: add `plugins//`, bump `version` in its +`manifest.json` on every change, run `python update_registry.py` there and +open a pull request. A third-party plugin can stay in its own repository and +be installed by URL. Git tags and releases are not read by the store; see +[PLUGIN_REGISTRY_SETUP_GUIDE.md](PLUGIN_REGISTRY_SETUP_GUIDE.md). ## Using Plugins @@ -166,20 +159,20 @@ follows this shape: "name": "Simple Clock", "author": "ChuckBuilds", "category": "time", - "repo": "https://github.com/ChuckBuilds/ledmatrix-clock-simple", - "versions": [ - { - "version": "1.0.0", - "ledmatrix_min_version": "2.0.0", - "download_url": "https://github.com/.../v1.0.0.zip" - } - ], + "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins", + "branch": "main", + "plugin_path": "plugins/clock-simple", + "latest_version": "1.0.0", "verified": true } ] } ``` +`plugin_path` is empty for a third-party plugin in its own repository. The +store offers an update when the installed manifest's `version` is older +than `latest_version`. + ## Benefits ### For Users @@ -212,8 +205,11 @@ intentionally simple: 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. +4. **Auto-updates**: off by default. Update from the Plugin Manager tab + (per plugin, or **Check & Update All**), or turn on weekly automatic + updates in the General tab (`auto_update.enabled`, + `web_interface/auto_update.py`), which update LEDMatrix and then the + installed plugins. 5. **Dependency conflicts**: each plugin's `requirements.txt` is installed via pip; conflicting versions across plugins are not resolved automatically. diff --git a/docs/PLUGIN_REGISTRY_SETUP_GUIDE.md b/docs/PLUGIN_REGISTRY_SETUP_GUIDE.md index 87457c14..0fcf7db8 100644 --- a/docs/PLUGIN_REGISTRY_SETUP_GUIDE.md +++ b/docs/PLUGIN_REGISTRY_SETUP_GUIDE.md @@ -1,415 +1,109 @@ # Plugin Registry Setup Guide -This guide explains how to set up and maintain your official plugin registry at [https://github.com/ChuckBuilds/ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins). +This page explains how the official plugin registry works and how a plugin +gets into it. The registry and the official plugins both live in one +repository, [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins); +its `SUBMISSION.md`, `VERIFICATION.md` and `docs/` are the authoritative +contributor guides. -## Overview +## How it fits together -Your plugin registry serves as a **central directory** that lists all official, verified plugins. The registry is just a JSON file; the actual plugins live in their own repositories. - -## Repository Structure - -``` +```text ledmatrix-plugins/ -├── README.md # Main documentation -├── LICENSE # GPL-3.0 -├── plugins.json # The registry file (main file!) -├── SUBMISSION.md # Guidelines for submitting plugins -├── VERIFICATION.md # Verification checklist -└── assets/ # Optional: screenshots, badges - └── screenshots/ +├── plugins/ +│ ├── clock-simple/ # one directory per official plugin +│ │ ├── manifest.json # source of truth for the plugin's version +│ │ ├── manager.py +│ │ ├── config_schema.json +│ │ └── requirements.txt +│ └── ... +├── plugins.json # the registry the Plugin Store reads +└── update_registry.py # regenerates plugins.json from the manifests ``` -## Step 1: Create plugins.json +- **Registry.** The Plugin Store fetches + `https://raw.githubusercontent.com/ChuckBuilds/ledmatrix-plugins/main/plugins.json` + (`PluginStoreManager.REGISTRY_URL` in `src/plugin_system/store_manager.py`) + and caches it for 15 minutes. +- **Monorepo plugins** have `repo` set to the ledmatrix-plugins URL and + `plugin_path` set to their directory (`plugins/`). The store downloads + just that directory (GitHub API, falling back to the repository ZIP), so + installed copies have no `.git` directory. +- **Third-party plugins** keep their own repository: `repo` points at it and + `plugin_path` is empty. The store installs them with `git clone`, falling + back to an archive download. +- **Updates.** For registry plugins the store compares the installed + manifest's `version` with the entry's `latest_version`. Git tags and GitHub + releases are not read. -This is the **core file** that the Plugin Store reads from. - -**Important**: The registry stores **metadata only** (name, description, repo URL, etc.). -The plugin store always pulls the latest commit information directly from GitHub, so you never manage semantic versions here. - -**File**: `plugins.json` +## A registry entry ```json { - "last_updated": "2025-01-09T12:00:00Z", - "plugins": [ - { - "id": "clock-simple", - "name": "Simple Clock", - "description": "A clean, simple clock display with date and time", - "author": "ChuckBuilds", - "category": "time", - "tags": ["clock", "time", "date"], - "repo": "https://github.com/ChuckBuilds/ledmatrix-clock-simple", - "branch": "main", - "stars": 12, - "downloads": 156, - "last_updated": "2025-01-09", - "last_commit": "abc1234", - "verified": true, - "screenshot": "https://raw.githubusercontent.com/ChuckBuilds/ledmatrix-plugins/main/assets/screenshots/clock-simple.png" - } - ] + "id": "clock-simple", + "name": "Simple Clock", + "description": "A clean, simple clock display with date and time", + "author": "ChuckBuilds", + "category": "time", + "tags": ["clock", "time", "date"], + "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins", + "branch": "main", + "plugin_path": "plugins/clock-simple", + "stars": 0, + "downloads": 0, + "last_updated": "2026-09-03", + "verified": true, + "screenshot": "", + "latest_version": "1.0.0" } ``` -**Note**: There's no need for version arrays or release tracking. The store queries GitHub for the latest commit details (date, branch, and short SHA) whenever metadata is requested. +[plugin_registry_template.json](plugin_registry_template.json) shows a +monorepo entry and a third-party entry. -## Step 2: Create Plugin Repositories +Don't edit `latest_version` or `last_updated` by hand for monorepo plugins: +`update_registry.py` in ledmatrix-plugins writes them from each plugin's +`manifest.json`. -Each plugin should have its own repository: +## Adding or changing an official plugin -### Example: Creating clock-simple Plugin +1. Add or edit `plugins//` in the monorepo. The store refuses + a manifest without `id`, `name`, `class_name` and `display_modes`; also + set `version`. +2. Bump `version` in the plugin's `manifest.json` for every change, or users + won't be offered the update. +3. Run `python update_registry.py` in ledmatrix-plugins and commit the + updated `plugins.json` with the plugin change. +4. Open a pull request. The monorepo's CI and review steps are described in + its `SUBMISSION.md`. -1. **Create new repo**: `ledmatrix-clock-simple` -2. **Add plugin files**: - ``` - ledmatrix-clock-simple/ - ├── manifest.json - ├── manager.py - ├── requirements.txt - ├── config_schema.json - ├── README.md - └── assets/ - ``` -3. **Add to registry**: Update `plugins.json` in ledmatrix-plugins repo +## Adding a third-party plugin -## Step 3: Update README.md +Test it with **Plugin Manager → Install from GitHub → Install Single Plugin** +(or `POST /api/v3/plugins/install-from-url`), then follow the "own +repository" option in the monorepo's `SUBMISSION.md` to request a registry +entry. -Create a comprehensive README for your plugin registry: - -```markdown -# LEDMatrix Official Plugins - -Official plugin registry for [LEDMatrix](https://github.com/ChuckBuilds/LEDMatrix). - -## Available Plugins - - - -| Plugin | Description | Category | Last Updated | -|--------|-------------|----------|--------------| -| [Simple Clock](https://github.com/ChuckBuilds/ledmatrix-clock-simple) | Clean clock display | Time | 2025-01-09 | -| [NHL Scores](https://github.com/ChuckBuilds/ledmatrix-nhl-scores) | Live NHL scores | Sports | 2025-01-07 | - -## Installation - -All plugins can be installed through the LEDMatrix web interface: - -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:5000/api/v3/plugins/install \ - -H "Content-Type: application/json" \ - -d '{"plugin_id": "clock-simple"}' -``` - -## Submitting Plugins - -See [SUBMISSION.md](SUBMISSION.md) for guidelines on submitting your plugin. - -## Creating Plugins - -See the main [LEDMatrix Plugin Developer Guide](https://github.com/ChuckBuilds/LEDMatrix/wiki/Plugin-Development). - -## Plugin Categories - -- **Time**: Clocks, timers, countdowns -- **Sports**: Scoreboards, schedules, stats -- **Weather**: Forecasts, current conditions -- **Finance**: Stocks, crypto, market data -- **Entertainment**: Games, animations, media -- **Custom**: Unique displays -``` - -## Step 4: Create SUBMISSION.md - -Guidelines for community plugin submissions: - -```markdown -# Plugin Submission Guidelines - -Want to add your plugin to the official registry? Follow these steps! - -## Requirements - -Before submitting, ensure your plugin: - -- ✅ Has a complete `manifest.json` with all required fields -- ✅ Follows the plugin architecture specification -- ✅ Has comprehensive README documentation -- ✅ Includes example configuration -- ✅ Has been tested on Raspberry Pi hardware -- ✅ Follows coding standards (PEP 8) -- ✅ Has proper error handling -- ✅ Uses logging appropriately -- ✅ Has no hardcoded API keys or secrets - -## Submission Process - -1. **Test Your Plugin** - ```bash - # Install via URL on your Pi - curl -X POST http://your-pi:5000/api/v3/plugins/install-from-url \ - -H "Content-Type: application/json" \ - -d '{"repo_url": "https://github.com/you/ledmatrix-your-plugin"}' - ``` - -2. **Fork This Repo** - Fork [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins) - -4. **Update plugins.json** - Add your plugin entry (metadata only - no versions needed): - ```json - { - "id": "your-plugin", - "name": "Your Plugin Name", - "description": "What it does", - "author": "YourName", - "category": "custom", - "tags": ["tag1", "tag2"], - "repo": "https://github.com/you/ledmatrix-your-plugin", - "branch": "main", - "verified": false - } - ``` - -5. **Submit Pull Request** - Create PR with title: "Add plugin: your-plugin-name" - -## Review Process - -1. **Automated Checks**: Manifest validation, structure check -2. **Code Review**: Manual review of plugin code -3. **Testing**: Test installation and basic functionality -4. **Approval**: If accepted, merged and marked as verified - -## After Approval - -- Plugin appears in official store -- `verified: true` badge shown -- Included in plugin count -- Featured in README - -## Updating Your Plugin - -Whenever you push new commits to your plugin repository's default branch, the store will automatically surface the latest commit timestamp and short SHA. No release tagging or manifest version bumps are required. - -You only need to update the registry if: -- Plugin metadata changes (name, description, category, etc.) -- Repository URL changes -- You want to update the verified status - -To update metadata: -1. Fork the registry repo -2. Update plugins.json with new metadata -3. Submit PR with changes -4. We'll review and merge - -## Questions? - -Open an issue in this repo or the main LEDMatrix repo. -``` - -## Step 5: Create VERIFICATION.md - -Checklist for verifying plugins: - -```markdown -# Plugin Verification Checklist - -Use this checklist when reviewing plugin submissions. - -## Code Review - -- [ ] Follows BasePlugin interface -- [ ] Has proper error handling -- [ ] Uses logging appropriately -- [ ] No hardcoded secrets/API keys -- [ ] Follows Python coding standards -- [ ] Has type hints where appropriate -- [ ] Has docstrings for classes/methods - -## Manifest Validation - -- [ ] All required fields present -- [ ] Valid JSON syntax -- [ ] Last updated metadata present when available -- [ ] Category is valid -- [ ] Tags are descriptive - -## Functionality - -- [ ] Installs successfully via URL -- [ ] Dependencies install correctly -- [ ] Plugin loads without errors -- [ ] Display output works correctly -- [ ] Configuration schema validates -- [ ] Example config provided - -## Documentation - -- [ ] README.md exists and is comprehensive -- [ ] Installation instructions clear -- [ ] Configuration options documented -- [ ] Examples provided -- [ ] License specified - -## Security - -- [ ] No malicious code -- [ ] Safe dependency versions -- [ ] Appropriate permissions -- [ ] No network access without disclosure -- [ ] No file system access outside plugin dir - -## Testing - -- [ ] Tested on Raspberry Pi -- [ ] Works with 64x32 matrix (minimum) -- [ ] No excessive CPU/memory usage -- [ ] No crashes or freezes - -## Approval - -Once all checks pass: -- [ ] Set `verified: true` in plugins.json -- [ ] Merge PR -- [ ] Welcome plugin author -- [ ] Update stats (downloads, stars) -``` - -## Step 6: Workflow for Adding Plugins - -### For Your Own Plugins +## Testing locally ```bash -# 1. Create plugin in separate repo -mkdir ledmatrix-clock-simple -cd ledmatrix-clock-simple -# ... create plugin files ... +# Validate a plugin headlessly (from LEDMatrix) +python3 scripts/check_plugin.py --plugin -# 2. Push to GitHub -git init -git add . -git commit -m "Initial commit" -git remote add origin https://github.com/ChuckBuilds/ledmatrix-clock-simple -git push -u origin main - -# 3. Update registry -cd ../ledmatrix-plugins -# Edit plugins.json to add new entry -git add plugins.json -git commit -m "Add clock-simple plugin" -git push -``` - -### For Community Submissions - -```bash -# 1. Receive PR on ledmatrix-plugins repo -# 2. Review using VERIFICATION.md checklist -# 3. Test installation: -curl -X POST http://pi:5000/api/v3/plugins/install-from-url \ - -H "Content-Type: application/json" \ - -d '{"repo_url": "https://github.com/contributor/plugin"}' - -# 4. If approved, merge PR -# 5. Set verified: true in plugins.json -``` - -## Step 7: Maintaining the Registry - -### Regular Updates - -```bash -# Refresh local clones of all plugin repos -python3 scripts/update_plugin_repos.py - -# (Re-)create local plugin repo checkouts from the registry -python3 scripts/setup_plugin_repos.py - -# Audit installed plugins for manifest/schema problems -python3 scripts/audit_plugins.py - -# Validate a single plugin -python3 scripts/check_plugin.py --plugin -``` - -Registry regeneration (`update_registry.py`) lives in the -`ledmatrix-plugins` monorepo, not in this repo. - -## Converting Existing Plugins - -To convert your existing plugins (hello-world, clock-simple) to this system: - -### 1. Move to Separate Repos - -```bash -# For each plugin in plugins/ -cd plugins/clock-simple - -# Create new repo -git init -git add . -git commit -m "Extract clock-simple plugin" -git remote add origin https://github.com/ChuckBuilds/ledmatrix-clock-simple -git push -u origin main -git tag v1.0.0 -git push origin v1.0.0 -``` - -### 2. Add to Registry - -Update `plugins.json` in ledmatrix-plugins repo. - -### 3. Keep or Remove from Main Repo - -Decision: -- **Keep**: Leave in main repo for backward compatibility -- **Remove**: Delete from main repo, users install via store - -## Testing the Registry - -After setting up: - -```bash -# Test registry fetch -curl https://raw.githubusercontent.com/ChuckBuilds/ledmatrix-plugins/main/plugins.json - -# Test plugin installation +# Fetch the registry the way the store does python3 -c " from src.plugin_system.store_manager import PluginStoreManager -store = PluginStoreManager() -registry = store.fetch_registry() -print(f'Found {len(registry[\"plugins\"])} plugins') +store = PluginStoreManager(plugins_dir='plugin-repos') +print(len(store.fetch_registry(force_refresh=True).get('plugins', [])), 'plugins') " ``` -## Benefits of This Setup - -✅ **Centralized Discovery**: One place to find all official plugins -✅ **Decentralized Storage**: Each plugin in its own repo -✅ **Easy Maintenance**: Update registry without touching plugin code -✅ **Community Friendly**: Anyone can submit via PR -✅ **Version Control**: Track plugin versions and updates -✅ **Verified Badge**: Show trust with verified plugins - -## Next Steps - -1. Create `plugins.json` in your repo -2. Update the registry URL in LEDMatrix code (already done) -3. Create SUBMISSION.md and README.md -4. Move existing plugins to separate repos -5. Add them to the registry -6. Announce the plugin store! +To work on monorepo plugins against a LEDMatrix checkout, see +[MULTI_ROOT_WORKSPACE_SETUP.md](MULTI_ROOT_WORKSPACE_SETUP.md) and the +[Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md). ## References -- Plugin Store Implementation: See `PLUGIN_IMPLEMENTATION_SUMMARY.md` -- User Guide: See `PLUGIN_STORE_GUIDE.md` -- Architecture: See `PLUGIN_ARCHITECTURE_SPEC.md` - +- Plugin Store user guide: [PLUGIN_STORE_GUIDE.md](PLUGIN_STORE_GUIDE.md) +- Plugin architecture (historical): [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) +- [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins) diff --git a/docs/PLUGIN_STORE_GUIDE.md b/docs/PLUGIN_STORE_GUIDE.md index fbec2a36..315c47fc 100644 --- a/docs/PLUGIN_STORE_GUIDE.md +++ b/docs/PLUGIN_STORE_GUIDE.md @@ -4,13 +4,22 @@ 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 Store → Search → Click Install +# 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" \ @@ -19,7 +28,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \ ### Install from GitHub URL ```bash -# Web UI: Plugin Store → "Install from URL" → Paste 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" \ @@ -57,7 +66,7 @@ The official plugin store contains curated, verified plugins that have been revi **Via Web Interface:** 1. Open the web interface at http://your-pi-ip:5000 -2. Navigate to the "Plugin Store" tab +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 @@ -74,7 +83,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \ ```python from src.plugin_system.store_manager import PluginStoreManager -store = PluginStoreManager() +store = PluginStoreManager(plugins_dir="plugin-repos") success = store.install_plugin('clock-simple') if success: print("Plugin installed!") @@ -90,10 +99,11 @@ Install any plugin directly from a GitHub repository, even if it's not in the of **Via Web Interface:** 1. Open the web interface -2. Navigate to the "Plugin Store" tab -3. Find the "Install from URL" section +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`) -5. Click "Install from URL" + and optionally a branch +5. Click "Install" 6. Review the warning about unverified plugins 7. Confirm installation 8. Wait for installation to complete @@ -110,7 +120,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/install-from-url \ ```python from src.plugin_system.store_manager import PluginStoreManager -store = PluginStoreManager() +store = PluginStoreManager(plugins_dir="plugin-repos") result = store.install_from_url('https://github.com/user/ledmatrix-my-plugin') if result['success']: @@ -144,7 +154,7 @@ curl "http://your-pi-ip:5000/api/v3/plugins/store/list?tags=nhl&tags=hockey" ```python from src.plugin_system.store_manager import PluginStoreManager -store = PluginStoreManager() +store = PluginStoreManager(plugins_dir="plugin-repos") # Search by query results = store.search_plugins(query="hockey") @@ -175,7 +185,7 @@ curl "http://your-pi-ip:5000/api/v3/plugins/installed" ```python from src.plugin_system.store_manager import PluginStoreManager -store = PluginStoreManager() +store = PluginStoreManager(plugins_dir="plugin-repos") installed = store.list_installed_plugins() for plugin_id in installed: @@ -216,7 +226,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/update \ ```python from src.plugin_system.store_manager import PluginStoreManager -store = PluginStoreManager() +store = PluginStoreManager(plugins_dir="plugin-repos") success = store.update_plugin('clock-simple') ``` @@ -239,7 +249,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \ ```python from src.plugin_system.store_manager import PluginStoreManager -store = PluginStoreManager() +store = PluginStoreManager(plugins_dir="plugin-repos") success = store.uninstall_plugin('clock-simple') ``` @@ -296,13 +306,17 @@ When installing from a custom GitHub URL, you'll see a warning about installing ### Plugin Won't Install -**Problem:** Installation fails with "Failed to clone or download repository" +**Problem:** Installation fails **Solutions:** -- Check that git is installed: `which git` +- 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 -- The system will automatically try ZIP download as fallback ### Plugin Won't Load @@ -410,10 +424,10 @@ As a plugin developer, you can share your plugin with others even before it's in 2. Share the URL with users 3. Users install via: - Open the LEDMatrix web interface - - Click "Plugin Store" tab - - Scroll to "Install from URL" + - Open the "Plugin Manager" tab + - Scroll to "Install from GitHub" → "Install Single Plugin" - Paste the URL - - Click "Install from URL" + - Click "Install" --- @@ -425,14 +439,14 @@ For advanced users, manage plugins via command line: # Install from registry python3 -c " from src.plugin_system.store_manager import PluginStoreManager -store = 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() +store = PluginStoreManager(plugins_dir='plugin-repos') result = store.install_from_url('https://github.com/user/plugin') print(result) " @@ -440,7 +454,7 @@ print(result) # List installed python3 -c " from src.plugin_system.store_manager import PluginStoreManager -store = PluginStoreManager() +store = PluginStoreManager(plugins_dir='plugin-repos') 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\")})') @@ -449,7 +463,7 @@ for plugin_id in store.list_installed_plugins(): # Uninstall python3 -c " from src.plugin_system.store_manager import PluginStoreManager -store = PluginStoreManager() +store = PluginStoreManager(plugins_dir='plugin-repos') store.uninstall_plugin('clock-simple') " ``` @@ -468,10 +482,17 @@ A: Yes, you can install anytime, but you must restart the display to load them. 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. +A: No, each plugin ID maps to a single installed copy. **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. +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. diff --git a/docs/plugin_registry_template.json b/docs/plugin_registry_template.json index 2f50a43d..989a3005 100644 --- a/docs/plugin_registry_template.json +++ b/docs/plugin_registry_template.json @@ -1,7 +1,6 @@ { "version": "1.0.0", - "last_updated": "2025-01-09T12:00:00Z", - "description": "Official plugin registry for LEDMatrix", + "last_updated": "2026-09-03", "plugins": [ { "id": "hello-world", @@ -10,86 +9,32 @@ "author": "ChuckBuilds", "category": "example", "tags": ["example", "tutorial", "beginner"], - "repo": "https://github.com/ChuckBuilds/LEDMatrix", + "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins", "branch": "main", - "path": "plugins/hello-world", - "versions": [ - { - "version": "1.0.0", - "ledmatrix_min_version": "2.0.0", - "released": "2025-01-09", - "download_url": "https://github.com/ChuckBuilds/LEDMatrix/archive/refs/heads/main.zip", - "changelog": "Initial release" - } - ], + "plugin_path": "plugins/hello-world", "stars": 0, "downloads": 0, - "last_updated": "2025-01-09", + "last_updated": "2026-09-03", "verified": true, - "documentation": "https://github.com/ChuckBuilds/LEDMatrix/blob/main/plugins/hello-world/README.md" + "screenshot": "", + "latest_version": "1.0.0" }, { - "id": "clock-simple", - "name": "Simple Clock", - "description": "A clean, simple clock display with date and time", - "author": "ChuckBuilds", - "category": "time", - "tags": ["clock", "time", "date"], - "repo": "https://github.com/ChuckBuilds/LEDMatrix", + "id": "my-third-party-plugin", + "name": "My Third-Party Plugin", + "description": "A plugin kept in its own repository (empty plugin_path)", + "author": "YourName", + "category": "custom", + "tags": ["example"], + "repo": "https://github.com/YourName/ledmatrix-my-third-party-plugin", "branch": "main", - "path": "plugins/clock-simple", - "versions": [ - { - "version": "1.0.0", - "ledmatrix_min_version": "2.0.0", - "released": "2025-01-09", - "download_url": "https://github.com/ChuckBuilds/LEDMatrix/archive/refs/heads/main.zip", - "changelog": "Initial release" - } - ], + "plugin_path": "", "stars": 0, "downloads": 0, - "last_updated": "2025-01-09", - "verified": true, - "documentation": "https://github.com/ChuckBuilds/LEDMatrix/blob/main/plugins/clock-simple/README.md" - } - ], - "categories": [ - { - "id": "time", - "name": "Time & Clocks", - "description": "Clock displays, timers, and time-related plugins" - }, - { - "id": "sports", - "name": "Sports", - "description": "Scoreboards, schedules, and sports statistics" - }, - { - "id": "weather", - "name": "Weather", - "description": "Weather forecasts and conditions" - }, - { - "id": "finance", - "name": "Finance", - "description": "Stock tickers, crypto, and market data" - }, - { - "id": "entertainment", - "name": "Entertainment", - "description": "Games, animations, and media displays" - }, - { - "id": "example", - "name": "Examples & Tutorials", - "description": "Example plugins for learning" - }, - { - "id": "custom", - "name": "Custom", - "description": "Unique and miscellaneous displays" + "last_updated": "2026-09-03", + "verified": false, + "screenshot": "", + "latest_version": "1.0.0" } ] } -