Skip to main content

Work with OpenEPaperLink / OpenDisplay

The OpenEPaperLink (OEPL) ecosystem and the related OpenDisplay project are open-source firmware/protocol stacks for driving e-paper displays. Modern releases run over Bluetooth Low Energy — your phone, computer, or Home Assistant talks directly to the device, no dedicated 802.15.4 access point required.

This guide covers two Seeed hardware paths into that ecosystem:

  • XIAO ePaper Display Board EN04 — an integrated kit running the OpenDisplay firmware over BLE.
  • ePaper Breakout Board for Seeed Studio XIAO — a more modular DIY path using the OEPL Config Builder + OEPL Image Uploader together with a XIAO nRF52840 series board.

Both flows share a common philosophy (BLE configuration, web-based tooling, low-power), but the hardware and firmware/web tools differ. Pick the tab that matches your hardware throughout the article.

Compatible Hardware​

XIAO ePaper Display Board EN04
Get One Now 🖱️

Powered by XIAO nRF52840 Plus, the XIAO EN04 ePaper Display Board is the easiest way to get started with Bluetooth-enabled e-paper displays. Direct wireless control from your phone, computer, or Home Assistant — no dedicated AP needed.

Why use OpenEPaperLink / OpenDisplay?​

  • No access point required — uses Bluetooth Low Energy for direct communication. No 802.15.4 hardware needed.
  • Web-based tools — install firmware, configure devices, and upload images straight from your browser.
  • Purpose-built hardware support — XIAO nRF52840 family, EN04, EE04, etc.
  • Open source & free — actively developed on GitHub.
  • Multiple microcontrollers — nRF52840, ESP32-S3, ESP32-C6, ESP32-C3.
  • Simple flow — drag-and-drop firmware install, configure via web, no complex programming.
  • Battery efficient — optimised for low-power e-paper.
  • Active community — OpenDisplay Discord.

Step 1: Hardware Setup​

Step 1. Connect display to the driver board
Align the FPC cable with the connector on the XIAO EN04 board, then secure the latch.

tip

The metal side of the FPC cable should face upwards, otherwise no content will be displayed. Most displays have 1 and 50 printed on the FPC; align them with the matching numbers on the board.

Step 2. Attach the battery
Connect the battery cable to the JST connector on the driver board. Red wire to +, black to −.

caution

Double-check the polarity. Different batteries can have mixed wiring. Misaligned wires can be removed from the JST connector with a needle and re-inserted correctly.

Step 2: Flash the Firmware​

The easiest path is the OpenDisplay web installer.

Step 1. Open the OpenDisplay Web Installer in a browser.

Step 2. Choose Seeed EN04 4.26 or Seeed EN04 7.3 (or whichever preset matches your display) from the device list.

Step 3. Click Download Firmware and save NRF52840.uf2 locally.

Step 4. Connect the EN04 board via USB-C.

Step 5. Press the reset button twice consecutively. A USB drive will appear on your computer (the EN04 in DFU mode). Copy NRF52840.uf2 to that drive.

tip

If the installer fails:

  • Try a different USB cable (some are power-only — use a data cable).
  • Press the reset button twice on the EN04 to re-enter DFU mode.
  • Try a different USB port.

Step 6. Open the OpenDisplay Configuration Page and connect to your board.

If you selected Seeed EN04 4.26 or Seeed EN04 7.3, you'll see Auto Install to Device — the easiest way to configure the kit.

Step 7. Press the Connect button. Select the new device in the pairing dialog and press Pair.

Step 8. Press Auto Install to Device to save the configuration to the board.

After installation and configuration, the display shows a startup screen and is ready to receive content over BLE.

Step 3: Configure the Device over BLE​

The OpenDisplay configuration step from the previous flash workflow already handles this — your EN04 should now boot to the OpenDisplay startup screen and accept image uploads.

Step 4: Upload Images​

The OpenDisplay project has a dedicated browser-based uploader.

Step 1. Open the OpenDisplay BLE Tester.

Step 2. Click Connect and pick your OpenDisplay device from the BLE pairing dialog.

