Skip to main content

Work with OpenEPaperLink / OpenDisplay

OpenDisplay and OpenEPaperLink (OEPL) are open-source ecosystems for driving ePaper displays over Bluetooth Low Energy (BLE). A phone, computer, or Home Assistant host can connect to the display directly, so the basic workflow does not require an 802.15.4 access point.

This guide covers two Seeed hardware paths:

  • OpenDisplay Toolbox path — recommended for ready-to-use OpenDisplay firmware on reTerminal E1001, reTerminal E1002, reTerminal E1003, and XIAO ePaper Display Board EN04.
  • OEPL_BLE path — useful for a modular DIY setup with ePaper Breakout Board for Seeed Studio XIAO and a XIAO nRF52840 series board.

The user experience is similar in both paths: install firmware, configure the device over BLE, then upload an image. The tools and supported presets differ, so follow the tab that matches your hardware.

Compatible Hardware​

The OpenDisplay Toolbox includes presets for reTerminal E1001, reTerminal E1002, and reTerminal E1003.

reTerminal E1001reTerminal E1002reTerminal E1003
Get One Now 🖱️
Get One Now 🖱️
Get One Now 🖱️
7.5" monochrome, 800 × 4807.3" Spectra 6 color, 800 × 48010.3" monochrome, 1404 × 1872, touch
Open in ToolboxOpen in ToolboxOpen in Toolbox

Use this path when you want to run OpenDisplay firmware directly on a finished reTerminal E Series device.

caution

Installing OpenDisplay firmware replaces the firmware currently running on the device. Keep a restore path ready by using the official reTerminal E-Series Firmware Hub or the firmware package recommended by your product Wiki.

Why Use OpenDisplay / OpenEPaperLink?​

  • BLE-first workflow — configure and upload images without a dedicated 802.15.4 access point.
  • Browser-based tools — install firmware, select presets, configure devices, and upload images from a supported browser.
  • Seeed hardware presets — OpenDisplay Toolbox includes presets for reTerminal E1001, E1002, E1003, and EN04.
  • Home Assistant support — OpenDisplay devices can be added through Home Assistant's official OpenDisplay integration.
  • Open-source ecosystem — firmware, tools, and integrations are developed in public repositories.

Step 1: Hardware Setup​

Step 1. Connect the reTerminal E Series device to your computer with a USB-C data cable.

Step 2. Turn the device on and keep it close to the computer. The browser will use USB for firmware installation and BLE for configuration.

Step 3. Match your hardware to the correct OpenDisplay Toolbox preset:

DeviceToolbox PresetDisplay
reTerminal E1001reterminal-e10017.5" monochrome, 800 × 480
reTerminal E1002reterminal-e10027.3" Spectra 6 color, 800 × 480
reTerminal E1003reterminal-e100310.3" monochrome, 1404 × 1872

Step 2: Install Firmware​

OpenDisplay provides direct Toolbox presets for the reTerminal E Series.

Step 1. Open the matching Toolbox preset in Chrome or Edge:

Step 2. Confirm that the selected preset matches your device.

Step 3. Click Install firmware (USB).

Step 4. In the browser pairing dialog, select the USB serial device that appears when the reTerminal is connected.

Step 5. Wait until the installer finishes and the device reboots.

After installation, continue with BLE configuration in the next step.

Step 3: Configure the Device over BLE​

Step 1. In the same OpenDisplay Toolbox page, click Configure over Bluetooth.

Step 2. Select your reTerminal device in the BLE pairing dialog.

Step 3. Wait for the Toolbox to write the selected preset to the device.

Step 4. Confirm that the display refreshes or shows the OpenDisplay startup/test image.

The device is now ready for image upload through OpenDisplay tools or Home Assistant.

Step 4: Upload Images​

OpenDisplay devices can receive images through the browser display tool.

Step 1. Open the OpenDisplay display tool.

Step 2. Click Connect and select your reTerminal device from the BLE pairing dialog.

Step 3. Click Select Image and choose a local image file.

Step 4. Click Upload Image.

When the transfer finishes, the ePaper display refreshes and shows the uploaded image.

tip

Use an image size that matches your panel for the cleanest result:

  • reTerminal E1001: 800 × 480 px
  • reTerminal E1002: 800 × 480 px
  • reTerminal E1003: 1404 × 1872 px

