feat: LED-aware effects for multi-LED device support

[JnyJny]

Summary

Implements comprehensive LED targeting support for all effects, enabling precise control of individual LEDs on multi-LED devices like Blink1 mk2.

Key Features

✅ LED-Aware Effects System

• All effects (Steady, Blink, Spectrum, Gradient) support LED targeting
• LED parameter: 0=all LEDs (default), 1+=specific LED (1=top, 2=bottom)
• 100% backward compatible - existing code works unchanged

✅ Unified Architecture

• Enhanced BaseEffect.execute() with led parameter
• Removed special-case LED blink implementation
• Consistent LED support across all interfaces

✅ Complete API Coverage

• CLI: Added --led parameter to all effect commands (rainbow, pulse, fli)
• Web API: Added led query parameter to all effect endpoints
• Python API: Enhanced apply_effect() with LED targeting

✅ Multi-LED Device Support

• Works with Blink1 mk2 (2 LEDs), Luxafor Flag (multiple LEDs)
• Safe fallback for single-LED devices (LED parameter ignored)
• LED convention: 1=first/top, 2=second/bottom, 3+=additional

Usage Examples

CLI:

busylight rainbow --led 1         # Rainbow on top LED only
busylight pulse red --led 2       # Pulse bottom LED only
busylight blink green --led 1 --count 3  # Blink top LED 3 times

Web API:

curl "http://localhost:8000/lights/rainbow?led=1"
curl "http://localhost:8000/lights/pulse?color=red&led=2"

Python API:

with LightController() as controller:
    controller.all().apply_effect(Spectrum(), led=1)      # Top LED rainbow
    controller.all().apply_effect(Gradient((255, 0, 0)), led=2)  # Bottom LED pulse

Testing & Documentation

✅ Comprehensive Testing

• 14 new LED-aware effect tests covering all functionality
• All existing tests pass - no regressions
• Backward compatibility verified

✅ Enhanced Documentation

• Updated effects guide with LED targeting examples
• Enhanced CLI examples with multi-LED patterns
• Added comprehensive migration guide
• Updated README with LED targeting examples

Technical Details

Files Changed:

• Core effects system: BaseEffect.execute() enhanced with LED parameter
• All built-in effects updated for LED awareness
• CLI commands: rainbow.py, pulse.py, fli.py enhanced
• Web API: All effect endpoints support LED parameter
• Controller: Unified LED handling, removed special cases

Device Compatibility:

• Multi-LED: Blink1 mk2, BlinkStick, Luxafor Flag, etc.
• Single-LED: Blynclight Plus, MuteMe Original, fit-statUSB (LED parameter ignored safely)

Creative Possibilities

This enhancement enables:

• Split LED Effects: Different colors/effects on different LEDs simultaneously
• Sequential Programming: Program LEDs one by one with different patterns
• Complex Patterns: Alternating effects, synchronized different effects
• Enhanced Status Systems: Use different LEDs for different status indicators

Test plan

• Verify all existing functionality works unchanged (backward compatibility)
• Test LED targeting with multi-LED devices (Blink1 mk2 if available)
• Confirm single-LED devices safely ignore LED parameter
• Validate CLI commands accept --led parameter for all effects
• Check Web API endpoints accept led query parameter
• Run comprehensive test suite to ensure no regressions

🤖 Generated with Claude Code

[github-actions]

📚 Documentation Preview

The documentation has been built successfully for this PR.

Changes detected in:

• Documentation files (docs/)
• MkDocs configuration (mkdocs.yml)

Build status: ✅ Success

The documentation will be automatically deployed to GitHub Pages when this PR is merged to master.

---

_{Generated by docs workflow}