# Lucent Cube — Hardware & Development Reference

A machine-readable reference to the Lucent Cube's construction, so developers and
AI coding assistants can write apps for it. To **control** a running cube over your
network, see the HTTP API: https://lucentcube.com/api

## At a glance
- **6 faces**, each a **64×64 RGB LED matrix** (HUB75-class panels).
- Onboard Linux compute (Raspberry Pi Compute Module 4 class).
- **Audio:** built-in microphone (standard) + **stereo speakers** driven by an onboard **5 W amplifier**.
- **Motion:** 3-axis accelerometer for orientation / tilt-aware apps.
- Control via the companion app (iOS, Android, Windows, macOS) or the local HTTP API.

## Faces
Six faces, addressed by index 0–5. Each face is a 64×64 grid. Face-local
coordinates are **(0,0) = top-left, (63,63) = bottom-right**, as seen when that
face is physically in front of you.

| Index | Name  |
|-------|-------|
| 0 | LEFT |
| 1 | BOT |
| 2 | FRONT |
| 3 | TOP |
| 4 | RIGHT |
| 5 | BACK |

## Physical canvas & face mapping (critical)
The six panels present one **192×128** pixel canvas (3 panels wide × 2 rows).
Each face maps to a slot with an origin and rotation:

| Face | Name  | Slot | Origin (ox, oy) | Rotation |
|------|-------|------|-----------------|----------|
| 0 | LEFT  | 3 | (0, 64)   | 0°      |
| 1 | BOT   | 2 | (128, 0)  | 90° CW  |
| 2 | FRONT | 4 | (64, 64)  | 0°      |
| 3 | TOP   | 0 | (0, 0)    | 90° CW  |
| 4 | RIGHT | 5 | (128, 64) | 0°      |
| 5 | BACK  | 1 | (64, 0)   | 270° CW |

`slot = col + row * 3`  (col = 0–2, row = 0–1)

## Drawing model
Address pixels **per face** in face-local coordinates; the rotation/flip to
physical canvas coordinates is handled for you. Reference logic:

```
setFacePixel(face, x, y, r, g, b):
    # x, y are face-local, 0..63 (ignore out-of-range)
    px, py = applyFlip(face, x, y)        # optional per-face flip
    switch face.rotation:
        case  90:  rx = 63 - py;  ry = px
        case 180:  rx = 63 - px;  ry = 63 - py
        case 270:  rx = py;       ry = 63 - px
        default:   rx = px;       ry = py
    canvas.setPixel(face.ox + rx, face.oy + ry, r, g, b)
```

## Face adjacency
The four side faces form a belt that wraps around; TOP and BOT cap it:

```
            [ TOP ]
[ LEFT ][ FRONT ][ RIGHT ][ BACK ]   ← belt wraps around
            [ BOT ]
```

Belt edges join with **no y-inversion** (coordinates match directly across):
LEFT.right↔FRONT.left, FRONT.right↔RIGHT.left, RIGHT.right↔BACK.left, BACK.right↔LEFT.left.

Vertical edges (sides ↔ caps):

| Face A | Edge A | Face B | Edge B |
|--------|--------|--------|--------|
| FRONT | top    | TOP  | bottom |
| FRONT | bottom | BOT  | top    |
| TOP   | left   | LEFT | top    |
| TOP   | right  | RIGHT| top    |
| TOP   | top    | BACK | top    |
| BOT   | left   | LEFT | bottom |
| BOT   | right  | RIGHT| bottom |
| BOT   | top    | BACK | bottom |

## Orientation (accelerometer)
A 3-axis accelerometer reports orientation:
- **Z axis** — through FRONT/BACK; `Z = -1` at rest (FRONT toward gravity).
- **X axis** — through TOP/BOT; `X = -1` tilting forward (nose-down).
- **Y axis** — through LEFT/RIGHT; `Y = +1` tilting right. **Y is inverted in hardware — negate before use.**

A "level" reference can be captured at runtime (`POST /reset-horizon`), so
orientation is relative to a chosen rest position rather than absolute world-down.

## Controlling a cube (HTTP API)
Everything the companion app does is available over the cube's local HTTP API —
playback, settings, playlists, visualisations, games, and LED hardware. Full
reference: **https://lucentcube.com/api**

## Contact
Building something, or want deeper integration docs? **info@lucentcube.com**