LCD Driver

Generic liquid crystal display APIs. More...

Topics
	LCD Controller
	Generic liquid crystal display controller specific APIs.
	LCD Commands
	LCD commands.

Data Structures
struct	lcd_config
struct	lcd_handle

Macros
#define	LCD_MAP_PINS(lcd_cfg)   LCD_MAP_PINS_4BIT(lcd_cfg)
	Mapping default LCD control and data pins.
#define	LCD_MAP_PINS_4BIT(lcd_cfg)
	Mapping 4-bit LCD control and data pins.
#define	LCD_MAP_PINS_8BIT(lcd_cfg)
	Mapping 8-bit LCD control and data pins.

Typedefs
typedef struct lcd_config	lcd_config_t
typedef void(*	init_sequence_ptr) (uint32_t)
	Init sequence prototype.
typedef struct lcd_handle	lcd_handle_t

Enumerations
enum	lcd_err_t { LCD_SUCCESS = 0 , LCD_ERROR = (-1) }
enum	lcd_select_t { LCD_SELECT_CMD = 0 , LCD_SELECT_DATA }
enum	lcd_mode_t { LCD_MODE_BIT_4 = 0 , LCD_MODE_BIT_8 }
enum	lcd_row_t { LCD_ROW_1 = 0x80 , LCD_ROW_2 = 0xC0 , LCD_ROW_3 = 0x94 , LCD_ROW_4 = 0xD4 }

Functions list
void	lcd_configure_default (lcd_config_t *config)
	Configure LCD configuration structure.
lcd_err_t	lcd_configure (lcd_handle_t *lcd_handle, lcd_config_t *config)
	Configures LCD handle with passed configuration structure.
void	lcd_init (lcd_handle_t lcd_handle, init_sequence_ptr init_sequence)
	Initializes LCD.
void	lcd_write (lcd_handle_t lcd_handle, char lcd_cmd_data, lcd_select_t cmd_or_data)
	Writes data to LCD.
void	lcd_write_text (lcd_handle_t lcd_handle, char *lcd_data, lcd_row_t row)
	Writes text to LCD.
void	lcd_shift_right (lcd_handle_t lcd_handle)
	Shifts data currently on LCD.
void	lcd_shift_left (lcd_handle_t lcd_handle)
	Shifts data currently on LCD.
void	lcd_set_row (lcd_handle_t lcd_handle, lcd_row_t row)
	Sets current active row on LCD.
void	lcd_turn_on (lcd_handle_t lcd_handle)
	Turns LCD ON.
void	lcd_turn_off (lcd_handle_t lcd_handle)
	Turns LCD OFF.
void	lcd_clear (lcd_handle_t lcd_handle)
	Clears LCD.
void	lcd_cursor_move_home (lcd_handle_t lcd_handle)
	Moves cursor to first position.
void	lcd_cursor_move_left (lcd_handle_t lcd_handle)
	Moves cursor position.
void	lcd_cursor_move_right (lcd_handle_t lcd_handle)
	Moves cursor position.
void	lcd_cursor_off (lcd_handle_t lcd_handle)
	Removes cursor.
void	lcd_cursor_on (lcd_handle_t lcd_handle)
	Shows cursor.
void	lcd_backlight_off (lcd_handle_t lcd_handle)
	Turns LCD backlight OFF.
void	lcd_backlight_on (lcd_handle_t lcd_handle)
	Turns LCD backlight ON.

Macro Definition Documentation

LCD_MAP_PINS

#define LCD_MAP_PINS

(

lcd_cfg

)

LCD_MAP_PINS_4BIT(lcd_cfg)

Attention

This API is called by default in LCD code initialization.

LCD_MAP_PINS_4BIT

#define LCD_MAP_PINS_4BIT

(

lcd_cfg

)

Value:

        lcd_cfg.pin_cs = TFT_CS; \
        lcd_cfg.pin_rst = TFT_RST; \
        lcd_cfg.pin_backlight = TFT_BPWM; \
        lcd_cfg.pin_d4 = TFT_D4; \
        lcd_cfg.pin_d5 = TFT_D5; \
        lcd_cfg.pin_d6 = TFT_D6; \
        lcd_cfg.pin_d7 = TFT_D7;

LCD_MAP_PINS_8BIT

#define LCD_MAP_PINS_8BIT

(

lcd_cfg

)

