General class for handling the HD44780 protocol. More...

#include <PololuHD44780.h>

Inheritance diagram for PololuHD44780Base:

Public Member Functions
virtual void	initPins ()=0

void	init ()

void	reinitialize ()

virtual void	send (uint8_t data, bool rsValue, bool only4bits)=0

void	clear ()

void	loadCustomCharacter (const uint8_t *picture, uint8_t number)

void	loadCustomCharacterFromRam (const uint8_t *picture, uint8_t number)

void	loadCustomCharacter (const char *picture, uint8_t number)

void	createChar (uint8_t number, uint8_t picture[])

void	gotoXY (uint8_t x, uint8_t y)

void	setCursor (uint8_t col, uint8_t row)

void	noDisplay ()

void	display ()

void	noCursor ()

void	cursor ()

void	noBlink ()

void	blink ()

void	cursorSolid ()

void	cursorBlinking ()

void	hideCursor ()

void	scrollDisplayLeft ()

void	scrollDisplayRight ()

void	home ()

void	leftToRight ()

void	rightToLeft ()

void	autoscroll ()

void	noAutoscroll ()

void	command (uint8_t cmd)

virtual size_t	write (uint8_t c)

virtual size_t	write (const uint8_t *buffer, size_t size)

Detailed Description

General class for handling the HD44780 protocol.

This is an abstract class that knows about the HD44780 LCD commands but does not directly read or write from the actual LCD. To make a usable class, you need to define a subclass of PololuHD44780Base and implement the initPins() and send() functions.

The subclass will inherit all the functions from PololuHD44780Base which are documented here. It will also inherit all of the functions from the Arduino Print class. For more information about what the Print class provides, see the Arduino print() documentation or look at Print.h in the Arduino IDE source code.

Most users of this library will not need to directly use this class and should use PololuHD44780 or some other subclass of PololuHD44780Base defined in a different library.

LCD scrolling

The PololuHD44780Base class provides several functions related to scrolling:

scrollDisplayLeft() scrolls everything on the screen one position to the left.
scrollDisplayRight() scrolls everything on the screen one position to the right.
autoscroll() and noAutoscroll() control whether auto-scrolling is enabled.
home() and clear() both reset the scroll position

The HD44780 actually stores 40 columns internally. By default, the left-most internal columns are the ones that are actually displayed on the screen, but the scrolling features allow that correspondence to change. The scrolling wraps around, so it is possible to display some of the right-most columns on the screen at the same time as some of the left-most columns.

For the gotoXY() function, the x coordinate actually corresponds to the internal column index. The left-most internal column has an x coordinate of 0, and the right-most has an x coordinate of 39.

For example, if you are controlling a 2×8 character LCD and you call scrollDisplayLeft() 35 times (or call scrollDisplayRight() 5 times), then the X coordinates of the columns displayed, from left to right, will be 35, 36, 37, 38, 39, 0, 1, and 2.

Definition at line 56 of file PololuHD44780.h.

Member Function Documentation

◆ autoscroll()

void PololuHD44780Base::autoscroll ( )

Turns on auto-scrolling.

When auto-scrolling is enabled, every time a character is written, the screen will automatically scroll by one column in the appropriate direction.

Definition at line 214 of file PololuHD44780.cpp.

◆ blink()

void PololuHD44780Base::blink ( )

Shows the blinking cursor.

This function sets the LCD's "B" configuration bit without changing the other bits.

The cursor will normally be a blinking rectangle, but there could also be a row of solid black pixels at the bottom if previous commands have enabled the solid cursor. For this reason, it is usually better to call cursorSolid() or cursorBlinking() instead. This function is only provided for compatibilty with the LiquidCrystal library.

Definition at line 177 of file PololuHD44780.cpp.

◆ clear()

void PololuHD44780Base::clear ( )

Clear the contents of the LCDs, resets the cursor position to the upper left, and resets the scroll position.

Definition at line 78 of file PololuHD44780.cpp.

◆ command()

void PololuHD44780Base::command ( uint8_t cmd )

inline

Send an arbitrary command to the LCD. This is here for compatibility with the LiquidCrystal library.

Definition at line 294 of file PololuHD44780.h.

◆ createChar()

void PololuHD44780Base::createChar	(	uint8_t	number,
		uint8_t	picture[]
	)

inline

Defines a custom character. This is provided for compatibility with the LiquidCrystal library.

Definition at line 152 of file PololuHD44780.h.

◆ cursor()

void PololuHD44780Base::cursor ( )

Shows the solid cursor.

