The LCD1602 controller is an HD44780-compatible controller that normally operates via an 8-bit or 4-bit wide parallel bus. More...

#include <stddef.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "esp_log.h"
#include "i2c-lcd1602.h"

Macros
#define	TAG "i2c-lcd1602"

#define	DELAY_POWER_ON 50000

#define	DELAY_INIT_1 4500

#define	DELAY_INIT_2 4500

#define	DELAY_INIT_3 120

#define	DELAY_CLEAR_DISPLAY 2000

#define	DELAY_RETURN_HOME 2000

#define	DELAY_ENABLE_PULSE_WIDTH 1

#define	DELAY_ENABLE_PULSE_SETTLE 50

#define	COMMAND_CLEAR_DISPLAY 0x01

#define	COMMAND_RETURN_HOME 0x02

#define	COMMAND_ENTRY_MODE_SET 0x04

#define	COMMAND_DISPLAY_CONTROL 0x08

#define	COMMAND_SHIFT 0x10

#define	COMMAND_FUNCTION_SET 0x20

#define	COMMAND_SET_CGRAM_ADDR 0x40

#define	COMMAND_SET_DDRAM_ADDR 0x80

#define	FLAG_ENTRY_MODE_SET_ENTRY_INCREMENT 0x02

#define	FLAG_ENTRY_MODE_SET_ENTRY_DECREMENT 0x00

#define	FLAG_ENTRY_MODE_SET_ENTRY_SHIFT_ON 0x01

#define	FLAG_ENTRY_MODE_SET_ENTRY_SHIFT_OFF 0x00

#define	FLAG_DISPLAY_CONTROL_DISPLAY_ON 0x04

#define	FLAG_DISPLAY_CONTROL_DISPLAY_OFF 0x00

#define	FLAG_DISPLAY_CONTROL_CURSOR_ON 0x02

#define	FLAG_DISPLAY_CONTROL_CURSOR_OFF 0x00

#define	FLAG_DISPLAY_CONTROL_BLINK_ON 0x01

#define	FLAG_DISPLAY_CONTROL_BLINK_OFF 0x00

#define	FLAG_SHIFT_MOVE_DISPLAY 0x08

#define	FLAG_SHIFT_MOVE_CURSOR 0x00

#define	FLAG_SHIFT_MOVE_LEFT 0x04

#define	FLAG_SHIFT_MOVE_RIGHT 0x00

#define	FLAG_FUNCTION_SET_MODE_8BIT 0x10

#define	FLAG_FUNCTION_SET_MODE_4BIT 0x00

#define	FLAG_FUNCTION_SET_LINES_2 0x08

#define	FLAG_FUNCTION_SET_LINES_1 0x00

#define	FLAG_FUNCTION_SET_DOTS_5X10 0x04

#define	FLAG_FUNCTION_SET_DOTS_5X8 0x00

#define	FLAG_BACKLIGHT_ON 0b00001000

#define	FLAG_BACKLIGHT_OFF 0b00000000

#define	FLAG_ENABLE 0b00000100

#define	FLAG_READ 0b00000010

#define	FLAG_WRITE 0b00000000

#define	FLAG_RS_DATA 0b00000001

#define	FLAG_RS_COMMAND 0b00000000

Functions
i2c_lcd1602_info_t *	i2c_lcd1602_malloc (void)
	Construct a new I2C-LCD1602 info instance. New instance should be initialised before calling other functions. More...

void	i2c_lcd1602_free (i2c_lcd1602_info_t **i2c_lcd1602_info)
	Delete an existing I2C-LCD1602 info instance. More...

esp_err_t	i2c_lcd1602_init (i2c_lcd1602_info_t i2c_lcd1602_info, smbus_info_t smbus_info, bool backlight, uint8_t num_rows, uint8_t num_columns, uint8_t num_visible_columns)
	Initialise a I2C-LCD1602 info instance with the specified SMBus information. More...

esp_err_t	i2c_lcd1602_reset (const i2c_lcd1602_info_t *i2c_lcd1602_info)
	Reset the display. Custom characters will be cleared. More...

esp_err_t	i2c_lcd1602_clear (const i2c_lcd1602_info_t *i2c_lcd1602_info)
	Clears entire display (clears DDRAM) and returns cursor to home position. DDRAM content is cleared, CGRAM content is not changed. More...

esp_err_t	i2c_lcd1602_home (const i2c_lcd1602_info_t *i2c_lcd1602_info)
	Move cursor to home position. Also resets any display shift that may have occurred. DDRAM content is not changed. CGRAM content is not changed. More...

esp_err_t	i2c_lcd1602_move_cursor (const i2c_lcd1602_info_t *i2c_lcd1602_info, uint8_t col, uint8_t row)
	Move cursor to specified column and row position. This is where a new character will appear. More...