Value:

        lcd_cfg.pin_cs = TFT_CS; \
        lcd_cfg.pin_rst = TFT_RST; \
        lcd_cfg.pin_backlight = TFT_BPWM; \
        lcd_cfg.pin_d0 = TFT_D0; \
        lcd_cfg.pin_d1 = TFT_D1; \
        lcd_cfg.pin_d2 = TFT_D2; \
        lcd_cfg.pin_d3 = TFT_D3; \
        lcd_cfg.pin_d4 = TFT_D4; \
        lcd_cfg.pin_d5 = TFT_D5; \
        lcd_cfg.pin_d6 = TFT_D6; \
        lcd_cfg.pin_d7 = TFT_D7;

Typedef Documentation

init_sequence_ptr

typedef void(* init_sequence_ptr) (uint32_t)

Note

Expected from user to provide valid routine address.

lcd_config_t

typedef struct lcd_config lcd_config_t

Main cofiguration structure.

lcd_handle_t

typedef struct lcd_handle lcd_handle_t

Main handle for LCD operations.

Enumeration Type Documentation

lcd_err_t

enum lcd_err_t

Return values.

Enumerator
LCD_SUCCESS	Success.
LCD_ERROR	Error.

lcd_mode_t

enum lcd_mode_t

Selects LCD data mode.

Enumerator
LCD_MODE_BIT_4	4 bit data mode.
LCD_MODE_BIT_8	8 bit data mode.

lcd_row_t

enum lcd_row_t

Selects desired row on initialized LCD.

Enumerator
LCD_ROW_1	First row.
LCD_ROW_2	Second row.
LCD_ROW_3	Third row.
LCD_ROW_4	Fourth row.

lcd_select_t

enum lcd_select_t

Selects type of data passed to LCD.

Enumerator
LCD_SELECT_CMD	Select command.
LCD_SELECT_DATA	Select data.

Function Documentation

lcd_backlight_off()

void lcd_backlight_off

(

lcd_handle_t

lcd_handle

)

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Clear display.
lcd_backlight_off(lcd);

lcd_backlight_on()

void lcd_backlight_on

(

lcd_handle_t

lcd_handle

)

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Clear display.
lcd_backlight_on(lcd);

lcd_clear()

void lcd_clear

(

lcd_handle_t

lcd_handle

)

Clears all characters on LCD.

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Clear display.
lcd_clear(lcd);

lcd_configure()

lcd_err_t lcd_configure	(	lcd_handle_t *	lcd_handle,
		lcd_config_t *	config )

Configures LCD handle to values set in passed configuration structure. Additionaly will initialize all provided pins.

Parameters

[in,out]	lcd_handle	LCD handle. See lcd_handle_t structure definition for detailed explanation.
[in]	config	LCD driver configuration structure. See lcd_config_t structure definition for detailed explanation.

Returns

lcd_err_t. Will return error if some of the pins weren't initialized correctly.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);

lcd_configure_default()

void lcd_configure_default

(

lcd_config_t *

config

)

Configures LCD structure to default initialization values. Take into consideration that this is just structure variable initial values setting. Values need to be redefined by user.

Parameters

[in,out]

config

LCD driver configuration structure. See lcd_config_t structure definition for detailed explanation.

Default values:

Function	Default value
PIN_CS	HAL_PIN_NC
PIN_RST	HAL_PIN_NC
PIN_BACKLIGHT	HAL_PIN_NC
PIN_D0	HAL_PIN_NC
PIN_D1	HAL_PIN_NC
PIN_D2	HAL_PIN_NC
PIN_D3	HAL_PIN_NC
PIN_D4	HAL_PIN_NC
PIN_D5	HAL_PIN_NC
PIN_D6	HAL_PIN_NC
PIN_D7	HAL_PIN_NC
MODE	LCD_MODE_BIT_4
WAITBETWEENWRITES	1000

Returns

Nothing.

Example

// LCD config structure.
lcd_config_t lcd_cfg;
 
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);

Note

PIN_BACKLIGHT is not required.

lcd_cursor_move_home()

void lcd_cursor_move_home

(

lcd_handle_t

lcd_handle

)

Moves current cursor position back to the home position.

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Clear display.
lcd_cursor_move_home(lcd);

lcd_cursor_move_left()

void lcd_cursor_move_left

(

lcd_handle_t

lcd_handle

)

Moves current cursor position one column to the left.

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Clear display.
lcd_cursor_move_left(lcd);

lcd_cursor_move_right()

void lcd_cursor_move_right