This function sets the LCD's "C" configuration bit without changing the other bits.

The cursor will normally be a solid line in the bottom row, but there could be a blinking rectangle superimposed on it if previous commands have enabled the blinking cursor. For this reason, it is usually better to call cursorSolid() or cursorBlinking() instead. This function is only provided for compatibility with the LiquidCrystal library.

Definition at line 167 of file PololuHD44780.cpp.

◆ cursorBlinking()

void PololuHD44780Base::cursorBlinking ( )

Enables a cursor that appears as a blinking black rectangle.

This sets the LCD's "C" and "B" configuration bits.

Note that the cursor will not be shown if the display is currently off (due to a call to noDisplay()), or if the cursor position is not within the bounds of the screen.

Definition at line 142 of file PololuHD44780.cpp.

◆ cursorSolid()

void PololuHD44780Base::cursorSolid ( )

Enables a cursor that appears as a solid line in the bottom row.

This sets the LCD's "C" configuration bit and clears its "B" bit.

Note that the cursor will not be shown if the display is currently off (due to a call to noDisplay()), or if the cursor position is not within the bounds of the screen.

Definition at line 137 of file PololuHD44780.cpp.

◆ display()

void PololuHD44780Base::display ( )

Turns the display on. This should only be needed if noDisplay() was previously called.

Definition at line 157 of file PololuHD44780.cpp.

◆ gotoXY()

void PololuHD44780Base::gotoXY	(	uint8_t	x,
		uint8_t	y
	)

Change the location of the cursor. The cursor (whether visible or invisible), is the place where the next character written to the LCD will be displayed.

Note that the scrolling features of the LCD change the correspondence between the x parameter and the physical column that the data is displayed on. See the "LCD scrolling" section above for more information.

Parameters

x	The number of the column to go to, with 0 being the leftmost column.
y	The number of the row to go to, with 0 being the top row.

Definition at line 88 of file PololuHD44780.cpp.

◆ hideCursor()

void PololuHD44780Base::hideCursor ( )

Hides the solid and blinking cursors.

This clears the LCD's "C" and "B" configuration bits.

Definition at line 147 of file PololuHD44780.cpp.

◆ home()

void PololuHD44780Base::home ( )

Resets the screen scrolling position back to the default and moves the cursor to the upper left corner of the screen.

This command takes about 1600 microseconds, so it would be faster to instead call scrollDisplayLeft() or scrollDisplayRight() the appropriate number of times and then call gotoXY(0, 0).

Definition at line 192 of file PololuHD44780.cpp.

◆ init()

void PololuHD44780Base::init ( )

inline

Initialize the LCD if it has not already been initialized.

Definition at line 67 of file PololuHD44780.h.

◆ initPins()

virtual void PololuHD44780Base::initPins ( )

pure virtual

Initializes the pins so that the send() function can be called successfully. This is the first step of initializing the LCD.

Implemented in PololuHD44780, and Romi32U4LCD.

◆ leftToRight()

void PololuHD44780Base::leftToRight ( )

Puts the LCD into left-to-right mode: the cursor will shift to the right after any character is written. This is the default behavior.

Definition at line 204 of file PololuHD44780.cpp.

◆ loadCustomCharacter() [1/2]

void PololuHD44780Base::loadCustomCharacter	(	const uint8_t *	picture,
		uint8_t	number
	)

Defines a custom character.

Parameters

picture	A pointer to the character dot pattern, in program space.
number	A number between 0 and 7.

Definition at line 103 of file PololuHD44780.cpp.

◆ loadCustomCharacter() [2/2]

void PololuHD44780Base::loadCustomCharacter	(	const char *	picture,
		uint8_t	number
	)

inline

This overload of loadCustomCharacter is only provided for compatibility with OrangutanLCD; a lot of Orangutan code defines an array of chars for custom character pictures.

Definition at line 145 of file PololuHD44780.h.

◆ loadCustomCharacterFromRam()

void PololuHD44780Base::loadCustomCharacterFromRam	(	const uint8_t *	picture,
		uint8_t	number
	)

Defines a custom character from RAM.

Parameters

picture	A pointer to the character dot pattern, in RAM.
number	A number between 0 and 7.

Definition at line 117 of file PololuHD44780.cpp.

◆ noAutoscroll()

void PololuHD44780Base::noAutoscroll ( )

Turns off auto-scrolling. Auto-scrolling is off by default.

Definition at line 219 of file PololuHD44780.cpp.

◆ noBlink()

void PololuHD44780Base::noBlink ( )

