rgb_lcd_display

[中文]

Overview

The display interface abstracts drivers for different screen interfaces. Users create a handle based on the screen type.

display hardware features:

1. Supports multiple screen types, such as RGB LCD (RGB565, RGB888) and MCU LCD (8-bit, 16-bit).

2. Supports pixel conversion, where the input data format can differ from the LCD output format. For example, you can provide YUYV frames for flushing.

   • YUYV to RGB565/RGB888/RGB666

   • RGB565 to RGB888

   • RGB888 to RGB565

   • RGB565 to RGB666

   • RGB888 to RGB666

3. For RGB565 format, used GPIO bits are the higher bits: R3-R7 high bits, G2-G7 high bits, B3-B7 high bits.

This section describes how the display module drives RGB LCDs, including API usage, parameter descriptions, and notes.

• For RGB LCD example projects, see:

  • RGB LCD Example

• For API reference, see:

  • RGB LCD Display API

Development Intro

1. Power LDO Control

By default in the BK7258 board SDK, the LCD LDO control pin is GPIO13. If your I/O differs, configure GPIOs explicitly in your application.

2. Backlight

Configure the LCD backlight control pin using the GPIO driver in your application.

3. LCD Device

In the BK7258 board SDK, the default RGB LCD device is ST7701SN. If your device differs, add your custom device to the solution.

For adding devices, see: - LCD Device Addition Guide

If the LCD requires SPI for initialization, pass the correct SPI IO pins when creating the handle. If IO initialization is not required, pass GPIO_INVALID_PIN (-1) for IO pins.

API Call Flow Overview

The typical RGB LCD Display usage flow is as follows:

┌─────────────────────────────────────────────────────────────┐
│              RGB LCD Display API Call Flow                   │
└─────────────────────────────────────────────────────────────┘

1. Hardware Setup     ──→  Configure LCD LDO and backlight GPIO
                          └─ Enable power and backlight control

2. bk_display_rgb_new()  ──→  Create RGB LCD controller instance
                              └─ Configure LCD device and SPI IO pins

3. bk_display_open()     ──→  Open display controller
                              └─ Initialize LCD hardware

4. bk_display_flush()    ──→  Refresh display (can be called multiple times)
                              └─ Send frame data to LCD

5. bk_display_close()    ──→  Close display controller
                              └─ Stop hardware, disable clock

6. bk_display_delete()   ──→  Delete controller instance
                              └─ Release resources

Attention

• APIs must be called in the above sequence

• Display must be created and opened before flushing

• Backlight and power should be turned off after operations

• Frame free callback must be properly implemented to avoid memory leaks

For complete usage example and detailed API descriptions, please refer to the Chinese documentation. The English version provides the same API structure and parameters.

Detailed API Description

1. Create LCD Controller

Parameters:

• handle: Output parameter that stores the created display controller handle

• config: Controller configuration containing LCD device info and GPIO pins

Example:

#include <components/bk_display/bk_display.h>
#include <components/bk_display/bk_display_types.h>

static bk_display_ctlr_handle_t lcd_display_handle = NULL;
static const lcd_device_t *lcd_device = &lcd_device_custom_st7701sn;  // custom device

// Create RGB LCD controller
bk_display_rgb_ctlr_config_t lcd_display_config = {0};
lcd_display_config.lcd_device = lcd_device;
lcd_display_config.clk_pin = GPIO_0;    // SPI clock
lcd_display_config.cs_pin = GPIO_12;     // chip select
lcd_display_config.sda_pin = GPIO_1;      // data
lcd_display_config.rst_pin = GPIO_6;     // reset

avdk_err_t ret = bk_display_rgb_new(&lcd_display_handle, &lcd_display_config);
if (ret != AVDK_ERR_OK) {
    // error handling
}

bk_display_rgb_ctlr_config_t reference:

• bk_display_rgb_ctlr_config_t

Attention

• If the RGB LCD does not require SPI IO configuration, set clk_pin, cs_pin, and sda_pin to GPIO_INVALID_PIN (-1).

• lcd_device is the pointer passed in to provide screen resolution, interface type, etc. If NULL, AVDK_ERR_INVAL is returned. For adding devices, see: LCD Device Addition Guide

2. Open LCD Display Controller

