Adding New Displays Guide

Required Knowledge and Resources

• Access to the OpenDisplay firmware source code
• Knowledge of the device's pin configuration
• Display panel specifications (resolution, color scheme, controller IC)
• Understanding of the BLE protocol (see BLE Protocol Flow)
• Familiarity with YAML configuration (see YAML Config Documentation)

Required Information

Before starting, collect the following information about your device:

• Display Panel:
  • Panel model number and manufacturer
  • Resolution (width × height in pixels)
  • Physical dimensions (width × height in mm)
  • Color scheme (B/W, B/W+R, B/W+Y, B/W+R+Y, 6-color, 4-gray)
  • Controller IC type
• Hardware Configuration:
  • MCU type (ESP32-S3, ESP32-C3, ESP32-C6, nRF52840)
  • Pin assignments (reset, busy, DC, CS, data/MOSI, clock/SCK)
  • SPI bus speed (if applicable)
  • Power management pins (if any)

2.1 Understanding Display Support

The OpenDisplay firmware uses the bb_epaper library for display driver support. This means that the available panel types are determined by what's supported in the bb_epaper library. Before adding a new panel, you should first check if your display is already supported.

2.2 Check Existing Panel Types

To find if your display is already supported, check the panel enumeration in the YAML configuration file in your local repository:

Navigate to packet type 32 (display) and look at the panel_ic_type field enumeration. This lists all currently supported panels with their:

• Panel ID number
• Panel name (e.g., ep213_122x250)
• Description (manufacturer/model information)

2.3 Search Strategies

When searching for your display, look for matches based on:

• Resolution: Match the pixel dimensions (width × height)
• Size: Physical size in inches (e.g., 2.13", 2.9", 4.2")
• Color Scheme: B/W, B/W+R, B/W+Y, B/W+R+Y, 6-color, or 4-gray
• Model Number: Check the description field for your panel's model number (e.g., GDEY042T81, DEPG0420BN)
• Controller IC: Some panels share the same controller IC and may be compatible

2.4 Using Config Builder to Browse

The easiest way to browse available panels is using the Config Builder:

1. Open the Config Builder tool
2. Load the YAML schema (it loads automatically)
3. Add a display packet (Packet Type 32)
4. Click on the panel_ic_type dropdown
5. Browse through all available panel options with their descriptions

The dropdown shows all supported panels in a searchable format, making it easy to find your display.

2.5 If Your Display is Not Listed

If you cannot find your display in the existing list, it means:

• The panel may not be supported by the bb_epaper library yet
• You may need to add support to bb_epaper first
• Or find a compatible panel that uses the same controller IC

In this case, you'll need to:

1. Check if bb_epaper supports your panel (check the bb_epaper library documentation or source code)
2. If supported in bb_epaper but not in OpenDisplay, proceed to add it to the YAML config (see Step 3)
3. If not supported in bb_epaper, you'll need to add support there first, or use a compatible alternative panel

3.1 When This Step is Needed

Only proceed with this step if:

• Your display is not found in the existing panel list (Step 2)
• The panel is supported by bb_epaper library but not yet added to OpenDisplay
• You've confirmed the panel constant exists in bb_epaper

If you found your display in Step 2, skip to Step 4 (Create Preset Configuration).

3.2 Verify bb_epaper Support

Before adding a panel to OpenDisplay, verify it's supported in the bb_epaper library:

• Check the bb_epaper library documentation or source code
• Look for the panel constant (e.g., EP_NEW_200x200)
• Ensure the panel initialization and refresh sequences are implemented

If the panel is not supported in bb_epaper, you must add support there first before proceeding.

3.3 Add Panel to YAML Config

In your local repository, edit the config file at config.yaml. Navigate to packet type 32 (display) and find the panel_ic_type enum. Add your new panel entry:

Naming Convention: Use descriptive names like ep[size][color][variant] (e.g., ep213r_122x250 for 2.13" red/black panel).

3.4 Add Panel Mapping in Firmware

In the firmware source code (src/main.cpp), find the mapEpd() function and add your panel mapping:

The panel constant (e.g., EP_NEW_200x200) must match the constant defined in the bb_epaper library.

4.1 Start with a Known Good Config

Best Practice: Instead of creating a configuration from scratch, start with an existing preset configuration for a similar board. This ensures you have all required fields properly configured.

1. Open the Config Builder tool
2. Load the YAML schema (it loads automatically)
3. Select a compatible preset from the dropdown:
   • For ESP32-S3 boards: Use "Seeed EE04 ESP 4.26" or "Seeed XIAO ESP32-S3 breakout 4.26"
   • For nRF52840 boards: Use "Seeed EN04 NRF 4.26" or "Seeed XIAO NRF52840 breakout 4.26"
   • For ESP32-C3/C6 boards: Use the corresponding XIAO breakout presets
4. Click "Read Config" or import the preset JSON file
5. Modify the configuration for your specific hardware:
   • Update pin assignments to match your board
   • Adjust display settings (panel type, dimensions, color scheme)
   • Update power settings if different
   • Modify manufacturer/board information if needed

This approach is much faster and less error-prone than building a config from scratch.

4.2 Manual Configuration (Alternative)

If you prefer to configure manually or no similar preset exists, you can build the configuration from scratch:

1. Add required packets:
   • Packet Type 1: system_config (IC type, communication modes)
   • Packet Type 2: manufacturer_data (manufacturer, board type)
   • Packet Type 4: power_option (power mode, battery, sleep settings)
2. Add display packet (Packet Type 32):
   • Set panel_ic_type to your panel ID (from Step 2 or 3)
   • Configure pixel dimensions
   • Set physical dimensions in mm
   • Configure color scheme
   • Set all pin assignments
   • Configure rotation if needed
   • Set partial_update_support
3. Add any optional packets (LEDs, sensors, buttons, etc.)

4.2 Export Configuration

Once configured, export the configuration as JSON using the "Export JSON" button in the Config Builder.

4.3 Save Preset File (Optional)

If you're contributing your configuration back to the project, save the exported JSON file to the presets directory in your local repository:

Use a descriptive filename that includes the MCU type and board name, e.g.:

• esp32-s3-custom-board.json
• nrf52840-diy-panel.json

Note: You can use the configuration locally without saving it to the presets directory. The preset file is only needed if you want to contribute it to the project.

6.1 Build and Flash Firmware

Note: This step is only necessary if you completed Step 3 (added a new panel type to the YAML config and firmware). If you found your display in the existing panel list (Step 2) and only created a configuration (Step 4), you can skip compilation and proceed directly to loading your configuration (Step 6.2).

If you did modify the firmware (Step 3), compile the firmware with your changes and flash it to your device using the Web Installer.

6.2 Load Configuration

Use the Config Builder to:

1. Load your preset configuration
2. Connect to your device via BLE
3. Write the configuration to the device
4. Reboot the device

6.3 Test Display

Use the BLE Tester to:

• Upload a test image
• Verify the display shows the image correctly
• Check that colors render properly (if color display)
• Test partial refresh (if supported)
• Verify rotation settings

6.4 Verify Configuration

Read back the configuration from the device to ensure it was stored correctly:

1. Connect to device via BLE
2. Click "Read Config" in Config Builder
3. Verify all values match your preset

Display Not Initializing

• Verify pin assignments are correct
• Check SPI bus speed (try lower speeds if issues occur)
• Ensure power management is configured correctly
• Verify panel type ID matches between YAML and firmware

Wrong Colors or Display Artifacts

• Verify color_scheme matches the actual panel
• Check rotation settings
• Ensure pixel dimensions are correct
• Verify the panel driver supports your color mode

Configuration Not Saving

• Check CRC validation (Config Builder shows CRC info)
• Ensure packet size doesn't exceed 4kB limit
• Verify all required packets are present
• Check for firmware errors in serial output

Share on Discord

If you successfully get a new display working, please share your findings and configuration on the OpenDisplay Discord. Include:

• Panel model and specifications
• Your configuration details (you can export and share the JSON config)
• Any issues you encountered and how you solved them
• Test results
• bb_epaper panel constant used (if you added a new panel)

Sharing your working configuration helps other users with the same display and allows the community to integrate it into the main project if desired.

9.1 Recommended: Measure Power Consumption

To provide accurate power consumption data for your device configuration, it's recommended to use a Nordic Power Profiler Kit II (PPK2) or similar power measurement tool. This helps the community understand the power characteristics of different configurations and enables accurate battery life calculations.

9.2 Measure Deep Sleep Current

Measure the deep sleep current consumption when the device is in deep sleep mode. This value should be added to the deep_sleep_current_ua field in the power_option packet (Packet Type 4). The value should be in microamperes (µA).

9.3 Measure Display Update Charge

Measure the total charge consumed for a complete display update. This is the energy consumed during the entire update process, from start to finish. The value should be added to the full_update_mC field in the display packet (Packet Type 32). The value should be in millicoulombs (mC).

To measure this, use the PPK2 to capture the charge consumed during a single display update cycle. Make sure to measure the complete update process including any initialization, data transfer, and refresh operations. The PPK2 can measure the total charge (in mC) consumed during the update.

9.4 Share Power Consumption Data

Include your power consumption measurements when sharing your configuration on Discord (Step 8). This information is valuable for:

• Battery life calculations
• Power optimization recommendations
• Comparing different hardware configurations
• Documenting device power characteristics

Scenario

Adding support for a new 2.9" B/W/R panel with resolution 128×296:

YAML Config Addition

Firmware Mapping Addition

Preset Configuration