Home Assistant Integration​

Home Assistant has an official OpenDisplay integration for OpenDisplay firmware devices. It communicates over BLE and provides the opendisplay.upload_image action for sending images to the display.

Prerequisites​

  • Home Assistant 2026.4 or later.
  • A working Bluetooth setup that supports active BLE connections.
  • An OpenDisplay firmware device powered on and within Bluetooth range.

The following Bluetooth paths are suitable:

  • Home Assistant Green or another Home Assistant host with supported Bluetooth hardware.
  • ESPHome Bluetooth Proxy running ESPHome firmware 2022.9.3 or later.
info

Shelly Bluetooth proxies are useful for passive BLE sensors, but OpenDisplay image upload requires active BLE connections. Use a Home Assistant Bluetooth adapter or ESPHome Bluetooth Proxy for this workflow.

Add the Device​

Step 1. In Home Assistant, go to Settings > Devices & services.

Step 2. If the device is discovered automatically, click Add on the OpenDisplay card.

Step 3. If it is not discovered automatically, click Add Integration, search for OpenDisplay, and follow the setup flow.

Step 4. Assign the device name and area.

After the device is added, Home Assistant can discover and connect to the OpenDisplay device over Bluetooth.

Upload an Image from Home Assistant​

Store your image in Home Assistant's local media folder, then call opendisplay.upload_image.

action: opendisplay.upload_image
data:
  device_id: "your_device_id"
  image:
    media_content_id: "media-source://media_source/local/photo.png"
    media_content_type: "image/png"

For scheduled updates, use the same action inside an automation.

triggers:
  - trigger: time
    at: "08:00:00"
actions:
  - action: opendisplay.upload_image
    data:
      device_id: "your_device_id"
      image:
        media_content_id: "media-source://media_source/local/daily.png"
        media_content_type: "image/png"
tip

Use Home Assistant automations to generate or copy a new PNG before calling opendisplay.upload_image. The OpenDisplay integration then handles the BLE transfer to the display.

Optional: Custom Draw Payloads​

The OpenDisplay community also maintains a HACS integration with a drawcustom workflow for drawing text, icons, shapes, QR codes, images, plots, and progress bars directly from Home Assistant payloads.

Use this path when you specifically need draw-command layouts instead of uploading a prepared image.

OpenDisplay HACS Integration

In the Home Assistant visual editor, create an automation, add a time trigger, then add the OpenDisplay draw action and select the target device.

Using ESPHome Bluetooth Proxy​

An ESPHome Bluetooth Proxy extends Bluetooth coverage and improves reliability when the display is far from the Home Assistant host.

Prerequisites​

  • An ESP32 device, such as XIAO ESP32S3.
  • ESPHome installed in Home Assistant.
  • A USB data cable for the first flash.

Step-by-step Configuration​

Step 1. Connect the ESP32 device to the computer or Home Assistant host used for flashing.

Step 2. Create a new ESPHome device and use a Bluetooth Proxy configuration similar to the example below.

esphome:
  name: esps3-proxy
  friendly_name: ESP32S3 Bluetooth Proxy

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf

logger:
  level: INFO

esp32_ble_tracker:
  scan_parameters:
    active: true

bluetooth_proxy:
  active: true

api:
  encryption:
    key: "YOUR_ENCRYPTION_KEY"

ota:
  - platform: esphome
    password: "YOUR_OTA_PASSWORD"

wifi:
  ssid: "YOUR_WIFI_SSID"
  password: "YOUR_WIFI_PASSWORD"

captive_portal:

Step 3. Click Install in ESPHome and flash the firmware to the ESP32 device.

Step 4. After the ESP32 connects to Wi-Fi, add the discovered Bluetooth Proxy in Home Assistant.

Step 5. Keep the proxy close to the OpenDisplay device during image uploads.

When the proxy is working, Home Assistant shows the Bluetooth Proxy as connected and the ePaper display can be discovered through it.

Bonus: 3D Printed Mount​

For EN04 with the 7.3" Spectra panel, this community model provides an insert for the IKEA RODALM picture frame:

Resources​

Tech Support & Product Discussion​

Thank you for choosing our products! We are here to provide you with different support to ensure that your experience with our products is as smooth as possible. We offer several communication channels to cater to different preferences and needs.

Loading Comments...