Protocol Documentation

Overview

The OpenDisplay protocol enables communication between client applications (running on computers, smartphones, or web browsers) and e-paper display devices. OpenDisplay Flex uses Bluetooth Low Energy (BLE) and optionally the same command set over Wi‑Fi (TCP to the device on the LAN). The simplified OpenDisplay standard is BLE-first, with a separate Wi‑Fi appendix for another deployment style. Clients can configure devices, read status information, and send image data for display.

The OpenDisplay protocol consists of two standards:

OpenDisplay - Simplified protocol for easy manufacturer integration. Minimal configuration, single-page specification.
OpenDisplay Flex - Full-featured protocol with comprehensive configuration system, YAML-based schema, and advanced capabilities.

Both standards share the same OpenDisplay Language for visual layouts. The image data format is included in the OpenDisplay standard specification.

Client

E-Paper Display

Devices & Protocols

Client Devices: Computers, smartphones, tablets, web browsers, or Home Assistant running client applications. A Python module is available for easy integration.
Display Devices: E-paper displays that implement the OpenDisplay BLE or OpenDisplay WiFi standard. This includes devices running OpenDisplay firmware on ESP32-S3, ESP32-C3, ESP32-C6, or nRF52840 microcontrollers, as well as other firmware implementations that speak the protocol.
Communication Protocol: For Flex, BLE (GATT) plus optional Wi‑Fi LAN (TCP, device as server); see OpenDisplay Flex and the communication protocol page.
Data Format: Binary packets defined by YAML configuration schema, supporting configuration, status reading, and image transfer

OpenDisplay

A simplified protocol standard designed for easy manufacturer integration. Minimal configuration, straightforward communication flow, and everything fits on a single page. Perfect for manufacturers who want to quickly add OpenDisplay compatibility to their e-paper displays.

View OpenDisplay Standard

OpenDisplay Flex

The full-featured protocol standard with comprehensive configuration system. Includes YAML-based configuration schema, communication over BLE and optional Wi‑Fi LAN (same commands), and support for all device capabilities. This is the standard used by OpenDisplay firmware and advanced implementations.

View Flex Standard

OpenDisplay Language

The format standard for describing visual layouts for e-paper displays. Complete specification including all drawing element types, color support, font options, and template examples. This format is shared by both Basic and Flex standards and defines how visual content is structured and interpreted.

View OpenDisplay Language