Implements text output to HD44780 and compatible display controllers, such as the SPLC780D. More...

#include <HD44780.hpp>

Inheritance diagram for duds::hardware::devices::displays::HD44780:

Collaboration diagram for duds::hardware::devices::displays::HD44780:

Classes
struct	Access
	Stores access objects together. More...

Public Member Functions
	HD44780 ()
	Initializes the object with an invalid display size and no pins to use. More...

	HD44780 (duds::hardware::interface::DigitalPinSet &&outPins, duds::hardware::interface::ChipSelect &&enablePin, unsigned int c, unsigned int r, std::chrono::nanoseconds delay=std::chrono::nanoseconds(8000))
	Initializes the object with everything required to begin communicating with the display, but does not initalize the display. More...

virtual	~HD44780 ()
	Calls off(). More...

virtual void	clear ()
	Removes all text from the display and moves the cursor to the upper left corner. More...

void	configure (duds::hardware::interface::DigitalPinSet &&outPins, duds::hardware::interface::ChipSelect &&enablePin, unsigned int c, unsigned int r, std::chrono::nanoseconds delay=std::chrono::nanoseconds(8000))
	Sets the pins to use for communicating with the display. More...

void	initialize ()
	Initializes the display for use. More...

void	off ()
	Commands the display to turn off. More...

void	on ()
	Commands the display to turn on. More...

void	setGlyph (const std::shared_ptr< duds::ui::graphics::BppImage > &glyph, int idx)
	Loads a glyph into the display's CGRAM (Character Generator Random Access Memory). More...

Public Member Functions inherited from duds::hardware::display::TextDisplay
virtual	~TextDisplay ()=0
	Allows destruction of a pointer of this base class to properly destruct the derived object. More...

void	clearTo (unsigned int c, unsigned int r)
	Clear text from the current cursor position to the given position, inclusive. More...

unsigned int	columnPos () const
	The current column position of the cursor. More...

unsigned int	columns () const
	Returns the number of columns on the display. More...

void	move (unsigned int c, unsigned int r)
	Moves the cursor to the given location. More...

unsigned int	rowPos () const
	The current row position of the cursor. More...

unsigned int	rows () const
	Returns the number of rows on the display. More...

void	write (int c)
	Writes a single character onto the display at the current cursor location and advances the cursor. More...

void	write (const std::string &text)
	Writes a string onto the display starting from the current cursor location. More...

void	write (const std::string &text, unsigned int c, unsigned int r)
	Writes a string onto the display starting from the given location. More...

Private Types
enum	{ dataMask = 0xFF, textFlag = 0x100, writeFlag = 0x200, nibbleFlag = 0x400 }

Private Member Functions
virtual void	moveImpl (unsigned int c, unsigned int r)
	Moves the display's cursor to the indicated position. More...

void	preparePins (Access &acc)
	Obtains access to the pins and configures them for output. More...

void	sendByte (Access &acc, int val)
	Sends a byte to the display a nibble at a time. More...

void	wait () const
	Waits until the time in soonestSend has passed. More...

virtual void	writeImpl (int c)
	Writes a single character to the display. More...

void	writeImpl (Access &acc, const std::string &text)

virtual void	writeImpl (const std::string &text)
	Writes a string to the display. More...

virtual void	writeImpl (const std::string &text, unsigned int c, unsigned int r)
	Writes a string to the display starting at the indicated location. More...

Private Attributes
duds::hardware::interface::ChipSelect	enable
	Used to represent the enable line of the LCD. More...

std::chrono::nanoseconds	nibblePeriod
	The amount of time to allow the display to read data. More...

std::vector< duds::hardware::interface::DigitalPinConfig >	outcfg
	The best output configuration for the display bus given the port in use. More...

duds::hardware::interface::DigitalPinSet	outputs
	Represents the 5 output lines, other than enable, that are needed to communicate with the LCD. More...

