mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-10 21:03:01 +00:00
eba2d4a711
Reviewed all 12 CodeRabbit comments on PR #306, verified each against the current code, and fixed the 11 valid ones. The 12th finding is a real code bug (cache_manager.delete() calls in api_helper.py and resource_monitor.py) that's already in the planned follow-up code-fix PR, so it stays out of this docs PR. Fixed: .cursor/plugins_guide.md, .cursor/README.md, .cursorrules - I claimed "there is no --emulator flag" in 3 places. Verified in run.py:19-20 that the -e/--emulator flag is defined and functional (it sets os.environ["EMULATOR"]="true" before the display imports). Other docs I didn't touch (.cursor/plugin_templates/QUICK_START.md, docs/PLUGIN_DEVELOPMENT_GUIDE.md) already use the flag correctly. Replaced all 3 wrong statements with accurate guidance that both forms work and explains the CLI flag's relationship to the env var. .cursorrules, docs/GETTING_STARTED.md, docs/WEB_INTERFACE_GUIDE.md, docs/PLUGIN_DEVELOPMENT_GUIDE.md - Four places claimed "the plugin loader also falls back to plugins/". Verified that PluginManager.discover_plugins() (src/plugin_system/plugin_manager.py:154) only scans the configured directory — no fallback. The fallback to plugins/ exists only in two narrower places: store_manager.py:1700-1718 (store install/update/uninstall operations) and schema_manager.py:70-80 (schema lookup for the web UI form generator). Rewrote all four mentions with the precise scope. Added a recommendation to set plugin_system.plugins_directory to "plugins" for the smoothest dev workflow with dev_plugin_setup.sh symlinks. docs/FONT_MANAGER.md - The "Status" warning told plugin authors to use display_manager.font_manager.resolve_font(...) as a workaround for loading plugin fonts. Verified in src/font_manager.py that resolve_font() takes a family name, not a file path — so the workaround as written doesn't actually work. Rewrote to tell authors to load the font directly with PIL or freetype-py in their plugin. - The same section said "the user-facing font override system in the Fonts tab still works for any element that's been registered via register_manager_font()". Verified in web_interface/blueprints/api_v3.py:5404-5428 that /api/v3/fonts/overrides is a placeholder implementation that returns empty arrays and contains "would integrate with the actual font system" comments — the Fonts tab does not have functional integration with register_manager_font() or the override system. Removed the false claim and added an explicit note that the tab is a placeholder. docs/ADVANCED_FEATURES.md:523 - The on-demand section said REST/UI calls write a request "into the cache manager (display_on_demand_config key)". Wrong — verified via grep that api_v3.py:1622 and :1687 write to display_on_demand_request, and display_on_demand_config is only written by the controller during activation (display_controller.py:1195, cleared at :1221). Corrected the key name and added controller file:line references so future readers can verify. docs/ADVANCED_FEATURES.md:803 - "Plugins using the background service" paragraph listed all scoreboard plugins but an orphaned "⏳ MLB (baseball)" bullet remained below from the old version of the section. Removed the orphan and added "baseball/MLB" to the inline list for clarity. web_interface/README.md - The POST /api/v3/system/action action list was incomplete. Verified in web_interface/app.py:1383,1386 that enable_autostart and disable_autostart are valid actions. Added both. - The Plugin Store section was missing GET /api/v3/plugins/store/github-status (verified at api_v3.py:3296). Added it. - The SSE line-range reference was app.py:607-615 but line 619 contains the "Exempt SSE streams from CSRF and add rate limiting" block that's semantically part of the same feature. Extended the range to 607-619. docs/GETTING_STARTED.md - Rows/Columns step said "Columns: 64 or 96 (match your hardware)". The web UI's validation accepts any integer in 16-128. Clarified that 64 and 96 are the common bundled-hardware values but the valid range is wider. Not addressed (out of scope for docs PR): - .cursorrules:184 CodeRabbit comment flagged the non-existent cache_manager.delete() calls in src/common/api_helper.py:287 and src/plugin_system/resource_monitor.py:343. These are real CODE bugs, not doc bugs, and they're the first item in the planned post-docs-refresh code-cleanup PR (see /home/chuck/.claude/plans/warm-imagining-river.md). The docs in this PR correctly state that delete() doesn't exist on CacheManager — the fix belongs in the follow-up code PR that either adds a delete() shim or updates the two callers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
146 lines
4.3 KiB
Markdown
146 lines
4.3 KiB
Markdown
# Cursor Helper Files for LEDMatrix Plugin Development
|
|
|
|
This directory contains Cursor-specific helper files to assist with plugin development in the LEDMatrix project.
|
|
|
|
## Files Overview
|
|
|
|
### `.cursorrules`
|
|
Comprehensive rules file that Cursor uses to understand plugin development patterns, best practices, and workflows. This file is automatically loaded by Cursor and helps guide AI-assisted development.
|
|
|
|
### `plugins_guide.md`
|
|
Detailed guide covering:
|
|
- Plugin system overview
|
|
- Creating new plugins
|
|
- Running plugins (emulator and hardware)
|
|
- Loading and configuring plugins
|
|
- Development workflow
|
|
- Testing strategies
|
|
- Troubleshooting
|
|
|
|
### `plugin_templates/`
|
|
Template files for quick plugin creation:
|
|
- `manifest.json.template` - Plugin metadata template
|
|
- `manager.py.template` - Plugin class template
|
|
- `config_schema.json.template` - Configuration schema template
|
|
- `README.md.template` - Plugin documentation template
|
|
- `requirements.txt.template` - Dependencies template
|
|
- `QUICK_START.md` - Quick start guide for using templates
|
|
|
|
## Quick Reference
|
|
|
|
### Creating a New Plugin
|
|
|
|
1. **Using templates** (recommended):
|
|
```bash
|
|
# See QUICK_START.md in plugin_templates/
|
|
cd plugins
|
|
mkdir my-plugin
|
|
cd my-plugin
|
|
cp ../../.cursor/plugin_templates/*.template .
|
|
# Edit files, replacing PLUGIN_ID and other placeholders
|
|
```
|
|
|
|
2. **Using dev_plugin_setup.sh**:
|
|
```bash
|
|
# Link from GitHub
|
|
./scripts/dev/dev_plugin_setup.sh link-github my-plugin
|
|
|
|
# Link local repo
|
|
./scripts/dev/dev_plugin_setup.sh link my-plugin /path/to/repo
|
|
```
|
|
|
|
### Running the Display
|
|
|
|
```bash
|
|
# Emulator mode (development, no hardware required)
|
|
python3 run.py --emulator
|
|
# (equivalent: EMULATOR=true python3 run.py)
|
|
|
|
# Hardware (production, requires the rpi-rgb-led-matrix submodule built)
|
|
python3 run.py
|
|
|
|
# As a systemd service
|
|
sudo systemctl start ledmatrix
|
|
|
|
# Dev preview server (renders plugins to a browser without running run.py)
|
|
python3 scripts/dev_server.py # then open http://localhost:5001
|
|
```
|
|
|
|
The `-e`/`--emulator` CLI flag is defined in `run.py:19-20` and
|
|
sets `os.environ["EMULATOR"] = "true"` before any display imports,
|
|
which `src/display_manager.py:2` then reads to switch between the
|
|
hardware and emulator backends.
|
|
|
|
### Managing Plugins
|
|
|
|
```bash
|
|
# List plugins
|
|
./scripts/dev/dev_plugin_setup.sh list
|
|
|
|
# Check status
|
|
./scripts/dev/dev_plugin_setup.sh status
|
|
|
|
# Update plugin(s)
|
|
./scripts/dev/dev_plugin_setup.sh update [plugin-name]
|
|
|
|
# Unlink plugin
|
|
./scripts/dev/dev_plugin_setup.sh unlink <plugin-name>
|
|
```
|
|
|
|
## Using These Files with Cursor
|
|
|
|
### `.cursorrules`
|
|
Cursor automatically reads this file to understand:
|
|
- Plugin structure and requirements
|
|
- Development workflows
|
|
- Best practices
|
|
- Common patterns
|
|
- API reference
|
|
|
|
When asking Cursor to help with plugins, it will use this context to provide better assistance.
|
|
|
|
### Plugin Templates
|
|
Use templates when creating new plugins:
|
|
1. Copy templates from `.cursor/plugin_templates/`
|
|
2. Replace placeholders (PLUGIN_ID, PluginClassName, etc.)
|
|
3. Customize for your plugin's needs
|
|
4. Follow the guide in `plugins_guide.md`
|
|
|
|
### Documentation
|
|
Refer to `plugins_guide.md` for:
|
|
- Detailed explanations
|
|
- Troubleshooting steps
|
|
- Best practices
|
|
- Examples and patterns
|
|
|
|
## Plugin Development Workflow
|
|
|
|
1. **Plan**: Determine plugin functionality and requirements
|
|
2. **Create**: Use templates or dev_plugin_setup.sh to create plugin structure
|
|
3. **Develop**: Implement plugin logic following BasePlugin interface
|
|
4. **Test**: Test with emulator first, then on hardware
|
|
5. **Configure**: Add plugin config to config/config.json
|
|
6. **Iterate**: Refine based on testing and feedback
|
|
|
|
## Resources
|
|
|
|
- **Plugin System**: `src/plugin_system/`
|
|
- **Base Plugin**: `src/plugin_system/base_plugin.py`
|
|
- **Plugin Manager**: `src/plugin_system/plugin_manager.py`
|
|
- **Example Plugins**: see the
|
|
[`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
|
|
repo for canonical sources (e.g. `plugins/hockey-scoreboard/`,
|
|
`plugins/football-scoreboard/`). Installed plugins land in
|
|
`plugin-repos/` (default) or `plugins/` (dev fallback).
|
|
- **Architecture Docs**: `docs/PLUGIN_ARCHITECTURE_SPEC.md`
|
|
- **Development Setup**: `scripts/dev/dev_plugin_setup.sh`
|
|
|
|
## Getting Help
|
|
|
|
1. Check `plugins_guide.md` for detailed documentation
|
|
2. Review `.cursorrules` for development patterns
|
|
3. Look at existing plugins for examples
|
|
4. Check logs for error messages
|
|
5. Review plugin system code in `src/plugin_system/`
|
|
|