OpenDisplay Home Assistant Integration

Overview

The OpenDisplay Home Assistant integration provides comprehensive control and monitoring for e-paper displays. It supports Access Point (AP) based OpenEPaperLink devices, OpenDisplay BLE devices, and ATC BLE devices, offering real-time updates, custom image generation, and full device management through Home Assistant's interface.

The integration automatically discovers devices, creates entities for monitoring and control, and provides services for drawing custom content using the OpenDisplay Language format.

Note: This integration is being renamed from "OpenEPaperLink" to "OpenDisplay" to reflect its expanded support for multiple device types. The previous integration repository is available at OpenEPaperLink/Home_Assistant_Integration.

Supported Device Types

Access Point (AP) Based OpenEPaperLink Devices

Devices connected via an OpenEPaperLink Access Point communicate over WebSocket, providing real-time updates and full feature support. The integration maintains a persistent WebSocket connection to receive tag updates, button presses, and AP status changes.

OpenDisplay BLE Devices

OpenDisplay BLE devices connect directly to Home Assistant via Bluetooth proxies (such as ESPHome Bluetooth proxies). No access point is required for BLE devices, making setup simpler and more flexible. The integration uses the OpenDisplay BLE Communication Protocol to communicate with devices running OpenDisplay firmware.

ATC BLE Devices

The integration also supports ATC (Atorch) BLE devices, providing compatibility with a wide range of e-paper display hardware. ATC devices connect via Bluetooth proxies and use the ATC BLE protocol for communication.

Entities

The integration automatically creates various entities for each device, organized by platform:

Sensors

Access Point Sensors:

• IP Address, WiFi SSID, WiFi RSSI
• Tag count, Low battery tags, Timed out tags
• Database size, LittleFS free space, Free heap, PSRAM free
• AP state, Run state, System time, Uptime

Tag Sensors (for both AP and BLE devices):

• Temperature
• Battery voltage and percentage
• Last seen timestamp
• RSSI (signal strength) - for BLE devices
• Hardware information (model, dimensions, capabilities)

Images

Each tag automatically gets an image entity that displays the current content shown on the e-paper display. The image is fetched from the device and converted to a standard format for viewing in Home Assistant.

Buttons

Button entities provide quick actions for tags and the AP:

• Tag buttons: Force refresh, Reboot tag, Clear pending status
• AP buttons: Reboot AP, Scan channels, Refresh tag types
• BLE devices: Clock mode controls

Switches

Switch entities control AP configuration options:

• Preview Images - Enable/disable preview images on the AP
• Bluetooth - Enable/disable Bluetooth functionality
• Nightly Reboot - Enable/disable automatic nightly reboot
• Show Timestamp - Enable/disable timestamps on ESL displays

Selects

Select entities provide dropdown options for AP configuration:

• Channel selection
• Sleep time configuration (no updates between specified hours)
• Various AP operational settings

Text Inputs

Text entities allow editing:

• Tag names - Customize display names for tags
• AP configuration values - Edit various AP settings

Lights (BLE Only)

BLE devices expose a light entity for controlling the LED indicator, allowing you to set brightness, color, and flash patterns.

Services

The integration provides several services for controlling devices and drawing custom content:

drawcustom

Draw Custom Image - The primary service for displaying custom content on e-paper displays. This service accepts an OpenDisplay Language payload (the same format used by the Layout Designer) and generates an image that is sent to the display.

Parameters:

• payload - OpenDisplay Language array defining drawing elements (text, shapes, images, QR codes, plots, etc.)
• background - Background color (white, black, accent, red, yellow)
• rotate - Rotation in degrees (0, 90, 180, 270)
• dither - Dithering option (0 = none, 1 = Floyd-Steinberg for photos, 2 = Ordered for halftone colors)
• ttl - Time to live in seconds (how long the tag sleeps before checking in again)
• dry-run - Generate image but don't send to device (for testing)

The service supports all drawing types from the OpenDisplay Language specification, including text, multiline text, lines, rectangles, polygons, circles, ellipses, arcs, icons, icon sequences, downloaded images, QR codes, plots, progress bars, and debug grids.

setled

Set LED Pattern - Configures the LED flash pattern for tags with LED indicators.

Parameters:

• mode - LED mode (off or flash)
• brightness - LED brightness (1-16)
• repeats - Number of times to repeat the pattern (1-255)
• color1/color2/color3 - RGB colors for each step in the pattern
• flashSpeed1/2/3 - Flash speed for each color (0-1.5 seconds)
• flashCount1/2/3 - Number of flashes for each color (0-15)
• delay1/2/3 - Delay after each color (0-25.5 seconds)

Other Services

• clear_pending - Clears the pending status for one or more tags
• force_refresh - Forces tags to refresh their display immediately
• reboot_tag - Reboots one or more tags
• scan_channels - Makes tags scan for available channels
• reboot_ap - Reboots the Access Point
• refresh_tag_types - Force refresh of tag type definitions from GitHub

Features

Automatic Device Discovery

The integration automatically discovers tags as they connect to the AP or become available via BLE. New tags are automatically added to Home Assistant with all appropriate entities created.

Real-Time Updates

For AP devices, the integration maintains a WebSocket connection that provides real-time updates for:

• Tag status changes (battery, temperature, last seen)
• Button presses on tags
• NFC interactions
• AP configuration and status changes

Image Generation

The integration includes a powerful image generation engine that converts OpenDisplay Language payloads into optimized images for e-paper displays. It handles:

• Text rendering with custom fonts and sizes
• Shape drawing (rectangles, circles, polygons, lines)
• Image loading and scaling from URLs
• QR code generation
• Plot/chart generation with legends and axes
• Icon rendering using Material Design Icons
• Color scheme conversion and dithering

Tag Management

The integration provides comprehensive tag management:

• Custom tag naming
• Tag blacklisting (exclude tags from discovery)
• Bulk operations (update multiple tags at once)
• Tag type detection and hardware information

AP Configuration

Full control over Access Point settings through Home Assistant entities:

• Network settings (WiFi, Bluetooth)
• Operational settings (preview images, timestamps, nightly reboot)
• Sleep time configuration
• Channel selection

Installation

The OpenDisplay integration can be installed through Home Assistant's integration store:

1. Go to Settings → Devices & Services
2. Click Add Integration
3. Search for "OpenDisplay" (or "OpenEPaperLink" for the legacy name)
4. Follow the setup wizard to configure your Access Point or BLE device

For BLE devices, ensure you have a Bluetooth proxy configured (such as ESPHome Bluetooth proxy) before adding the integration. The integration will automatically discover:

• OpenDisplay BLE devices running OpenDisplay firmware
• ATC BLE devices

Previous Integration Repository: OpenEPaperLink/Home_Assistant_Integration

Related Resources

• Layout Designer - Visual editor for creating OpenDisplay Language payloads
• Protocol Documentation - Learn about the OpenDisplay communication protocols
• BLE Communication Protocol - Details on BLE device communication
• Firmware Tools - Install and configure OpenDisplay firmware