rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-10-10 17:16:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(store): describe the monorepo registry and the store UI as they are

Browse Source 
- PLUGIN_STORE_GUIDE: the Plugin Store is a section of the Plugin
  Manager tab; URL installs are "Install from GitHub" -> "Install Single
  Plugin"; bulk update exists (Check & Update All) plus opt-in weekly
  auto-update; PluginStoreManager() defaults to plugins/, so the Python
  examples pass plugin-repos; registry plugins are downloaded (GitHub API,
  ZIP fallback), not cloned; updates compare version with latest_version.
- PLUGIN_REGISTRY_SETUP_GUIDE: replace the per-plugin-repo + tag
  walkthrough with a short page on the monorepo registry (plugin_path,
  latest_version, update_registry.py) that points at the monorepo's own
  SUBMISSION.md. Drops the reference to the deleted
  PLUGIN_IMPLEMENTATION_SUMMARY.md and setup_plugin_repos.py.
- plugin_registry_template.json: use the real entry shape.
- PLUGIN_QUICK_REFERENCE: automatic background updates exist (opt-in);
  registry example and publishing steps use the monorepo, not tags.
- PLUGIN_DEVELOPMENT_GUIDE: tags/releases are not read by the store.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Chuck
2026-09-22 16:24:47 -04:00
co-authored by Claude Opus 5.5
parent 698807cc62
commit db131e811b
5 changed files with 165 additions and 507 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PLUGIN_DEVELOPMENT_GUIDE.md
+4 -2
View File
@@ -660,7 +660,8 @@ To have your plugin added to the official plugin store:
For your plugin to work well in the plugin store: For your plugin to work well in the plugin store:
- **GitHub repository**: Must be publicly accessible on GitHub - **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 - **README.md**: Clear installation and configuration instructions
- **config_schema.json**: Recommended for web UI configuration - **config_schema.json**: Recommended for web UI configuration
- **manifest.json**: Required with all required fields - **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): 1. **Official Registry** (Recommended):
- Listed in default plugin store - 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 - Verified badge
- Requires approval - Requires approval
docs/PLUGIN_QUICK_REFERENCE.md
+20 -24
View File
@@ -99,20 +99,13 @@ class MyPlugin(BasePlugin):
### 3. Publishing ### 3. Publishing
```bash Official plugins live in the
# Create repo [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins)
git init monorepo: add `plugins/<your-plugin-id>/`, bump `version` in its
git add . `manifest.json` on every change, run `python update_registry.py` there and
git commit -m "Initial commit" open a pull request. A third-party plugin can stay in its own repository and
git remote add origin https://github.com/YourName/ledmatrix-my-plugin be installed by URL. Git tags and releases are not read by the store; see
git push -u origin main [PLUGIN_REGISTRY_SETUP_GUIDE.md](PLUGIN_REGISTRY_SETUP_GUIDE.md).
# Tag release
git tag v1.0.0
git push origin v1.0.0
# Submit to registry (PR to ChuckBuilds/ledmatrix-plugins)
```
## Using Plugins ## Using Plugins
@@ -166,20 +159,20 @@ follows this shape:
"name": "Simple Clock", "name": "Simple Clock",
"author": "ChuckBuilds", "author": "ChuckBuilds",
"category": "time", "category": "time",
"repo": "https://github.com/ChuckBuilds/ledmatrix-clock-simple", "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins",
"versions": [ "branch": "main",
{ "plugin_path": "plugins/clock-simple",
"version": "1.0.0", "latest_version": "1.0.0",
"ledmatrix_min_version": "2.0.0",
"download_url": "https://github.com/.../v1.0.0.zip"
}
],
"verified": true "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 ## Benefits
### For Users ### For Users
@@ -212,8 +205,11 @@ intentionally simple:
slow plugins, but no hard CPU/memory caps. slow plugins, but no hard CPU/memory caps.
3. **Plugin ratings**: not yet — the Plugin Store shows version, 3. **Plugin ratings**: not yet — the Plugin Store shows version,
author, and category but no community rating system. author, and category but no community rating system.
4. **Auto-updates**: manual via the Plugin Manager tab; no automatic 4. **Auto-updates**: off by default. Update from the Plugin Manager tab
background updates. (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 5. **Dependency conflicts**: each plugin's `requirements.txt` is
installed via pip; conflicting versions across plugins are not installed via pip; conflicting versions across plugins are not
resolved automatically. resolved automatically.
docs/PLUGIN_REGISTRY_SETUP_GUIDE.md
+78 -384
View File
@@ -1,415 +1,109 @@
# Plugin Registry Setup Guide # 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. ```text
## Repository Structure
```
ledmatrix-plugins/ ledmatrix-plugins/
├── README.md # Main documentation ├── plugins/
├── LICENSE # GPL-3.0 │ ├── clock-simple/ # one directory per official plugin
├── plugins.json # The registry file (main file!) │ │ ├── manifest.json # source of truth for the plugin's version
├── SUBMISSION.md # Guidelines for submitting plugins │ │ ├── manager.py
├── VERIFICATION.md # Verification checklist │ │ ├── config_schema.json
└── assets/ # Optional: screenshots, badges │ │ └── requirements.txt
└── screenshots/ │ └── ...
├── 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/<id>`). 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. ## A registry entry
**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`
```json ```json
{ {
"last_updated": "2025-01-09T12:00:00Z", "id": "clock-simple",
"plugins": [ "name": "Simple Clock",
{ "description": "A clean, simple clock display with date and time",
"id": "clock-simple", "author": "ChuckBuilds",
"name": "Simple Clock", "category": "time",
"description": "A clean, simple clock display with date and time", "tags": ["clock", "time", "date"],
"author": "ChuckBuilds", "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins",
"category": "time", "branch": "main",
"tags": ["clock", "time", "date"], "plugin_path": "plugins/clock-simple",
"repo": "https://github.com/ChuckBuilds/ledmatrix-clock-simple", "stars": 0,
"branch": "main", "downloads": 0,
"stars": 12, "last_updated": "2026-09-03",
"downloads": 156, "verified": true,
"last_updated": "2025-01-09", "screenshot": "",
"last_commit": "abc1234", "latest_version": "1.0.0"
"verified": true,
"screenshot": "https://raw.githubusercontent.com/ChuckBuilds/ledmatrix-plugins/main/assets/screenshots/clock-simple.png"
}
]
} }
``` ```
**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/<your-plugin-id>/` 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` ## Adding a third-party plugin
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
## 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: ## Testing locally
```markdown
# LEDMatrix Official Plugins
Official plugin registry for [LEDMatrix](https://github.com/ChuckBuilds/LEDMatrix).
## Available Plugins
<!-- This table is auto-generated from plugins.json -->
| 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
```bash ```bash
# 1. Create plugin in separate repo # Validate a plugin headlessly (from LEDMatrix)
mkdir ledmatrix-clock-simple python3 scripts/check_plugin.py --plugin <id>
cd ledmatrix-clock-simple
# ... create plugin files ...
# 2. Push to GitHub # Fetch the registry the way the store does
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 <plugin-id>
```
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
python3 -c " python3 -c "
from src.plugin_system.store_manager import PluginStoreManager from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager() store = PluginStoreManager(plugins_dir='plugin-repos')
registry = store.fetch_registry() print(len(store.fetch_registry(force_refresh=True).get('plugins', [])), 'plugins')
print(f'Found {len(registry[\"plugins\"])} plugins')
" "
``` ```
## Benefits of This Setup To work on monorepo plugins against a LEDMatrix checkout, see
[MULTI_ROOT_WORKSPACE_SETUP.md](MULTI_ROOT_WORKSPACE_SETUP.md) and the
✅ **Centralized Discovery**: One place to find all official plugins [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md).
✅ **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!
## References ## References
- Plugin Store Implementation: See `PLUGIN_IMPLEMENTATION_SUMMARY.md` - Plugin Store user guide: [PLUGIN_STORE_GUIDE.md](PLUGIN_STORE_GUIDE.md)
- User Guide: See `PLUGIN_STORE_GUIDE.md` - Plugin architecture (historical): [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md)
- Architecture: See `PLUGIN_ARCHITECTURE_SPEC.md` - [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins)
docs/PLUGIN_STORE_GUIDE.md
+45 -24
View File
@@ -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. 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 ## Quick Reference
### Install from Store ### Install from Store
```bash ```bash
# Web UI: Plugin Store → Search → Click Install # Web UI: Plugin Manager → Plugin Store section → Search → Click Install
# API: # API:
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \ curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
-H "Content-Type: application/json" \ -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 ### Install from GitHub URL
```bash ```bash
# Web UI: Plugin Store → "Install from URL" → Paste URL # Web UI: Plugin Manager → Install from GitHub → "Install Single Plugin" → Paste URL
# API: # API:
curl -X POST http://your-pi-ip:5000/api/v3/plugins/install-from-url \ curl -X POST http://your-pi-ip:5000/api/v3/plugins/install-from-url \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
@@ -57,7 +66,7 @@ The official plugin store contains curated, verified plugins that have been revi
**Via Web Interface:** **Via Web Interface:**
1. Open the web interface at http://your-pi-ip:5000 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 3. Browse or search for plugins
4. Click "Install" on the desired plugin 4. Click "Install" on the desired plugin
5. Wait for installation to complete 5. Wait for installation to complete
@@ -74,7 +83,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/install \
```python ```python
from src.plugin_system.store_manager import PluginStoreManager from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager() store = PluginStoreManager(plugins_dir="plugin-repos")
success = store.install_plugin('clock-simple') success = store.install_plugin('clock-simple')
if success: if success:
print("Plugin installed!") 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:** **Via Web Interface:**
1. Open the web interface 1. Open the web interface
2. Navigate to the "Plugin Store" tab 2. Navigate to the "Plugin Manager" tab
3. Find the "Install from URL" section 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`) 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 6. Review the warning about unverified plugins
7. Confirm installation 7. Confirm installation
8. Wait for installation to complete 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 ```python
from src.plugin_system.store_manager import PluginStoreManager 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') result = store.install_from_url('https://github.com/user/ledmatrix-my-plugin')
if result['success']: if result['success']:
@@ -144,7 +154,7 @@ curl "http://your-pi-ip:5000/api/v3/plugins/store/list?tags=nhl&tags=hockey"
```python ```python
from src.plugin_system.store_manager import PluginStoreManager from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager() store = PluginStoreManager(plugins_dir="plugin-repos")
# Search by query # Search by query
results = store.search_plugins(query="hockey") results = store.search_plugins(query="hockey")
@@ -175,7 +185,7 @@ curl "http://your-pi-ip:5000/api/v3/plugins/installed"
```python ```python
from src.plugin_system.store_manager import PluginStoreManager from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager() store = PluginStoreManager(plugins_dir="plugin-repos")
installed = store.list_installed_plugins() installed = store.list_installed_plugins()
for plugin_id in installed: for plugin_id in installed:
@@ -216,7 +226,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/update \
```python ```python
from src.plugin_system.store_manager import PluginStoreManager from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager() store = PluginStoreManager(plugins_dir="plugin-repos")
success = store.update_plugin('clock-simple') success = store.update_plugin('clock-simple')
``` ```
@@ -239,7 +249,7 @@ curl -X POST http://your-pi-ip:5000/api/v3/plugins/uninstall \
```python ```python
from src.plugin_system.store_manager import PluginStoreManager from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager() store = PluginStoreManager(plugins_dir="plugin-repos")
success = store.uninstall_plugin('clock-simple') 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 ### Plugin Won't Install
**Problem:** Installation fails with "Failed to clone or download repository" **Problem:** Installation fails
**Solutions:** **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 - Verify the GitHub URL is correct
- Check your internet connection - Check your internet connection
- The system will automatically try ZIP download as fallback
### Plugin Won't Load ### 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 2. Share the URL with users
3. Users install via: 3. Users install via:
- Open the LEDMatrix web interface - Open the LEDMatrix web interface
- Click "Plugin Store" tab - Open the "Plugin Manager" tab
- Scroll to "Install from URL" - Scroll to "Install from GitHub" → "Install Single Plugin"
- Paste the URL - Paste the URL
- Click "Install from URL" - Click "Install"
--- ---
@@ -425,14 +439,14 @@ For advanced users, manage plugins via command line:
# Install from registry # Install from registry
python3 -c " python3 -c "
from src.plugin_system.store_manager import PluginStoreManager from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager() store = PluginStoreManager(plugins_dir='plugin-repos')
store.install_plugin('clock-simple') store.install_plugin('clock-simple')
" "
# Install from URL # Install from URL
python3 -c " python3 -c "
from src.plugin_system.store_manager import PluginStoreManager 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') result = store.install_from_url('https://github.com/user/plugin')
print(result) print(result)
" "
@@ -440,7 +454,7 @@ print(result)
# List installed # List installed
python3 -c " python3 -c "
from src.plugin_system.store_manager import PluginStoreManager from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager() store = PluginStoreManager(plugins_dir='plugin-repos')
for plugin_id in store.list_installed_plugins(): for plugin_id in store.list_installed_plugins():
info = store.get_installed_plugin_info(plugin_id) info = store.get_installed_plugin_info(plugin_id)
print(f'{plugin_id}: {info[\"name\"]} (Last updated: {info.get(\"last_updated\", \"unknown\")})') 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 # Uninstall
python3 -c " python3 -c "
from src.plugin_system.store_manager import PluginStoreManager from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager() store = PluginStoreManager(plugins_dir='plugin-repos')
store.uninstall_plugin('clock-simple') 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. A: The existing copy will be replaced with the latest code from the repository.
**Q: Can I install multiple versions of the same plugin?** **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?** **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?** **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. A: Yes, if a plugin needs API keys, it can access them like core managers do.
docs/plugin_registry_template.json
+18 -73
View File
@@ -1,7 +1,6 @@
{ {
"version": "1.0.0", "version": "1.0.0",
"last_updated": "2025-01-09T12:00:00Z", "last_updated": "2026-09-03",
"description": "Official plugin registry for LEDMatrix",
"plugins": [ "plugins": [
{ {
"id": "hello-world", "id": "hello-world",
@@ -10,86 +9,32 @@
"author": "ChuckBuilds", "author": "ChuckBuilds",
"category": "example", "category": "example",
"tags": ["example", "tutorial", "beginner"], "tags": ["example", "tutorial", "beginner"],
"repo": "https://github.com/ChuckBuilds/LEDMatrix", "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins",
"branch": "main", "branch": "main",
"path": "plugins/hello-world", "plugin_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"
}
],
"stars": 0, "stars": 0,
"downloads": 0, "downloads": 0,
"last_updated": "2025-01-09", "last_updated": "2026-09-03",
"verified": true, "verified": true,
"documentation": "https://github.com/ChuckBuilds/LEDMatrix/blob/main/plugins/hello-world/README.md" "screenshot": "",
"latest_version": "1.0.0"
}, },
{ {
"id": "clock-simple", "id": "my-third-party-plugin",
"name": "Simple Clock", "name": "My Third-Party Plugin",
"description": "A clean, simple clock display with date and time", "description": "A plugin kept in its own repository (empty plugin_path)",
"author": "ChuckBuilds", "author": "YourName",
"category": "time", "category": "custom",
"tags": ["clock", "time", "date"], "tags": ["example"],
"repo": "https://github.com/ChuckBuilds/LEDMatrix", "repo": "https://github.com/YourName/ledmatrix-my-third-party-plugin",
"branch": "main", "branch": "main",
"path": "plugins/clock-simple", "plugin_path": "",
"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"
}
],
"stars": 0, "stars": 0,
"downloads": 0, "downloads": 0,
"last_updated": "2025-01-09", "last_updated": "2026-09-03",
"verified": true, "verified": false,
"documentation": "https://github.com/ChuckBuilds/LEDMatrix/blob/main/plugins/clock-simple/README.md" "screenshot": "",
} "latest_version": "1.0.0"
],
"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"
} }
] ]
} }