std::chrono::high_resolution_clock::time_point	soonestSend
	The soonest time a new command can be sent to the display. More...

Additional Inherited Members
Protected Member Functions inherited from duds::hardware::display::TextDisplay
	TextDisplay ()
	Initializes the object with an invalid display size and cursor position. More...

	TextDisplay (unsigned int c, unsigned int r)
	Initializes the object with the given display size and an invalid cursor position. More...

virtual bool	advance ()
	Advances the column position, and if it goes off the visible portion of the display, updates the row position. More...

Protected Attributes inherited from duds::hardware::display::TextDisplay
std::uint8_t	columnsize
	Number of columns on the display. More...

std::uint8_t	cpos
	Cursor column position. More...

std::uint8_t	rowsize
	Number of rows on the display. More...

std::uint8_t	rpos
	Cursor row position. More...

Detailed Description

Implements text output to HD44780 and compatible display controllers, such as the SPLC780D.

These displays feature text output to a matrix that is typically 5 pixels wide by 8 tall per character. The most common displays are LCDs, but some compatible controllers are found on VFDs. They have a parallel interface with three control lines. Only the 4-bit wide data interface is supported, and only sending data to the display is supported. This limits the number of digital I/O lines required.

This class is not thread-safe because using it directly from multiple threads makes little sense.

Note: The one-way interface with the display used here makes it impossible to tell if there is a display on the other end, or if that display is functional.

Todo:: Support the brightness control available on some VFDs.

Author: Jeff Jackowski

Definition at line 42 of file HD44780.hpp.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

private

Enumerator
dataMask	General data mask for the display.
textFlag	Flag for sending text to the display rather than a command. Often labeled as "RS" in display documentation.
writeFlag	Unsupported display-side write flag.
nibbleFlag	Flag to send only a nibble rather than a whole byte; used in display initalization.

Definition at line 75 of file HD44780.hpp.

Constructor & Destructor Documentation

◆ HD44780() [1/2]

duds::hardware::devices::displays::HD44780::HD44780 ( )

Initializes the object with an invalid display size and no pins to use.

Definition at line 18 of file HD44780.cpp.

◆ HD44780() [2/2]

duds::hardware::devices::displays::HD44780::HD44780	(	duds::hardware::interface::DigitalPinSet &&	outPins,
		duds::hardware::interface::ChipSelect &&	enablePin,
		unsigned int	c,
		unsigned int	r,
		std::chrono::nanoseconds	delay = `std::chrono::nanoseconds(8000)`
	)

Initializes the object with everything required to begin communicating with the display, but does not initalize the display.

Postcondition: The objects in outPins and enablePins are moved to internal members. They will be the same as default-constructed objects after this function returns.

Parameters

outPins	The set of pins used for 4-bit data output and the text flag. This object is moved to an internal member. The pins are, in order: Data bit 4 Data bit 5 Data bit 6 Data bit 7 Text flag; often labeled "RS"
enablePin	The chip select used for the enable line on the display. It is often labeled "E". The object is moved to an internal member.

Warning: Only one HD44780 can be used with a ChipBinarySelectManager. The other selectable item must not be a HD44780. A logic inverter will not work around this issue.

Parameters

c	The number of columns on the display. The value must be between 1 and 20, and will almost always be either 16 or 20.
r	The number of rows on the display. The value must be between 1 and 4.
delay	The number of nanoseconds to delay while the display reads in data. Delays as short as 500ns should be possible with HD44780 display controllers. Compatible controllers may have different requirements. Specific circuits, especially non-permanent prototypes like ones on breadboards, may require longer delays. The default value seems to work well for such prototypes.

Exceptions

duds::hardware::display::DisplaySizeError	Either the width or height size is outside the supported range.
duds::hardware::interface::PinDoesNotExist	outPins or enablePin is empty.
duds::hardware::interface::PinRangeError	outPins lacks all the required pins.
duds::hardware::interface::DigitalPinCannotOutputError	A pin in outPins does not support output.

