YAML Configuration

Part of OpenDisplay Flex standard

The OpenDisplay Flex protocol uses a YAML-based configuration schema to define the BLE protocol structure. This schema describes all packet types, their fields, data types, and constraints. The configuration is parsed into binary bytes and saved on the device, where it serves as the complete specification of the device's capabilities and settings.

This configuration fully explains all capabilities the device has, including display specifications, power management options, communication modes, sensor support, and all other device settings. The configuration is used by tools like the Config Builder to generate and parse configuration packets, and by clients to understand what features are available on a particular device.

The configuration schema is designed to be extensible. New packet types and fields can be added to support additional features while maintaining backward compatibility through versioning and reserved fields. This allows the protocol to evolve and accommodate new device capabilities without breaking existing implementations.

Packet Structure

The configuration is organized as an outer packet containing multiple inner packets. Each inner packet represents a specific aspect of the device configuration (display, power, sensors, etc.):

Outer Packet

length (2 bytes)

version (1 byte)

Single Packet #0

number (1 byte) = 0

id (1 byte) = 1

Payload: system_config data

Single Packet #1

number (1 byte) = 1

id (1 byte) = 2

Payload: manufacturer_data

Single Packet #2

number (1 byte) = 2

id (1 byte) = 32

Payload: display configuration

... more packets ...

crc (2 bytes)

Outer Packet

The outer packet wraps the entire configuration transfer:

Field	Size	Description
`length`	2 bytes	Total length including CRC (max 4kB recommended)
`version`	1 byte	Major protocol version
`packets`	variable	Sequence of single_packet entries
`crc`	2 bytes	CRC16-CCITT checksum (excluding CRC field)

Single Packet

Each packet in the sequence has this structure:

Field	Size	Description
`number`	1 byte	Packet index (0-based, sequential)
`id`	1 byte	Packet type identifier
`payload`	variable	Packet-specific payload

Field Types

Fixed-Size Fields

Fields with a fixed size are specified with a number:

- name: ic_type
  size: 2
  description: IC used in this device

Enumerations

Fields can have enumerated values:

- name: ic_type
  size: 2
  enum:
    1:
      name: NRF52840
      description: nrf52840 based boards
    2:
      name: ESP32S3
      description: esp32-s3 based boards

Conditional Enumerations

Enum values can depend on another field's value:

- name: board_type
  size: 1
  conditional_enum:
    depends_on: manufacturer_id
    values:
      1:  # if manufacturer_id == 1 (Seeed)
        0:
          name: EE04
          description: XIAO ePaper Display EE04

Bitfields

Fields can be bitfields where each bit has a specific meaning:

- name: communication_modes
  size: 1
  bits:
    0:
      name: ble
      description: BLE transfer supported
    1:
      name: oepl
      description: OEPL based transfer supported

Packet Types

The protocol defines multiple packet types, each representing a different aspect of device configuration. For detailed field definitions, enumerations, and constraints, use the Config Builder tool, which provides an interactive interface to explore all packet types and their fields.

Packet Type 1: system_config Required

Contains information about the host microcontroller (IC type) and power management configuration.

Packet Type 2: manufacturer_data Required

Identifies the manufacturer and specific board model/revision.

Packet Type 4: power_option Required

Defines power supply settings, battery capacity, sleep behavior, and power consumption characteristics.

Packet Type 32: display Repeatable

Specifies display/panel configuration including dimensions, color scheme, controller type, and pin assignments. This packet is required for the protocol to function. Can appear multiple times for devices with multiple displays.

Packet Type 33: led Repeatable

Optional LED configuration for devices with status or RGB LEDs.

Packet Type 35: sensor_data Repeatable

Optional sensor configuration for devices with environmental or other sensors.

Packet Type 36: data_bus Repeatable

Defines communication buses (I2C, SPI, etc.) used by sensors or other peripherals.

Packet Type 37: binary_inputs Repeatable

Optional configuration for buttons, switches, or other binary input devices.

Packet Type 38: wifi_config

WiFi network configuration for devices that support WiFi communication (coming soon).

Packet Properties

Required Packets

Some packet types are marked as required, meaning they must appear in every configuration

Repeatable Packets

Some packet types are marked as repeatable, meaning they can appear multiple times

Using the YAML Config

The Config Builder web tool loads the YAML configuration to:

Generate UI forms for each packet type
Validate field values against enums and constraints
Build binary configuration packets
Parse received configuration data

Configuration Flow

Load YAML schema from config.yaml
User selects/edits packet instances
Tool validates all fields
Tool builds binary packet with CRC
Packet is sent to device via BLE

Reserved Fields

Many packet types include reserved fields for future compatibility. According to the protocol specification:

Reserved fields MUST be set to 0 unless otherwise specified
Reserved byte blocks are provided for forward compatibility
Older parsers should ignore reserved fields they don't understand