How to display an image on an ESP32 e-paper display

Last updated 2026-10-28

An e-paper panel does not understand JPEG or PNG files. It expects a frame buffer: a block of bytes where every pixel is already one of the few colors the panel can show. Getting a photo onto the screen means resizing it to the panel’s resolution, reducing it to the panel’s palette and packing the pixels into bytes in the order the controller expects. This guide walks through that process for an ESP32.

1. Find your panel’s size, resolution and colors

Look at the label on the flex cable or the product listing. You need three facts:

• Diagonal size, for example 7.5 inches.
• Resolution, for example 800×480. Some sizes come in more than one resolution, so check this carefully.
• Colors: black and white, 4-level gray, 3-color (black, white and red or yellow), 4-color, 6-color or 7-color.

If the resolution or color count is wrong, the image will appear shifted, striped or in the wrong colors. A quick way to confirm is to check the size of the buffer the driver’s example code allocates. An 800×480 black and white panel needs 48,000 bytes; the same panel in 6 colors needs 192,000 bytes. The size pages list the buffer size for every combination.

2. Prepare the image

Open the converter, choose your size and colors, then upload a photo.

• Orientation: choose Portrait if the frame stands upright. You crop a tall image and the buffer is rotated to the panel’s native layout for you.
• Crop: drag and zoom to frame the subject. E-paper panels are small, so tighter crops usually look better than wide scenes.
• Adjustments: Auto mode stretches the contrast, lifts shadows and boosts muted colors. It is tuned for e-paper, which has much lower contrast than a phone screen. Switch to Manual only if you want full control.

The preview on the right shows the dithered result. Use the 1:1 and 2× views to see individual pixels.

3. Choose a file format

• .h if the image never changes. It becomes part of your firmware.
• .bin if you want to swap images without reflashing. Copy it to flash (LittleFS) or an SD card and read it at runtime.

4. Include the header and draw

#include "my_image.h"

void setup() {
  epd_init();                              // your driver's init
  epd_write_frame(my_image, MY_IMAGE_SIZE); // send the whole buffer
  epd_refresh();                            // start the refresh
  epd_sleep();                              // e-paper keeps the image without power
}

Function names differ between drivers, but almost every e-paper driver has three steps: write the buffer to the controller’s RAM, trigger a refresh and wait for the BUSY pin to go low.

5. Watch your memory

The ESP32 has plenty of flash, but heap memory is limited. Small black and white buffers fit anywhere. Color buffers for large panels do not:

A .h array marked const lives in flash and costs no RAM. A .bin file read at runtime needs a RAM buffer. Above about 100 KB, use a board with PSRAM and allocate the buffer with ps_malloc, or stream the file to the panel in chunks if your driver supports writing rows.

6. If the picture looks wrong

• Shifted or diagonal stripes: the resolution is wrong, or the driver expects a different row padding.
• Mirrored or rotated: change the buffer rotation under Advanced output options.
• Inverted (white is black): tick “Invert bits”.
• Wrong colors on a color panel: your driver uses different color codes. Edit them under Advanced output options so they match the driver’s color table.

See how e-paper frame buffers are laid out for the details behind each option.

Open the converter →