mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-11 21:33:00 +00:00
93e2d29af6
The .cursor/ directory holds the dev-side helper docs that Cursor and
contributors using AI tooling rely on to bootstrap plugin development.
Several of them had the same bug patterns as the user-facing docs.
.cursor/plugin_templates/QUICK_START.md
- "Adding Image Rendering" section showed
display_manager.draw_image(image, x=0, y=0). That method doesn't
exist on DisplayManager (same bug as PLUGIN_API_REFERENCE.md and
PLUGIN_DEVELOPMENT_GUIDE.md). Replaced with the canonical
display_manager.image.paste((x,y)) pattern, including the
transparency-mask form.
.cursor/plugins_guide.md
- 10 occurrences of ./dev_plugin_setup.sh — the script lives at
scripts/dev/dev_plugin_setup.sh, so anyone copy-pasting these
examples gets "command not found". Bulk fixed via sed.
- "Test with emulator: python run.py --emulator" — there's no
--emulator flag. Replaced with the real options:
EMULATOR=true python3 run.py for the full display, or
scripts/dev_server.py for the dev preview.
- Secrets management section showed a fictional
"config_secrets": { "api_key": "my-plugin.api_key" } reference
field. Verified in src/config_manager.py:162-172 that secrets are
loaded by deep-merging config_secrets.json into the main config.
There is no separate reference field — just put the secret under
the same plugin namespace and read it from the merged config.
Rewrote the section with the real pattern.
- "ssh pi@raspberrypi" -> "ssh ledpi@your-pi-ip" (consistent with
the rest of LEDMatrix docs which use ledpi as the default user)
.cursor/README.md
- Same ./dev_plugin_setup.sh -> ./scripts/dev/dev_plugin_setup.sh
fix (×6 occurrences via replace_all).
- Same "python run.py --emulator" -> "EMULATOR=true python3 run.py"
fix. Also added a pointer to scripts/dev_server.py for previewing
plugins without running the full display.
- "Example Plugins: plugins/hockey-scoreboard/" — the canonical
source is the ledmatrix-plugins repo. Installed copies land in
plugin-repos/ or plugins/. Updated the line to point at the
ledmatrix-plugins repo and explain both local locations.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
144 lines
4.2 KiB
Markdown
144 lines
4.2 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)
|
|
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
|
|
```
|
|
|
|
There is no `--emulator` flag — the emulator is selected via the
|
|
`EMULATOR=true` environment variable, which `src/display_manager.py:2`
|
|
checks at import time.
|
|
|
|
### 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/`
|
|
|