A class for efficiently driving an LDC display connected to the I2C bus on Arduino or Pi Pico. More...

Static Public Attributes
static constexpr uint8_t	CUSTOM_SYMBOL_SIZE = 8
	A reminder of the size of custom character arrays. More...

static constexpr byte	LCD_5x10DOTS = 0x04
	needed for Arduino Constructor More...

static constexpr byte	LCD_5x8DOTS = 0x00
	needed for Arduino Constructor More...

Pi Pico Constructor
	LCD_I2C (byte address, byte columns, byte rows, i2c_inst *I2C=PICO_DEFAULT_I2C_INSTANCE) noexcept
	The Pi Pico Constructor. More...

Writing to the screen on the Pi Pico
These are the simplest output routines for writing characters to the LCD screen. They are in the spirit of the example in the Pi Pico SDK. Of course the Arduino routines below can also be used on the Pico, and these routines can be used on Arduino. Also see the Theory of Operation for hints on maximizing display speed.
void	writeChar (byte val, bool Enable_Buffering=false) noexcept
	Output a character to the screen. More...

void	writeString (const char str[], bool Enable_Buffering=false) noexcept
	Output a string to the screen. Naming is more in the style of the Pico SDK, and the Enable_Buffering parameter can be utilized. More...

void	printstr (const char str[]) noexcept
	An alias for writeString (for compatibility with earlier programs) More...

Writing to the screen on Arduino
On the Arduino, the LCD I2C class is derived from the Arduino Print class, so all the print() methods need to work. These routines override various forms of the write() methods in the print class to efficiently direct the data from the print() methods to the LCD display. Of course these methods can be called directly on the Arduino or the Pi Pico as well. Also see the Theory of Operation for hints on maximizing display speed.
size_t	write (uint8_t c) noexcept
	Override the write byte method of the Arduino print class. More...

size_t	write (const uint8_t *buffer, size_t size, bool Enable_Buffering=false) noexcept
	Override the write array of bytes method of the Arduino print class. More...

size_t	write (const char *str) noexcept
	Override write string method of the Arduino Print class. More...

size_t	write (const char *buffer, size_t size, bool Enable_Buffering=false) noexcept
	Override the write buffer of type char method from Arduino print. More...

Simple display control
void	setCursor (byte line, byte position, bool Enable_Buffering=false) noexcept
	Move the input cursor to a location on the screen. More...

void	clear (void) noexcept
	Clear the display. More...

void	home (void) noexcept
	"Home" the display. More...

void	backlight (void) noexcept
	Turn on the display backlight. More...

void	noBacklight (void) noexcept
	Turn off the display backlight More...

void	setBacklight (uint8_t newVal) noexcept
	Set the backlight to a given value. More...

void	display (void) noexcept
	Turns the display on without modifying data on it. More...

void	noDisplay (void) noexcept
	Turns the display off without modifying data on it. More...

Cursor Appearance Controls
The cursor can be displayed on the screen as an underscore at the current location, or as a blinking inversion of the character at the cursor location. Both of these modes can be enabled at once, or they can both be turned off, making the cursor invisible!
void	cursor (void) noexcept
	Display the underline cursor at the current cursor location. More...

void	cursor_on () noexcept
	Alias for cursor() to turn the underline cursor on. More...

void	noCursor (void) noexcept
	Hides the underline cursor at the current cursor location. More...

void	cursor_off () noexcept
	An alias for noCursor to turn off the underline cursor. More...

void	blink (void) noexcept
	Display the blinking inverted cursor at the current cursor location. More...

void	blink_on () noexcept
	Alias for blink() to display the blinking inverted cursor. More...

void	noBlink (void) noexcept
	Disable the blinking inverted cursor at the current cursor location. More...

void	blink_off () noexcept
	Alias for noBlink() to turn off the blinking inverted cursor. More...

Advanced Display Control
void	scrollDisplayLeft (void) noexcept
	Scrolls the display and cursor one position to the left. home() will restore it to its original position. More...

void	scrollDisplayRight (void) noexcept
	Scrolls the display and cursor one position to the right. home() will restore it to its original position. More...

void	autoscroll (void) noexcept
	Turns on automatic scrolling of the display. More...

void	noAutoscroll (void) noexcept
	Turns off automatic scrolling of the display. More...

