Skip to main content

py-opendisplay

PyPI Python License Tests Lint Ruff mypy

Python library for communicating with OpenDisplay BLE e-paper displays.

Installation

pip install py-opendisplay

Quick Start

Option 1: Using MAC Address

from opendisplay import OpenDisplayDevice
from PIL import Image

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    image = Image.open("photo.jpg")
    await device.upload_image(image)

Option 2: Using Device Name (Auto-Discovery)

from opendisplay import OpenDisplayDevice, discover_devices
from PIL import Image

# List available devices
devices = await discover_devices()
print(devices)  # {"OpenDisplay-A123": "AA:BB:CC:DD:EE:FF", ...}

# Connect using name
async with OpenDisplayDevice(device_name="OpenDisplay-A123") as device:
  image = Image.open("photo.jpg")
  await device.upload_image(image)

New entry point: opendisplay.connect()

connect() returns a Device that describes the device it connected to, for firmware 2.x and 3.0 alike. It also connects to a device that has no config yet.

import opendisplay

async with opendisplay.connect("AA:BB:CC:DD:EE:FF") as dev:
    print(dev.profile.generation, dev.profile.width, dev.profile.height, dev.profile.configured)
    config = await dev.config.read()   # raises NoStoredConfigError when the device has none

await dev.config.clear() erases the stored config (CONFIG_CLEAR 0x0045) and refreshes the profile. A claimed firmware 3.0 device keeps its reset-pin settings (the 0x27 packet).

dev.profile is built from the firmware version, the stored config and, on firmware 3.0 and up, the device identity. Everything not yet on the new surface is reached through dev.legacy, the wrapped OpenDisplayDevice. OpenDisplayDevice remains supported.

Drive modes (firmware 3.0)

A firmware 3.0 config can declare several drive modes for a panel, for example colour16, which drives a BWRY panel in three passes to show 16 colours. dev.profile.drive_mode_names lists them; dev.display.show() uploads in one:

async with opendisplay.connect("AA:BB:CC:DD:EE:FF") as dev:
    print(dev.profile.drive_mode_names)        # the modes the config declares, e.g. colour16
    await dev.display.show(image, mode="colour16")

Without mode, show() is upload_image() with the same options. If the device runs a different mode than the one asked for, DriveModeSubstitutedError is raised and nothing is uploaded.

CLI

Run without installing (requires uv):

uvx --from "py-opendisplay[cli]" opendisplay --help

Or after pip install py-opendisplay[cli]:

# Discover nearby devices
opendisplay scan

# Read device info (size, color, firmware, board)
opendisplay info --device AA:BB:CC:DD:EE:FF

# Upload an image
opendisplay upload --device AA:BB:CC:DD:EE:FF photo.jpg
opendisplay upload --device AA:BB:CC:DD:EE:FF photo.jpg --fit cover --refresh-mode fast

# Reboot the device
opendisplay reboot --device AA:BB:CC:DD:EE:FF

# Export / write device configuration
opendisplay export-config --device AA:BB:CC:DD:EE:FF config.json
opendisplay write-config --device AA:BB:CC:DD:EE:FF config.json

# Upload in a drive mode the config declares (firmware 3.0; `info` lists them)
opendisplay upload --device AA:BB:CC:DD:EE:FF photo.jpg --mode colour16

# Move a device to firmware 3.0 (see "Moving to firmware 3.0" below)
opendisplay backup-config --device OD4064C9 backup.json
opendisplay migrate --device OD4064C9 --dry-run
opendisplay migrate --device OD4064C9

# Set up a 3.0 display, or move a 2.x one to 3.0 (see "Setting up a display" below)
opendisplay setup --device OD4064C9 --claim
opendisplay upgrade --device OD5A2F4C --no-key --state-file en05.json

# Send a firmware 3.x image (see "Firmware 3.x updates" below)
opendisplay update --device OD4064C9 --file opendisplay-s3-n32r8-extuart-app.bin

# Debugging: send one command frame and print the reply as hex (nothing checks it)
opendisplay raw --device OD4064C9 --cmd 0043
opendisplay raw --device OD4064C9 --cmd 000f --no-reply

# Firmware 3.0 device keys (see "Firmware 3.0 security" below)
opendisplay claim --device OD4064C9
opendisplay rotate-key --device OD4064C9
opendisplay unclaim --device OD4064C9
opendisplay key export --device OD4064C9
opendisplay key import --device OD4064C9 0102030405060708090a0b0c0d0e0f10

