Base abstract class models a generic Seven Segment display hardware. More...

#include <SevenSegDispHw.h>

Inheritance diagram for SevenSegDispHw:

[legend]

Collaboration diagram for SevenSegDispHw:

Public Member Functions
	SevenSegDispHw ()
	Default class constructor.
	SevenSegDispHw (uint8_t *ioPins, uint8_t dspDigits=4, bool commAnode=true, uint8_t dspDigitsQtyMax=0)
	Class constructor.
virtual	~SevenSegDispHw ()
	Class destructor.
virtual bool	begin (uint32_t updtLps=0)
	Sets up the hardware display to work, and starts the display activities.
virtual bool	end ()
	Reverts the begin(uint32_t) actions, stopping the display activities, turning the display off and freeing the resources used by the Seven Segment display hardware object.
virtual uint8_t	getBrghtnssLvl ()
	Returns the current display brightness level setting for the display.
virtual uint8_t	getBrghtnssMaxLvl ()
	Returns the maximum display brightness level setting allowed for the display.
virtual uint8_t	getBrghtnssMinLvl ()
	Returns the minimum display brightness level setting for the display.
bool	getCommAnode ()
	Returns a value indicating if the display module component of the display hardware uses a common anode or a common cathode led wiring.
uint8_t *	getDspBuffPtr ()
	Returns a pointer to the display buffer.
uint8_t	getHwDspDigitsQty ()
	Returns the quantity of digits of the display module.
virtual bool	getIsOn ()
	Returns the state of the display.
uint8_t *	getxcdDspBuffPtr ()
	Returns a pointer to an array holding the contents for the digits/ports available from the display controller but not used for plain digits display.
virtual void	ntfyUpdDsply ()
	Notifies the SevenSegDispHw component object of a change of content available in the display buffer, so that the object proceeds to update the display.
virtual bool	setBrghtnssLvl (const uint8_t &newBrghtnssLvl)
	Sets the brightness level for the display.
virtual bool	setDigitsOrder (uint8_t *newOrderPtr)
	Sets a mapping to relate the display buffer positions to the display port assigned to exhibit it's contents.
void	setDspBuffPtr (uint8_t *newDspBuffPtr)
	Sets the pointer to the Display Buffer memory area.
virtual void	turnOff ()
	Turns the display module off.
virtual void	turnOn ()
	Turns the display module on.
virtual void	turnOn (const uint8_t &newBrghtnssLvl)
	Turns the display module on set at the provided brightness level.

Protected Attributes
uint8_t	_allLedsOff {}
	Value to set in the display port to set all leds off (a "space"), dependent of _commAnode.
uint8_t	_brghtnssLvl {0}
	Current display brightness level.
uint8_t	_brghtnssLvlMax {0}
	Maximum display brightness level.
uint8_t	_brghtnssLvlMin {0}
	Minimum display brightness level.
uint8_t *	_dspBlankBuffPtr {nullptr}
	Pointer to a display buffer filled with _allLedsOff ("spaces") to use as display buffer while in "Off State".
uint8_t *	_dspBuffPtr {nullptr}
	Pointer to the display buffer, will be provided by the SevenSegDisplays object when it's instantiated.
uint8_t *	_dspBuffPtrBkp {nullptr}
	Pointer to the display buffer, copy of the original _dspBuffPtr to be used as backup.
bool	_isOn {false}
	Current display status: On/Off.
uint8_t *	_xcdDspBuffPtr {nullptr}
	A pointer to a buffer the size of the exceeding digits used to control display specific amenities.
uint8_t	_xcdDspDigitsQty {}
	Number of unused available display ports, its the difference (_dspDigitsQtyMax - _dspDigitsQty), being the size of the array pointed by _xcdDspBuffPtr.

Detailed Description

Base abstract class models a generic Seven Segment display hardware.

Note

This library, from it's base class to the last of it's subclasses, adhere to the following concepts: Seven Segment display hardware: is a hardware construction capable of receiving data in 8-bits units, each unit corresponding to a segment or decimal point of a seven segment display digit, as it is already normalized across the electronic industry. The Seven Segment display is composed of two basic elements:

The display controller component: Is conformed by the electronics receiving the data to be displayed and send the needed signals to turn on the corresponding segments to show the data at the display module. The display controller component might be as autonomous and complex as a specific "display controller chip", as simple as a "SIPO Shift Register" or as "non physical existent" as a "cable connector to the MCU", so that the MCU will have to take care of the data update and display logic, making the MCU the "display controller component".
The display module component: Is conformed by the seven segments led display unit or units if more than one is required. This units include the leds to be lit as segments and decimal point, and some include colons to represent time values, or special icons in very specific use models. Each display module component will have it's internal wiring, the seven segment part pretty standard, the other components wired differently. As for this library the only display module characteristic considered essential is if the digit leds are connected in common anode or common cathode way. This required information is provided by each display module datasheet, the corresponding display module code is usually found printed in one side or at the bottom of the module.

Constructor & Destructor Documentation

◆ SevenSegDispHw()

SevenSegDispHw::SevenSegDispHw	(	uint8_t *	ioPins,
		uint8_t	dspDigits = 4,
		bool	commAnode = true,
		uint8_t	dspDigitsQtyMax = 0 )

Class constructor.

Parameters

ioPins	A pointer to an array holding the identifiers for the MCU GPIO pins required to send the data to be displayed to the Display controller. The correlation between the array positions and the pin function is given as in-class defined constants for each instantiable subclass.
dspDigits	Quantity of digits/ports of the display. This value is directly related to the display module component quantity of ports and characteristics.
commAnode	Boolean indicating if the hardware uses a display module component wired as common anode (true) or common cathode (false).
dspDigitsQtyMax	Maximum quantity of digits/ports the display controller is able to manage. Sometimes display module components are attached to display controller component able to manage more than the display digits/ports.

Note: In the case the there are remaining display controller unused positions, they might be reasigned for special uses or artifacts, see the complete documentation for access to those positions.

Attention: The dspDigits parameter, indicating the quantity of digits of the display module, is a basic fundamental parameter passed at instantiation time. This information provides the value to be used to create the data buffer of the right size, the digits order table, auxiliary buffers and the required information to calculate the range of values displayable and to generate a valid left or right aligned display. Obviously the quantity is bigger than 0, and must be less than or equal to the hardware maximum display digits capability.

Warning: The dspDigits parameter value must not be confused with the maximum display digits a display controller component can handle. Many displays are designed using part of the controller's digits management for real seven segment displays digits while using non connected to ports pins to manage some other display elements, like individual leds, icons, special backlighting elements, etc. The class instantiated object needs the right amount of display digits available as such, the exceeding digits/ports is currently out of the libray management scope.

Member Function Documentation

◆ begin()

bool SevenSegDispHw::begin ( uint32_t updtLps = 0 )

virtual

Sets up the hardware display to work, and starts the display activities.

Depending on the display technology and the resources it needs to work with, this method takes care of those preparations. That means that each specific subclass of display will provide it's own version of begin() that will take care of:

Configuring timers or interrupts required.
Setup tasks and unblocking procedures to get new contents from the SevenSegDisplays object.
Setup communications parameters and establish communications with the display hardware.
Other specific services configuration and setups.
Turn On the display.

Parameters

updtLps Time lapse between updating activities required, specially by dynamic subclasses. The parameter will be used according to each subclass needs, which will be described in each class begin() method.

Return values

true	The specific configurations and startups could be successfully completed.

Returns: false One or more of the specific configurations or startups failed.

Reimplemented in SevenSegDynamic, SevenSegDynDummy, SevenSegDynHC595, SevenSegHT16K33, SevenSegMax7219, SevenSegStatHC595, and SevenSegTM163X.

Here is the call graph for this function:

◆ end()

bool SevenSegDispHw::end ( )

virtual

Reverts the begin(uint32_t) actions, stopping the display activities, turning the display off and freeing the resources used by the Seven Segment display hardware object.

Returns: true The display activities could be stopped and resources freed with no problems.; false The display activities couldn't be stopped. The method failed.

Note: The end() method does not destroy the object, and it's effect can be reverted by invoking a new begin(uint32_t) method for the object.

Reimplemented in SevenSegDynamic, SevenSegDynDummy, SevenSegDynHC595, SevenSegHT16K33, SevenSegMax7219, and SevenSegTM163X.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getBrghtnssLvl()

uint8_t SevenSegDispHw::getBrghtnssLvl ( )