void	leftToRight (void) noexcept
	Sets the text direction to left to right. Each character output advances the cursor one position to the right. This is the default condition. More...

void	rightToLeft (void) noexcept
	Sets the text direction to right to left. Each character output advances the cursor one position to the left. More...

Custom Characters
The display can store 8 user defined custom characters. They are stored at "memory addresses" 0-7. They are displayed when character codes 0-7 are written to the display. Of course, character value "0" cannot be included in a string because it would be the string terminator. A 0 can be written using the write single character routines, or the write() method with an array of characters and a character count. As an alternative, the display controller also duplicates the special characters as character codes 8-15 (0x8-0xf), which can be encoded and written as strings.
void	createChar (byte charnum, const byte char_map[]) noexcept
	Create a custom character. More...

void	load_custom_character (uint8_t char_num, uint8_t *rows) noexcept
	An alias for createChar() for loading custom character data. More...

Advanced Buffering Control
int	show (void) noexcept
	Empties the buffer to "show" any data not yet output to the screen. More...

Detailed Description

A class for efficiently driving an LDC display connected to the I2C bus on Arduino or Pi Pico.

For the Arduino, the class is derived from the Print class so that all the Arduino Print or write methods can be used.

For the Pi Pico, this is a stand-alone class.

Constructor & Destructor Documentation

◆ LCD_I2C()

LCD_I2C::LCD_I2C	(	byte	address,
		byte	columns,
		byte	rows,
		i2c_inst *	I2C = `PICO_DEFAULT_I2C_INSTANCE`
	)

noexcept

The Pi Pico Constructor.

Parameters

address	The I2C address
columns	The LCD's number of columns
rows	The LCD's number of rows (lines)
I2C	The I2C instance

Note: The Pi Pico pins and the I2C bus are not initialized! (See LCD_I2C_Setup())

The Pico constructor initializes the object using the provided I2C instance and calls the display's Init() function.

Remember that constructor usage for ARDUINO and Pi Pico is quite different.

For ARDUINO: Create the object with the constructor and then call the begin() method. If you wish to change the bus speed, do it before calling begin().

For PI PICO: Initialize the I2C instance and pins (See LCD_I2C_Setup()) and then create the object by calling the constructor. The bus speed is set during the I2C bus initialization.

Member Function Documentation

◆ autoscroll()

void LCD_I2C::autoscroll ( void )

noexcept

Turns on automatic scrolling of the display.

This command causes the buffer to be output to the display before execution.

◆ backlight()

void LCD_I2C::backlight ( void )

noexcept

Turn on the display backlight.

This command causes the buffer to be output to the display before execution.

◆ blink()

void LCD_I2C::blink ( void )

noexcept

Display the blinking inverted cursor at the current cursor location.

This command causes the buffer to be output to the display before execution.

◆ blink_off()

void LCD_I2C::blink_off ( )

inlinenoexcept

Alias for noBlink() to turn off the blinking inverted cursor.

◆ blink_on()

void LCD_I2C::blink_on ( )

inlinenoexcept

Alias for blink() to display the blinking inverted cursor.

◆ clear()

void LCD_I2C::clear ( void )

noexcept

Clear the display.

All data on the display is erased and the cursor returns to the top left (0,0) location. This command causes the buffer to be output to the display before execution. It also takes a long time.

◆ createChar()

void LCD_I2C::createChar	(	byte	charnum,
		const byte	char_map[]
	)

noexcept

Create a custom character.

Load a custom character into the display by specifying the location in memory to be stored (8 locations maximum, starting from 0) and an array of 8 bytes. The bytes contain a bit map of the 5x7 dot matrix to display. Each byte specifies one row of character dots starting with the top-most row. The lsb of each byte is the right-most dot on its corresponding line of the character.

This command causes the buffer to be output to the display before execution.

Parameters

charnum	The memory address (character code) 0-7
char_map	The byte array

◆ cursor()

void LCD_I2C::cursor ( void )

noexcept

Display the underline cursor at the current cursor location.

This command causes the buffer to be output to the display before execution.

◆ cursor_off()

void LCD_I2C::cursor_off ( )

inlinenoexcept

An alias for noCursor to turn off the underline cursor.

◆ cursor_on()

void LCD_I2C::cursor_on ( )

inlinenoexcept