Definition at line 20 of file HD44780.cpp.

◆ ~HD44780()

duds::hardware::devices::displays::HD44780::~HD44780 ( )

virtual

Calls off().

Definition at line 34 of file HD44780.cpp.

Member Function Documentation

◆ clear()

void duds::hardware::devices::displays::HD44780::clear ( )

virtual

Removes all text from the display and moves the cursor to the upper left corner.

Precondition: initialize() has been successfully called.

Implements duds::hardware::display::TextDisplay.

Definition at line 254 of file HD44780.cpp.

◆ configure()

void duds::hardware::devices::displays::HD44780::configure	(	duds::hardware::interface::DigitalPinSet &&	outPins,
		duds::hardware::interface::ChipSelect &&	enablePin,
		unsigned int	c,
		unsigned int	r,
		std::chrono::nanoseconds	delay = `std::chrono::nanoseconds(8000)`
	)

Sets the pins to use for communicating with the display.

After calling this, initialize() must be called before using the display.

Postcondition: The objects in outPins and enablePins are moved to internal members. They will be the same as default-constructed objects after this function returns.

Parameters

outPins	The set of pins used for 4-bit data output and the text flag. This object is moved to an internal member. The pins are, in order: Data bit 4 Data bit 5 Data bit 6 Data bit 7 Text flag; often labeled "RS"
enablePin	The chip select used for the enable line on the display. It is often labeled "E". The object is moved to an internal member.

Warning: Only one HD44780 can be used with a ChipBinarySelectManager. The other selectable item must not be a HD44780. A logic inverter will not work around this issue.

Parameters

c	The number of columns on the display. The value must be between 1 and 20, and will almost always be either 16 or 20.
r	The number of rows on the display. The value must be between 1 and 4.
delay	The number of nanoseconds to delay while the display reads in data. Delays as short as 500ns should be possible with HD44780 display controllers. Compatible controllers may have different requirements. Specific circuits, especially non-permanent prototypes like ones on breadboards, may require longer delays. The default value seems to work well for such prototypes.

Exceptions

duds::hardware::display::DisplaySizeError	Either the width or height size is outside the supported range.
duds::hardware::interface::PinDoesNotExist	outPins or enablePin is empty.
duds::hardware::interface::PinRangeError	outPins lacks all the required pins.
duds::hardware::interface::DigitalPinCannotOutputError	A pin in outPins does not support output.

Definition at line 40 of file HD44780.cpp.

Referenced by HD44780().

◆ initialize()

void duds::hardware::devices::displays::HD44780::initialize ( )

Initializes the display for use.

This function must be called before sending text or any other commands to the display. It may be called more than once.

Precondition: The pins to use have already been configured, and the display size has been set.

Postcondition: The display is in the "on" state; on() has been called.; Functions that send data to the display may be used.; The display is blank; it has no text.; The cursor is positioned at the upper left corner.

Exceptions

DisplayUninitialized The display object has not been given any pins to use.

Definition at line 146 of file HD44780.cpp.

◆ moveImpl()

void duds::hardware::devices::displays::HD44780::moveImpl	(	unsigned int	c,
		unsigned int	r
	)

privatevirtual

Moves the display's cursor to the indicated position.

The position has already passed a range check. The new position will be recorded by the caller, move(unsigned int, unsigned int), so there is no need for this function to record the new position.

Implements duds::hardware::display::TextDisplay.

Definition at line 202 of file HD44780.cpp.

◆ off()

void duds::hardware::devices::displays::HD44780::off ( )

Commands the display to turn off.

This should prevent any text from being visible, but may not appear to do anything else. The text displayed prior to calling this function should remain in the display's buffer.

Precondition: initialize() has been successfully called.

Bug:: Name isn't technically correct; change it.

Definition at line 183 of file HD44780.cpp.

Referenced by ~HD44780().

◆ on()

void duds::hardware::devices::displays::HD44780::on ( )

Commands the display to turn on.

