# colorduino-plasma

The classic **ColorduinoPlasma** demo for the ITead Colorduino 8×8 RGB LED matrix, plus a
**browser simulator** that renders the exact same effect on your PC — at the original 8×8 or at
much higher resolutions.

## Contents

| Path | What |
|---|---|
| `arduino/ColorduinoPlasma/` | The plasma demo sketch (from the lincomatic Colorduino library) |
| `arduino/ColorduinoMatrixTest/` | Hardware test: full colours, row/column scan, per-LED walk, brightness ramps, checkerboard |
| `libraries/Colorduino/` | Colorduino library v1.2.6 by Sam C. Lin ([lincomatic/Colorduino](https://github.com/lincomatic/Colorduino) @ `fff7bd3`) |
| `web/index.html` | Browser simulator — open it directly, no server needed |
| `firmware/` | Prebuilt hex files for ATmega328(P/PB) @ 16 MHz |

## Browser simulator

Open `web/index.html` in any browser.

It is a straight port of `plasma_morph()` / `HSVtoRGB()` and matches the AVR build bit for bit
as closely as possible:

- all maths in 32-bit float (`Math.fround`), like `double` = `float` on AVR
- the hue cast `(unsigned char)(value * 128)` **wraps negative values** (two's complement),
  which is what avr-libc's `__fixunssfsi` does — clamping to 0 would give a very different image
- same `gamma8` table, same start value `paletteShift = 128000`

Controls:

- **Width / Height** — the plasma is an infinite field; a larger grid shows more of it.
  The Colorduino shows the top-left 8×8 (toggle *Mark 8×8 area*).
- **Detail** — sub-samples between LED positions, so the same area renders smoothly.
- **Colour** — *LED light* converts the gamma-corrected PWM values (linear light) to sRGB so it
  looks like the LEDs; *Raw PWM values* shows the bytes sent to the DM163; *Without gamma table*
  skips the gamma lookup.
- **Speed**, **Rotate**, **LED dots**, pause (Space), step (→), fullscreen (F).

The board's white balance (`{36, 63, 63}`) is an LED current correction and is not applied on screen.

## Building the sketches

1. Copy `libraries/Colorduino` into your Arduino `libraries` folder
   (e.g. `Documents/Arduino/libraries/Colorduino`).
2. Open a sketch from `arduino/`, select board **Arduino Uno**, and build.

With arduino-cli, no install needed:

```bash
arduino-cli compile -b arduino:avr:uno --library libraries/Colorduino arduino/ColorduinoPlasma
```

> The library drives all of PORTD (including RX/TX), so `Serial` can't be used alongside it.

## Flashing

### Over serial (bootloader present)

Connect a USB-serial adapter (FTDI-style, with DTR for auto-reset) to the Colorduino's serial
header and upload as **Arduino Uno** (Optiboot, 115200 baud).

### Over ISP (Arduino as ISP)

A normal ISP write erases the chip, including the bootloader. Flash the combined image to keep it:

```bash
avrdude -p m328pb -c stk500v1 -P COM16 -b 19200 -U flash:w:firmware/ColorduinoPlasma_16MHz_optiboot.hex:i
```

Use `-p m328p` if your board has an ATmega328P (signature `1E 95 0F`) rather than a 328PB
(`1E 95 16`).

Fuses used here (16 MHz crystal, 512-byte Optiboot boot section):

| low | high | extended |
|---|---|---|
| `0xFF` | `0xD6` | `0xF5` |

## License

The sketches, the library and the simulator (a port of the sketch) are licensed under the
GNU LGPL v2.1 or later — see [LICENSE](LICENSE). Original copyrights: Sam C. Lin (Colorduino
library and demo), Ben Combee, Ken Corey, Windell H. Oskay (color cycling plasma),
zzy@IteadStudio. The library folder includes its upstream `COPYING` file.