cleishm/idfxx_epaper_uc8179

3.0.0

Latest
uploaded 6 hours ago
UC8179 ePaper panel driver (up to 800x600, e.g. 7.5" 800x480)

Readme

# idfxx_epaper_uc8179

UC8179 ePaper panel driver (up to 800x600, e.g. 7.5" 800x480).

πŸ“š **[Full API Documentation](https://cleishm.github.io/idfxx/group__idfxx__epaper.html)**

## Features

- Implements the full `idfxx::epaper::panel` interface β€” application code written against the
  abstract panel works unchanged.
- Full, fast (register-written shortened waveform), and flicker-free partial refreshes.
- 4-level grayscale (`color_mode::gray4`) using the glass's factory grayscale waveform, with a
  configurable frame rate and source voltage.
- Selectable border: driven white or black on full/fast refreshes, or held so it never flickers.
- Deep sleep and wake (hardware reset + re-initialization).
- `restore_baseline()` support, to keep partial refreshes across a wake or an ESP32 deep sleep (in
  `color_mode::mono`).
- No shadow frame: the UC8179 copies the new-image RAM to the previous-image RAM when a refresh
  completes, so partial refreshes diff against what is on the glass without host-side bookkeeping.
- Configurable dimensions covering all UC8179 glasses (up to 800 sources x 600 gates); defaults
  match the 7.5" 800x480 GDEY075T7 glass.
- `spi_io_config()` helper pre-fills the controller's SPI framing for `idfxx::panel_io`.

## Requirements

- ESP-IDF 5.5 or later
- C++23 compiler
- `idfxx_epaper` (abstract interface and framebuffers)
- `idfxx_panel_io` (panel I/O transport)
- `idfxx_gpio` (BUSY and reset lines)
- `idfxx_core` (error handling)

## Installation

### ESP-IDF Component Manager

Add to your project's `idf_component.yml`:

```yaml
dependencies:
  cleishm/idfxx_epaper_uc8179:
    version: "^3.0.0"
```

Or add `idfxx_epaper_uc8179` to the `REQUIRES` list in your component's `CMakeLists.txt`.

## Usage

Wiring for the Seeed Studio XIAO ePaper Display Board EE05 (ESP32-S3 Plus) with the 7.5" panel:

```cpp
#include <idfxx/epaper/mono_framebuffer>
#include <idfxx/epaper/uc8179>
#include <idfxx/spi/master>

idfxx::spi::bus_config bus_cfg{};
bus_cfg.mosi = idfxx::gpio_9;
bus_cfg.sclk = idfxx::gpio_7;
idfxx::spi::master_bus bus(idfxx::spi::host_device::spi2, idfxx::spi::dma_chan::ch_auto, bus_cfg);

idfxx::panel_io io(bus, idfxx::epaper::uc8179::spi_io_config(idfxx::gpio_44, idfxx::gpio_10));
idfxx::epaper::uc8179 display(io, {
    .reset_gpio = idfxx::gpio_38,
    .busy_gpio = idfxx::gpio_4,
});

idfxx::epaper::mono_framebuffer fb(display.width(), display.height());
fb.set_pixel(10, 20, true); // black ink
display.write(fb);          // upload to controller RAM (48 KB, streamed by DMA)
display.refresh();          // make it visible (blocks until done; start_refresh() returns a future)
display.sleep();            // deep sleep between updates
```

The same flow with the result-based API:

```cpp
auto display = idfxx::epaper::uc8179::make(io, {.reset_gpio = idfxx::gpio_38, .busy_gpio = idfxx::gpio_4});
if (!display) {
    return idfxx::error(display.error());
}
auto fb = idfxx::epaper::mono_framebuffer::make(display->width(), display->height());
if (!fb) {
    return idfxx::error(fb.error());
}
fb->set_pixel(10, 20, true);
if (auto r = display->try_write(*fb); !r) {
    return r;
}
if (auto r = display->try_refresh(); !r) {
    return r;
}
return display->try_sleep();
```

### Partial and fast refreshes

```cpp
display.refresh(idfxx::epaper::refresh_mode::fast);    // shortened full waveform
display.write(fb);
display.refresh(idfxx::epaper::refresh_mode::partial); // differential, no flash
```

### Grayscale

```cpp
display.set_color_mode(idfxx::epaper::color_mode::gray4);
idfxx::epaper::gray4_framebuffer gray_fb(display.width(), display.height());
gray_fb.fill(idfxx::epaper::gray4::light);
display.write(gray_fb);
display.refresh(); // gray4 supports full refresh only
display.set_color_mode(idfxx::epaper::color_mode::mono); // back to monochrome
```

The grayscale operating point is set in the config (see Important Notes):

```cpp
idfxx::epaper::uc8179 display(io, {
    .busy_gpio = idfxx::gpio_4,
    .gray4_frame_rate = quanta::frequency::hertz{50},
    .gray4_source_voltage = quanta::electro::millivolts{10'000},
});
```

### Border

```cpp
idfxx::epaper::uc8179 display(io, {.busy_gpio = idfxx::gpio_4, .border = idfxx::epaper::border::hold});
display.set_border(idfxx::epaper::border::black); // driven black from the next full/fast refresh
```

See `examples/ee05_demo` for a complete application exercising all refresh modes on the EE05 board.

## API Overview

The panel API (`write`, `write_rows`, `clear`, `restore_baseline`, `refresh`, `start_refresh`,
`set_color_mode`, `set_border`, `sleep`, `wake`, and their `try_*` forms) is inherited from
`idfxx::epaper::panel` β€” see the `idfxx_epaper` documentation.

Driver-specific surface:

- `uc8179(panel_io&, config)` / `uc8179::make(panel_io&, config)` β€” construction; resets and
  initializes the controller and clears both image planes to white.
- `config` β€” `width`/`height` (default 800x480; width must be a multiple of 8), `reset_gpio`
  (required for `wake`, strongly recommended in general), `busy_gpio` (required), `busy_timeout`
  (default 30 s), `border` (default `border::white`; all three values supported, changeable later
  with `set_border`), `gray4_frame_rate` / `gray4_source_voltage` (grayscale operating point,
  default 20 Hz at +/-15 V).
- `spi_io_config(cs, dc, pclk = 10 MHz)` β€” pre-filled `panel_io::spi_config` (mode 0, 8-bit
  command/parameter framing).

## Error Handling

Uses `idfxx::result<T>` and `idfxx::errc` from `idfxx_core`:

- `errc::invalid_arg` β€” unconnected `busy_gpio`, dimensions outside the controller's 800x600 range,
  a width not a multiple of 8, an unsupported `gray4_frame_rate` or `gray4_source_voltage`, or
  invalid write placement.
- `errc::invalid_state` β€” writing/refreshing while asleep, a framebuffer not matching the color
  mode, or `wake` without a `reset_gpio`.
- `errc::timeout` β€” the BUSY line did not release within `busy_timeout`.
- `errc::not_supported` β€” `fast`/`partial` refresh in gray4 mode.

Using a moved-from driver object is undefined behavior.

## Important Notes

- **BUSY is required.** The UC8179 holds BUSY low (active low, unlike the SSD1680) for several
  seconds during full refreshes of the 7.5" glass; `refresh` blocks on it (with a tick-sleep poll,
  not a busy-spin). `start_refresh` returns while the glass is still driving: the driver then waits
  for BUSY before the next controller command.
- **Memory**: a full-frame `mono_framebuffer` at 800x480 is 48 KB and a `gray4_framebuffer` is 96
  KB, all DRAM. Grayscale writes additionally stage each plane through a transient buffer of up to
  48 KB (the controller's gray bit sense is inverted from the canonical encoding).
  `gfx::render_banded` with a band-sized framebuffer keeps mono drawing memory small.
- **Waveform switching resets the controller.** The UC8179 selects its waveform at initialization,
  so changing refresh mode between refreshes hardware-resets and re-initializes the controller
  (image RAM survives). Wire `reset_gpio` β€” without it, mode switches leave stale register state
  behind. Repeated refreshes in the same mode skip this entirely.
- **Fast refresh uses register-written waveform tables** (from Seeed's driver for this glass).
  Quality varies by panel batch and temperature β€” validate on hardware, and prefer `full` when in
  doubt.
- **Gray4 levels are tunable, and shift when you tune them.** The grayscale waveform tables are the
  factory grayscale waveform of the GDEY075T7 glass (on other UC8179 glasses, validate on hardware).
  `config::gray4_frame_rate` and `config::gray4_source_voltage` select the operating point. The
  default, 20 Hz at +/-15 V, gives the deepest black and the widest gray spacing, independent of the
  image content, at ~9 s per refresh. 50 Hz at +/-10 V keeps the vendor's 3.6 s refresh with
  content-stable levels, but its black is lighter and both grays sit in the dark end of the range.
  The vendor's own point, 50 Hz at +/-15 V, gives a deep black at 3.6 s, but its gray levels drop by
  up to ~15 % on content with dense horizontal detail (the drive supplies sag under source-switching
  load). The gray levels move with either setting, so recalibrate any gray mapping after changing
  them.
- **Fast refresh trades contrast for durability of the image.** The shortened waveform under-drives
  the ink, leaving black pixels in a weakly held state: they look black on their own, but a
  subsequent partial refresh can settle them to a visibly gray level (a one-time step, not
  progressive fading). Start a long partial-refresh sequence from a `full` refresh, which drives
  pixels to their stable extremes.
- **Ghosting**: issue a `full` refresh every ~10 partial refreshes to clean accumulated ghosting.
- **A white border flashes with each full refresh.** The controller has no fixed-level border drive:
  it drives the border with the black-to-white pixel waveform, so `border::white` flashes along with
  the image. `border::hold` leaves the border undriven, keeping its last color β€” once the border is
  white, switching to `hold` stops it flashing. Whether a floating border stays clean across many
  full refreshes depends on the glass; drive it white again now and then if it grays. In
  `color_mode::gray4` white is not drivable, so a white setting holds the border (black is still
  driven). Partial refreshes and deep sleep always float the border, whatever the setting.
- **Gray4 amplifies ghosting from long-displayed content.** The gray midtones are open-loop drives,
  so they expose residual polarization the ink accumulates while content sits in one state β€” content
  that was black on the glass for a long time can ghost faintly through the gray levels even after
  the panel has been cleared to a uniform white. The simplest mitigation is sequencing: refresh
  grayscale content while the glass is fresh, before any one image has been held for long
  (`examples/ee05_demo` runs its grayscale stage early for exactly this reason). Repeated scrub
  cycles do not help once the polarization exists: a drive applied identically to every pixel cannot
  remove a per-pixel differential. When long-held content is unavoidable, inverse compensation
  works: display the *inverse* of the long-held content (every pixel makes a full opposite
  transition), hold it β€” the compensation grows with hold time, and a hold approaching the original
  display time all but eliminates the ghost β€” then `clear()` and refresh. In mono mode `clear()`
  blanks only the new-image plane, so that final refresh applies the deep black-to-white erase
  waveform to previously-black pixels rather than the gentle white-to-white one.
- The destructor powers off an awake controller and puts it into deep sleep; call `wake()` after
  re-constructing a driver on a previously slept panel.

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

Links

Supports all targets

To add this component to your project, run:

idf.py add-dependency "cleishm/idfxx_epaper_uc8179^3.0.0"

download archive

Stats

  • Archive size
    Archive size ~ 28.94 KB
  • Downloaded in total
    Downloaded in total 30 times
  • Weekly Downloads Weekly Downloads (All Versions)
  • Downloaded this version
    This version: 0 times

Badge

cleishm/idfxx_epaper_uc8179 version: 3.0.0
|