Hides the blinking cursor.

This functions clears the LCD's "B" configuration bit without changing the other bits.

Calling this function does not enable or disable the solid cursor (a solid line in the bottom row) so it is usually better to call hideCursor() or cursorSolid() instead. This function is only provided for compatibilty with the LiquidCrystal library.

Definition at line 172 of file PololuHD44780.cpp.

◆ noCursor()

void PololuHD44780Base::noCursor ( )

Hides the solid cursor.

This function clears the LCD's "C" configuration bit without changing the other bits.

If the "B" bit is set to 1, a blinking cursor will still be displayed even after calling this function. For that reason, it is usually better to call hideCursor() instead. This function is only provided for compatibility with the LiquidCrystal library.

Definition at line 162 of file PololuHD44780.cpp.

◆ noDisplay()

void PololuHD44780Base::noDisplay ( )

Turns off the display while preserving its state.

You can turn the display on again by calling display().

Definition at line 152 of file PololuHD44780.cpp.

◆ reinitialize()

void PololuHD44780Base::reinitialize ( )

inline

Reinitialize the LCD. This performs the same initialization that is done automatically the first time any function is called that writes to the LCD. This is useful if you want to get it back to a totally clean state.

Definition at line 80 of file PololuHD44780.h.

◆ rightToLeft()

void PololuHD44780Base::rightToLeft ( )

Puts the LCD into right-to-left mode: the cursor will shift to the left after any character is written.

Definition at line 209 of file PololuHD44780.cpp.

◆ scrollDisplayLeft()

void PololuHD44780Base::scrollDisplayLeft ( )

Scrolls everything on the screen one position to the left.

This command takes about 37 microseconds.

Definition at line 182 of file PololuHD44780.cpp.

◆ scrollDisplayRight()

void PololuHD44780Base::scrollDisplayRight ( )

Scrolls everything on the screen one position to the right.

This command takes about 37 microseconds.

Definition at line 187 of file PololuHD44780.cpp.

◆ send()

virtual void PololuHD44780Base::send	(	uint8_t	data,
		bool	rsValue,
		bool	only4bits
	)

pure virtual

Sends data or commands to the LCD.

The initPins() function will always be called before the first time this function is called. This function does not need to worry about the delays necessary to make sure the previous command has finished; that is taken care of by PololuHD44780Base.

This function, along with initPins(), comprise the hardware abstraction layer for the LCD, and must be defined in a subclass of PololuHD44780Base. All other functions use these two functions to communicate with the LCD.

Parameters

data	The data to send to the LCD.
rsValue	True to drive the RS pin high, false to drive it low.
only4bits	If true, and the LCD is using a 4-bit interface, only sends the lower 4 bits of the data.

Implemented in PololuHD44780, and Romi32U4LCD.

◆ setCursor()

void PololuHD44780Base::setCursor	(	uint8_t	col,
		uint8_t	row
	)

inline

Changes the location of the cursor. This is just a wrapper around gotoXY provided for compaitibility with the LiquidCrystal library.

Definition at line 170 of file PololuHD44780.h.

◆ write() [1/2]

size_t PololuHD44780Base::write ( uint8_t c )

virtual

Writes a single character to the LCD.

Definition at line 62 of file PololuHD44780.cpp.

◆ write() [2/2]

size_t PololuHD44780Base::write	(	const uint8_t *	buffer,
		size_t	size
	)

virtual

Writes multiple characters to the LCD.

Parameters

buffer	Pointer to a string of characters in RAM, not necessarily null-terminated.
size	The number of characters to write to the LCD, excluding any null termination character.

Definition at line 68 of file PololuHD44780.cpp.

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

Public Member Functions

Detailed Description

LCD scrolling

Member Function Documentation

◆ autoscroll()

◆ blink()

◆ clear()

◆ command()

◆ createChar()

◆ cursor()

◆ cursorBlinking()

◆ cursorSolid()

◆ display()

◆ gotoXY()

◆ hideCursor()

◆ home()

◆ init()

◆ initPins()

◆ leftToRight()

◆ loadCustomCharacter() [1/2]

◆ loadCustomCharacter() [2/2]

◆ loadCustomCharacterFromRam()

◆ noAutoscroll()

◆ noBlink()

◆ noCursor()

◆ noDisplay()

◆ reinitialize()

◆ rightToLeft()

◆ scrollDisplayLeft()

◆ scrollDisplayRight()

◆ send()

◆ setCursor()

◆ write() [1/2]

◆ write() [2/2]