This is done inside initialize() so it is only needed if off() is called. The contents of the displays buffer should become visible after this function.

Precondition: initialize() has been successfully called.

Bug:: Name isn't technically correct; change it.

Definition at line 189 of file HD44780.cpp.

◆ preparePins()

void duds::hardware::devices::displays::HD44780::preparePins ( HD44780::Access & acc )

private

Obtains access to the pins and configures them for output.

Before obtaining access, a call to wait() is made. In the case of sending a single byte to the display, this allows at least 48us for other threads to use the hardware.

Parameters

acc	The object that contains the access objects to fill.

Exceptions

DisplayUninitialized The display object has not been given any pins to use.

Definition at line 98 of file HD44780.cpp.

Referenced by clear(), initialize(), moveImpl(), off(), on(), setGlyph(), and writeImpl().

◆ sendByte()

void duds::hardware::devices::displays::HD44780::sendByte	(	HD44780::Access &	acc,
		int	val
	)

private

Sends a byte to the display a nibble at a time.

Precondition: A call to wait() has been made since the last call to this function.

Parameters

acc	The access objects required to communicate with the display.
val	The data to send. The value within dataMask is sent over the four data lines. If textFlag is set, the text flag line, more commonly known as "RS", will be set. Otherwise, it will be cleared. If nibbleFlag is set, only the value in the mask 0xF0 will be sent, and only one send will be done instead of the normal two.

Definition at line 113 of file HD44780.cpp.

Referenced by clear(), initialize(), moveImpl(), off(), on(), setGlyph(), and writeImpl().

◆ setGlyph()

void duds::hardware::devices::displays::HD44780::setGlyph	(	const std::shared_ptr< duds::ui::graphics::BppImage > &	glyph,
		int	idx
	)

Loads a glyph into the display's CGRAM (Character Generator Random Access Memory).

These displays typically allow for eight glyphs to be specified and changed at will. Whenever a glyph is changed, any spot on the display showing that character value will also change in appearance.

The display uses character values 0 through 7 and 8 through 15 to reference the glyphs. The 4th bit is ignored, so values 0 and 8 will show the same glyph. The parameter idx works the same way.

Issues using the glyphs in output: Using character value 0 is bothersome since it is usually interpreted as the end of a string. std::string actually stores a length so it can hold character zero, but any string literal assigned to it is seen as a null terminated string unless a length is explicitly provided.

: The characters '\n' and '\r' are 10 and 13, respectively, which puts them into the 8 to 15 range for the glyphs. The TextDisplayStreambuf class, and thus indirectly the TextDisplayStream class, interpret these characters as a request to move the cursor rather than a request to show a printable character. None of the TextDisplay::write() functions do this; they handle all characters as printable. They can also be used interchangeably with a TextDisplayStream.

: The best solution may be to use character values 1 through 8 for the custom glyphs. It avoids unintended null termination, and allows any custom glyph to be used from a TextDisplayStream. To make this a little easier, idx can be given values 1 through 8 to be consistent.

Parameters

glyph	The image to load. It may be no larger than 5 by 8. If smaller, it will be placed in the upper right.
idx	The index for the glyph. It must be between 0 and 15. The 4th bit is ignored so values 8 through 15 work the same as values 0 through 7. Text that has a character with the same value, ignoring the 4th bit, will show the corresponding glyph.

Exceptions

DisplayGlyphIndexError	The index value idx is outside the supported range of 0 to 15, inclusive.
DisplayGlyphSizeError	The image is too large.

Definition at line 263 of file HD44780.cpp.

◆ wait()

void duds::hardware::devices::displays::HD44780::wait ( ) const

private

Waits until the time in soonestSend has passed.

This is used to assure that the display isn't sent data too rapidly while allowing the thread a chance to do other work rather than always wait on the display. It is called in preparePins() so that functions needing to call sendByte() once do not need to call wait, and so that the wait occurs without hardware access to allow other threads a chance to use the hardware.

