Liquid Crystal Display (LCD)

Overview

The lcd library provides support for configuring and displaying text to alphanumeric dot-matrix liquid crystal displays that are based on the Hitachi HD74480 controller and connected to the ESP32 via I2C.

Application Examples

Application examples demonstrating the functionality of the LCD library are provided in the examples directory of the repository. There are two example apps provided, lcd_tools and lcd_example.

lcd_tools was derived from i2c_tools and provides a tool for testing the functionality of the lcd API and also to test the capability of an attached LCD display.

lcd_example demonstrates some of the features of the LCD API and provides an example application that could be used where an alphanumeric liquid crystal display (LCD) based on the HD44780 chipset is connected to the esp32 MCU via an I2C bus.

API Reference

Header File

Functions

esp_err_t lcd_init(lcd_handle_t *lcd_handle)

Initialise LCD panel and lcd_handle data structure.

I2C driver must be configured and installed prior to calling lcd_init().

Parameters

lcd_handle – [inout] Handle to be used for future interaction with the LCD panel

Returns

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG if parameter is invalid

  • ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode

  • ESP_ERR_NOT_FOUND if LCD not found at the io handle

esp_err_t lcd_probe(const lcd_handle_t *handle)

Probe for existence of LCD at the specified address on the I2C bus.

Parameters

handle – [in] LCD handle

Returns

  • ESP_OK Success

  • ESP_ERR_NOT_FOUND LCD not found

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode

  • ESP_ERR_TIMEOUT Operation timeout because the bus is busy

esp_err_t lcd_home(lcd_handle_t *handle)

Move the cursor to the home position.

This is a relatively slow function, taking 1.52ms with a 270kHz clock. Please use lcd_clear_screen() as a faster alternative if possible.

Parameters

handle – [inout] LCD handle. Cursor position details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_write_char(lcd_handle_t *handle, char c)

Write a character to the LCD.

Parameters

  • handle – [inout] LCD handle. Cursor position details are updated

  • c – [in] Character to be written to the LCD at the current cursor position

Returns

  • ESP_OK Success

  • ESP_ERR_INVALID_SIZE Write would cause screen display overflow

  • ESP error code propagated from error source

esp_err_t lcd_write_str(lcd_handle_t *handle, char *str)

Write a character string to the LCD.

Characters in the string are written to the LCD one character at a time. If the character string is too long for the LCD, only the characters that will fit on the display will be written and ESP_ERR_INVALID_SIZE error will be returned. NOTE: This is not true - pls check the code Brad.

Parameters

  • handle – [inout] LCD handle. Cursor position details are updated

  • str – [in] Character string to be written to the LCD starting at the current cursor position

Returns

  • ESP_OK Success

  • ESP_ERR_INVALID_SIZE Write would cause screen display overflow

  • ESP error code propagated from error source

esp_err_t lcd_set_cursor(lcd_handle_t *handle, uint8_t col, uint8_t row)

Move the cursor to a specified row and column.

Column and row numbers commence at 0. Therefore, the home position is col=0, row=0.

Parameters

  • handle – [inout] LCD handle. Cursor position details are updated.

  • col – [in] The column number to move the cursor to.

  • row – [in] The row number to move the cursor to.

Returns

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Invalid parameter

  • ESP error code propagated from error source

esp_err_t lcd_clear_screen(lcd_handle_t *handle)

Clear the display. Cursor row and column reset to 0.

This function is very fast to execute and should be used instead of it’s sibling function lcd_home(), which is much slower. Refer Table 6 of HD44780U datasheet for details.

Parameters

handle – [inout] LCD. Cursor position details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_no_display(lcd_handle_t *handle)

Turn the display off.

Parameters

handle – [inout] LCD. Display control details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_display(lcd_handle_t *handle)

Turn the display on.

Parameters

handle – [inout] LCD. Display control details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_no_cursor(lcd_handle_t *handle)

Turn the cursor off.

Parameters

handle – [inout] LCD. Display control details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_cursor(lcd_handle_t *handle)

Turn the cursor on.

Parameters

handle – [inout] LCD. Display control details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_no_blink(lcd_handle_t *handle)

Turn character blink at cursor position off.

Parameters

handle – [inout] LCD. Display control details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_blink(lcd_handle_t *handle)

Turn character blink at cursor position on.

Parameters

handle – [inout] LCD. Display control details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_display_shift_left(lcd_handle_t *handle)

Shifts the display to the left.

Shifts the display left without writing or reading display data. This function is used to correct or search the display. The address counter contents will not change.

Parameters

handle – [in] LCD.

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_display_shift_right(lcd_handle_t *handle)

Shifts the display to the right.

Shifts the display right without writing or reading display data. This function is used to correct or search the display. The address counter contents will not change.

Parameters

handle – [in] LCD.

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_left_to_right(lcd_handle_t *handle)

Set text direction to be left to right.

Increments the DDRAM address by 1 when a character code is written into or read from DDRAM

Parameters

handle – [in] LCD. Display control details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_right_to_left(lcd_handle_t *handle)

Set text direction to be right to left.

Decrements the DDRAM address by 1 when a character code is written into or read from DDRAM

Parameters

handle – [in] LCD. Display control details are updated

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_autoscroll(lcd_handle_t *handle)

Enable autoscroll.

This gives the effect that the cursor will seem to not move but the display does. Enabling this function breaks the row and column tracking capability of the lcd_handle and hence is not yet supported by the LCD API.

Parameters

handle – [inout] Display mode is updated.

Returns

  • ESP_ERR_NOT_SUPPORTED This function is not yet supported

esp_err_t lcd_no_autoscroll(lcd_handle_t *handle)

Disable autoscroll.

Parameters

handle – [inout] Display mode is updated.

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_backlight(lcd_handle_t *handle)

Enables backlight.

Parameters

handle – [inout] Backlight element of the handle is updated.

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_no_backlight(lcd_handle_t *handle)

Disables backlight.

Parameters

handle – [inout] Backlight element of the handle is updated.

Returns

  • ESP_OK Success

  • ESP error code propagated from error source

esp_err_t lcd_write_cgram(lcd_handle_t *handle, uint8_t location, uint8_t *charmap)

Write custom character to CGRAM at specified location.

Writes character given in byte array[8] to CGRAM and resets cursor address.

Parameters

  • handle – [inout] LCD handle. Character written to CGRAM. Cursor position set to 0.

  • location – [in] The location in CGRAM.

  • charmap – [in] The character bitmap in form of byte array[8].

Returns

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Invalid parameter

  • ESP error code propagated from error source