OpenEPaperLink integration for Home Assistant

Home Assistant Integration for the OpenEPaperLink project, enabling control and monitoring of electronic shelf labels (ESLs) through Home Assistant.

Multi-AP release / Multi-AP-Version

Important

Create a Home Assistant backup and a separate copy of your existing custom_components/open_epaper_link folder before installation. Version 3.0.3 is the stable Multi-AP release of this public fork and has not yet been merged into the upstream project.

Vor der Installation ein Home-Assistant-Backup und zusätzlich eine Kopie des vorhandenen Ordners custom_components/open_epaper_link erstellen. Version 3.0.3 ist die stabile Multi-AP-Version dieses öffentlichen Forks und noch nicht in das Upstream-Projekt übernommen.

Release version: 3.0.3

Feedback and bug reports: GitHub Issues in the fork

English Multi-AP installation

This release allows multiple OpenEPaperLink AP config entries in one Home Assistant instance. A physical tag remains one logical Home Assistant device. Tag actions are routed only through an AP that reports a local, non-replicated tag record; if several local APs qualify, the freshest last_seen value wins.

1. Create a full Home Assistant backup.
2. Back up the existing /config/custom_components/open_epaper_link folder separately.
3. Install the release using one of these methods:
   • HACS custom repository (recommended): In HACS, open the three-dot menu, select Custom repositories, add https://github.com/wendefeuer/Home_Assistant_Integration as type Integration, then use Download or Redownload. Under Need a different version?, select 3.0.3 if necessary.
   • Manual: Download the source archive from the 3.0.3 release, extract it, and copy its custom_components/open_epaper_link folder to /config/custom_components/open_epaper_link, replacing the integration files.
4. Restart Home Assistant. Do not edit files below .storage.
5. Open Settings → Devices & services → OpenEPaperLink and add each AP separately. Existing AP entries can remain in place.
6. Verify that every AP has its own device, shared tags appear only once, and a test action reaches the expected online AP.

To roll back, restore the backed-up integration folder or reinstall the latest upstream stable release, restart Home Assistant, and verify the integration and its devices again.

When reporting a problem, use the fork issue tracker and include the release version, Home Assistant version, AP count and firmware versions, reproduction steps, and sanitized logs. Remove tokens, passwords, private addresses, tag identifiers, and other personal data before posting.

Deutsche Multi-AP-Installation

Diese Version erlaubt mehrere OpenEPaperLink-AP-Konfigurationseinträge in einer Home-Assistant-Instanz. Ein physisches Tag bleibt ein logisches Home-Assistant-Gerät. Tag-Aktionen werden nur über einen AP mit einem lokalen, nicht replizierten Tag-Eintrag geleitet; kommen mehrere lokale APs infrage, gewinnt der neueste last_seen-Wert.

1. Ein vollständiges Home-Assistant-Backup erstellen.
2. Den vorhandenen Ordner /config/custom_components/open_epaper_link zusätzlich separat sichern.
3. Die Version mit einer der folgenden Methoden installieren:
   • HACS Custom Repository (empfohlen): In HACS das Drei-Punkte-Menü öffnen, Benutzerdefinierte Repositories auswählen, https://github.com/wendefeuer/Home_Assistant_Integration mit dem Typ Integration hinzufügen und anschließend Herunterladen oder Erneut herunterladen wählen. Unter Andere Version benötigt? bei Bedarf 3.0.3 auswählen.
   • Manuell: Das Quellarchiv der Version 3.0.3 herunterladen, entpacken und den enthaltenen Ordner custom_components/open_epaper_link nach /config/custom_components/open_epaper_link kopieren. Dabei die vorhandenen Integrationsdateien ersetzen.
4. Home Assistant neu starten. Keine Dateien unter .storage bearbeiten.
5. Unter Einstellungen → Geräte & Dienste → OpenEPaperLink jeden AP einzeln hinzufügen. Vorhandene AP-Einträge können bestehen bleiben.
6. Prüfen, ob jeder AP ein eigenes Gerät besitzt, gemeinsam sichtbare Tags nur einmal erscheinen und eine Testaktion den erwarteten erreichbaren AP erreicht.

Für ein Rollback den gesicherten Integrationsordner wiederherstellen oder die aktuelle stabile Upstream-Version erneut installieren, Home Assistant neu starten und anschließend Integration und Geräte erneut prüfen.

Probleme bitte zentral im Issue-Tracker des Forks melden. Dabei Release-Version, Home-Assistant-Version, Anzahl und Firmwarestände der APs, Reproduktionsschritte und bereinigte Logs angeben. Tokens, Passwörter, private Adressen, Tag-Kennungen und andere personenbezogene Daten vor dem Veröffentlichen entfernen.

Known limitations / Bekannte Einschränkungen

