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:

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

Encryption

OpenDisplay devices can be configured to require AES-128 encryption for all Bluetooth Low Energy communication.

If your device has encryption enabled, the setup flow will ask for a 32-character hexadecimal encryption key after the initial connection attempt. The key is shown on the display when the device boots.

If the encryption key changes after the device has been set up, Home Assistant will prompt you to re-enter the key.

Supported functionality

The OpenDisplay integration provides the following entities.

Button events

OpenDisplay Flex devices with configured physical inputs show up as 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] entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] in Home Assistant. One 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] entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] is created for each physical button.

• button_down: Fires when the button is pressed.
• button_up: Fires when the button is released.

triggers:
  - trigger: state
    entity_id: event.opendisplay_1234_button_1
    attribute: event_type
    to: button_down
actions:
  - action: light.turn_on
    target:
      entity_id: light.my_light

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.

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

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.

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

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.