2026.9.2
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. You can upload images to the display from automations and scripts.

Supported devices

Any device running the OpenDisplay firmware is supported. 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, such as 10.3-inch monochrome panels, are not supported because of connector incompatibility.
  • Shelly Bluetooth proxies do not support active Bluetooth Low Energy connections and cannot upload images.

Prerequisites

  • A working Bluetooth setup that supports active connections, for example:
    • Built-in Bluetooth adapter
    • ESPHome Bluetooth proxy with firmware 2022.9.3 or later
  • An OpenDisplay device that is 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.

Encryption

OpenDisplay devices can require AES-128 encryption for Bluetooth Low Energy communication. If your device requires encryption, the setup flow asks for the 32-character hexadecimal encryption key after the initial connection attempt. The device shows the key when it starts.

Tip

To avoid typing the key, scan the QR code on the device display. The page that opens shows the encryption key. Copy the key, and paste it into Home Assistant.

If the encryption key changes after you set up the device, Home Assistant prompts you to enter the new key.

Supported functionality

The OpenDisplay integration provides the following entities.

Binary sensors

  • Connectivity: Reports whether Home Assistant has recently received a Bluetooth Low Energy advertisement from the device.

Sensors

Devices configured with OpenDisplay Flex, including devices set up with an OpenDisplay Toolbox preset, can provide the following diagnostic sensors. Other OpenDisplay devices provide only the Connectivity binary sensor.

  • Temperature: The device chip temperature. Disabled by default.
  • Battery voltage: The voltage of the attached battery. Available when the device uses battery or solar power. Disabled by default.
  • Battery: The battery charge as a percentage. Available when the device uses battery or solar power.

Button events

OpenDisplay Flex devices with configured physical inputs provide eventEvery time something happens in Home Assistant, an event is fired. There are different types of events, such as state change events, when an action was triggered, or the time changed. All entities produce state change events. Every time a state changes, a state change event is produced. Events can be used to trigger automations or scripts. For example, you can trigger an automation when a light is turned on, then a speaker turns on in that room. Events can also be used to trigger actions in the frontend. For example, you can trigger an action when a button is pressed. [Learn more] entities. Home Assistant creates one event entity for each physical button.

  • button_down: The button was pressed.
  • button_up: The button was released.

Note

Home Assistant detects button events by comparing Bluetooth Low Energy advertisements, so it does not need an active Bluetooth connection. A press and release that happens between two advertisements might not be detected.

List of actions

The OpenDisplay integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following actions. Each link below opens a dedicated page with examples, parameters, and a step-by-step UI walkthrough.

  • Upload image (opendisplay.upload_image) Uploads an image to an OpenDisplay device.

For an overview of every action across all integrations, see the actions reference.

OpenDisplay automation examples

You can use automations to show information or images at useful times.

Tip

You don’t need to edit YAML to use these examples. Copy a YAML snippet from this page, open the automation editor in Home Assistant, and press Ctrl+V (or Cmd+V on Mac). Home Assistant automatically converts the pasted YAML into the visual editor format, whether it’s a full automation, a single trigger, a condition, or an action.

Automation: Show a daily image every morning

Show an image from your media folder on the display each morning.

  • Trigger: Time: 07:00:00
  • Action: OpenDisplay: Upload image
    • Device: Your OpenDisplay device
    • Image: The image to show
Show example YAML
AutomationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more] 
alias: "Show the daily image on the display"
triggers:
  - trigger: time
    at: "07:00:00"
actions:
  - action: opendisplay.upload_image
    data:
      device_id: "a1b2c3d4e5f6"
      image:
        media_content_id: "media-source://media_source/local/daily.png"
        media_content_type: "image/png"

Automation: Show an image at sunset

Change the display image when the sun sets.

  • Trigger: Sun: sunset
  • Action: OpenDisplay: Upload image
    • Device: Your OpenDisplay device
    • Image: The image to show
Show example YAML
AutomationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more] 
alias: "Show a sunset image on the display"
triggers:
  - trigger: sun
    event: sunset
actions:
  - action: opendisplay.upload_image
    data:
      device_id: "a1b2c3d4e5f6"
      image:
        media_content_id: "media-source://media_source/local/sunset.png"
        media_content_type: "image/png"

Known limitations

  • Bluetooth Low Energy range is limited. Displays far from a Bluetooth adapter can have unreliable transfers.
  • Starting a new image upload cancels an upload that is already in progress for the same integration entry.

Troubleshooting

Device is not discovered

Resolution

Check that the Bluetooth integration is set up and working. Then, confirm that your OpenDisplay device is powered on and within range of your Home Assistant host or an ESPHome Bluetooth proxy.

Authentication fails

Description

The encryption key stored in Home Assistant no longer matches the key on the device.

Resolution

Go to Settings > Devices & services > OpenDisplay, and select Re-authenticate to enter the correct key.

Image upload fails with a connection error

Description

Bluetooth Low Energy connections can drop at longer ranges.

Resolution

Move the display closer to your Bluetooth adapter. If you use an ESPHome Bluetooth proxy, check that it has a stable Wi-Fi connection.

Image appears rotated or upside down

Description

Home Assistant applies EXIF orientation automatically before processing the image.

Resolution

If the image is still rotated, use the Rotation option in the Upload image action to correct it.

Removing the integration

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. From the list of devices, select the integration instance you want to remove.
  3. Next to the entry, select the three dots menu. Then, select Delete.