virtual

Returns the current display brightness level setting for the display.

For displays with variable display brighness levels this method will return the current brightness level. The returned value will be in the range getBrghtnssMinLvl() <= getBrghtnssLvl() <= getBrghtnssMaxLvl(), see setBrghtnssLvl(const uint8_t &) for more details.

Note: For display classes that models object without the capacity of changing brightness levels, getBrghtnssMinLvl() = getBrghtnssLvl() = getBrghtnssMaxLvl() = 0, this implies that using (getBrghtnssMinLvl() == getBrghtnssMaxLvl()) condition is enough to identify if a given display has or has not the capacity of changing brightness levels.

Returns: The current display brightness level setting, as long as the display has the capacity of changing brightness levels.

Reimplemented in SevenSegTM163X.

◆ getBrghtnssMaxLvl()

uint8_t SevenSegDispHw::getBrghtnssMaxLvl ( )

virtual

Returns the maximum display brightness level setting allowed for the display.

For displays with variable display brightness levels this method will return the maximum brightness level value valid setting. See setBrghtnssLvl(const uint8_t &) for more details.

Note: For display classes that models object without the capacity of changing brightness levels, getBrghtnssMinLvl() = getBrghtnssLvl() = getBrghtnssMaxLvl() = 0, this implies that using (getBrghtnssMinLvl() == getBrghtnssMaxLvl()) condition is enough to identify if a given display has or has not the capacity of changing brightness levels.

Returns: The display brightness level maximum value setting as long as the display has the capacity of changing brightness levels.

Here is the caller graph for this function:

◆ getBrghtnssMinLvl()

uint8_t SevenSegDispHw::getBrghtnssMinLvl ( )

virtual

Returns the minimum display brightness level setting for the display.

For displays with variable display brightness levels this method will return the minimum brightness level value setting. See setBrghtnssLvl(const uint8_t &) for more details.

Note: For display classes that models object without the capacity of changing brightness levels, getBrghtnssMinLvl() = getBrghtnssLvl() = getBrghtnssMaxLvl() = 0, this implies that using (getBrghtnssMinLvl() == getBrghtnssMaxLvl()) condition is enough to identify if a given display has or has not the capacity of changing brightness levels.

Returns: The display brightness level minimum value setting, as long as the display has the capacity of changing brightness levels.

◆ getCommAnode()

bool SevenSegDispHw::getCommAnode ( )

Returns a value indicating if the display module component of the display hardware uses a common anode or a common cathode led wiring.

The SevenSegDisplays instantiated objects will compose the values corresponding to each character it displays according to the SevenSegDispHw _commAnode attribute. Each SevenSegDispHw instantiable subclass will have that constant attribute set by the subclass developer to correspond to the technical specifications of the display module component, unless the display module has the capacity to work with both technologies, in wich case the subclass constructor will include a _commAnode boolean parameter to set that attribute.

Return values

true	The display is built with a Common Anode display module component.
false	The display is built with a Common Cathode display module component.

◆ getDspBuffPtr()

uint8_t * SevenSegDispHw::getDspBuffPtr ( )

Returns a pointer to the display buffer.

The display buffer is the memory area set by the SevenSegDisplays class object instantiated to hold the data to be displayed, and so it's shared by that object and it's SevenSegDispHw subclass object component. When the SevenSegDisplays object is constructed it sets the SevenSegDispHw subclass object buffer pointer to the memory area it set for that purpose. This method retrieves that memory pointer.

Returns: uint8_t* The pointer to the buffer area used by the SevenSegDispHw to get the data to display.

Warning: If getDspBuffPtr() returns a nullptr it means the setDspBuffPtr(uint8_t*) invoked by the SevenSegDisplays constructor failed and the SevenSegDispHw object has no source for the data to be displayed.

◆ getHwDspDigitsQty()

uint8_t SevenSegDispHw::getHwDspDigitsQty ( )

Returns the quantity of digits of the display module.

The value returned correspond to the dspDigits parameter passed at instantiation time.

Returns: uint8_t The display module component digits quantity.

Warning: The dspDigits parameter value return by this method must not be confused with the maximum display digits a display controller component can handle. For more information see SevenSegDispHw(uint8_t*, uint8_t, bool commAnode)

◆ getIsOn()

