Implements graphic output to the ST7920 LCD controller using a 4-bit parallel interface. More...

#include <ST7920.hpp>

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

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

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

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

	ST7920 (duds::hardware::interface::DigitalPinSet &&outPins, duds::hardware::interface::ChipSelect &&enablePin, unsigned int w, unsigned int h, 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	~ST7920 ()
	Calls off(). More...

void	configure (duds::hardware::interface::DigitalPinSet &&outPins, duds::hardware::interface::ChipSelect &&enablePin, unsigned int w, unsigned int h, 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...

Public Member Functions inherited from duds::hardware::display::BppGraphicDisplay
const duds::ui::graphics::ImageDimensions &	dimensions () const
	Returns the dimensions of the frame buffer. More...

const duds::ui::graphics::BppImage &	frame () const
	Provides access to the image in the frame buffer. More...

int	height () const
	Returns the height of the frame buffer. More...

int	width () const
	Returns the width of the frame buffer. More...

void	write (const duds::ui::graphics::BppImage *img)
	Writes the new image to the display. More...

void	write (const std::shared_ptr< const duds::ui::graphics::BppImage > &img)
	Writes the new image to the display. More...

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

Private Member Functions
virtual void	outputFrame (const duds::ui::graphics::BppImage *img)
	Writes out only the changed portions of the image to the display, and updates the image in frmbuf to match. 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...

void	writeBlock (ST7920::Access &acc, const std::uint16_t start, const std::uint16_t end, int pos)
	Writes a contiguous block of pixel data to the display after setting the next location to write. 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::BppGraphicDisplay
	BppGraphicDisplay ()=default
	Construct with an empty frame buffer. More...

	BppGraphicDisplay (const duds::ui::graphics::ImageDimensions &dim)
	Construct with a frame buffer of the specified size. More...

Protected Attributes inherited from duds::hardware::display::BppGraphicDisplay
duds::ui::graphics::BppImage	frmbuf
	The frame buffer. More...

Detailed Description

Implements graphic output to the ST7920 LCD controller using a 4-bit parallel interface.

Note: If a darkend pixel has no adjacent darkened pixel in the same column, it will have low contrast. Two or more contiguous darkened pixels in the same column have much better contrast.

The controller manages a display up to 256 by 64 pixels with an internal frame buffer. This driver maintains its own frame buffer so that it can update only the portions of the frame that change. The controller has a parallel interface that is almost identical to the HD44780's. It has three control lines and 4 or 8 data 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.

Author: Jeff Jackowski

Definition at line 42 of file ST7920.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 ST7920.hpp.

Constructor & Destructor Documentation

◆ ST7920() [1/2]

duds::hardware::devices::displays::ST7920::ST7920 ( )

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

Definition at line 19 of file ST7920.cpp.

◆ ST7920() [2/2]

duds::hardware::devices::displays::ST7920::ST7920	(	duds::hardware::interface::DigitalPinSet &&	outPins,
		duds::hardware::interface::ChipSelect &&	enablePin,
		unsigned int	w,
		unsigned int	h,
		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 ST7920 can be used with a ChipBinarySelectManager. The other selectable item must not be a ST7920. A logic inverter will not work around this issue.

Parameters

w	The width of the display in pixels. It must not exceed 256.
h	The height of the display in pixels. It must not exceed 64.
delay	The number of nanoseconds to delay while the display reads in data. Delays as short as 1000ns should be possible. 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 21 of file ST7920.cpp.

◆ ~ST7920()

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

virtual

Calls off().

Definition at line 37 of file ST7920.cpp.

Member Function Documentation

◆ configure()

void duds::hardware::devices::displays::ST7920::configure	(	duds::hardware::interface::DigitalPinSet &&	outPins,
		duds::hardware::interface::ChipSelect &&	enablePin,
		unsigned int	w,
		unsigned int	h,
		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 ST7920 can be used with a ChipBinarySelectManager. The other selectable item must not be a ST7920. A logic inverter will not work around this issue.

Parameters

w	The width of the display in pixels. It must not exceed 256.
h	The height of the display in pixels. It must not exceed 64.
delay	The number of nanoseconds to delay while the display reads in data. Delays as short as 1000ns should be possible. 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 43 of file ST7920.cpp.

Referenced by ST7920().

◆ initialize()

void duds::hardware::devices::displays::ST7920::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 clear (pixels changed to false).

Exceptions

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

Definition at line 149 of file ST7920.cpp.

◆ off()

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

Commands the display to turn off.

This should make the display appear blank, but it does not clear the display's frame buffer. Sending any command or data to the display will cause it to start displaying its image again.

Precondition: initialize() has been successfully called.

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

Definition at line 190 of file ST7920.cpp.

Referenced by ~ST7920().

◆ on()

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

Commands the display to turn on.

There is no need to use this with the ST7920 LCD controller; any display command will cause the display to show the contents of its frame buffer. The function exists for consistency with other display classes.

Precondition: initialize() has been successfully called.

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

Definition at line 196 of file ST7920.cpp.

◆ outputFrame()

void duds::hardware::devices::displays::ST7920::outputFrame ( const duds::ui::graphics::BppImage * img )

privatevirtual

Writes out only the changed portions of the image to the display, and updates the image in frmbuf to match.

Parameters

img	The new image to show.

Implements duds::hardware::display::BppGraphicDisplay.

Definition at line 224 of file ST7920.cpp.

Referenced by initialize().

◆ preparePins()

void duds::hardware::devices::displays::ST7920::preparePins ( ST7920::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 78us 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 101 of file ST7920.cpp.

Referenced by initialize(), off(), on(), and outputFrame().

◆ sendByte()

void duds::hardware::devices::displays::ST7920::sendByte	(	ST7920::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 116 of file ST7920.cpp.

Referenced by initialize(), off(), on(), and writeBlock().

◆ wait()

void duds::hardware::devices::displays::ST7920::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 94 of file ST7920.cpp.

Referenced by preparePins(), and writeBlock().

◆ writeBlock()

void duds::hardware::devices::displays::ST7920::writeBlock	(	ST7920::Access &	acc,
		const std::uint16_t *	start,
		const std::uint16_t *	end,
		int	pos
	)

private

Writes a contiguous block of pixel data to the display after setting the next location to write.

Parameters

acc	The access objects required to communicate with the display.
start	The starting address of the pixel data to send.
end	The ending address of the pixel data to send. May be the same as start, but should not extend past the end of the current horizontal line.
pos	The starting position to send to the display. The Y-coordinate is in the LSB, and the X-coordinate is shifted to lose the low order 4 bits and placed in the next significant byte.

Definition at line 202 of file ST7920.cpp.

Referenced by outputFrame().

Member Data Documentation

◆ enable

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

private

Used to represent the enable line of the LCD.

It must go low to make the display read data.

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

Definition at line 60 of file ST7920.hpp.

Referenced by configure(), and preparePins().

◆ nibblePeriod

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

private

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

Definition at line 74 of file ST7920.hpp.

Referenced by configure(), and sendByte().

◆ outcfg

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

private

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

Definition at line 64 of file ST7920.hpp.

Referenced by configure(), and preparePins().

◆ outputs

duds::hardware::interface::DigitalPinSet duds::hardware::devices::displays::ST7920::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
Image data flag; often labled "RS"

Definition at line 52 of file ST7920.hpp.

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

◆ soonestSend

std::chrono::high_resolution_clock::time_point duds::hardware::devices::displays::ST7920::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 ST7920.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

◆ ST7920() [1/2]

◆ ST7920() [2/2]

◆ ~ST7920()

Member Function Documentation

◆ configure()

◆ initialize()

◆ off()

◆ on()

◆ outputFrame()

◆ preparePins()

◆ sendByte()

◆ wait()

◆ writeBlock()

Member Data Documentation

◆ enable

◆ nibblePeriod

◆ outcfg

◆ outputs

◆ soonestSend