esp_err_t	i2c_lcd1602_set_backlight (i2c_lcd1602_info_t *i2c_lcd1602_info, bool enable)
	Enable or disable the LED backlight. More...

esp_err_t	i2c_lcd1602_set_display (i2c_lcd1602_info_t *i2c_lcd1602_info, bool enable)
	Enable or disable the display. When disabled, the backlight is not affected, but any contents of the DDRAM is not displayed, nor is the cursor. The display is "blank". Re-enabling the display does not affect the contents of DDRAM or the state or position of the cursor. More...

esp_err_t	i2c_lcd1602_set_cursor (i2c_lcd1602_info_t *i2c_lcd1602_info, bool enable)
	Enable or disable display of the underline cursor. If enabled, this visually indicates where the next character written to the display will appear. It may be enabled alongside the blinking cursor, however the visual result is inelegant. More...

esp_err_t	i2c_lcd1602_set_blink (i2c_lcd1602_info_t *i2c_lcd1602_info, bool enable)
	Enable or disable display of the blinking block cursor. If enabled, this visually indicates where the next character written to the display will appear. It may be enabled alongside the underline cursor, however the visual result is inelegant. More...

esp_err_t	i2c_lcd1602_set_left_to_right (i2c_lcd1602_info_t *i2c_lcd1602_info)
	Set cursor movement direction following each character write to produce left-to-right text. More...

esp_err_t	i2c_lcd1602_set_right_to_left (i2c_lcd1602_info_t *i2c_lcd1602_info)
	Set cursor movement direction following each character write to produce right-to-left text. More...

esp_err_t	i2c_lcd1602_set_auto_scroll (i2c_lcd1602_info_t *i2c_lcd1602_info, bool enable)
	Enable or disable auto-scroll of display. When enabled, the display will scroll as characters are written to maintain the cursor position on-screen. Left-to-right text will appear to be right-justified from the cursor position. When disabled, the display will not scroll and the cursor will move on-screen. Left-to-right text will appear to be left-justified from the cursor position. More...

esp_err_t	i2c_lcd1602_scroll_display_left (const i2c_lcd1602_info_t *i2c_lcd1602_info)
	Scroll the display one position to the left. On-screen text will appear to move to the right. More...

esp_err_t	i2c_lcd1602_scroll_display_right (const i2c_lcd1602_info_t *i2c_lcd1602_info)
	Scroll the display one position to the right. On-screen text will appear to move to the left. More...

esp_err_t	i2c_lcd1602_move_cursor_left (const i2c_lcd1602_info_t *i2c_lcd1602_info)
	Move the cursor one position to the left, even if it is invisible. This affects where the next character written to the display will appear. More...

esp_err_t	i2c_lcd1602_move_cursor_right (const i2c_lcd1602_info_t *i2c_lcd1602_info)
	Move the cursor one position to the right, even if it is invisible. This affects where the next character written to the display will appear. More...

esp_err_t	i2c_lcd1602_define_char (const i2c_lcd1602_info_t *i2c_lcd1602_info, i2c_lcd1602_custom_index_t index, const uint8_t pixelmap[])
	Define a custom character from an array of pixel data. More...

esp_err_t	i2c_lcd1602_write_char (const i2c_lcd1602_info_t *i2c_lcd1602_info, uint8_t chr)
	Write a single character to the display at the current position of the cursor. Depending on the active mode, the cursor may move left or right, or the display may shift left or right. Custom characters can be written using the I2C_LCD1602_CHARACTER_CUSTOM_X definitions. More...

esp_err_t	i2c_lcd1602_write_string (const i2c_lcd1602_info_t i2c_lcd1602_info, const char string)
	Write a string of characters to the display, starting at the current position of the cursor. Depending on the active mode, the cursor may move left or right, or the display may shift left or right, after each character is written. More...

Detailed Description

The LCD1602 controller is an HD44780-compatible controller that normally operates via an 8-bit or 4-bit wide parallel bus.

https://www.sparkfun.com/datasheets/LCD/HD44780.pdf

The LCD1602 controller is connected to a PCF8574A I/O expander via the I2C bus. Only the top four bits are connected to the controller's data lines. The lower four bits are used as control lines:

B7: data bit 3
B6: data bit 2
B5: data bit 1
B4: data bit 0
B3: backlight (BL): off = 0, on = 1
B2: enable (EN): change from 1 to 0 to clock data into controller
B1: read/write (RW): write = 0, read = 1
B0: register select (RS): command = 0, data = 1

Therefore to send a command byte requires the following operations:

// First nibble: val = command & 0xf0 // extract top nibble val |= 0x04 // RS = 0 (command), RW = 0 (write), EN = 1 i2c_write_byte(i2c_address, val) sleep(2ms) val &= 0xfb // EN = 0 i2c_write_byte(i2c_address, val)