• This is a stable release of a public fork and is not yet part of the upstream project. / Dies ist eine stabile Version eines öffentlichen Forks und noch nicht Teil des Upstream-Projekts.
• Multi-AP routing applies to AP-based tags. Existing BLE behavior is intentionally unchanged. / Das Multi-AP-Routing gilt für AP-basierte Tags. Das bestehende BLE-Verhalten bleibt absichtlich unverändert.
• Write routing requires a local, non-replicated tag record and depends on AP connectivity. If several local APs qualify, the most recent tag last_seen data decides. / Schreibzugriffe benötigen einen lokalen, nicht replizierten Tag-Eintrag und hängen von der AP-Erreichbarkeit ab. Kommen mehrere lokale APs infrage, entscheiden die neuesten last_seen-Daten des Tags.
• A tag shared by multiple APs is intentionally shown as one HA device and has no permanent parent-AP assignment. / Ein von mehreren APs erfasstes Tag wird absichtlich als ein HA-Gerät angezeigt und besitzt keine dauerhafte Zuordnung zu einem übergeordneten AP.
• An AP reboot can close the HTTP connection before returning a response; an accepted reboot request followed by that disconnect is treated as successful. / Ein AP-Neustart kann die HTTP-Verbindung schließen, bevor eine Antwort zurückkommt; eine zuvor angenommene Neustartanforderung wird in diesem Fall als erfolgreich behandelt.
• Version 3.0.3 contains the Multi-AP implementation validated with two APs on Home Assistant Core 2026.7.2, including the local-versus-replicated routing fix. Other AP counts, firmware combinations, and HA versions have not been validated to the same extent. / Version 3.0.3 enthält die mit zwei APs unter Home Assistant Core 2026.7.2 geprüfte Multi-AP-Implementierung einschließlich der Korrektur für lokale und replizierte Tag-Einträge. Andere AP-Anzahlen, Firmwarekombinationen und HA-Versionen wurden noch nicht im gleichen Umfang validiert.

Requirements

Hardware

AP-Based Setup:

• OpenEPaperLink Access Point (ESP32-based)
• Compatible Electronic Shelf Labels connected to AP

BLE-Based Setup (ATC firmware):

• BLE-compatible Electronic Shelf Labels with ATC BLE firmware
• Home Assistant with Bluetooth adapter or proxy (e.g., ESPHome)
• No separate AP required - direct device communication

Mixed Setup:

• Both AP and BLE devices can coexist in the same Home Assistant instance

OpenDisplay users: OpenDisplay (OEPL BLE) devices are no longer supported by this integration. OpenDisplay now has dedicated integrations:

• Core integration — send images to the display via the upload_image action
• Custom integration — full support including the drawcustom action

Features

🔌 Device Integration

• Each tag and AP appears as a device in Home Assistant
• Device triggers for buttons, NFC, and GPIO
• Automatic tag discovery and configuration

⚙️ Configuration Controls

• AP settings management (WiFi, Bluetooth, language, etc.)
• Tag inventory and blacklist management

🎨 Display Controls

drawcustom (Recommended)

The most flexible and powerful service for creating custom displays. Supports:

• Text with multiple fonts and styles
• Shapes (rectangles, circles, lines)
• Icons from Material Design Icons
• QR codes
• Images from URLs
• Plots of Home Assistant sensor data
• Progress bars

View full drawcustom documentation

Legacy Services (Deprecated)

The following services have been deprecated in favor of drawcustom:

• dlimg: Download and display images from URLs
• lines5: Display 5 lines of text (1.54" displays only)
• lines4: Display 4 lines of text (2.9" displays only)

These legacy services were removed in the 1.0 release. Please migrate to using drawcustom.

🚦 Device Management

• clear_pending: Clear pending updates
• force_refresh: Force display refresh
• reboot_tag: Reboot tag
• scan_channels: Initiate channel scan
• reboot_ap: Reboot the access point
• Automatic tag detection and configuration
• Support for tag blacklisting to ignore unwanted devices
• Hardware capability detection for buttons, NFC, and GPIO features

🔋 Battery Optimization

To maximize tag battery life when using this integration:

• Shorten latency during config setting: This setting can be set to no either directly on the AP's web interface or through the integration's AP device in Home Assistant.

  If set to yes, tags will only sleep for 40 seconds between check-ins instead of using the configured longer sleep periods, reducing battery life.

  This occurs because Home Assistant maintains a constant WebSocket connection to the AP, which the AP interprets as being in configuration mode.

Installation

⚠️ Important: BLE Tag Firmware & Configuration

For the integration to discover and control BLE-based e-paper tags, they MUST be running the correct firmware and be properly configured. Tags with their original stock firmware will not be discovered by Home Assistant.

Step 1: Flash ATC_BLE_OEPL Firmware

The flashing method depends on the tag model:

• For tags previously used with an OpenEPaperLink BLE AP: The web-based OTA flasher can likely be used.
• For other tags: A manual flash is often required. This video provides a comprehensive guide: Universal E-Paper Firmware Flashing.

Step 2: Set the Device Type

After flashing, the correct device type for the tag model must be set.

1. Connect to the tag using the ATC_BLE_OEPL Image Upload tool.
2. Use the "Set Type" dropdown to select the specific tag model (e.g., "12: 290 Gici BWR SSD").
3. Click the "Set Type" button.

Getting Help

For any issues, the #atc_ble_oepl and #home_assistant channel on the OpenEPaperLink Discord is a great resource for community support.

Once flashed and configured, tags are discovered by HA automatically.

Option 1: HACS Installation (Recommended)

If the button does not add the repository, open HACS → three-dot menu → Custom repositories and add https://github.com/wendefeuer/Home_Assistant_Integration with category Integration.

Falls die Schaltfläche das Repository nicht hinzufügt, in HACS → Drei-Punkte-Menü → Benutzerdefinierte Repositories die Adresse https://github.com/wendefeuer/Home_Assistant_Integration mit der Kategorie Integration eintragen.

Option 2: Manual Installation

1. Download the open_epaper_link folder from the latest release
2. Copy it to your custom_components folder
3. Restart Home Assistant

Configuration

This step is only needed when using OpenEPaperLink in AP mode. When using a BLE-only setup, the tags will be detected automatically as soon as OpenEPaperLink has been installed.

Automatic Configuration

Add OpenEPaperLink to your Home Assistant instance using this button:

Manual Configuration

1. Browse to your Home Assistant instance
2. Go to Settings → Devices & Services
3. Click the Add Integration button in the bottom right
4. Search for and select "OpenEPaperLink"
5. Follow the on-screen instructions

Integration Options

After setup, you can configure additional options through the integration's option flow:

Tag Management

• Blacklisted Tags: Select tags to hide and ignore.
• Button Debounce Time: Adjust sensitivity of button triggers (0.0-5.0 seconds)
• NFC Debounce Time: Adjust sensitivity of NFC triggers (0.0-5.0 seconds)

Device Discovery

AP Device Configuration:

• Automatic Discovery (recommended): APs are automatically discovered via DHCP when connected to the network
• Manual Setup (fallback): Go to Settings → Integrations → Add Integration and enter your AP's IP address
• Multiple AP hubs supported: Add every AP separately. A physical tag remains one logical Home Assistant device; actions are routed to the online AP with the freshest tag check-in.
• All tags connected to the AP are automatically discovered

BLE Device Discovery:

• Automatic discovery via Bluetooth scanning
• Devices appear when in range and advertising
• Each BLE device creates a separate integration entry
• No limit on number of BLE devices

Usage Examples

Basic Text Display

- type: "text"
  value: "Hello World!"
  x: 10
  y: 10
  size: 40
  color: "red"

Progress Bar with Icon

- type: "progress_bar"
  x_start: 10
  y_start: 10
  x_end: 180
  y_end: 30
  progress: 75
  fill: "red"
  show_percentage: true
- type: "icon"
  value: "mdi:battery-70"
  x: 190
  y: 20
  size: 24

Sensor Display

- type: "text"
  value: "Temperature: {{ states('sensor.temperature') }}°C"
  x: 10
  y: 10
  size: 24
  color: "black"
- type: "text"
  value: "Humidity: {{ states('sensor.humidity') }}%"
  x: 10
  y: 40
  size: 24
  color: "black"

Migrating to Version 1.0

Breaking Changes

1. Service Changes
   • dlimg, lines4, and lines5 services have been deprecated
   • All image/text display should now use drawcustom service
   • Service target now uses device ID instead of entity ID
2. Entity Changes
   • Entities for each device have also changed significantly

To make sure no potential bugs carry over from the old version, please remove the old integration and re-add it. This will ensure that all entities are correctly setup.

Service Migration

Text Display

Old format (lines5 service):

line1: "Hello"
line2: "World"

New format (drawcustom payload):

- type: "text"
  value: "Hello"
  x: 10
  y: 10
  size: 24
- type: "text"
  value: "World"
  x: 10
  y: 40
  size: 24

Image Display

Old format (dlimg service):

url: "https://example.com/image.jpg"
x: 0
y: 0
xsize: 296
ysize: 128

New format (drawcustom payload):

- type: "dlimg"
  url: "https://example.com/image.jpg"
  x: 0
  y: 0
  xsize: 296
  ysize: 128

The device selection, background color, rotation, and other options are now configured through dropdown menus in the service UI.

Contributing

• Feature requests and bug reports are welcome! Please open an issue on GitHub
• Pull requests are encouraged
• Join the Discord server to discuss ideas and get help