LCD

Introduction

ESP chips can generate various kinds of timings that needed by common LCDs on the market, like SPI LCD, I80 LCD (a.k.a Intel 8080 parallel LCD), RGB LCD, I2C LCD, etc. The esp_lcd component is officially to support those LCDs with a group of universal APIs across chips.

Functional Overview

In esp_lcd, an LCD panel is represented by esp_lcd_panel_handle_t, which plays the role of an abstract frame buffer, regardless of the frame memory is allocated inside ESP chip or in external LCD controller. Based on the location of the frame buffer, the LCD panel allocation functions are mainly grouped into the following categories:

• RGB LCD panel - is simply based on a group of specific synchronous signals indicating where to start and stop a frame.

• Controller based LCD panel involves multiple steps to get a panel handle, like bus allocation, IO device registration and controller driver install.

After we get the LCD handle, the remaining LCD operations are the same for different LCD interfaces and vendors.

Application Example

LCD examples are located under: peripherals/lcd:

• Jpeg decoding and LCD display - peripherals/lcd/tjpgd

• LVGL porting and animation UI - peripherals/lcd/lvgl

API Reference

Header File

• components/hal/include/hal/lcd_types.h

Enumerations

enum lcd_clock_source_t

LCD clock source.

Note

User should select the clock source based on the real requirement:

LCD clock source	Features	Power Management
LCD_CLK_SRC_PLL160M	High resolution	ESP_PM_APB_FREQ_MAX lock
LCD_CLK_SRC_APLL	Configurable resolution	ESP_PM_NO_LIGHT_SLEEP lock
LCD_CLK_SRC_XTAL	Medium resolution	No PM lock

Values:

LCD_CLK_SRC_PLL160M

Select PLL160M as the source clock

LCD_CLK_SRC_APLL

Select APLL as the source clock

LCD_CLK_SRC_XTAL

Select XTAL as the source clock

Header File

• components/esp_lcd/include/esp_lcd_types.h

Type Definitions

typedef struct esp_lcd_panel_io_t *esp_lcd_panel_io_handle_t

Type of LCD panel IO handle

typedef struct esp_lcd_panel_t *esp_lcd_panel_handle_t

Type of LCD panel handle

Enumerations

enum esp_lcd_color_space_t

LCD color space type definition.

Values:

ESP_LCD_COLOR_SPACE_RGB

Color space: RGB

ESP_LCD_COLOR_SPACE_BGR

Color space: BGR

ESP_LCD_COLOR_SPACE_MONOCHROME

Color space: monochrome

Header File

• components/esp_lcd/include/esp_lcd_panel_io.h

Functions

esp_err_t esp_lcd_panel_io_tx_param(esp_lcd_panel_io_handle_t io, int lcd_cmd, const void *param, size_t param_size)

Transmit LCD command and corresponding parameters.

Note

Commands sent by this function are short, so they are sent using polling transactions. The function does not return before the command tranfer is completed. If any queued transactions sent by esp_lcd_panel_io_tx_color() are still pending when this function is called, this function will wait until they are finished and the queue is empty before sending the command(s).

Return

• ESP_ERR_INVALID_ARG if parameter is invalid

• ESP_OK on success

Parameters

• [in] io: LCD panel IO handle, which is created by other factory API like esp_lcd_new_panel_io_spi()

• [in] lcd_cmd: The specific LCD command

• [in] param: Buffer that holds the command specific parameters, set to NULL if no parameter is needed for the command

• [in] param_size: Size of param in memory, in bytes, set to zero if no parameter is needed for the command

esp_err_t esp_lcd_panel_io_tx_color(esp_lcd_panel_io_handle_t io, int lcd_cmd, const void *color, size_t color_size)

Transmit LCD RGB data.

Note

This function will package the command and RGB data into a transaction, and push into a queue. The real transmission is performed in the background (DMA+interrupt). The caller should take care of the lifecycle of the color buffer. Recycling of color buffer should be done in the callback on_color_trans_done().

Return

• ESP_ERR_INVALID_ARG if parameter is invalid

• ESP_OK on success

Parameters

• [in] io: LCD panel IO handle, which is created by factory API like esp_lcd_new_panel_io_spi()

• [in] lcd_cmd: The specific LCD command

• [in] color: Buffer that holds the RGB color data

• [in] color_size: Size of color in memory, in bytes

esp_err_t esp_lcd_panel_io_del(esp_lcd_panel_io_handle_t io)

Destory LCD panel IO handle (deinitialize panel and free all corresponding resource)

Return

• ESP_ERR_INVALID_ARG if parameter is invalid

• ESP_OK on success

Parameters

• [in] io: LCD panel IO handle, which is created by factory API like esp_lcd_new_panel_io_spi()