Firmware 2.x devices with encryption require --key HEX (32 hex characters). Firmware 3.0 keys live in a key store, ~/.config/opendisplay/keys.json by default (--key-store PATH to change it). Pass -v / --verbose for debug logging.

Every command that talks to a display reads the key store, so a claimed firmware 3.0 display works with all of them once its key is there (from claim, or key import).

export-config keeps config packets this library does not recognise in an unparsed_tail field, so writing the file back restores them. If a file has lost that field (for example after editing it in another tool) and the device has such packets, write-config refuses to write. Pass --keep-unknown-packets to carry the device's packets over unchanged, or --discard-unknown-packets to delete them.

Image Fitting

Images are automatically fitted to the display dimensions. Control how aspect ratio mismatches are handled with the fit parameter:

from opendisplay import OpenDisplayDevice, FitMode
from PIL import Image

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    image = Image.open("photo.jpg")

    # Default: scale to fit, pad with white (no distortion, no cropping)
    await device.upload_image(image, fit=FitMode.CONTAIN)

    # Scale to cover display, crop overflow (no distortion, fills display)
    await device.upload_image(image, fit=FitMode.COVER)

    # Distort to fill exact dimensions
    await device.upload_image(image, fit=FitMode.STRETCH)

    # No scaling, center-crop at native resolution (pad if smaller)
    await device.upload_image(image, fit=FitMode.CROP)
Mode Aspect Ratio Fills Display Content Loss
CONTAIN (default) Preserved No (white padding) None
COVER Preserved Yes Edges cropped
STRETCH Distorted Yes None (but distorted)
CROP Preserved Depends on source size Edges cropped if larger

Image Rotation

Rotate source images before fitting/encoding using the rotate parameter:

from opendisplay import OpenDisplayDevice, Rotation
from PIL import Image

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    image = Image.open("photo.jpg")
    await device.upload_image(image, rotate=Rotation.ROTATE_90)

Rotation is applied before fit, so crop/pad behavior matches the rotated orientation. Rotation angles use clockwise semantics (ROTATE_90 = 90 degrees clockwise).

Dithering Algorithms

E-paper displays have limited color palettes, requiring dithering to convert full-color images. py-opendisplay supports 9 dithering algorithms with different quality/speed tradeoffs:

Available Algorithms

  • none - Direct palette mapping without dithering (fastest, lowest quality)
  • ordered - Bayer/ordered dithering using pattern matrix (fast, visible patterns)
  • burkes - Burkes error diffusion (default, good balance)
  • floyd-steinberg - Floyd-Steinberg error diffusion (most popular, widely used)
  • sierra-lite - Sierra Lite (fast, simple 3-neighbor algorithm)
  • sierra - Sierra-2-4A (balanced quality and performance)
  • atkinson - Atkinson (designed for early Macs, artistic look)
  • stucki - Stucki (high quality, wide error distribution)
  • jarvis-judice-ninke - Jarvis-Judice-Ninke (highest quality, smooth gradients)

Usage Example

from opendisplay import OpenDisplayDevice, RefreshMode, DitherMode
from PIL import Image

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    image = Image.open("photo.jpg")

    # Use Floyd-Steinberg dithering
    await device.upload_image(
        image,
        dither_mode=DitherMode.FLOYD_STEINBERG,
        refresh_mode=RefreshMode.FULL
    )

Comparing Dithering Modes

To preview how different dithering algorithms will look on your e-paper display, use the img2lcd.com online tool. Upload your image and compare the visual results before choosing an algorithm.

Quality vs Speed Tradeoff:

Category Algorithms
Fastest / Lowest Cost none, ordered, sierra-lite
Best Cost-to-Quality floyd-steinberg, burkes, sierra
Heavy / Rarely Worth It stucki, jarvis-judice-ninke
Stylized / High Contrast atkinson

Color Palettes

py-opendisplay automatically selects the best color palette for your display based on its hardware specifications.

Measured and Idealised Palettes

Measured palettes (default) use colours measured on real panels:

  • Spectra 6 7.3" (ep73_spectra_800x480), also used for the 13.3" split panel (T133A01)
  • 3.97" BWRY (ep397yr_800x480)

Idealised palettes use the pure colours of the display's colour scheme (black, white, red, ...). Every other display uses these.

To add a measured palette for your panel, see docs/palettes.md.