Alias for cursor() to turn the underline cursor on.

◆ display()

void LCD_I2C::display ( void )

noexcept

Turns the display on without modifying data on it.

The display is unblanked, and all data sent to the display is displayed. This command causes the buffer to be output to the display before execution.

◆ home()

void LCD_I2C::home ( void )

noexcept

"Home" the display.

Moves cursor to 0,0 and removes any shifts. This command causes the buffer to be output to the display before execution. It also takes a long time.

◆ leftToRight()

void LCD_I2C::leftToRight ( void )

noexcept

Sets the text direction to left to right. Each character output advances the cursor one position to the right. This is the default condition.

This command causes the buffer to be output to the display before execution.

◆ load_custom_character()

void LCD_I2C::load_custom_character	(	uint8_t	char_num,
		uint8_t *	rows
	)

inlinenoexcept

An alias for createChar() for loading custom character data.

Parameters

char_num	is the character number to create (0-7)
rows	is the dot matrix data for the character

◆ noAutoscroll()

void LCD_I2C::noAutoscroll ( void )

noexcept

Turns off automatic scrolling of the display.

This command causes the buffer to be output to the display before execution.

◆ noBacklight()

void LCD_I2C::noBacklight ( void )

noexcept

Turn off the display backlight

This command causes the buffer to be output to the display before execution.

◆ noBlink()

void LCD_I2C::noBlink ( void )

noexcept

Disable the blinking inverted cursor at the current cursor location.

This command causes the buffer to be output to the display before execution.

◆ noCursor()

void LCD_I2C::noCursor ( void )

noexcept

Hides the underline cursor at the current cursor location.

This command causes the buffer to be output to the display before execution.

◆ noDisplay()

void LCD_I2C::noDisplay ( void )

noexcept

Turns the display off without modifying data on it.

The display is blanked as though it had been cleared, but the data and cursor position are not changed. This command causes the buffer to be output to the display before execution.

◆ printstr()

void LCD_I2C::printstr ( const char str[] )

inlinenoexcept

An alias for writeString (for compatibility with earlier programs)

Parameters

str	is a pointer to the string to display

◆ rightToLeft()

void LCD_I2C::rightToLeft ( void )

noexcept

Sets the text direction to right to left. Each character output advances the cursor one position to the left.

This command causes the buffer to be output to the display before execution.

◆ scrollDisplayLeft()

void LCD_I2C::scrollDisplayLeft ( void )

noexcept

Scrolls the display and cursor one position to the left. home() will restore it to its original position.

This command is never buffered and causes the buffer to be flushed before execution.

◆ scrollDisplayRight()

void LCD_I2C::scrollDisplayRight ( void )

noexcept

Scrolls the display and cursor one position to the right. home() will restore it to its original position.

This command causes the buffer to be output to the display before execution.

◆ setBacklight()

void LCD_I2C::setBacklight ( uint8_t newVal )

inlinenoexcept

Set the backlight to a given value.

This command causes the buffer to be output to the display before execution.

Parameters

newVal is backlight value, != 0 is ON

◆ setCursor()

void LCD_I2C::setCursor	(	byte	line,
		byte	position,
		bool	Enable_Buffering = `false`
	)

noexcept

Move the input cursor to a location on the screen.

All output to the screen is placed at the current cursor position. In the default mode, the cursor then advances one position to the right. The cursor does not scroll to the next line.

Parameters

line	Specifies the row (or line) on the display
position	Specifies the position on the row (or column) on the display
Enable_Buffering	If true, the command is simply added to the output buffer. If false or missing, the command is added to the output buffer and the buffer is immediately written to the display.

Warning: Line and position parameters swap positions between Arduino and Pi Pico SDK!; (So Sad!) This is the Pi Pico version!

◆ show()

int LCD_I2C::show ( void )

noexcept

Empties the buffer to "show" any data not yet output to the screen.

Calling show when the buffer is empty is explicitly allowed! See the Theory of Operation for a discussion about usage. This routine is not needed unless the advanced buffering capabilities have been used by calling output and setCursor routines with the enableBuffering parameter set to TRUE.

Returns: (int) The number of bytes transmitted. Remember that each character or command sent to the display may generate 4 or 5 bytes of output to be transmitted, so this will not match the number of characters or comands written.

◆ write() [1/4]