// Second nibble: val = command & 0x0f // extract bottom nibble val |= 0x04 // RS = 0 (command), RW = 0 (write), EN = 1 i2c_write_byte(i2c_address, val) sleep(2ms) val &= 0xfb // EN = 0 i2c_write_byte(i2c_address, val)

Sending a data byte is very similar except that RS = 1 (data)

When the controller powers up, it defaults to:

display cleared
8-bit interface, 1 line display, 5x8 dots per character
increment by 1 set
no shift

The controller must be set to 4-bit operation before proper communication can commence. The initialisation sequence for 4-bit operation is:

0. wait > 15ms after Vcc rises to 4.5V, or > 40ms after Vcc rises to 2.7V

send nibble 0x03 // select 8-bit interface
wait > 4.1ms
send nibble 0x03 // select 8-bit interface again
wait > 100us
send command 0x32 // select 4-bit interface
send command 0x28 // set 2 lines and 5x7(8?) dots per character
send command 0x0c // display on, cursor off
send command 0x06 // move cursor right when writing, no scroll
send command 0x80 // set cursor to home position (row 1, column 1)

Function Documentation

i2c_lcd1602_info_t* i2c_lcd1602_malloc ( void )

Construct a new I2C-LCD1602 info instance. New instance should be initialised before calling other functions.

Returns: Pointer to new device info instance, or NULL if it cannot be created.

void i2c_lcd1602_free ( i2c_lcd1602_info_t ** tsl2561_info )

Delete an existing I2C-LCD1602 info instance.

Parameters

[in,out] tsl2561_info Pointer to I2C-LCD1602 info instance that will be freed and set to NULL.

esp_err_t i2c_lcd1602_init	(	i2c_lcd1602_info_t *	i2c_lcd1602_info,
		smbus_info_t *	smbus_info,
		bool	backlight,
		uint8_t	num_rows,
		uint8_t	num_columns,
		uint8_t	num_visible_columns
	)

Initialise a I2C-LCD1602 info instance with the specified SMBus information.

Parameters

[in]	i2c_lcd1602_info	Pointer to I2C-LCD1602 info instance.
[in]	smbus_info	Pointer to SMBus info instance.
[in]	backlight	Initial backlight state.
[in]	num_rows	Maximum number of supported rows for this device. Typical values include 2 (1602) or 4 (2004).
[in]	num_columns	Maximum number of supported columns for this device. Typical values include 40 (1602, 2004).
[in]	num_visible_columns	Number of columns visible at any one time. Typical values include 16 (1602) or 20 (2004).

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_reset ( const i2c_lcd1602_info_t * i2c_lcd1602_info )

Reset the display. Custom characters will be cleared.

Parameters

[in] i2c_lcd1602_info Pointer to I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_clear ( const i2c_lcd1602_info_t * i2c_lcd1602_info )

Clears entire display (clears DDRAM) and returns cursor to home position. DDRAM content is cleared, CGRAM content is not changed.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_home ( const i2c_lcd1602_info_t * i2c_lcd1602_info )

Move cursor to home position. Also resets any display shift that may have occurred. DDRAM content is not changed. CGRAM content is not changed.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_move_cursor	(	const i2c_lcd1602_info_t *	i2c_lcd1602_info,
		uint8_t	col,
		uint8_t	row
	)

Move cursor to specified column and row position. This is where a new character will appear.

Parameters

[in]	i2c_lcd1602_info	Pointer to initialised I2C-LCD1602 info instance.
[in]	col	Zero-based horizontal index of intended cursor position. Column 0 is the left column.
[in]	row	Zero-based vertical index of intended cursor position. Row 0 is the top row.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_set_backlight	(	i2c_lcd1602_info_t *	i2c_lcd1602_info,
		bool	enable
	)

Enable or disable the LED backlight.

Parameters

[in]	i2c_lcd1602_info	Pointer to initialised I2C-LCD1602 info instance.
[in]	enable	True to enable, false to disable.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_set_display	(	i2c_lcd1602_info_t *	i2c_lcd1602_info,
		bool	enable
	)

Enable or disable the display. When disabled, the backlight is not affected, but any contents of the DDRAM is not displayed, nor is the cursor. The display is "blank". Re-enabling the display does not affect the contents of DDRAM or the state or position of the cursor.

Parameters

[in]	i2c_lcd1602_info	Pointer to initialised I2C-LCD1602 info instance.
[in]	enable	True to enable, false to disable.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_set_cursor	(	i2c_lcd1602_info_t *	i2c_lcd1602_info,
		bool	enable
	)