Parameters:

• handle: display controller handle

Description: Open LCD display and initialize the controller.

Example:

// Enable LCD LDO. If your board drives the pin directly, just use the GPIO driver
gpio_dev_unmap(lcd_ldo_io);
BK_LOG_ON_ERR(bk_gpio_enable_output(lcd_ldo_io));
BK_LOG_ON_ERR(bk_gpio_pull_up(lcd_ldo_io));
bk_gpio_set_output_high(lcd_ldo_io);

// Turn on backlight via GPIO or PWM
gpio_dev_unmap(bl_io);
BK_LOG_ON_ERR(bk_gpio_enable_output(bl_io));
BK_LOG_ON_ERR(bk_gpio_pull_up(bl_io));
bk_gpio_set_output_high(bl_io);

// Open display controller
ret = bk_display_open(lcd_display_handle);
if (ret != AVDK_ERR_OK) {
    // error handling
}

3. Flush LCD Display

Parameters:

• handle: display controller handle

• frame: pointer to the frame to display

• free_t: callback to release the frame

Description:

• Refresh the LCD with the frame data.

• Supported source formats: PIXEL_FMT_RGB565, PIXEL_FMT_RGB888, PIXEL_FMT_RGB666, PIXEL_FMT_YUYV; set in frame->fmt.

• The frame release callback free_t: after the next frame is provided, the display module will call free_t to release the previous frame. If there is only one frame, the release is called on close.

• If the source resolution is larger than the LCD resolution, the display module shows the centered area by default.

Attention

• If the source resolution is smaller than the LCD resolution, due to LCD refresh characteristics the display will be abnormal.

Example:

// Frame release callback
static avdk_err_t display_frame_free_cb(void *frame)
{
    frame_buffer_display_free((frame_buffer_t *)frame);
    return AVDK_ERR_OK;
}

// Allocate display frame buffer based on resolution and pixel format
uint32_t frame_size = lcd_device->width * lcd_device->height * PIXEL_RGB565_SIZE;

frame_buffer_t *disp_frame = frame_buffer_display_malloc(frame_size);
if (!disp_frame) {
    // handle allocation failure
}

// Configure frame
disp_frame->fmt = PIXEL_FMT_RGB565;     // source data format
disp_frame->width = lcd_device->width;  // source pixel width
disp_frame->height = lcd_device->height; // source pixel height

// Fill with random color data (sample)
lcd_fill_rand_color(frame_size, disp_frame->frame);

// Flush display
ret = bk_display_flush(lcd_display_handle, disp_frame, display_frame_free_cb);
if (ret != AVDK_ERR_OK) {
    // error handling; manually free frame
    display_frame_free_cb(disp_frame);
}

Attention

1: display_frame_free_cb releases the frame after refresh completes. Passing NULL for free_t returns AVDK_ERR_INVAL. Passing NULL for frame returns AVDK_ERR_INVAL.

2: If display_frame_free_cb does not free the frame, memory leaks may occur.

4. Close LCD Display

Parameters: - handle: display controller handle

Description: Close LCD display and stop the controller.

Example:

// Close display controller
ret = bk_display_close(lcd_display_handle);
if (ret != AVDK_ERR_OK) {
    // error handling
}

// Turn off backlight (drive GPIO low or stop PWM)
bk_gpio_set_output_low(bl_io);

// Disable LCD LDO
bk_gpio_set_output_low(lcd_ldo_io);

5. Delete LCD Controller

Parameters: - handle: display controller handle

Description: Delete the LCD controller and free resources.

Example:

// Delete display controller
ret = bk_display_delete(lcd_display_handle);
if (ret != AVDK_ERR_OK) {
    // error handling
}
lcd_display_handle = NULL; // reset handle

Notes

1. Ensure the display controller is created and opened successfully before calling flush

2. The frame release callback must be implemented correctly to avoid memory leaks

3. Different LCD devices require correct GPIO configuration, including backlight and LCD LDO pins

4. Frame buffer size should be calculated based on actual resolution and pixel format

5. Close and delete the controller promptly after operations to release resources

API List

• bk_display_new: Create display controller

• bk_display_open: Open display controller

• bk_display_flush: Flush display

• bk_display_close: Close display controller

• bk_display_delete: Delete display controller