bool SevenSegDispHw::getIsOn ( )

virtual

Returns the state of the display.

Returns a boolean value indicating if the display is turned On or Off

Return values

true	The display is turned On
false	The display is turned Off

Reimplemented in SevenSegMax7219.

◆ getxcdDspBuffPtr()

uint8_t * SevenSegDispHw::getxcdDspBuffPtr ( )

Returns a pointer to an array holding the contents for the digits/ports available from the display controller but not used for plain digits display.

Returns: uint8_t* The pointer to the array holding the contents for the exceeding display controller ports.

◆ ntfyUpdDsply()

void SevenSegDispHw::ntfyUpdDsply ( )

virtual

Notifies the SevenSegDispHw component object of a change of content available in the display buffer, so that the object proceeds to update the display.

While the dynamic displays must periodically refresh the data displayed, and so they get the most updated content from the display buffer without the need to receive any notification, the data displayed by the static displays internal buffer to hold the displayed data. The internal buffer contents remain constant until it's data buffer or registers are loaded with new data. This method notifies the display that the data buffer content has changed and it must load the new contents of it's internal registers or buffers to display the new information.

Note: The usual possibilities to work in these cases are two: exception notification or constant polling. The exception notification mechanism has been selected for economy of resources and usual considerations of similar cases.

Reimplemented in SevenSegHT16K33, SevenSegMax7219, SevenSegStatHC595, and SevenSegTM163X.

Here is the caller graph for this function:

◆ setBrghtnssLvl()

bool SevenSegDispHw::setBrghtnssLvl ( const uint8_t & newBrghtnssLvl )

virtual

Sets the brightness level for the display.

Although dummy dynamic and dummy static displays brightness might be dimmed using PWM management, both displays require MCU intervention, added to the regular required cinematic effect generation workload, making the brightness control very expensive in resources use. For this reason the brightness control in this library will be available for the smart static displays equiped with a display controller unit specifically providing the option. Each class description and documentation will detail if the service is available or not, and in case the method is invoked in an object instantiated from a class with no brightness control capabilities, the value returned will be false, avoiding the need of a error handling mechanism.

Parameters

newBrghtnssLvl The new brightness level for the display. The value must be in the range getBrghtnssMinLvl() <= newBrghtnssLvl <= getBrghtnssMaxLvl()

Return values