Enable or disable display of the underline cursor. If enabled, this visually indicates where the next character written to the display will appear. It may be enabled alongside the blinking cursor, however the visual result is inelegant.

Parameters

[in]	i2c_lcd1602_info	Pointer to initialised I2C-LCD1602 info instance.
[in]	enable	True to enable, false to disable.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_set_blink	(	i2c_lcd1602_info_t *	i2c_lcd1602_info,
		bool	enable
	)

Enable or disable display of the blinking block cursor. If enabled, this visually indicates where the next character written to the display will appear. It may be enabled alongside the underline cursor, however the visual result is inelegant.

Parameters

[in]	i2c_lcd1602_info	Pointer to initialised I2C-LCD1602 info instance.
[in]	enable	True to enable, false to disable.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_set_left_to_right ( i2c_lcd1602_info_t * i2c_lcd1602_info )

Set cursor movement direction following each character write to produce left-to-right text.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_set_right_to_left ( i2c_lcd1602_info_t * i2c_lcd1602_info )

Set cursor movement direction following each character write to produce right-to-left text.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_set_auto_scroll	(	i2c_lcd1602_info_t *	i2c_lcd1602_info,
		bool	enable
	)

Enable or disable auto-scroll of display. When enabled, the display will scroll as characters are written to maintain the cursor position on-screen. Left-to-right text will appear to be right-justified from the cursor position. When disabled, the display will not scroll and the cursor will move on-screen. Left-to-right text will appear to be left-justified from the cursor position.

Parameters

[in]	i2c_lcd1602_info	Pointer to initialised I2C-LCD1602 info instance.
[in]	enable	True to enable, false to disable.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_scroll_display_left ( const i2c_lcd1602_info_t * i2c_lcd1602_info )

Scroll the display one position to the left. On-screen text will appear to move to the right.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_scroll_display_right ( const i2c_lcd1602_info_t * i2c_lcd1602_info )

Scroll the display one position to the right. On-screen text will appear to move to the left.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_move_cursor_left ( const i2c_lcd1602_info_t * i2c_lcd1602_info )

Move the cursor one position to the left, even if it is invisible. This affects where the next character written to the display will appear.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_move_cursor_right ( const i2c_lcd1602_info_t * i2c_lcd1602_info )

Move the cursor one position to the right, even if it is invisible. This affects where the next character written to the display will appear.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_define_char	(	const i2c_lcd1602_info_t *	i2c_lcd1602_info,
		i2c_lcd1602_custom_index_t	index,
		const uint8_t	pixelmap[]
	)

Define a custom character from an array of pixel data.

There are eight possible custom characters, and the zero-based index is used to select a character to define. Any existing character definition at that index will be lost. Characters are 5 pixels wide and 8 pixels tall. The pixelmap array consists of up to eight bytes, each byte representing the pixel states per row. The first byte represents the top row. The eighth byte is often left as zero (to leave space for the underline cursor). For each row, the lowest five bits represent pixels that are to be illuminated. The least significant bit represents the right-most pixel. Empty rows will be zero.

NOTE: After calling this function, the DDRAM will not be selected and the cursor position will be undefined. Therefore it is important that the DDRAM address is set following this function, if text is to be written to the display. This can be performed with a call to i2c_lcd1602_home() or i2c_lcd1602_move_cursor().

Custom characters are written using the I2C_LCD1602_CHARACTER_CUSTOM_X definitions.

Parameters

[in]	i2c_lcd1602_info	Pointer to initialised I2C-LCD1602 info instance.
[in]	index	Zero-based index of the character to define. Only values 0-7 are valid.
[in]	pixelmap	An 8-byte array defining the pixel map for the new character definition.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_write_char	(	const i2c_lcd1602_info_t *	i2c_lcd1602_info,
		uint8_t	chr
	)

Write a single character to the display at the current position of the cursor. Depending on the active mode, the cursor may move left or right, or the display may shift left or right. Custom characters can be written using the I2C_LCD1602_CHARACTER_CUSTOM_X definitions.

The display is I2C_LCD1602_NUM_COLUMNS wide, and upon encountering the end of the first line, the cursor will automatically move to the beginning of the second line.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

esp_err_t i2c_lcd1602_write_string	(	const i2c_lcd1602_info_t *	i2c_lcd1602_info,
		const char *	string
	)

Write a string of characters to the display, starting at the current position of the cursor. Depending on the active mode, the cursor may move left or right, or the display may shift left or right, after each character is written.

The display is I2C_LCD1602_NUM_COLUMNS wide, and upon encountering the end of the first line, the cursor will automatically move to the beginning of the second line.

Parameters

[in] i2c_lcd1602_info Pointer to initialised I2C-LCD1602 info instance.

Returns: ESP_OK if successful, otherwise an error constant.

Macros

Functions

Detailed Description

Function Documentation