size_t LCD_I2C::write	(	const char *	buffer,
		size_t	size,
		bool	Enable_Buffering = `false`
	)

inlinenoexcept

Override the write buffer of type char method from Arduino print.

Parameters

buffer	The array of type char to output
size	The number of characters to write
Enable_Buffering	If true, the data is simply added to the output buffer. If false or missing, data is added to the output buffer and the buffer is immediately written to the display.

Returns: (size_t) The number of characters written

◆ write() [2/4]

size_t LCD_I2C::write ( const char * str )

inlinenoexcept

Override write string method of the Arduino Print class.

Parameters

str	A pointer to the string to output

Returns: (size_t) The number of bytes written

◆ write() [3/4]

size_t LCD_I2C::write	(	const uint8_t *	buffer,
		size_t	size,
		bool	Enable_Buffering = `false`
	)

noexcept

Override the write array of bytes method of the Arduino print class.

This is the method used by the print strings and some of the print number forms within the Print class as well.

Parameters

buffer	The array of bytes to output
size	The number of bytes to write
Enable_Buffering	If true, the data is simply added to the output buffer. If false or missing, data is added to the output buffer and the buffer is immediately written to the display.

Returns: (size_t) The number of bytes written

◆ write() [4/4]

size_t LCD_I2C::write ( uint8_t c )

inlinenoexcept

Override the write byte method of the Arduino print class.

Parameters

c	the byte to output

Returns: (size_t) The number of bytes written

◆ writeChar()

void LCD_I2C::writeChar	(	byte	val,
		bool	Enable_Buffering = `false`
	)

noexcept

Output a character to the screen.

Parameters

val	is the character to display
Enable_Buffering	If true, data is simply added to the output buffer. If false or missing, data is added to the output buffer and the buffer is immediately written to the display.

◆ writeString()

void LCD_I2C::writeString	(	const char	str[],
		bool	Enable_Buffering = `false`
	)

noexcept

Output a string to the screen. Naming is more in the style of the Pico SDK, and the Enable_Buffering parameter can be utilized.

Parameters

str	is pointer to the string to display
Enable_Buffering	If true, data is simply added to the output buffer. If false or missing, data is added to the output buffer and the buffer is immediately written to the display.

Member Data Documentation

◆ CUSTOM_SYMBOL_SIZE

constexpr uint8_t LCD_I2C::CUSTOM_SYMBOL_SIZE = 8

staticconstexpr

A reminder of the size of custom character arrays.

◆ LCD_5x10DOTS

constexpr byte LCD_I2C::LCD_5x10DOTS = 0x04

staticconstexpr

needed for Arduino Constructor

◆ LCD_5x8DOTS

constexpr byte LCD_I2C::LCD_5x8DOTS = 0x00

staticconstexpr

needed for Arduino Constructor

The documentation for this class was generated from the following files:

C:/Users/Keith/Documents/PiPico/Fast-LCD-I2C/src/include/LCD_I2C.hpp
C:/Users/Keith/Documents/PiPico/Fast-LCD-I2C/src/LCD_I2C.cpp

Static Public Attributes

Pi Pico Constructor

Writing to the screen on the Pi Pico

Writing to the screen on Arduino

Simple display control

Cursor Appearance Controls

Advanced Display Control

Custom Characters

Advanced Buffering Control

Detailed Description

Constructor & Destructor Documentation

◆ LCD_I2C()

Member Function Documentation

◆ autoscroll()

◆ backlight()

◆ blink()

◆ blink_off()

◆ blink_on()

◆ clear()

◆ createChar()

◆ cursor()

◆ cursor_off()

◆ cursor_on()

◆ display()

◆ home()

◆ leftToRight()

◆ load_custom_character()

◆ noAutoscroll()

◆ noBacklight()

◆ noBlink()

◆ noCursor()

◆ noDisplay()

◆ printstr()

◆ rightToLeft()

◆ scrollDisplayLeft()

◆ scrollDisplayRight()

◆ setBacklight()

◆ setCursor()

◆ show()

◆ write() [1/4]

◆ write() [2/4]

◆ write() [3/4]

◆ write() [4/4]

◆ writeChar()

◆ writeString()

Member Data Documentation

◆ CUSTOM_SYMBOL_SIZE

◆ LCD_5x10DOTS

◆ LCD_5x8DOTS