LedCubePCB

┌──────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
│  PATTERN ENGINE  │    │  LED CONTROLLER     │    │  PHYSICAL LEDS   │
│                  │    │                     │    │                  │
│ • Animation Gen  │────▶• Pixel Mapping     │────▶• RGB Addressable │
│ • Color Calc     │    │ • SPI/Data Driver  │    │   Output         │
│ • Timing Logic   │    │ • Brightness PWM   │    │                  │
└──────────────────┘    └─────────────────────┘    └──────────────────┘

// Manages frame buffer and multiplexed LED display output
class LEDCube {
    // Frame buffer operations
    setLED(layer, col, on);              // Set individual LED
    setLayer(layer, mask);               // Set entire layer
    clearFrame();                        // Clear all LEDs
    fillAll();                           // Turn on all LEDs
    
    // Display operations
    refresh();                           // Perform one refresh cycle
    Button::Event refreshFor(ms);        // Refresh with button polling
    
    // Button access
    Button& button();                    // Get button object
}

// Contains 12 distinct animation methods
class Animator {
    // Each returns Button::Event to signal button press
    Button::Event allOn();               // Fill entire cube
    Button::Event layerSweep();          // Sweep through layers
    Button::Event rain();                // Falling particles
    Button::Event bounceBall();          // Bouncing sphere
    Button::Event spiral();              // Spiral pattern
    Button::Event checkerboard();        // Alternating pattern
    Button::Event sparkle();             // Random twinkling
    Button::Event wipe();                // Progressive wipe
    Button::Event propeller();           // Rotating blades
    Button::Event snake();               // Snake movement
    Button::Event firework();            // Explosion effect
    Button::Event allOff();              // Turn off all
}

// Manages animation dispatch and button-triggered switching
class AnimationManager {
    void run();                          // Main loop - runs animations
    void flashIndex();                   // Visual feedback for mode
    
    // Internally:
    // • Tracks current animation index
    // • Dispatches to Animator methods
    // • SHORT PRESS → next animation
    // • LONG PRESS  → previous animation
}

// Handles debounced button input detection
class Button {
    enum Event { NONE, SHORT_PRESS, LONG_PRESS };
    Button::Event check();               // Poll button state
}

# Clone repository
git clone https://github.com/yourusername/LED-Cube.git
cd LED-Cube

# Open in VS Code with PlatformIO
code .

# Install via PlatformIO
pio pkg install

# Required libraries will be automatically installed

namespace Config {
    // 74HC595 Shift Register pins
    constexpr uint8_t DS    = 2;      // Data input
    constexpr uint8_t RCLK  = 3;      // Latch clock
    constexpr uint8_t SRCLK = 4;      // Shift clock
    
    // Layer selection pins (NPN transistors)
    constexpr uint8_t LAYER_PINS[4] = {5, 6, 7, 8};
    
    // Button input pin
    constexpr uint8_t BUTTON_PIN = 10;
    
    // Cube dimensions
    constexpr uint8_t NUM_LAYERS  = 4;
    constexpr uint8_t NUM_COLUMNS = 16;
    
    // Timing parameters
    constexpr uint16_t LAYER_ON_US = 500;     // Microseconds per layer
    constexpr uint16_t DEBOUNCE_MS = 50;      // Button debounce
    constexpr uint16_t LONG_PRESS_MS = 600;   // Long press threshold
}

# Build project
pio run

# Upload to Arduino Nano
pio run -t upload

# Monitor serial output
pio device monitor

// main.cpp — Main program loop
LEDCube          cube;           // Display driver & button handler
Animator         anim(cube);     // Animation engine
AnimationManager mgr(cube, anim); // Animation dispatcher

void setup() {
    randomSeed(analogRead(A0));
    cube.begin();
}

void loop() {
    mgr.run();   // Runs current animation, switches on button press
}

SHORT PRESS (< 600ms)  → Advance to next animation
LONG PRESS  (≥ 600ms)  → Return to previous animation

Button::Event Animator::layerSweep() {
    // Animate through each layer
    for (uint8_t layer = 0; layer < NUM_LAYERS; layer++) {
        // Set frame for this layer
        _cube.setLayer(layer, 0xFFFF);  // All columns ON
        
        // Refresh and check for button press
        Button::Event evt = _tick(100);  // Refresh for 100ms
        if (evt != Button::NONE) {
            return evt;  // Button pressed - exit and switch
        }
    }
    return Button::NONE;  // Loop again
}

// 1. Add method declaration in Animator.h
Button::Event myNewAnimation();

// 2. Implement in Animator.cpp
Button::Event Animator::myNewAnimation() {
    // Your animation code
    return _tick(delayMs);  // Refresh and return button event
}

// 3. Register in AnimationManager.cpp dispatch table
// Update _total count and add to dispatcher

LED-Cube/
│
├── code/                          # Firmware Source Code
│   ├── src/
│   │   ├── main.cpp               # Entry point & main loop
│   │   ├── LEDCube.cpp            # Frame buffer & display driver
│   │   ├── AnimationManager.cpp   # Animation dispatcher & controller
│   │   ├── Animator.cpp           # 12 animation implementations
│   │   ├── Button.cpp             # Button input handling
│   │   ├── LayerController.cpp    # Layer multiplexing control
│   │   └── ShiftRegister.cpp      # 74HC595 shift register driver
│   │
│   ├── include/
│   │   ├── Config.h               # Hardware pinout & settings
│   │   ├── LEDCube.h              # Frame buffer interface
│   │   ├── AnimationManager.h     # Animation manager interface
│   │   ├── Animator.h             # Animation methods interface
│   │   ├── Button.h               # Button control interface
│   │   ├── LayerController.h      # Layer control interface
│   │   └── ShiftRegister.h        # Shift register interface
│   │
│   ├── test/
│   │   └── nano_test.cpp          # Unit tests for Arduino Nano
│   │

MIT License

Copyright (c) 2024 LED Cube Project

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.