inks_ee05

Example of the component cleishm/idfxx_epaper v2.0.1
# Inks on EE05

Shows a frame that was converted to the panel's inks elsewhere, as a phone or browser would, on the
7.5" screen of the Seeed Studio XIAO ePaper Display Board EE05, with no image decoder or converter
on the device.

## What it demonstrates

- Switching on the display's power supply, setting up an SPI bus and panel I/O, and creating an
  `idfxx::epaper::uc8179` driver as in the `idfxx_epaper_uc8179` `ee05_demo` example
- Starting the gray levels from a known state: a full black refresh, then `clear()` and a white one,
  then selecting `color_mode::gray4`
- Reading a frame of four-gray inks from an `idfxx::memory_source` over the frame embedded in the
  app
- Writing it to the whole panel with `idfxx::epaper::write_inks()`, a band of rows at a time
- Showing it with `refresh()`, then putting the panel into deep sleep with `sleep()`, after which
  the image stays on screen without power

The example uses the exception-based API (`CONFIG_COMPILER_CXX_EXCEPTIONS=y` in
`sdkconfig.defaults`). A real device would read the frame from a network connection instead, which
means writing an `idfxx::byte_source` type for the connection. `write_inks()` takes any
`idfxx::byte_source`, so the only line that changes here is the one that creates the source.
`write_inks()` checks the frame's length only; see [Writing a frame of inks from a byte
source](https://github.com/cleishm/idfxx/tree/main/components/displays/idfxx_epaper#writing-a-frame-of-inks-from-a-byte-source)
for what else can be checked.

## Hardware required

- A Seeed Studio XIAO ePaper Display Board EE05 (ESP32-S3 Plus)
- A 7.5" 800x480 UC8179 ePaper panel with GDEY075T7 glass connected to the board

The example is for the ESP32-S3 only (`sdkconfig.defaults` sets the target to `esp32s3`). It runs in
internal RAM, as the frame is read a few rows at a time.

The example uses the EE05's display wiring. To use a different board, change the `PIN_*` constants
at the top of `main/display_setup.hpp`.

| Display signal             | ESP32-S3 GPIO |
| -------------------------- | ------------- |
| SCLK                       | GPIO 7        |
| MOSI                       | GPIO 9        |
| CS                         | GPIO 44       |
| DC                         | GPIO 10       |
| RESET                      | GPIO 38       |
| BUSY                       | GPIO 4        |
| Power enable (active high) | GPIO 43       |

> [!NOTE]
> GPIO 43 and 44 are the ESP32-S3's default UART0 TX and RX pins, which the example takes over for
> the display. `sdkconfig.defaults` puts the console on the USB Serial/JTAG port, so log output
> reaches the monitor there.

## How to use

Create a project from this example:

```bash
idf.py create-project-from-example "cleishm/idfxx_epaper:inks_ee05"
cd inks_ee05
```

Then build and flash it, then watch the serial output:

```bash
idf.py set-target esp32s3
idf.py -p PORT flash monitor
```

Replace `PORT` with your board's serial port. Press `Ctrl-]` to exit the monitor.

The panel goes black and then white, then refreshes to a photo of two macaws, in four grays.

## The frame

`main/frame.bin` is the whole 800x480 panel in four grays at 2 bits per pixel, 0 for the darkest to
3 for the lightest, packed as `epi_pack_row` with `EPI_PACK_2BPP` does: each row padded to a whole
byte, rows from top to bottom, no header, so exactly 96,000 bytes. It was made from the 768x512 JPEG
`photo.jpg` of the `idfxx_epaper_image` `photo_ee05` example with the
[`cleishm/epaper-image`](https://github.com/cleishm/epaper-image) library's `convert` tool, using
the library's calibration for the GDEY075T7 in four grays and its default preset, covering the panel
and cropping the photo to fit:

```bash
convert --panel gdey075t7-gray4 --cover photo_ee05/main/photo.jpg main/frame.bin
```

That calibration was measured with the uc8179 driver's default four-gray waveform, at its default 20
Hz and ±15 V, which this example doesn't change, so the grays come out as the converter intended. A
frame made for different settings, or other glass, needs its own calibration; `write_inks()` can't
tell the difference.

The photo is `kodim23` from the [Kodak Lossless True Color Image
Suite](https://r0k.us/graphics/kodak/), photographed by Steve Kelly. That page states its
understanding that Kodak released the suite for unrestricted usage.

To create a project from this example, run:

idf.py create-project-from-example "cleishm/idfxx_epaper=2.0.1:inks_ee05"

or download archive (~49.16 KB)