esp_err_t esp_lcd_new_panel_io_spi(esp_lcd_spi_bus_handle_t bus, const esp_lcd_panel_io_spi_config_t *io_config, esp_lcd_panel_io_handle_t *ret_io)

Create LCD panel IO handle, for SPI interface.

Return

• ESP_ERR_INVALID_ARG if parameter is invalid

• ESP_ERR_NO_MEM if out of memory

• ESP_OK on success

Parameters

• [in] bus: SPI bus handle

• [in] io_config: IO configuration, for SPI interface

• [out] ret_io: Returned IO handle

esp_err_t esp_lcd_new_panel_io_i2c(esp_lcd_i2c_bus_handle_t bus, const esp_lcd_panel_io_i2c_config_t *io_config, esp_lcd_panel_io_handle_t *ret_io)

Create LCD panel IO handle, for I2C interface.

Return

• ESP_ERR_INVALID_ARG if parameter is invalid

• ESP_ERR_NO_MEM if out of memory

• ESP_OK on success

Parameters

• [in] bus: I2C bus handle

• [in] io_config: IO configuration, for I2C interface

• [out] ret_io: Returned IO handle

Structures

struct esp_lcd_panel_io_event_data_t

Type of LCD panel IO event data.

struct esp_lcd_panel_io_spi_config_t

Panel IO configuration structure, for SPI interface.

Public Members

int cs_gpio_num

GPIO used for CS line

int dc_gpio_num

GPIO used to select the D/C line, set this to -1 if the D/C line not controlled by manually pulling high/low GPIO

int spi_mode

Traditional SPI mode (0~3)

unsigned int pclk_hz

Frequency of pixel clock

size_t trans_queue_depth

Size of internal transaction queue

esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done

Callback invoked when color data transfer has finished

void *user_ctx

User private data, passed directly to on_color_trans_done’s user_ctx

int lcd_cmd_bits

Bit-width of LCD command

int lcd_param_bits

Bit-width of LCD parameter

unsigned int dc_as_cmd_phase : 1

D/C line value is encoded into SPI transaction command phase

unsigned int dc_low_on_data : 1

If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa

unsigned int octal_mode : 1

transmit with octal mode (8 data lines), this mode is used to simulate Intel 8080 timing

struct esp_lcd_panel_io_i2c_config_t

Public Members

uint32_t dev_addr

I2C device address

esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done

Callback invoked when color data transfer has finished

void *user_ctx

User private data, passed directly to on_color_trans_done’s user_ctx

size_t control_phase_bytes

I2C LCD panel will encode control information (e.g. D/C seclection) into control phase, in several bytes

unsigned int dc_bit_offset

Offset of the D/C selection bit in control phase

int lcd_cmd_bits

Bit-width of LCD command

int lcd_param_bits

Bit-width of LCD parameter

unsigned int dc_low_on_data : 1

If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa

Type Definitions

typedef void *esp_lcd_spi_bus_handle_t

Type of LCD SPI bus handle

typedef void *esp_lcd_i2c_bus_handle_t

Type of LCD I2C bus handle

typedef struct esp_lcd_i80_bus_t *esp_lcd_i80_bus_handle_t

Type of LCD intel 8080 bus handle

typedef bool (*esp_lcd_panel_io_color_trans_done_cb_t)(esp_lcd_panel_io_handle_t panel_io, esp_lcd_panel_io_event_data_t *edata, void *user_ctx)

Declare the prototype of the function that will be invoked when panel IO finishes transferring color data.

Return

Whether a high priority task has been waken up by this function

Parameters

• [in] panel_io: LCD panel IO handle, which is created by factory API like esp_lcd_new_panel_io_spi()

• [in] edata: Panel IO event data, fed by driver

• [in] user_ctx: User data, passed from esp_lcd_panel_io_xxx_config_t

Header File

• components/esp_lcd/include/esp_lcd_panel_ops.h

Functions

esp_err_t esp_lcd_panel_reset(esp_lcd_panel_handle_t panel)

Reset LCD panel.

Note

Panel reset must be called before attempting to initialize the panel using esp_lcd_panel_init().

Return

• ESP_OK on success

Parameters