true	The parameter was in the valid range, the display will be set to the new brightness level (or keep it's brightness level if the parameter passed is equal to the current brightness level)

Returns: false The display module does not support brightness level setting, or the parameter passed is outside the valid range, no brightness level changes could be made.

Reimplemented in SevenSegHT16K33, SevenSegMax7219, and SevenSegTM163X.

Here is the caller graph for this function:

◆ setDigitsOrder()

bool SevenSegDispHw::setDigitsOrder ( uint8_t * newOrderPtr )

virtual

Sets a mapping to relate the display buffer positions to the display port assigned to exhibit it's contents.

As different Seven Segment display hardware implement different wiring schemes between the display controller component and the display module component, some implement the leftmost display port as it's lowest memory position of it's buffer, while some implement the rightmost position to it. When more than one display module components are used, it adds a new level of hardware implementation that differs from one supplier to the other. The library implements a mechanism to provide the instantiated object to relate the positions of the display ports to the display buffer positions through an array. The array has the size of the display buffer, and each array element is meant to hold the number of the corresponding port that is wired to display the data in that display buffer position The array is default defined in the constructor as (0, 1, 2,...) that is the most usual implementation found. If the order needs to be changed the setDigitsOrder() method is the way to set a new mapping.

Parameters

newOrderPtr Pointer to an uint8_t array of _dspDigits length containing the position of the port in the display module components wired to display that buffer position content. Each value will be checked against the _dspDigits value to ensure that they are all in the range acceptable, 0 <= value <= _dspDigits - 1. If one of the values is out of the valid range no change will be done. Please note that no checking will be done to ensure all of the array values are different. A repeated value will be accepted, ending in an undetermined non-critic, display behavior.

Returns: true All of the elements of the array were in the accepted range. The change was performed.; false At least one of the values of the array passed were out of range. The change wasn't performed.

Use example:

const uint8_t diyMore8Bits[8] {3, 2, 1, 0, 7, 6, 5, 4}; //Builds an array with the port order of the "DIY MORE 8-bit LED Display".
const uint8_t stdLtoRx4 [4] {0, 1, 2, 3};  // Simple left to right 4 digits order
const uint8_t stdRtoLx4 [4] {3, 2, 1, 0};  // Simple right to left 4 digits order (default)
 
myLedDisp.setDigitsOrder(diyMore8Bits); //Changes the display bit to port mapping according to the display characteristics.  

◆ setDspBuffPtr()

void SevenSegDispHw::setDspBuffPtr ( uint8_t * newDspBuffPtr )

Sets the pointer to the Display Buffer memory area.

When a SevenSegDisplays object is instantiated it's constructor sets a display buffer memory area to store the contents ready to be displayed. Part of the constructor execution includes passing to the SevenSegDispHw subclass component that pointer, as the underlying hardware display object will be taking the information to display from that memory buffer. The resource to set the pointer is this method.

Returns: uint8_t* The pointer to the Display Buffer Memory Area.

Attention: Using this method is a resource to generate "animations" by changing the memory area from with the hardware displays takes it's contents, to some other area with ready to display information.

Note: The dspBuffPtr attribute might be changed to use a temporary different source of data to be displayed.

Warning: Setting the display buffer pointer to an address not coinciding with the one configured in the SevenSegDisplays will disable the possibility for it to get new SevenSegDisplays generated content displayed!! Handle with extreme care, first saving the original provided pointer, changing it as needed, and reseting the _dspBuffPtr to the saved value!!

◆ turnOff()

void SevenSegDispHw::turnOff ( )

virtual

Turns the display module off.

The display module will be cleared and will keep that status until a turnOn(), or turnOn(const uint8_t &) is invoked.

Note: Turning the display Off is not the same as clearing the display -see clear() method- as clearing the display implies changing the display data buffer content to fill it with spaces, while turning it off implies keeping the display data buffer updated, while showing the display leds turned off. Some of the display modules managed by display controllers have the hability to turn off the leds display while keeping it's buffer contents unmodified. So turning On/Off those displays will have the effect of holding the data displayed and even receiving and filling their buffer with updated data while keeping their display with no leds turned on.

Reimplemented in SevenSegDynDummy, SevenSegHT16K33, SevenSegMax7219, and SevenSegTM163X.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ turnOn() [1/2]

void SevenSegDispHw::turnOn ( )

virtual

Turns the display module on.

The display module will be turned on, making visible the contents of the display buffer. For more information see turnOff() method.

Reimplemented in SevenSegDynDummy, SevenSegHT16K33, SevenSegMax7219, and SevenSegTM163X.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ turnOn() [2/2]

void SevenSegDispHw::turnOn ( const uint8_t & newBrghtnssLvl )

virtual

Turns the display module on set at the provided brightness level.

For correct execution and visual response, this method executes a setBrghtnssLvl(const uint8_t &) method followed by a turnOn() method execution.

Warning: If the setBrghtnssLvl(const uint8_t &) method returns false indicating it has failed, this method will go on invoking the turnOn() method instead of failing altogether, as it gives higher priority to the turning on of the display than to the brightness level setting. If the developer is not ok with this scheme he can always use the two methods independently in the sequence he decides better fits his needs and act as his own criteria dictates after the setBrghtnssLvl(const uint8_t &) fails.

Parameters

newBrghtnssLvl The new brightness level for the display. The value must be in the range getBrghtnssMinLvl() <= newBrghtnssLvl <= getBrghtnssMaxLvl()

Reimplemented in SevenSegHT16K33, SevenSegMax7219, and SevenSegTM163X.

Here is the call graph for this function:

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SevenSegDispHw()

Member Function Documentation

◆ begin()

◆ end()

◆ getBrghtnssLvl()

◆ getBrghtnssMaxLvl()

◆ getBrghtnssMinLvl()

◆ getCommAnode()

◆ getDspBuffPtr()

◆ getHwDspDigitsQty()

◆ getIsOn()

◆ getxcdDspBuffPtr()

◆ ntfyUpdDsply()

◆ setBrghtnssLvl()

◆ setDigitsOrder()

◆ setDspBuffPtr()

◆ turnOff()

◆ turnOn() [1/2]

◆ turnOn() [2/2]