mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 21:03:01 +00:00

Files

Chuck 93e2d29af6 docs: fix .cursor/ helper docs

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>

2026-04-07 10:08:46 -04:00

plans

Plugins (#145 )

2025-12-27 14:15:49 -05:00

plugin_templates

docs: fix .cursor/ helper docs

2026-04-07 10:08:46 -04:00

rules

cursor rules (#87 )

2025-09-29 21:42:12 -04:00

plugins_guide.md

docs: fix .cursor/ helper docs

2026-04-07 10:08:46 -04:00

README.md

docs: fix .cursor/ helper docs

2026-04-07 10:08:46 -04:00

README.md

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

Using templates (recommended):

# 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

Using dev_plugin_setup.sh:

# 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

# 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

# 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:

Copy templates from .cursor/plugin_templates/
Replace placeholders (PLUGIN_ID, PluginClassName, etc.)
Customize for your plugin's needs
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

Plan: Determine plugin functionality and requirements
Create: Use templates or dev_plugin_setup.sh to create plugin structure
Develop: Implement plugin logic following BasePlugin interface
Test: Test with emulator first, then on hardware
Configure: Add plugin config to config/config.json
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 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

Check plugins_guide.md for detailed documentation
Review .cursorrules for development patterns
Look at existing plugins for examples
Check logs for error messages
Review plugin system code in src/plugin_system/