Definition at line 91 of file HD44780.cpp.

Referenced by preparePins(), and writeImpl().

◆ writeImpl() [1/4]

void duds::hardware::devices::displays::HD44780::writeImpl ( int c )

privatevirtual

Writes a single character to the display.

Using this function rather than one that writes a string allows the display's bus to be freed after each character to allow other uses for those lines.

Implements duds::hardware::display::TextDisplay.

Definition at line 226 of file HD44780.cpp.

Referenced by writeImpl().

◆ writeImpl() [2/4]

void duds::hardware::devices::displays::HD44780::writeImpl	(	Access &	acc,
		const std::string &	text
	)

private

Definition at line 209 of file HD44780.cpp.

◆ writeImpl() [3/4]

void duds::hardware::devices::displays::HD44780::writeImpl ( const std::string & text )

privatevirtual

Writes a string to the display.

This function must handle advancing the cursor, and must reposition the cursor when repos is true. The default implementation calls writeImpl(int), advance(), and moveImpl() in a loop.

Reimplemented from duds::hardware::display::TextDisplay.

Definition at line 233 of file HD44780.cpp.

◆ writeImpl() [4/4]

void duds::hardware::devices::displays::HD44780::writeImpl	(	const std::string &	text,
		unsigned int	c,
		unsigned int	r
	)

privatevirtual

Writes a string to the display starting at the indicated location.

This function must handle moving and advancing the cursor. The default implementation calls move(), then write(const std::string &).

Reimplemented from duds::hardware::display::TextDisplay.

Definition at line 239 of file HD44780.cpp.

Member Data Documentation

◆ enable

duds::hardware::interface::ChipSelect duds::hardware::devices::displays::HD44780::enable

private

Used to represent the enable line of the LCD.

It must go low to make the display read data.

Warning: Only one HD44780 object can be used with a ChipBinarySelectManager. The other selectable item must not be a HD44780.

Definition at line 60 of file HD44780.hpp.

Referenced by configure(), and preparePins().

◆ nibblePeriod

std::chrono::nanoseconds duds::hardware::devices::displays::HD44780::nibblePeriod

private

The amount of time to allow the display to read data.

Definition at line 74 of file HD44780.hpp.

Referenced by configure(), and sendByte().

◆ outcfg

std::vector<duds::hardware::interface::DigitalPinConfig> duds::hardware::devices::displays::HD44780::outcfg

private

The best output configuration for the display bus given the port in use.

Definition at line 64 of file HD44780.hpp.

Referenced by configure(), and preparePins().

◆ outputs

duds::hardware::interface::DigitalPinSet duds::hardware::devices::displays::HD44780::outputs

private

Represents the 5 output lines, other than enable, that are needed to communicate with the LCD.

The pins are, in order:

Data bit 4
Data bit 5
Data bit 6
Data bit 7
Text flag; often labled "RS"

Definition at line 52 of file HD44780.hpp.

Referenced by configure(), preparePins(), and ~HD44780().

◆ soonestSend

std::chrono::high_resolution_clock::time_point duds::hardware::devices::displays::HD44780::soonestSend

private

The soonest time a new command can be sent to the display.

The display requires some time to process incoming data. This value allows that time to elapse while the thread does something else.

Definition at line 70 of file HD44780.hpp.

Referenced by sendByte(), and wait().

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

Classes

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ HD44780() [1/2]

◆ HD44780() [2/2]

◆ ~HD44780()

Member Function Documentation

◆ clear()

◆ configure()

◆ initialize()

◆ moveImpl()

◆ off()

◆ on()

◆ preparePins()

◆ sendByte()

◆ setGlyph()

◆ wait()

◆ writeImpl() [1/4]

◆ writeImpl() [2/4]

◆ writeImpl() [3/4]

◆ writeImpl() [4/4]

Member Data Documentation

◆ enable

◆ nibblePeriod

◆ outcfg

◆ outputs

◆ soonestSend