Step 3. Click Select Image and choose a file from your computer.

tip

For best results:

  • Use images that match your display resolution (the 7.3" panel is 800×480 px).
  • Black-and-white images render best on monochrome displays.
  • The tool automatically converts and dithers colour images.

Step 4. Click Upload Image. The e-paper refreshes and your image appears.

You can also create custom content with image editors (GIMP, Photoshop), Python + Pillow scripts, web-based image generators, or a Home Assistant integration (covered below).

Home Assistant Integration (EN04 / OpenDisplay only)​

tip

To integrate with Home Assistant, you need a Bluetooth-capable setup:

  • Home Assistant Green (built-in Bluetooth)
  • Home Assistant OS / Supervised on hardware with Bluetooth support
  • ESPHome Bluetooth Proxy (recommended for better range — see below)

Note: Shelly devices acting as Bluetooth proxies do not support active connections required by OpenDisplay, so they cannot be used.

Step 1. Install the integration

For detailed installation instructions, see the OpenDisplay Home Assistant Integration repository.

The easiest path is via HACS (Home Assistant Community Store):

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

info

After installing the custom integration via HACS, restart Home Assistant for the changes to take effect.

Step 2. Add the discovered device

Once Home Assistant is back up:

  1. Go to Settings → Devices & services.
  2. Find your OpenDisplay device under Discovered.
  3. Click Add.
  4. Set the Name and Area, then click Finish.

A new image appears on the display, confirming Home Assistant is connected.

Automating display updates​

The primary service is open_epaper_link.drawcustom, which lets you draw text, icons, images, and shapes. See the drawcustom docs for the full type/parameter reference.

Example 1 — display sensor data (Visual Editor)​

  1. Go to Settings → Automations & Scenes and click Create Automation.
  2. Add a Time Pattern trigger (e.g. every 10 minutes).
  1. Add an Action → OpenDisplay: Draw Custom Image.
  1. Pick the target device.
  1. In the Payload field, enter the layout configuration:
- type: "text"
  value: "Living Room"
  x: "50%"
  y: 50
  anchor: "mm"
  size: 70
  color: "red"
- type: "icon"
  value: "mdi:thermometer"
  x: "35%"
  y: 200
  anchor: "mm"
  size: 100
  color: "black"
- type: "text"
  value: "{{ states('sensor.living_room_temperature') }}°C"
  x: "65%"
  y: 200
  anchor: "mm"
  size: 100
  color: "black"
- type: "icon"
  value: "mdi:water-percent"
  x: "35%"
  y: 350
  anchor: "mm"
  size: 100
  color: "black"
- type: "text"
  value: "{{ states('sensor.living_room_humidity') }}%"
  x: "65%"
  y: 350
  anchor: "mm"
  size: 100
  color: "black"
Entity IDs

The entity IDs above (e.g. sensor.living_room_temperature) are placeholders. Replace them with your actual Home Assistant entity IDs.

Example 2 — countdown timer (YAML)​

For advanced users, edit the automation as YAML. This example counts down to a date and renders the result on the display.

alias: Update ePaper Display - Countdown
description: Displays days until Christmas
triggers:
  - at: "00:00:00"
    trigger: time
actions:
  - variables:
      days_left: "{{ (as_datetime('2025-12-24').date() - now().date()).days }}"
  - action: open_epaper_link.drawcustom
    data:
      background: white
      payload:
        - type: text
          value: "{{ 'Christmas Countdown' if days_left > 0 else '' }}"
          x: 50%
          "y": 50
          anchor: mm
          size: 60
          color: black
        - type: text
          value: "{{ days_left if days_left > 0 else '' }}"
          x: 50%
          "y": 240
          anchor: mm
          size: 250
          color: red
        - type: text
          value: >-
            {{ 'Day Left' if days_left == 1 else ('Days Left' if days_left > 0
            else '') }}
          x: 50%
          "y": 430
          anchor: mm
          size: 60
          color: black
        - type: text
          value: "{{ 'It''s Christmas!!!' if days_left == 0 else '' }}"
          x: 50%
          "y": 50%
          anchor: mm
          size: 100
          color: red
    target:
      device_id: 2ad706d4aa7c657b6fe99a733cef2253
Device ID

The device_id above is a placeholder. Find your actual device ID by:

  1. Creating a new automation in the Visual Editor.
  2. Selecting your OpenDisplay device in the action settings.
  3. Switching to YAML mode (three-dot menu in the action card).
  4. Copying the device_id and pasting it into your automation.

Bonus​

Looking for a stylish way to mount the display? This 3D-printed insert fits the IKEA RODÅLM picture frame and makes mounting easy:

Troubleshooting​

Firmware installation issues​

Problem: PC doesn't detect a new USB drive after connecting the board.

  • Try a different USB cable (data cable, not power-only).
  • Press the reset button twice after connecting the board.

Configuration issues​

Problem: The board isn't discovered.

  • Verify the LED on the board blinks — confirms the device is powered.
  • Try rebooting the board.
  • Re-flash the firmware.

Problem: Display shows nothing after firmware installation.

  • Verify the FPC cable orientation (metal contacts facing up).
  • Confirm the cable is fully inserted and latched.
  • Re-check the configuration via the configurator.

Bluetooth connection issues​

Problem: Cannot find the device in Bluetooth pairing.

  • Ensure the device is powered on and the firmware is installed.
  • Move closer (within 2–3 m).
  • Confirm Bluetooth is enabled on your computer / phone.

Problem: Connection drops during image upload.

  • Stay close to the device during upload.
  • Charge the battery sufficiently or power via USB.
  • Avoid uploading very large images.
  • Try again in a less congested Bluetooth environment.

Battery and power issues​

Problem: Short battery life.

  • Configure longer sleep intervals in the configurator.
  • Always run the latest firmware (each release improves power use).
  • Reduce display refresh frequency.
  • Verify the battery is fully charged (4.2 V for Li-Po).

Problem: Device won't charge.

  • Check polarity (red = +, black = −).
  • Verify the charging cable provides ≥500 mA.
  • Ensure the power switch is ON.
  • Try a different USB power source.

Home Assistant / Integration issues​

Problem: "Insufficient connection slots" when adding devices via Raspberry Pi + HA.

This often happens because the Raspberry Pi's built-in Bluetooth adapter has hit its concurrent connection limit.

Error: Insufficient connection slots Example of the "Insufficient connection slots" message.

Recommended fix: use an ESP32 device (e.g. XIAO ESP32S3) as an ESPHome Bluetooth Proxy. This offloads the Bluetooth connection from the Pi, providing more stable "slots" for your e-paper displays.

Using ESPHome Bluetooth Proxy​

If you hit "Insufficient connection slots" using a Raspberry Pi with Home Assistant, an ESPHome Bluetooth Proxy is the most effective fix.

Prerequisites​

  • An ESP32 device (e.g. XIAO ESP32S3).
  • ESPHome installed in Home Assistant.
  • A USB data cable to connect the ESP32 to your Pi (for the first flash).

Step-by-step configuration​

  1. Connect the device — plug the XIAO ESP32S3 into a USB port on your Raspberry Pi.

  2. Create a new ESPHome configuration with the YAML below:

    ESPHome YAML Configuration

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

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

    # 1. Enable detailed logging (useful for debugging)
    logger:
      level: VERY_VERBOSE

    # 2. Core: Enable Bluetooth Tracker
    esp32_ble_tracker:
      scan_parameters:
        active: true

    # 3. Core: Enable Bluetooth Proxy
    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:

  3. Install / flash:

    • Pick Install → Plug into this computer (or the device running ESPHome).

      ESPHome flashing process

    • On first flash, ESPHome may download the esp-idf toolchain. Make sure your environment has stable Internet access to GitHub.

    • After compilation, the logs show "WiFi connected" and Bluetooth scan activity.

  4. Add the proxy to Home Assistant:

    • Home Assistant will automatically discover the new Bluetooth Proxy.
    • Once added, your e-paper displays should be discoverable through the proxy without the "insufficient slots" error.

    Success: Bluetooth Proxy connected

    Success: e-paper display added

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...