In both, the pure inks are named, so a colour that asks for an ink (such as #000000 text) comes out as that ink, solid.

Disabling Measured Palettes

To use the idealised palette even where a measured one exists (useful for testing or comparison):

from opendisplay import OpenDisplayDevice

async with OpenDisplayDevice(
    mac_address="AA:BB:CC:DD:EE:FF",
    use_measured_palettes=False
) as device:
    await device.upload_image(image)

Tone and Gamut

Two opt-in strengths from 0.0 (off, the default) to 1.0:

  • tone lifts the black point to bring out shadow detail, at the cost of the panel's deepest black.
  • gamut pulls colours the panel can't show towards ones it can before dithering.
async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    # Default: both off
    await device.upload_image(image)

    # Full black-point lift and gamut compression for a photo
    await device.upload_image(image, tone=1.0, gamut=1.0)

Refresh Modes

Control how the display updates when uploading images:

from opendisplay import RefreshMode

await device.upload_image(
    image,
    refresh_mode=RefreshMode.FULL  # Options: FULL, FAST
)

Available Modes

Mode Description
RefreshMode.FULL Full display refresh (default). Cleanest image quality; eliminates ghosting; slower (~5–15 seconds).
RefreshMode.FAST Fast refresh. Quicker updates; may show slight ghosting. Only supported on some B/W displays.

Note: Fast refresh support varies by display hardware. Color and grayscale displays only support full refresh.

Partial Updates

B/W (MONO) panels with partial_update_support in their device config can update just the changed region of the screen using the differential 0x76 protocol — no full-refresh flash. Partial updates are opt-in: create a PartialState and pass it to every upload. The first upload is always full; subsequent uploads diff against the previous frame and go partial when possible.

from opendisplay import OpenDisplayDevice, PartialState

state = PartialState()

async with OpenDisplayDevice(device_name="OD1234AB", encryption_key=key) as device:
    await device.upload_image(dashboard_frame(1), state=state)  # full upload
    await device.upload_image(dashboard_frame(2), state=state)  # partial (flicker-free)
    await device.upload_image(dashboard_frame(3), state=state)  # partial

The library handles all preconditions and falls back to a full upload automatically (unsupported panel, etag mismatch after another client wrote the screen, firmware NACK, no previous frame). state is mutated in place; persist it across processes with state.to_bytes() / PartialState.from_bytes().

Practical notes:

  • Blacks rendered by the partial waveform are slightly lighter than a full refresh. Do a periodic full refresh (e.g. every 10-50 updates, or on a schedule) by passing state=None once — this also removes any ghosting.
  • Requires reference firmware ≥ 1.8 and partial_update_support: 1 in the device config; the panel itself must support differential refresh.
  • Some panels (e.g. EP426 / Seeed EN05) require the partial stream to cover the full panel: firmware white-fills the controller RAM at partial start, so content outside the region would be erased (Firmware#80). Device configs signal this with partial_update_support: 2 (PartialUpdateSupport.FULL_FRAME), and the library expands the region to the whole screen automatically — still flicker-free. Older device configs may still report 1 on affected panels; update the config to 2 to get correct behavior.

Advanced Features

Device Interrogation

Query the complete device configuration including hardware specs, sensors, and capabilities:

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    # Automatic interrogation on first connect
    config = device.config
    
    print(f"IC Type: {config.system.ic_type_enum.name}")
    print(f"Displays: {len(config.displays)}")
    print(f"Sensors: {len(config.sensors)}")
    print(f"WiFi config present: {config.wifi_config is not None}")

Skip interrogation if the device info is already cached:

# Provide cached config to skip interrogation
device = OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF", config=cached_config)

# Or provide minimal capabilities
capabilities = DeviceCapabilities(296, 128, ColorScheme.BWR, 0)
device = OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF", capabilities=capabilities)

Firmware Version

Read the device firmware version including git commit SHA:

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    fw = await device.read_firmware_version()
    print(f"Firmware: {fw['major']}.{fw['minor']}")
    print(f"Git SHA: {fw['sha']}")

    # Example output:
    # Firmware: 0.65
    # Git SHA: e63ae32447a83f3b64f3146999060ca1e906bf15

Writing Configuration

Modify device settings and write them back to the device:

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    # Read current config
    config = device.config

    # Modify settings
    config.displays[0].rotation = 1

    # Write config back to device
    await device.write_config(config)

    # Reboot to apply changes
    await device.reboot()

Note: Many configuration changes (rotation, pin assignments, IC type) require a device reboot to take effect. write_config() requires system, manufacturer, power, and at least one display. When present, optional wifi_config (packet 0x26) is preserved on write.

JSON Import/Export

Export and import configurations using JSON files compatible with the Open Display Config Builder web tool:

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    # Export current config to JSON
    device.export_config_json("my_device_config.json")

# Import config from JSON file
config = OpenDisplayDevice.import_config_json("my_device_config.json")

# Write imported config to another device
async with OpenDisplayDevice(mac_address="BB:CC:DD:EE:FF:00") as device:
    await device.write_config(config)
    await device.reboot()

import_config_json() raises ValueError if required packets (system, manufacturer, power) or all display packets are missing. JSON packet id 38 (wifi_config / TLV 0x26) is supported for import/export.

Moving to firmware 3.0

Firmware 3.0 drives the panel from data in the device's config. A device updated from 2.x needs that data before it can draw; dev.profile.needs_migration says so. The CLI does the move:

opendisplay backup-config --device OD4064C9 backup.json   # never overwrites a file
opendisplay migrate --device OD4064C9 --dry-run           # show what would change
opendisplay migrate --device OD4064C9                     # write it, then read it back
  • --panel ID picks the panel (panel_ic_type) when the config does not say which one it is.
  • --yes-untested writes drive data not yet seen working on real glass without asking.
  • --from-backup FILE restores a backup instead of starting from the device's config. A backup that carries secrets (the 2.x key, a WiFi password, FindMy keys) is written inside the session of a claimed device; an unclaimed device does not store secrets, so it is refused there unless --strip-secrets writes the backup without them. Claim the display first to keep them.

In Python, dev.config.plan_migration() returns the plan and dev.config.write(config) writes a config and reads it back.

Firmware 3.0 security (claiming a display)

Firmware 3.0 replaces the 2.x key with a key the display generates itself. A display without a key is open, as before. Claiming gives it a key that only you hold:

  1. Put the display in claim mode: switch it off and on, wait about 5 seconds, switch it off and on again. It shows SETUP MODE. Leave it off for at least 2 seconds each time.
  2. Run opendisplay claim --device OD4064C9. The display draws a 6-digit code (a colour panel can take a minute); type it in. If a code was already showing before you started, stop: someone else is claiming the display.
  3. The new key is saved in the key store. Every later connect opens an encrypted session with it.

A wrong code is never sent to the display, and nothing is kept. If the key is lost, factory-reset the display with five quick power cycles.

In Python, pass a key store; connect() reads the display's security state before any handshake and picks the scheme itself (2.x, firmware 3.0 unclaimed, or firmware 3.0 claimed):

import opendisplay
from opendisplay.sec2.keystore import JsonFileKeyStore

store = JsonFileKeyStore()   # ~/.config/opendisplay/keys.json, mode 0600

async with opendisplay.connect(name="OD4064C9", key_store=store) as dev:
    if dev.security.status.claim_mode:
        flow = await dev.security.claim()
        await flow.begin()
        code = await flow.exchange_nonces()     # the display now draws the code
        await flow.confirm(input("Code: "))     # checked here before anything is sent
    await dev.display.show(image)               # sealed in the session
  • Keys. encryption_key= takes a DeviceKey (firmware 3.0), a LegacyKey (2.x) or plain bytes, tried with whichever scheme the display speaks. A key is stored as confirmed only after it opens a session, and a key the display refuses is never deleted. At most three keys are tried.
  • A key migrated from 2.x is replaced by a display-generated one right after the first session. Pass rotate_legacy_key=False to keep it.
  • dev.security: status, claim(), rotate_key(), unclaim(), use_without_key() (leave claim mode and use the display open).
  • Several clients (Home Assistant, the web tool, another computer) share one key per display. Move it with opendisplay key export / opendisplay key import (hex, or an opendisplay.org/l/ link that carries the key). Anyone with the key can change the display, update its firmware, and read its WiFi password and FindMy keys. After rotate-key, every other client needs the new key.
  • Errors say what to do: NotInClaimModeError (power-cycle twice), Sec2KeyRequiredError (no key opened a session; import it, or factory-reset), Sec2CodeMismatchError, DeviceLockedError, RateLimitedError, Sec2BusyError, and Sec2RequiredError when a 2.x-only API meets a claimed display.
  • LAN: claiming, sessions and key changes run over Bluetooth only. TLS with a firmware 3.0 key is not supported yet.

Firmware 3.x updates

dev.firmware.update(image) updates a device that already runs firmware 3.x, over Bluetooth. The method follows the device: mcumgr SMP on ESP32, nRF52840 and nRF54 (built in, no extra needed), the Silicon Labs AppLoader on a BG22 (the silabs-ota extra). nRF52811 and Telink are not supported yet. The first move from 2.x to 3.0 is a different job; see "Moving to firmware 3.0".

from opendisplay.firmware import ReleaseManifest, UpdateOutcome

manifest = ReleaseManifest.parse(json.loads(manifest_json))  # the release's manifest.json
board = manifest.board("s3-n32r8-extuart")                   # ESP32: the board must be named
image = Path(board.ble_ota_files[0]).read_bytes()            # downloaded from the same release

async with opendisplay.connect(name="OD4064C9") as dev:
    if not dev.firmware.can_roll_back:
        ...  # a BG22 cannot undo a bad image by itself: ask the user first
    result = await dev.firmware.update(image, on_progress=lambda done, total: print(done, total))
    print(result.outcome, result.version_before, result.version_after, result.detail)
  • Outcomes: UPDATED, ROLLED_BACK (the new image did not start and the device is back on its old one), WAITING_IN_BOOTLOADER (a BG22 in its AppLoader, advertising as OTA, waiting for a .gbl), and NOT_UPDATED (for example a transfer cut off part-way, which leaves the old image running). detail says what to do next.
  • Refused before anything is sent (UpdateRefusedError): firmware 2.x, claim mode (claim the display or call dev.security.use_without_key() first), and an image for another target or chip.
  • Security: an unclaimed display takes an update as it is. A claimed one is unlocked with a sealed ENTER_DFU on its session first, and again after the reboot, to read the image slots (the reboot locks SMP again); dev.firmware.enable_ota() does only that step.
  • Confirmation: after the reboot, update() reconnects and sends one command, which makes the new image permanent on ESP32 and nRF. Until then, a reset returns the device to its old image.
  • Time: an ESP32-S3 image (1.2 MB) takes about 47 s from a Mac, and the reboot and redraw that follow take up to 3 minutes. update() waits for both. macOS works for SMP updates.
  • Version shown: ESP32 3.x builds show 3.0.0 on the boot screen and in read_firmware_version() whatever they run (Firmware_Unified#103). update() reads the version over SMP, which is correct.
  • Home Assistant passes find_device= (a coroutine giving the BLEDevice for an address), so the update works through an ESPHome Bluetooth proxy.

Setting up a display (setup and upgrade)

opendisplay setup takes a display from wherever it stands to set up, one step at a time:

  • No config, or a config that needs migration: configure the panel.
  • Check the panel: draw a test pattern and ask whether it looks right.
  • Key: claim it, or use it without a key.
  • A claimed display with a 2.x key: rotate that key.

It prints a line as each step starts. When it wrote the config itself, it always checks the panel afterwards, with a key or without.

opendisplay upgrade is the same flow for a 2.x display:

  1. Back up the config to --backup (default opendisplay-backup-<device>.json). The backup holds the key, so it is written with mode 0600 and never over an earlier file.
  2. Install 3.0. A BG22 is installed over Bluetooth through its AppLoader, after you type yes, since it has no old image to return to. A board that needs USB pauses: the command names the files and the website flasher and saves its state to --state-file.
  3. Go on. Once the display runs 3.0, run the same command again. It goes on from the state file, restores the config from the backup, then sets the display up.
opendisplay upgrade --device OD5A2F4C --no-key --state-file en05.json
# ... install over USB as it says, then (the display may advertise under a new name):
opendisplay upgrade --device ODD2292B --no-key --state-file en05.json

--claim / --no-key decide the key, otherwise it asks. --board names the board when several share a chip (ESP32-S3), --config FILE gives a config when the display has none and there is no backup, --release TAG picks a Firmware_Unified release (default: the latest; files are checked against its manifest and cached), and --yes-untested writes drive data not yet seen on a panel without asking.

In Python the flow is opendisplay.setup:

  • device_state() and plan_setup() say where a device stands and which steps it needs.
  • SetupRun performs those steps. run_until_input(open_device) returns the next request (NeedClaimCode, NeedConfirmation, NeedWiredInstall, ...), or None once the display is set up or the user declined a confirmation. answer(request, value) answers it.
  • on_step, if set, is called with each step just before it runs.
  • to_json() / from_json() save and restore a run across a restart; the saved run never holds a secret. A resumed run reads the device again, so it never repeats a step the device shows as done.

Encryption (firmware 2.x)

Firmware 2.x devices with encryption enabled require authentication before accepting any commands (except read_firmware_version). For firmware 3.0, see "Firmware 3.0 security" above. Pass the 16-byte AES-128 master key to the constructor — authentication and session setup happen automatically before the first interrogation.

from opendisplay import OpenDisplayDevice

key = bytes.fromhex("0102030405060708090a0b0c0d0e0f10")

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF", encryption_key=key) as device:
    await device.upload_image(image)

All commands are transparently encrypted after authentication. Devices without encryption enabled work exactly as before — the encryption_key parameter is ignored if the device does not require it.

Getting the key

The encryption key is set when configuring the device via the Open Display Config Builder web tool. It can be read from the device config once authenticated:

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF", encryption_key=key) as device:
    sc = device.config.security_config
    print(sc.encryption_key.hex())         # 32-char hex string
    print(sc.encryption_enabled_flag)      # True
    print(sc.rewrite_allowed)              # True if WRITE_CONFIG works without auth
    print(sc.session_timeout_seconds)      # How long before re-authentication is needed

Error handling

from opendisplay import AuthenticationRequiredError, AuthenticationFailedError

try:
    async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
        pass
except AuthenticationRequiredError:
    # Device has encryption enabled but no key was provided
    # (or the session expired and re-authentication is needed)
    print("This device requires an encryption key")
except AuthenticationFailedError:
    # A key was provided but the device rejected it (wrong key or rate-limited)
    print("Wrong encryption key")

Both exceptions are subclasses of AuthenticationError, which can be used as a catch-all when the distinction doesn't matter.

Rebooting the Device

Remotely reboot the device (useful after configuration changes or troubleshooting):

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    await device.reboot()
    # Device will reset after ~100ms
    # BLE connection will drop (this is expected)

Note: The device performs an immediate system reset and does not send an ACK response. The BLE connection will be terminated when the device resets. Wait a few seconds before attempting to reconnect.

LED Activation (Firmware 1.0+)

Trigger the firmware LED flash routine (0x0073):

from opendisplay import LedFlashConfig, OpenDisplayDevice

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    # Provide a typed flash pattern for this activation
    flash_config = LedFlashConfig.single(
        color=0xE0,            # RGB packed color byte used by firmware
        flash_count=2,         # Pulses per loop (0-15)
        loop_delay_units=2,    # 100ms units (0-15)
        inter_delay_units=5,   # 100ms units (0-255)
        brightness=8,          # 1-16
        group_repeats=1,       # 1-255, or None for infinite
    )
    await device.activate_led(led_instance=0, flash_config=flash_config, timeout=30.0)

activate_led() waits for the firmware response after the LED routine finishes. If firmware returns an LED-specific error response (0xFF73), the method raises ProtocolError. It validates firmware version first and raises on versions below 1.0 where command 0x0073 is not supported.

Configuration Inspection

Access detailed device configuration:

from opendisplay import BoardManufacturer

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    # Board manufacturer (requires config from interrogation or config=...)
    manufacturer = device.get_board_manufacturer()
    if isinstance(manufacturer, BoardManufacturer):
        print(f"Manufacturer: {manufacturer.name}")
    else:
        print(f"Manufacturer ID (unknown): {manufacturer}")
    mfg = device.config.manufacturer
    print(f"Manufacturer slug: {mfg.manufacturer_name or f'unknown({mfg.manufacturer_id})'}")
    print(f"Board model: {mfg.board_type_name or f'unknown({mfg.board_type})'}")
    print(f"Board revision: {mfg.board_revision}")

    # Display configuration
    display = device.config.displays[0]
    print(f"Panel IC: {display.panel_ic_type}")
    print(f"Rotation: {display.rotation}")
    print(f"Diagonal: {display.screen_diagonal_inches:.1f}\"" if display.screen_diagonal_inches is not None else "Diagonal: unknown")
    print(f"Supports ZIP: {display.supports_zip}")
    print(f"Supports Direct Write: {display.supports_direct_write}")

    # System configuration
    system = device.config.system
    print(f"IC Type: {system.ic_type_enum.name}")
    print(f"Has external power pin: {system.has_pwr_pin}")

    # Power configuration
    power = device.config.power
    print(f"Battery: {power.battery_mah}mAh")
    print(f"Power mode: {power.power_mode_enum.name}")

    # Optional WiFi configuration (firmware packet 0x26)
    wifi = device.config.wifi_config
    if wifi is not None:
        print(f"WiFi SSID: {wifi.ssid_text}")
        print(f"WiFi encryption: {wifi.encryption_type}")
        print(f"WiFi server: {wifi.server_url_text}:{wifi.server_port}")

Advertisement Parsing

Parse real-time sensor data from BLE advertisements:

from opendisplay import parse_advertisement

# Parse manufacturer data from BLE advertisement
adv_data = parse_advertisement(manufacturer_data)
print(f"Battery: {adv_data.battery_mv}mV")
print(f"Temperature: {adv_data.temperature_c}°C")
print(f"Loop counter: {adv_data.loop_counter}")
print(f"Format: {adv_data.format_version}")  # "legacy" or "v1"

if adv_data.format_version == "v1":
    print(f"Reboot flag: {adv_data.reboot_flag}")
    print(f"Connection requested: {adv_data.connection_requested}")
    print(f"Dynamic bytes: {adv_data.dynamic_data.hex()}")
    print(f"Button byte 0 pressed: {adv_data.is_pressed(0)}")

parse_advertisement() auto-detects both firmware formats without connecting:

  • Legacy payload: 11 bytes (battery_mv, signed temperature_c, loop_counter)
  • v1 payload: 14 bytes (firmware 1.0+, encoded temperature/battery + status flags)

It also accepts payloads where the manufacturer ID (0x2446) is still prefixed.

Track button up/down transitions across packets with AdvertisementTracker:

from opendisplay import AdvertisementTracker, parse_advertisement

tracker = AdvertisementTracker()

adv = parse_advertisement(manufacturer_data)
for event in tracker.update(address, adv):
    print(event.event_type, event.button_id, event.pressed, event.press_count)

Live Listener Script

Use the included script to scan and print parsed advertisement data live, including v1 button transition events (button_down, button_up, press_count_changed):

uv run python examples/listen_advertisements.py --duration 60 --all

Device Discovery

List all nearby OpenDisplay devices:

from opendisplay import discover_devices

# Scan for 10 seconds
devices = await discover_devices(timeout=10.0)

for name, mac in devices.items():
    print(f"{name}: {mac}")

# Output:
# OpenDisplayA123: AA:BB:CC:DD:EE:FF
# OpenDisplayB456: 11:22:33:44:55:66

Connection Reliability

py-opendisplay uses bleak-retry-connector for robust BLE connections with:

  • Automatic retry logic with exponential backoff
  • Connection slot management for ESP32 Bluetooth proxies
  • GATT service caching for faster reconnections
  • Better error categorization

Displays that are redrawing

While a display redraws its panel it goes silent: no advertisements, and commands are held until the refresh ends. A colour (Spectra) panel takes about 30 s. This is the firmware's design, so the library waits for it:

  • After the library itself makes the panel redraw (a config write, reboot(), the end of a claim, a key rotation while the key is shown on screen), the next replies, scans and connects to that display wait up to 60 s for it, in the same process. A command is never sent twice: the firmware answers it after the refresh. Waiting ends as soon as the display answers.
  • Otherwise a silent display fails as fast as before, because "redrawing" and "gone" look the same. The error then ends with "If the display is redrawing (some colour panels take about 30 s after a power-up, reboot or config change), try again in 30 s."
  • A firmware 3.0 handshake that the display answers with BUSY is retried every 10 s, which stays under the display's limit on handshake attempts. RATE_LIMITED is never retried.
  • The CLI always allows for a redraw, because you have often just switched the display on. It prints Waiting for the display to finish redrawing... once when it waits. --no-wait gives the fast failure instead.

Home Assistant Integration

When using py-opendisplay in Home Assistant custom integrations, pass the BLEDevice object for optimal performance:

from homeassistant.components import bluetooth
from opendisplay import OpenDisplayDevice

# Get BLEDevice from Home Assistant
ble_device = bluetooth.async_ble_device_from_address(hass, mac_address)

async with OpenDisplayDevice(mac_address=mac_address, ble_device=ble_device) as device:
    await device.upload_image(image)

Retry Configuration

Configure retry behavior for unreliable environments:

# Increase retry attempts for poor BLE conditions
async with OpenDisplayDevice(
    mac_address="AA:BB:CC:DD:EE:FF",
    max_attempts=6,  # Try up to 6 times (default: 4)
) as device:
    await device.upload_image(image)

# Disable service caching after firmware updates
async with OpenDisplayDevice(
    mac_address="AA:BB:CC:DD:EE:FF",
    use_services_cache=False,  # Force fresh service discovery
) as device:
    await device.upload_image(image)

Firmware Updates (OTA)

py-opendisplay supports over-the-air firmware updates for nRF52 and EFR32BG22 devices via BLE. ESP32 variants do not have a BLE OTA path.

macOS not supported for OTA. CoreBluetooth caches GATT services and provides no API to invalidate the cache. After the device reboots into bootloader/AppLoader mode its GATT service table changes, but macOS continues to serve the stale cached services — making the OTA service invisible to bleak. OTA works on Linux (BlueZ) and is the intended path via Home Assistant running on a Linux host.

Installation

Install the optional OTA dependencies for your device:

# nRF52840 / nRF52811
pip install "py-opendisplay[nrf-ota]"

# EFR32BG22
pip install "py-opendisplay[silabs-ota]"

# Both
pip install "py-opendisplay[all-ota]"

nRF52840 / nRF52811 — Nordic Legacy DFU

nRF devices use the Nordic Legacy DFU protocol. After triggering the bootloader, the device reboots and advertises a new DFU service (often at MAC+1). find_nrf_dfu_device() polls for up to 30 s to locate it.

from opendisplay import OpenDisplayDevice
from opendisplay.ota import find_nrf_dfu_device, perform_nrf_dfu

# Load the .zip firmware archive
with open("NRF52840.zip", "rb") as f:
    firmware_bytes = f.read()

# Step 1: trigger the bootloader
async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    await device.trigger_dfu_bootloader()

# Step 2: wait for the DFU device to appear
dfu_device = await find_nrf_dfu_device("AA:BB:CC:DD:EE:FF")
if dfu_device is None:
    raise RuntimeError("DFU device not found after 30 s")

# Step 3: flash
await perform_nrf_dfu(
    firmware_bytes,
    dfu_device,
    on_progress=lambda pct: print(f"{pct:.0f}%"),
    on_log=print,
)

Requires the nrf-ota package (pip install nrf-ota).

EFR32BG22 — Silicon Labs AppLoader OTA

EFR32BG22 devices use the Silicon Labs AppLoader protocol. After the bootloader trigger, the device reboots into AppLoader mode at the same BLE address. perform_silabs_ota() waits for AppLoader to be ready automatically.

from opendisplay import OpenDisplayDevice
from opendisplay.ota import perform_silabs_ota

# Load the .gbl firmware file
with open("opendisplay-bg22-v1.2.gbl", "rb") as f:
    firmware_bytes = f.read()

# Step 1: trigger the bootloader
ble_device = ...  # BLEDevice from BleakScanner or HA
async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF", ble_device=ble_device) as device:
    ota_device = ...  # same BLEDevice, or re-scan after disconnect
    await device.trigger_dfu_bootloader()

# Step 2: flash (perform_silabs_ota waits for AppLoader internally)
await perform_silabs_ota(
    firmware_bytes,
    ota_device,
    on_progress=lambda pct: print(f"{pct:.0f}%"),
    on_log=print,
)

The on_progress callback receives a float from 0–100. Both functions raise OTAError on failure.

Determining IC type

Use device.config.system.ic_type (an ICType enum value) to select the right OTA path:

from opendisplay.models.enums import ICType

async with OpenDisplayDevice(mac_address="AA:BB:CC:DD:EE:FF") as device:
    ic = device.config.system.ic_type
    if ic in (ICType.NRF52840, ICType.NRF52811):
        # use Nordic DFU path
    elif ic == ICType.EFR32BG22:
        # use Silabs AppLoader path
    else:
        # ESP32 — no BLE OTA available

Development

uv sync --all-extras
uv run pytest

Metadata

Release files for py-opendisplay 8.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for py-opendisplay 8.2.0
File Size Uploaded Provenance Actions
py_opendisplay-8.2.0.tar.gz 746.5 kB With provenance Details for py_opendisplay-8.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for py-opendisplay 8.2.0
File Interpreter ABI Platform Actions
py_opendisplay-8.2.0-py3-none-any.whl Python 3 none any Details for py_opendisplay-8.2.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / py_opendisplay-8.2.0.tar.gz

Download URL py_opendisplay-8.2.0.tar.gz
Size 746.5 kB
Tags Source
SHA-256 checksum
How to use checksums
199dab45f4834b7353a6b26700d7482321f254aee936d53b27cb76935f74df21
BLAKE2b-256 checksum
How to use checksums
a4da269bda3e08f5947cc3462f09a92ae9e92df84ad08e12a479de053c75199a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / py_opendisplay-8.2.0-py3-none-any.whl

Download URL py_opendisplay-8.2.0-py3-none-any.whl
Size 344.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
840f5d3da3270ceedffda67bb648abd40686b95f521e3a5ea48171bf7f6c5ed8
BLAKE2b-256 checksum
How to use checksums
da8d5eaa3f9622460203fd937671b75c6e6cbc6cc15407c73ec7c4dfdcb09bcc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for py-opendisplay 8.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for py_opendisplay-8.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

8.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page