Add led-matrix-painter

[BeanRepo]

LED Matrix Tool - Interactive Frame Designer & Animation Player

Overview

Complete LED Matrix designer application for Arduino UNO R4 WiFi/UNO Q boards, featuring real-time frame editing, persistent storage, animation playback, and C header export. The backend is production-ready with comprehensive logging and error handling. The frontend provides functional but minimal UI.

---

File Structure

extras/R3/led-matrix-painter/
├── python/
│   ├── main.py           # FastAPI endpoints, animation logic
│   ├── store.py          # SQLite persistence layer
│   └── app_frame.py      # Extended Frame with animation support
├── sketch/
│   └── sketch.ino        # Arduino sketch with Bridge RPC providers
├── assets/
│   ├── app.js            # Frontend logic
│   ├── index.html        # UI structure
│   └── style.css         # Minimal styling
├── data/
│   └── dbstorage_sqlstore/  # SQLite database
├── app.yaml              # App metadata
└── README.md             # Usage instructions

Backend Implementation (Python)

Core Architecture

• WebUI and SQLStore Bricks used
• arduino.app_utils (Frame, FrameDesigner, Bridge, WebUI) used
• Added AppFrame subclass that inherits Frame definition with serialiazation methods for frontend and DB

Key Components

1. Frame Management (python/main.py)

Unified Persist Architecture:

• Single 150ms debounced operation updates both board and database atomically
• Backend-controlled progressive naming: Frame1, Frame2, etc.

API Endpoints:

POST /persist_frame      # Create/update frame (auto-naming, unified persist)
POST /load_frame         # Load frame for editing or create empty
GET  /list_frames        # List all frames ordered by position
POST /delete_frame       # Delete with edge case handling
POST /reorder_frames     # Update positions via drag & drop
POST /transform_frame    # Apply operations (invert, rotate, flip)
POST /export_frames      # Export as C header (frames or animations)
POST /play_animation     # Play animation sequence on board
GET  /config             # Runtime configuration

2. Storage Layer (python/store.py)

Backend-Controlled Naming:

def save_frame(frame: AppFrame) -> int:
    """
    Assigns progressive 'Frame{id}' name if empty.
    Backend is sole authority for frame naming.
    """

Database Schema:

CREATE TABLE frames (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    rows TEXT NOT NULL,              -- JSON: [[brightness,...], ...]
    duration_ms INTEGER DEFAULT 1000,
    position INTEGER,
    brightness_levels INTEGER DEFAULT 8
)

3. Transform Operations (python/main.py)

Uses FrameDesigner from arduino.app_utils:

• Invert: 255 - brightness
• Invert non-null: Inverts only lit pixels
• Rotate 180°: Full rotation
• Flip Horizontal/Vertical: Mirror operations

Frontend triggers transforms → backend applies → returns transformed frame → frontend persists.

4. Export System (python/main.py)

Dual-Mode Export:

Frames Mode (individual arrays):

// Frame1 (id 1)
const uint8_t Frame1[] = {
    255, 128, 64, ...  // 104 bytes (12×8 grayscale)
};

Animations Mode (sequences):

// Animation: HeartBeat
const uint32_t HeartBeat[][5] = {
    {0x12345678, 0x9ABCDEF0, 0x11223344, 0x55667788, 1000},  // Frame1, 1000ms
    {0xAABBCCDD, 0xEEFF0011, 0x22334455, 0x66778899, 500},   // Frame2, 500ms
};

5. AppFrame Extension (python/app_frame.py)

Extends base Frame class with animation support:

class AppFrame(Frame):
    def to_animation_hex(self) -> list[str]:
        """
        Converts frame to Arduino_LED_Matrix animation format.
        Returns: [pixel0_hex, pixel1_hex, pixel2_hex, pixel3_hex, duration_hex]
        """
        # Rescale brightness 0-7 → 0-255
        # Pack 104 pixels into 128 bits (4×32-bit words)
        # Append duration_ms as 5th value
        return ['0x12345678', '0x9ABCDEF0', '0x11223344', '0x55667788', '0x000003E8']
    
    def to_c_string(self) -> str:
        """Exports frame as C uint8_t array."""

Frontend (Functional UI)

Technology: Vanilla JavaScript + HTML/CSS

Features:

• 13×8 grid editor with brightness slider (0-7)
• Auto-persist: 150ms debounced
• Frame list with drag & drop reordering
• Mode toggle: Frames / Animations
• Transform buttons: Clear, Invert, Rotate, Flip
• Export button: Downloads .h file
• Play Animation button: Triggers board playback

---

[CLAassistant]

All committers have signed the CLA.