planar-EL512.256-H/README.md

# Planar EL512.256-H on ESP32

Drive a Planar EL512.256-H (512 × 256, monochrome electroluminescent) panel from an
ESP-WROOM-32 (classic ESP32), with an [Adafruit GFX](https://github.com/adafruit/Adafruit-GFX-Library)
compatible driver so the usual drawing, text and font APIs work.

The panel has no frame memory and needs a continuous video stream. The ESP32's I2S0
peripheral in 8-bit parallel (LCD) mode streams a precomputed frame from DMA, so the
CPU is free while the panel refreshes.

**Status:** framebuffer, GFX layer, row encoder and I2S/DMA refresh are implemented and
build cleanly; the signal timing has not yet been checked on hardware. Updates are not
yet tear-free.

## Hardware

- ESP-WROOM-32 dev board (`esp32dev`)
- Planar EL512.256-H, configured for **two-bit parallel mode** (mode jumper OFF, see datasheet)
- Datasheet: [docs/datasheet/EL512.256-H3 FRB.pdf](docs/datasheet/EL512.256-H3%20FRB.pdf)
- Check the panel's logic-level and supply requirements in the datasheet before wiring.

## Wiring

| Panel signal | Function                                | ESP32 GPIO | DMA byte bit |
|--------------|-----------------------------------------|-----------:|-------------:|
| VCLK         | Video clock (rising edge)               | 18         | I2S0 BCK     |
| VID          | Pixel data, even columns                | 19         | 0            |
| TVID         | Pixel data, odd columns (two-bit mode)  | 21         | 1            |
| HS           | Horizontal sync                         | 22         | 2            |
| VS           | Vertical sync                           | 23         | 3            |
| ENABLE       | Display enable                          | 25         | —            |
| _LOWPWR      | Low-power mode (active low)             | 26         | —            |
| GND          | Ground                                  | GND        | —            |

The pin map lives in [include/pins.h](include/pins.h).

## Timing

| Parameter            | Value                                   |
|----------------------|-----------------------------------------|
| Pixel clock (VCLK)   | 5 MHz, 2 pixels per clock               |
| Clocks per row       | 272 (256 data + 16 blanking)            |
| Lines per frame      | 261 (256 visible + 5 blanking)          |
| Refresh              | 5 MHz / (272 × 261) ≈ 70.4 Hz           |

## Layout

```
platformio.ini        build config (esp32dev, Arduino, Adafruit GFX)
include/pins.h        pin map
src/main.cpp          test sketch: test pattern + text
lib/EL512/            local library
  src/EL512Panel.*    framebuffer, row encoder, I2S DMA refresh
  src/EL512_GFX.*     Adafruit_GFX subclass
test/                 unit tests (placeholder)
docs/                 datasheet and notes
```

## Build and flash

Requires [PlatformIO](https://platformio.org/) (CLI or the VS Code extension).

```bash
pio run
```

```bash
pio run -t upload
```

```bash
pio device monitor
```

## Using the driver

```cpp
#include <EL512.h>
#include "pins.h"

EL512Panel panel({el512pins::VCLK, el512pins::VID, el512pins::TVID, el512pins::HS,
                  el512pins::VS, el512pins::ENABLE, el512pins::LOWPWR_N});
EL512_GFX display(panel);

void setup() {
  display.begin();
  display.setTextColor(1);
  display.print("Hello");
  display.display();   // push the drawing buffer to the refresh stream
}
```

See [docs/README.md](docs/README.md) for design notes and the plan.