• [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

esp_err_t esp_lcd_panel_init(esp_lcd_panel_handle_t panel)

Initialize LCD panel.

Note

Before calling this function, make sure the LCD panel has finished the reset stage by esp_lcd_panel_reset().

Return

• ESP_OK on success

Parameters

• [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

esp_err_t esp_lcd_panel_del(esp_lcd_panel_handle_t panel)

Deinitialize the LCD panel.

Return

• ESP_OK on success

Parameters

• [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

esp_err_t esp_lcd_panel_draw_bitmap(esp_lcd_panel_handle_t panel, int x_start, int y_start, int x_end, int y_end, const void *color_data)

Draw bitmap on LCD panel.

Return

• ESP_OK on success

Parameters

• [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

• [in] x_start: Start index on x-axis (x_start included)

• [in] y_start: Start index on y-axis (y_start included)

• [in] x_end: End index on x-axis (x_end not included)

• [in] y_end: End index on y-axis (y_end not included)

• [in] color_data: RGB color data that will be dumped to the specific window range

esp_err_t esp_lcd_panel_mirror(esp_lcd_panel_handle_t panel, bool mirror_x, bool mirror_y)

Mirror the LCD panel on specific axis.

Note

Combined with esp_lcd_panel_swap_xy(), one can realize screen rotation

Return

• ESP_OK on success

• ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel

Parameters

• [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

• [in] mirror_x: Whether the panel will be mirrored about the x axis

• [in] mirror_y: Whether the panel will be mirrored about the y axis

esp_err_t esp_lcd_panel_swap_xy(esp_lcd_panel_handle_t panel, bool swap_axes)

Swap/Exchange x and y axis.

Note

Combined with esp_lcd_panel_mirror(), one can realize screen rotation

Return

• ESP_OK on success

• ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel

Parameters

• [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

• [in] swap_axes: Whether to swap the x and y axis

esp_err_t esp_lcd_panel_set_gap(esp_lcd_panel_handle_t panel, int x_gap, int y_gap)

Set extra gap in x and y axis.

The gap is the space (in pixels) between the left/top sides of the LCD panel and the first row/column respectively of the actual contents displayed.

Note

Setting a gap is useful when positioning or centering a frame that is smaller than the LCD.

Return

• ESP_OK on success

Parameters

• [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

• [in] x_gap: Extra gap on x axis, in pixels

• [in] y_gap: Extra gap on y axis, in pixels

esp_err_t esp_lcd_panel_invert_color(esp_lcd_panel_handle_t panel, bool invert_color_data)

Invert the color (bit-wise invert the color data line)

Return

• ESP_OK on success

Parameters

• [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

• [in] invert_color_data: Whether to invert the color data

esp_err_t esp_lcd_panel_disp_off(esp_lcd_panel_handle_t panel, bool off)

Turn off the display.

Return

• ESP_OK on success

• ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel

Parameters

• [in] panel: LCD panel handle, which is created by other factory API like esp_lcd_new_panel_st7789()

• [in] off: Whether to turn off the screen

Header File

• components/esp_lcd/include/esp_lcd_panel_rgb.h

Header File

• components/esp_lcd/include/esp_lcd_panel_vendor.h

Functions

esp_err_t esp_lcd_new_panel_st7789(const esp_lcd_panel_io_handle_t io, const esp_lcd_panel_dev_config_t *panel_dev_config, esp_lcd_panel_handle_t *ret_panel)

Create LCD panel for model ST7789.

Return

• ESP_ERR_INVALID_ARG if parameter is invalid

• ESP_ERR_NO_MEM if out of memory

• ESP_OK on success

Parameters

• [in] io: LCD panel IO handle

• [in] panel_dev_config: general panel device configuration

• [out] ret_panel: Returned LCD panel handle

esp_err_t esp_lcd_new_panel_nt35510(const esp_lcd_panel_io_handle_t io, const esp_lcd_panel_dev_config_t *panel_dev_config, esp_lcd_panel_handle_t *ret_panel)

Create LCD panel for model NT35510.

Return

• ESP_ERR_INVALID_ARG if parameter is invalid

• ESP_ERR_NO_MEM if out of memory

• ESP_OK on success

Parameters

• [in] io: LCD panel IO handle

• [in] panel_dev_config: general panel device configuration

• [out] ret_panel: Returned LCD panel handle

esp_err_t esp_lcd_new_panel_ssd1306(const esp_lcd_panel_io_handle_t io, const esp_lcd_panel_dev_config_t *panel_dev_config, esp_lcd_panel_handle_t *ret_panel)

Create LCD panel for model SSD1306.

Return

• ESP_ERR_INVALID_ARG if parameter is invalid

• ESP_ERR_NO_MEM if out of memory

• ESP_OK on success

Parameters

• [in] io: LCD panel IO handle

• [in] panel_dev_config: general panel device configuration

• [out] ret_panel: Returned LCD panel handle

Structures

struct esp_lcd_panel_dev_config_t

Configuration structure for panel device.

Public Members

int reset_gpio_num

GPIO used to reset the LCD panel, set to -1 if it’s not used

esp_lcd_color_space_t color_space

Set the color space used by the LCD panel

unsigned int bits_per_pixel

Color depth, in bpp

unsigned int reset_active_high : 1

Setting this if the panel reset is high level active

Provide feedback about this document