(

lcd_handle_t

lcd_handle

)

Moves current cursor position one column to the right.

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Clear display.
lcd_cursor_move_right(lcd);

lcd_cursor_off()

void lcd_cursor_off

(

lcd_handle_t

lcd_handle

)

Removes cursor from current position on the display.

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Clear display.
lcd_cursor_off(lcd);

lcd_cursor_on()

void lcd_cursor_on

(

lcd_handle_t

lcd_handle

)

Shows current cursor position on the display.

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Clear display.
lcd_cursor_on(lcd);

Attention

Turns cursor blinking ON for better visibility as well.

lcd_init()

void lcd_init	(	lcd_handle_t	lcd_handle,
		init_sequence_ptr	init_sequence )

Initializes LCD with default values.

Parameters

[in]	lcd_handle	LCD handle.
[in]	init_sequence_ptr	Pointer to init sequence API. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd, hd44780_lcd_init);

Note

init_sequence_ptr can be declared by user as well.

lcd_set_row()

void lcd_set_row	(	lcd_handle_t	lcd_handle,
		lcd_row_t	row )

Sets active row on the LCD where data is to be output.

Parameters

[in]	lcd_handle	LCD handle. See lcd_handle_t structure definition for detailed explanation.
[in]	row	Desired row. Takes lcd_row_t values.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Write out "Some text" to LCD row 2.
lcd_set_row(lcd, LCD_ROW_2);
lcd_write_text(lcd, "Some text", LCD_ROW_1);

lcd_shift_left()

void lcd_shift_left

(

lcd_handle_t

lcd_handle

)

Shifts the data on all rows on LCD one character at a time.

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Write out "Some text" to LCD row 1.
lcd_write_text(lcd, "Some text", LCD_ROW_1);
 
// Move text to the right 7 times.
for(char i=0; i<8; i++) {
    lcd_shift_right(lcd);
    Delay_ms(250);
}

lcd_shift_right()

void lcd_shift_right

(

lcd_handle_t

lcd_handle

)

Shifts the data on all rows on LCD one character at a time.

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Write out "Some text" to LCD row 1.
lcd_write_text(lcd, "Some text", LCD_ROW_1);
 
// Move text to the left 7 times.
for(char i=0; i<8; i++) {
    lcd_shift_left(lcd);
    Delay_ms(250);
}

lcd_turn_off()

void lcd_turn_off

(

lcd_handle_t

lcd_handle

)

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Turn LCD OFF.
lcd_turn_off(lcd);

lcd_turn_on()

void lcd_turn_on

(

lcd_handle_t

lcd_handle

)

Parameters

[in]

lcd_handle

LCD handle. See lcd_handle_t structure definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Turn LCD ON.
lcd_turn_on(lcd);

lcd_write()

void lcd_write	(	lcd_handle_t	lcd_handle,
		char	lcd_cmd_data,
		lcd_select_t	cmd_or_data )

Writes either commands or data to LCD lines.

Parameters

[in]	lcd_handle	LCD handle. See lcd_handle_t structure definition for detailed explanation.
[in]	lcd_cmd_data	Data or command.
[in]	cmd_or_data	Selector for pulse signaling. See lcd_select_t enum definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Write command to set first row as active one.
lcd_write(lcd, LCD_ROW_1, LCD_SELECT_CMD);
 
// Write out character 'A'.
lcd_write(lcd, 'A', LCD_SELECT_DATA);

lcd_write_text()

void lcd_write_text	(	lcd_handle_t	lcd_handle,
		char *	lcd_data,
		lcd_row_t	row )

Writes array of characters to LCD lines one by one.

Parameters

[in]	lcd_handle	LCD handle. See lcd_handle_t structure definition for detailed explanation.
[in]	lcd_data	Data.
[in]	row	Selects row to write to. See lcd_row_t enum definition for detailed explanation.

Returns

Nothing.

Example

// LCD handle.
lcd_handle_t lcd;
// LCD config structure.
lcd_config_t lcd_cfg;
// Fill structure with default values.
lcd_configure_default(&lcd_cfg);
// Set default pins.
LCD_MAP_PINS(lcd_cfg);
 
// Initialize handle and pins.
lcd_configure(&lcd, &lcd_cfg);
// Initialize LCD.
lcd_init(lcd);
 
// Write out "Some text" to LCD row 1.
lcd_write_text(lcd, "Some text", LCD_ROW_1);