Home ▸ Integrations

OpenDisplay

The OpenDisplay integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] lets you use OpenDisplay e-paper displays with Home Assistant over Bluetooth Low Energy.

Supported devices

Any device running the OpenDisplay firmware. For a full list of supported boards and displays, see the OpenDisplay hardware compatibility page.

Unsupported devices

Displays with 40-pin or 60-pin connectors (for example, 10.3” monochrome panels) are not supported due to connector incompatibility.
Shelly Bluetooth proxies do not support active BLE connections and cannot be used to upload images.

Prerequisites

A working Bluetooth setup that supports active connections:
- Built-in adapter: Supported
- ESPHome Bluetooth proxy: Supported (firmware 2022.9.3 or later)
- Shelly Bluetooth proxy: Not supported
An OpenDisplay device powered on and within Bluetooth range.

Configuration

To add the OpenDisplay device to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

Browse to your Home Assistant instance.
Go to Settings > Devices & services.
In the bottom right corner, select the Add Integration button.
From the list, select OpenDisplay.
Follow the instructions on screen to complete the setup.

Once the Bluetooth integration is active, OpenDisplay devices are discovered automatically.

Actions

Action: Upload image

The opendisplay.upload_image action allows you to upload an image to a display. The image is resized and dithered to match the display’s resolution and color palette.

Data attribute	Description	Required	Default
`device_id`	The OpenDisplay device to upload the image to.	Yes	-
`image`	The image to upload, selected from a media source.	Yes	-
`rotation`	Clockwise rotation in degrees: 0, 90, 180, or 270.	No	0
`dither_mode`	Dithering algorithm for converting to the display’s color palette.	No	Burkes
`refresh_mode`	Refresh mode to use. Full clears ghosting but is slower; fast is not supported on all displays.	No	Full
`fit_mode`	How the image is fitted to the display.	No	Contain
`tone_compression`	Dynamic range compression strength as a percentage (0–100). Omit to use automatic adjustment.	No	Automatic

Refresh modes:

Full: Clears ghosting but takes longer
Fast: Faster refresh, not supported on all displays

Dither modes: None, Burkes, Ordered, Floyd-Steinberg, Atkinson, Stucki, Sierra, Sierra Lite, Jarvis, Judice, and Ninke

Fit modes:

Contain: Scale to fit within the display, pad remaining space with white
Cover: Scale to fill the display, crop edges that overflow
Stretch: Distort to fill the exact display dimensions
Crop: Center-crop at native resolution without scaling

Examples

Uploading an image

Upload an image from local media

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"

Updating the display on a schedule

You can use an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more] to refresh the display at a set time each day.

Update display daily at 8:00 AM

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"

Known limitations

BLE range is limited. Displays far from a Bluetooth adapter may experience unreliable transfers.
Starting a new upload while one is already in progress cancels the ongoing transfer.

Troubleshooting

Device is not discovered

Check that the Bluetooth integration is set up and working, then confirm your OpenDisplay device is powered on and in range of your Home Assistant host or a Bluetooth proxy.

Upload fails with a connection error

BLE connections can drop at longer ranges. Try moving the display closer to your Bluetooth adapter. If you are using an ESPHome proxy, check that it has a stable Wi-Fi connection.

Image appears rotated or upside down

The integration applies EXIF orientation automatically. If the result is still rotated, use the rotation parameter in the Upload image action to correct it manually.