Default constructor. More...

#include <SevenSegDisplays.h>

Collaboration diagram for SevenSegDisplays:

[legend]

Public Member Functions
	SevenSegDisplays (SevenSegDispHw *dspUndrlHwPtr)
	Class constructor.
	~SevenSegDisplays ()
	Class destructor.
virtual bool	begin (uint32_t updtLps=0)
	Sets up the hardware display to work, and starts the display activities.
bool	blink ()
	Makes the display blink the contents it is showing.
bool	blink (const uint32_t &onRate, const uint32_t &offRate=0)
	Makes the display blink the contents it is showing.
void	clear ()
	Clears the display, turning off all the segments and dots.
bool	doubleGauge (const int &levelLeft, const int &levelRight, char labelLeft=' ', char labelRight=' ')
	Displays a basic graphical representation of the level of fulfillment or completeness of two segmented values or tasks.
bool	end ()
	Ends the activity of the display.
bool	gauge (const int &level, char label=' ')
	Displays a basic graphical representation of the level of fulfillment or completeness of a segmented value or task.
bool	gauge (const double &level, char label=' ')
	Displays a basic graphical representation of the level of fulfillment or completeness of a segmented value or task.
uint8_t	getCurBrghtnssLvl ()
	Returns the current brightness level of the display.
uint8_t	getDigitsQty ()
	Return the number of digits of the display hardware.
uint8_t	getDspCount ()
	Returns the quantity of instantiated SevenSegDisplays class objects at invocation moment.
bool	getDspIsDmmbl ()
	Returns the logic value indicating if the display is dimmable.
SevenSegDispHw *	getDspUndrlHwPtr ()
	Returns a pointer to the underlying hardware display object.
int32_t	getDspValMax ()
	Returns a value equivalent to the greatest displayable number for the display.
int32_t	getDspValMin ()
	Returns a value equivalent to the smallest displayable number for the display.
bool	getIsOn ()
	Returns a logic value indicating if the display is in On state.
uint32_t	getMaxBlinkRate ()
	Returns the maximum rate the display can be configured to blink at.
uint8_t	getMaxBrghtnssLvl ()
	Returns the maximum brightness value setting for the display.
uint32_t	getMinBlinkRate ()
	Returns the minimum rate the display can be configured to blink at.
uint8_t	getMinBrghtnssLvl ()
	Returns the minimum brightness value setting for the display.
uint16_t	getSerialNbr ()
	Returns a unique numeric identification of the object.
bool	isBlank ()
	Returns a value indicating if the display is blank.
bool	isBlinking ()
	Returns a boolean value indicating if the display is set to blink or not.
bool	isWaiting ()
	Returns a boolean value indicating if the display is set to "waiting mode" or not.
bool	noBlink ()
	Stops the display blinking, if it was doing so, leaving the display turned on.
bool	noWait ()
	Stops the Waiting mode, if it was doing so, leaving the display turned on.
bool	print (String text)
	Displays a text string.
bool	print (const int32_t &value, bool rgtAlgn=false, bool zeroPad=false)
	Displays an integer value as long as the length representation fits the available space of the display.
bool	print (const double &value, const unsigned int &decPlaces, bool rgtAlgn=false, bool zeroPad=false)
	Displays a floating point value.
void	resetBlinkMask ()
	Resets the blinking mask.
void	setBlinkMask (const bool *newBlnkMsk)
	Sets a new blinking mask for the display.
bool	setBlinkRate (const uint32_t &newOnRate, const uint32_t &newOffRate=0)
	Changes the time parameters to use for the display blinking of the contents it shows.
bool	setBrghtnssLvl (const uint8_t &newBrghtnssLvl)
	Set the brightness level for the display.
bool	setWaitChar (const char &newChar)
	Sets the "Waiting" character.
bool	setWaitRate (const uint32_t &newWaitRate)
	Changes the timing parameter used to show the "progress ongoing bar advancement" speed.
void	turnOff ()
	Turns the display module off.
void	turnOn ()
	Turns the display module on.
void	turnOn (const uint8_t &newBrghtnssLvl)
	Turns the display module on.
bool	wait ()
	Makes the display enter the "Waiting mode".
bool	wait (const uint32_t &newWaitRate)
	Makes the display enter the "Waiting mode" with a specific wait rate.
bool	write (const uint8_t &segments, const uint8_t &port)
	Prints one character to the display, at a designated position (digit or port), without affecting the rest of the characters displayed.
bool	write (const String &character, const uint8_t &port)
	Prints one character to the display, at a designated position (digit or port), without affecting the rest of the characters displayed.

Detailed Description

Default constructor.

Constructor & Destructor Documentation

◆ SevenSegDisplays()

SevenSegDisplays::SevenSegDisplays ( SevenSegDispHw * dspUndrlHwPtr )

Class constructor.

Instantiates a SevenSegDisplays class object

Parameters

dspUndrlHw A pointer to an instantiated SevenSegDispHw subclass object that models the hardware display that composes the SevenSegDisplays object

Note: The library structure design, built on the idea of keeping the API and the services provided consistent, and connecting to the hardware managing level through specific subclasses of the SevenSegDispHw class gives a variety of valid instantiation procedures, through different code but with the same result. This might help the developer to keep his/hers most comfortable practices to get the object needed created. Some examples of this are:

A three lines step by step code example:

SevenSegDynHC595 myLedDispHw(myDispIOPins, 4, true);  // Instantiation of the underlying hardware object
SevenSegDispHw* myLedDispHwPtr = &myLedDispHw;        // Creation of a pointer to the instantiated hardware object
SevenSegDisplays myLedDisp(myLedDispHwPtr);           // Instantiation of the SevenSegDisplays object using the pointer created

A two lines example using the & operand to pass the pointer to the constructor

SevenSegDynHC595 myLedDispHw(myDispIOPins, 4, true); // Instantiation of the underlying hardware object

SevenSegDisplays myLedDisp(&myLedDispHw); // Instantiation of the SevenSegDisplays object using the & operand over the hardware object created

A two lines example using a sub-class pointer to a dynamic instantiated object

SevenSegDynHC595* myLedDispPtr {new SevenSegDynHC595 (myDispIOPins, 4, true)}; // Dynamic instantiation of the underlying hardware object, pointed by a subclass pointer

SevenSegDisplays myLedDisp(myLedDispPtr); // Instantiation of the SevenSegDisplays object using the subclass pointer to the hardware object dynamically created

SevenSegDisplays

Default constructor.

Definition SevenSegDisplays.h:59

A two lines example using a base class pointer to a dynamic instantiated object

SevenSegDispHw* myLedDispPtr {new SevenSegDynHC595 (myDispIOPins, 4, true)}; // Dynamic instantiation of the underlying hardware object, pointed by a base class pointer

SevenSegDisplays myLedDisp(myLedDispPtr); // Instantiation of the SevenSegDisplays object using the base class pointer to the hardware object dynamically created

A one liner example using as argument the pointer returned from dynamic instantiated object

SevenSegDisplays myLedDisp(new SevenSegDynHC595 (myDispIOPins, 4, true)); // Easy to understand reading from right to left, as usual!!

Attention: Note that two or more lines instantiations will be needed when specific display hardware configuration is required before the hardware use: semicolon setting, starting brightness levels, etc. Making use of the one, two, three or more lines instantiation is not a sign of smartness or elegance, but options to be taken by the development need.

Here is the call graph for this function:

Member Function Documentation

◆ begin()

bool SevenSegDisplays::begin ( uint32_t updtLps = 0 )

virtual

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

Depending on the display controller characteristics the setup procedure may include different defined steps, each class will execute the needed steps for each display controller.

Attention: The begin() method is different from the turnOn() method. The first one ensures the display controller unit is ready to receive data to be displayed, including communications and internal memory management, while the second enables the display to turn on the corresponding leds to exhibit the data received. The fact that some display technologies needs no configuration and/or not explicit turning on the display is hidden for the user benefit: all displays must invoke the begin() method, all displays have acces to a end(), turnOn() and turnOff(). Executing a begin() method will invoke automatically the turnOn() method. Invoking a turnOff() in a begun display will let the display to keep receiving data, but it will not be visible untila a new turnOn() is invoked.

Parameters

updtLps Optional parameter, sets the rate needed by the dynamic type displays, will be ignored by othe types of displays. Is no value is passed to the dynamic displays they will used a preset stantard parameter.

Return values

true	The display was initialized without errors.
false	The display couldn't be initialized due to an error.

◆ blink() [1/2]

bool SevenSegDisplays::blink ( )

Makes the display blink the contents it is showing.

The display will blink the contents it is showing until a noBlink() method is invoked. The display will continue blinking even if the contents are changed.
By default all the digits will be set to blink, but each digit might be configured individually to blink or not by using the setBlinkMask(const bool*) method.
When invoking the blink() method with no parameters the blinking pace (timings) previously set will be used. If no setBlinkRate(const unsigned long, const unsigned long) and no blink(const unsigned long, const unsigned long) with parameters was used before this call, the blinking will be symmetrical, meaning that the time the display shows the contents and the time the display is blank are equal. The on time and the off time of the blinking starts at a preset rate this first time the method is invoked.
The blinking rate can be changed by using the setBlinkRate(const unsigned long, const unsigned long) method. After changing the blinking rate, the new blinking rate will be kept after a noBlink() call is done, until it is modified with a new setBlinkRate(const unsigned long, const unsigned long) call, or it is restarted by a blink(const unsigned long, const unsigned long) with parameters.

Note: To restart the blinking with a blink() or a blink(const unsigned long, const unsigned long) the service must first be stopped, as the method call makes no changes if the blinking service was already running.

Return values

true	If the display blinking process started ok, or was already set to blink
false	The display blinking failed to start.

Use example:

myLedDisp.blink(); // Begin blinking at the already set rate

Here is the call graph for this function:

Here is the caller graph for this function:

◆ blink() [2/2]

bool SevenSegDisplays::blink	(	const uint32_t &	onRate,
		const uint32_t &	offRate = 0 )

Makes the display blink the contents it is showing.

Makes the display blink the contents it shows until a noBlink() method is invoked. The blinking is symmetrical if only one parameter is passed, asymmetrical if two different parameters are passed, meaning that the time the display shows the contents and the time the display is blank will be equal (symmetrical) or not (asymmetrical), depending of those two parameters. The blinking starts at a passed rate when the method is invoked. The blinking rate can be changed by using the .setBlinkRate(const unsigned long, const unsigned long) method. The blink rate set will be kept after a .noBlink(), until it is modified with a new .setBlinkRate(const unsigned long, const unsigned long) call, or it is restarted by a .blink(const unsigned long, const unsigned long) with parameters.

Note: To restart the blinking with a blink() or a blink(const unsigned long, const unsigned long) the service must first be stopped, as the method call makes no changes if the blinking service was already running.

Parameters

onRate Value indicating the time (in milliseconds) the display must stay on, the value must be in the range _minBlinkRate <= onRate <= _maxBlinkRate. Those preset values can be known by the use of the getMinBlinkRate() and the getMaxBlinkRate() methods.

offRate Optional value indicating the time (in milliseconds) the display must stay off, the value must be in the range _minBlinkRate <= offRate <= _maxBlinkRate. Those preset values might be known by the use of the getMinBlinkRate() and the getMaxBlinkRate() methods. If no offRate value is provided the method will assume it's a symmetric blink call and use a value for offRate equal to the value passed for onRate.

Return values

true	If the display was already set to blink, or was not blinking and the blinking started with the provided parameters. If the display was already blinking no change will be made to the blinking rate.
false	One or more of the parameters passed were out of range.

Use examples:

myLedDisp.blink(400); // Starts blinking setting the rate to 400 millisecs on, 400 millisecs off (symmetrical blink). And returns true.

myLedDisp.blink(800, 200); // Sets the blinking rate to 800 millisecs on, 200 millisecs off (asymmetrical blink), starts blinking, and returns true.

unsigned long rateTooBig {myLedDisp.getMaxBlinkRate() + 10} // Saves in a variable a blinking rate out of accepted range

myLedDisp.blink(rateTooBig); //Returns false and the display stays without change.

Here is the call graph for this function:

◆ clear()

void SevenSegDisplays::clear ( )

Clears the display, turning off all the segments and dots.

To ensure success the method must also clean auxiliary buffers used to save the main buffer contents while blinking, as the backup buffer will be restored, so the display clear() would be reverted

Note: The method will not produce any change if it's in "Waiting mode" as the blanked ports will be immediately overwritten by the waiting process, so it makes no sense. Consider, though, that the "Waiting mode" clears the display at it's exit.

Use example:

myLedDisp.clear();

Here is the caller graph for this function:

◆ doubleGauge()

bool SevenSegDisplays::doubleGauge	(	const int &	levelLeft,
		const int &	levelRight,
		char	labelLeft = ' ',
		char	labelRight = ' ' )

Displays a basic graphical representation of the level of fulfillment or completeness of two segmented values or tasks.

The data displayed gives a general fast notion on the matter, as a battery charge level, liquids deposit level, time remaining, tasks completeness and so on. The levels are represented by the horizontal segments (0, 1, 2 or 3 from bottom to top), and a character might be added before each of the graphical representations to give an indication of what the display is showing, passed through the labelLeft and labelRight parameters. As four 7 segments digit ports will be used, this method only applies to displays with 4 to 8 LED digits, the display is splitted in two sectors, the left side and the right side, and each one of them must have a valid value (0 <= value <= 3) to enable them to be displayed, and might have (or not) a single displayable character to give a visual hint to what the value is showing. For more information check the gauge(const int, char) method.

Parameters

levelLeft	The integer value to display must be in the range 0 <= level <= 3 for the two leftside 7 segments displays.
levelRight	The integer value to display must be in the range 0 <= level <= 3 for the two rightside 7 segments displays.
labelLeft	A char, optional parameter (if not specified the default value, a Space, will be assumed), that will be displayed in the leftmost digit of the display. The character must be one of the "displayable" characters, as listed in the print() method description.
labelRight	A char, optional parameter (if not specified the default value, a Space, will be assumed), that will be displayed in the position left to the levelRight display, just before the levelRight value. The character must be one of the "displayable" characters, as listed in the .print(String) method description.

Return values

true	If the values could be represented.
false	Otherwise, being that the levelLeft and/or levelRight parameter was out of range and/or the labelLeft and/or labelRight parameter was not in the list of displayable characters. The display will be blanked.

Use example:

myLedDisp.gauge(3, 2); // Displays a double gauge with no labels, the left level in the fourth (higher) level, the right level in it's third level.

myLedDisp.gauge(2, 1, 'b', 't'); // Displays a double gauge, the left indicator with a **b** letter as label and a third level value, and the right side indicator with a **t** label and a second level value.

myLedDisp.gauge(1, 3, 'F'); // Displays a double gauge, the left indicator with a **F** letter as label and a second level value, and the right side indicator with a no label and a fourth level value.

myLedDisp.gauge(4, 2,'d', 'b'); // Error: the left level is outside valid range (value 4, valid range is 0<=value<=3). The method will return false and the display will be cleared.

myLedDisp.gauge(3, 0, 'X'); // Error: 'X' (the left indicator label) is not a "displayable" character. The method will return false and the display will be cleared.

Here is the call graph for this function:

◆ end()

bool SevenSegDisplays::end ( )

Ends the activity of the display.

After the end() is invoked, the display will stop accepting new data, stop it's refreshing and all activities involved in keeping it's contents updated. To keep the expected level of accuracy and security the display will be cleaned before stopping it's activity.

Returns: True

◆ gauge() [1/2]

bool SevenSegDisplays::gauge	(	const double &	level,
		char	label = ' ' )

Displays a basic graphical representation of the level of fulfillment or completeness of a segmented value or task.

The data displayed gives a general fast notion on the matter, as a battery charge level, liquids deposit level, time remaining, tasks completeness and so on. The levels are represented by the horizontal segments (0, 1, 2 or 3 from bottom to top, and from left to right), and a character might be added before the graphical representation to give an indication of what the display is showing, passed through the label parameter.

Parameters

level	The double value to display must be in the range 0.0 <= level <= 1.0, being the range the representation of the percentage of the 'full' level, so that the ranges are: 0.0 <= level < 0.25 for the first level, 0.25 <= level < 0.50 for the second level, 0.50 <= level < 0.75 for the third level, and 0.75 <= level <= 1.00 for the fourth and upper level.
label	char, optional parameter (if not specified the default value, a Space, will be assumed), that will be displayed in the leftmost digit of the display. The character must be one of the "displayable" characters, as listed in the print(String) method description.

Returns: true If the value could be represented.; false Otherwise, being that the level parameter was out of range and/or the label parameter was not in the list of displayable characters. The display will be blanked.

Use example:

myLedDisp.gauge(0.0); // Generates a display with no label and 0 level indication, so it will be a blank display

myLedDisp.gauge(0.4); // Generates a display with no label, and level 1 indicator

myLedDisp.gauge(0.55, 'b'); // Generates a display with a letter b as label, the level 1 and level 2 indicators

myLedDisp.gauge(1.0, 'F'); // Generates a display with a letter F as label, the level 1 level 2 and level 3 indicators

myLedDisp.gauge(1.5, 'd'); //Error: 4 is outside the accepted values range

myLedDisp.gauge(3.0, 'X'); //Error: 'X' is not a "displayable" character

Here is the call graph for this function:

◆ gauge() [2/2]

bool SevenSegDisplays::gauge	(	const int &	level,
		char	label = ' ' )

Displays a basic graphical representation of the level of fulfillment or completeness of a segmented value or task.

The displayed data gives a general fast notion on the matter, as a battery charge level, liquids deposit level, time remaining, tasks completeness and so on. The levels are represented by the horizontal segments (0, 1, 2 or 3 from bottom to top, and from left to right), and a character might be added before the graphical representation to give an indication of what the display is showing, passed through the label parameter. This method is usable in displays which have from 4 and up to 8 digits, and the representation always makes use of exactly 4 digits.

Parameters

level	The integer value to display must be in the range 0 <= level <= 3.
label	char, optional parameter (if not specified the default value, a Space, will be assumed), that will be displayed in the leftmost digit of the display. The character must be one of the "displayable" characters, as listed in the print(String) method description.

Returns: true If the value could be represented.; false Otherwise, being that the level parameter was out of range and/or the label parameter was not in the list of displayable characters. The display will be blanked.

Use example:

`myLedDisp.gauge(2, 'b');` // Displays a gauge with a label **b** in it's leftmost position, the next two positions with level indicators for second and third levels

`myLedDisp.gauge(3);` // Displays a gauge with a blank space as label and the next three positions with their respective levels indicators

`myLedDisp.gauge(1, 'F');` // Displays a gauge with a **F** as label in it's leftmost position, and the next position holding the second level indicator

`myLedDisp.**gauge(4, 'd');` // Error, the value 4 is outside valid range, the method will return **false** and the display will be cleared.

SevenSegDisplays::gauge

bool gauge(const int &level, char label=' ')

Displays a basic graphical representation of the level of fulfillment or completeness of a segmented ...

Definition SevenSegDisplays.cpp:382

`myLedDisp.gauge(3, 'X');` // Error, **X** is not a displayable character, the method will return **false** and the display will be cleared

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getCurBrghtnssLvl()

uint8_t SevenSegDisplays::getCurBrghtnssLvl ( )

Returns the current brightness level of the display.

Returns: uint8_t Brightness level

◆ getDigitsQty()

uint8_t SevenSegDisplays::getDigitsQty ( )

Return the number of digits of the display hardware.

Returns an unsigned short integer value indicating the the quantity of digits (ports), the display have as declared at the object instantiation. Each time the class is instantiated the object is created with the needed resources and the range of values it's capable of displaying are calculated based on the dspDigits parameter, and that value is the one returned by this method.

Returns: The unsigned short number indicating the quantity of digits of the instantiated display.

Use example:

uint8_t portsQty = myLedDisp.getDigitsQty(); // Saves in the portsQty variable the number of display ports (digits) of the display

◆ getDspCount()

uint8_t SevenSegDisplays::getDspCount ( )

Returns the quantity of instantiated SevenSegDisplays class objects at invocation moment.

Returns: The quantity of instantiated displays.

◆ getDspIsDmmbl()

bool SevenSegDisplays::getDspIsDmmbl ( )

Returns the logic value indicating if the display is dimmable.

Return values

true	The display is dimmable (variable brightness configuration)
false	The display is not dimmable (only constant brightness)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getDspUndrlHwPtr()

SevenSegDispHw * SevenSegDisplays::getDspUndrlHwPtr ( )

Returns a pointer to the underlying hardware display object.

The pointer returned is of the type SevenSegDispHw*, i.e. a base class pointer. One of the most important and practical use for this method is to give direct access to exclusive attributes, properties and characteristics some of the hardware display models have, and functions they may execute that have no way of being used through the SevenDisplays class methods. Some of those attributes known to exist are:

Activation and deactivation of semicolons
Change the level of brightness
Change the display color
Some kind of contents animations
Reading the state of pushbuttons managed by the driver chip

Returns: A SevenSegDispHw* type pointer to the underlying display object

◆ getDspValMax()

int32_t SevenSegDisplays::getDspValMax ( )

Returns a value equivalent to the greatest displayable number for the display.

The value indicates the greatest displayable number according to the quantity of digits (ports) the display have as indicated at the object instantiation.

Returns: The integer number indicating the maximum value that the display might display according to the quantity of digits of the instantiated display.
Use example:

Use example:

int32_t maxLimit = myLedDisp.getDspMax(); // Sets the variable maxLimit to the maximum displayable value for the display

◆ getDspValMin()

int32_t SevenSegDisplays::getDspValMin ( )

Returns a value equivalent to the smallest displayable number for the display.

The value indicates the smallest displayable number according to the quantity of digits (ports) the display have as indicated at the object instantiation.

Returns: The integer number indicating the minimum value that the display might display according to the quantity of digits of the instantiated display.

Use example:

`uint32_t minLimit = myLedDisp.getDspMin();` // Sets the variable minLimit to the minimum displayable value for the display

◆ getIsOn()

bool SevenSegDisplays::getIsOn ( )

Returns a logic value indicating if the display is in On state.

Return values

true	The display is on
false	The display is off

◆ getMaxBlinkRate()

uint32_t SevenSegDisplays::getMaxBlinkRate ( )

Returns the maximum rate the display can be configured to blink at.

The maximum rate the display can be configured to blink at helps keeping the blinkRate setters inside the accepted range. At least two aspects of the blinking process are involved in the determination if this value.

The technical aspect is related to the hardware possibility to manage the display contents change to show the blinking effect.
The perception aspect is related to keep the blinking effect range in a rhythm at which the display turns on and off as part of the information that it provides, and doesn't make it look like a display failure or any other kind of bug.

Returns: The maximum time, in milliseconds, the display can be set to blink. This value is the maximum to set as the turned-on or the turned-off stage of the blinking process started by a blink() or a blink(const unsigned long, const unsigned long) method.

Attention: Opposite to the concept of Hertz, that designates how many times an action happens in a fixed period of time (a second), the value used in the blink() and all related methods is the time set to elapse before the next action happens.

Use example:

unsigned long myDispMaxBlnkRt = myLedDisp.getMaxBlinkRate();

◆ getMaxBrghtnssLvl()

uint8_t SevenSegDisplays::getMaxBrghtnssLvl ( )

Returns the maximum brightness value setting for the display.

Returns: uint8_t Maximum brightness value setting.

Note: If the display has no brightness configuration control then getMaxBrghtnssLvl() = getMinBrghtnssLvl() = getCurBrghtnssLvl() = 0, and getDspIsDmmbl() returns false

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getMinBlinkRate()

uint32_t SevenSegDisplays::getMinBlinkRate ( )

Returns the minimum rate the display can be configured to blink at.

The minimum rate the display can be configured to blink at helps keeping the blinkRate setters inside the accepted range. At least two aspects of the blinking process are involved in the determination if this value.

The technical aspect is related to the hardware possibility to manage the display contents change to show the blinking effect.
The perception aspect is related to keep the blinking effect range in a rhythm at which the display turns on and off as part of the information that it provides, and doesn't make it look like a display failure or any other kind of bug.

Returns: The minimum time, in milliseconds, the display can be set to blink. This value is the minimum to set as the turned-on or the turned-off stage of the blinking process started by a .blink() or a blink(const unsigned long, const unsigned long) method.

Attention: Opposite to the concept of Hertz, that designates how many times an action happens in a fixed period of time (a second), the value used in the blink() and all related methods is the time set to elapse before the next action happens.

Use example:

unsigned long myDispMinBlnkRt = myLedDisp.getMinBlinkRate();

◆ getMinBrghtnssLvl()

uint8_t SevenSegDisplays::getMinBrghtnssLvl ( )

Returns the minimum brightness value setting for the display.

Returns: uint8_t Minimum brightness value setting.

Note: If the display has no brightness configuration control then getMaxBrghtnssLvl() = getMinBrghtnssLvl() = getCurBrghtnssLvl() = 0, and getDspIsDmmbl() returns false

Here is the caller graph for this function:

◆ getSerialNbr()

uint16_t SevenSegDisplays::getSerialNbr ( )

Returns a unique numeric identification of the object.

The Returned unsigned integer value identifies the object. Each time the class is instantiated the created object receives a serial instantiation number that can be used in order to identify each object in case of need.

Returns: The unsigned number indicating the identification Instance Number.

Note: As SevenSegDisplays objects might be constructed and destructed at need, the largest Instance number is not necessarily coincidental with the quantity of objects instantiated at any given moment, as the numeric identification of the object is an always increasing value incremented every time a new object is instantiated, but never decremented due to destructions. To know the quantity of instantiated displays at any given moment see uint8_t getDspCount()

Attention: Not to be confused with a pointer to the object or other internal unique identification mechanism results

Use example:

uint8_t dspNmbr = myLedDisp.getSerialNbr();

◆ isBlank()

bool SevenSegDisplays::isBlank ( )

Returns a value indicating if the display is blank.

The condition of blank is the one in which "All the display ports/digits of the display show spaces, and no decimal points or semicolons are active". This definition is important as it not refers to the display buffer holding any specific arbitrary value (0x00 or 0xFF) but the value designated as _space.

Return values

true	The display buffer is filled with _space values
false	At least one memory element of the buffer is filled with a value that is not a _space

Use example:

if(!myDisplay.isBlank())

myDisplay.clear();

◆ isBlinking()

bool SevenSegDisplays::isBlinking ( )

Returns a boolean value indicating if the display is set to blink or not.

Return values

true	The display is set to blink.
false	The display is set not to blink.

Use example:

if(myDisplay.isBlinking)

myDisplay.noBlink();

◆ isWaiting()

bool SevenSegDisplays::isWaiting ( )

Returns a boolean value indicating if the display is set to "waiting mode" or not.

Knowing if the display is set to "waiting mode" might be useful as the display will force the mode disabling if a print(), write(), gauge(), etc. methods is invoked.

Returns: true If the display is set to Waiting mode.; false If the display is not set to Waiting mode.

Use example:

if(myDisplay.isWaiting)

myDisplay.noWait();

◆ noBlink()

bool SevenSegDisplays::noBlink ( )

Stops the display blinking, if it was doing so, leaving the display turned on.

Stoping the blinking process includes retrieving the original contents from the _dspAuxPtr pointed memory (the Auxiliary Buffer), freeing the Auxiliary Buffer memory, stoping the timer attached to the process and cleaning the blinking state related flags

Return values

true	The display was set to not blinking, either because the display was set to blink and was stopped, either the display was not set to blink.
false	The display was set to blink, and the blink stopping failed.

Code example:

myLedDisp.noBlink();

Here is the caller graph for this function:

◆ noWait()

bool SevenSegDisplays::noWait ( )

Stops the Waiting mode, if it was doing so, leaving the display turned on.

Stoping the "Waiting mode" process includes retrieving the original contents from the _dspAuxPtr pointed memory (the Auxiliary Buffer), freeing the Auxiliary Buffer memory, stoping the timer attached to the process and cleaning the waiting state related flags

Return values

true	If the display was set to wait, the Waiting mode is stopped.
false	If the display was not set to wait, no changes will be done.

Code example:

myLedDisp.noWait();

Here is the caller graph for this function:

◆ print() [1/3]

bool SevenSegDisplays::print	(	const double &	value,
		const unsigned int &	decPlaces,
		bool	rgtAlgn = false,
		bool	zeroPad = false )

Displays a floating point value.

The floating point value will be displayed as long as the length representation fits the available space of the display. If the integer part of value is not in the displayable range or if the sum of the spaces needed by the integer part plus the indicated decimal places to display is greater than the available digits space, the print() will fail, returning a false value and clearing the display.

Parameters

value	The floating point value which must be in the range ((-1)*(pow(10, ((dspDigits - decPlaces) - 1)) - 1)) <= value <= (pow(10, (dspDigits - decPlaces)) - 1), or _dspValMin <= value <= _dspValMax.
decPlaces	Decimal places to be displayed after the decimal point, ranging 0 <= decPlaces < dspDigits, selecting 0 value will display the number as an integer, with no '.' displayed. In any case the only modification that will be applied if value has a decimal part longer than the decPlaces number of digits is truncation, if any other rounding criteria is desired the developer must apply it to value before calling this method.
rgtAlgn	Boolean, optional parameter (if not specified the default value, false, will be assumed), indicates if the represented value must be displayed right aligned, with the missing heading characters being completed with spaces or zeros, depending in the zeroPad optional parameter. When a negative value is displayed and it's less than (dspDigits - 1) digits long, a right aligned display will keep the '-' sign in the leftmost position, and the free space to the leftmost digit will be filled with spaces or zeros, depending in the zeroPad optional parameter.
zeroPad	Boolean, optional parameter (if not specified the default value, false, will be assumed), indicates if the heading free spaces of the value right aligned displayed must be filled with zeros (true) or spaces (false). In the case of a negative value the spaces or zeros will fill the gap between the '-' sign kept in the leftmost position, and the first digit.

Return values

true	The value could be represented.
false	The value couldn't be represented. The display is blanked.

Code example (on a 4-bits display):

myLedDisp.print(1.2, 2);   //Displays '1.20 '  
myLedDisp.print(1.2, 2, true);   //Displays ' 1.20'  
myLedDisp.print(12, 2, true, true); //Displays '01.20'    
myLedDisp.print(-1.2, 2);  //Displays '-1.20'  
myLedDisp.print(-1.28, 1, true); //Displays '- 1.2'  
myLedDisp.print(-1.28, 1, true, true); //Displays '-01.2'    
myLedDisp.print(-1.28, 3, true, true); //Error

Here is the call graph for this function:

◆ print() [2/3]

bool SevenSegDisplays::print	(	const int32_t &	value,
		bool	rgtAlgn = false,
		bool	zeroPad = false )

Displays an integer value as long as the length representation fits the available space of the display.

Parameters

value	The integer value to display which must be in the range (-1)*(pow(10, (dspDigits - 1)) - 1) <= value <= (pow(10, dspDigits) - 1), or _dspValMin <= value <= _dspValMax.
rgtAlgn	Boolean, optional parameter (if not specified the default value, false, will be assumed), indicates if the represented value must be displayed right aligned, with the missing heading characters being completed with spaces or zeros, depending in the zeroPad optional parameter. When a negative value is displayed and it's less than (dspDigits - 1) digits long, a right aligned display will keep the '-' sign in the leftmost position, and the free space to the leftmost digit will be filled with spaces or zeros, depending in the zeroPad optional parameter.
zeroPad	Boolean, optional parameter (if not specified the default value, false, will be assumed), indicates if the heading free spaces of the integer right aligned displayed must be filled with zeros (true) or spaces (false). In the case of a negative integer the spaces or zeros will fill the gap between the '-' sign kept in the leftmost position, and the first digit.

Returns: true If the value could be represented.; false If the value couldn't be represented as it was out of the valid range. The display will be blanked.

Code example

myLedDisp.print(12);  //Displays '12  ' on a 4 digits display  
myLedDisp.print(12, true); //Displays '  12' on a 4 digits display  
myLedDisp.print(12, true, true); //Displays '0012' on a 4 digits display  
myLedDisp.print(-12);   //Displays '-12     ' on a 8 digits display  
myLedDisp.print(-12, true);   //Displays '-   12' on a 6 digits display  
myLedDisp.print(-12, true, true);   //Displays '-012' on a 4 digits display    

Here is the call graph for this function:

◆ print() [3/3]

bool SevenSegDisplays::print ( String text )

Displays a text string.

The text string must contains all "displayable" characters, which are the ones included in the following list: 0123456789AabCcdEeFGHhIiJLlnOoPqrStUuY-_. and the space. There are other special characters displayable, details in the notes.

Parameters

text String, up to dspDigits displayable characters long PLUS usable dots, all characters included in the representable characters list. Each valid character might be followed by a "." if needed, without being counted as a character, even spaces and special chars. If two or more consecutive dots are passed, an intermediate space is considered to be included between each pair of them, and that space counts as one of the available characters to display.

Return values

true	If the text complies with the requirements to be represented. The text string will be displayed.
false	Otherwise. The display will be blanked.

Note: There are other 3 characters that can be represented in the display, but the conversion from a character to use while programming is "host language setting dependant", so those where assigned to available ASCII non displayable characters of easy access in any keyboard layout in most languages, they can be used as part of the text string to display, and they are:
**=** Builds a character formed by lighting the lower 2 horizontal segments (the d and g segments) of the digit display, can be described as a "lower equal" symbol.
**~** Builds a character formed by lighting the 3 horizontal segments (the a, d and g segments) of the digit display, can be described as an "equivalent" symbol.
'*' (asterisk) Builds a character by lighting the upper 4 segments (the a, b, f and g segments), forming a little square, can be described as the "degrees" symbol or º.

Code example:

myLedDisp.print("Hi");  // Valid for 2 or more digits displays  
myLedDisp.print("Strt");   // Valid for 4 or more digits displays  
myLedDisp.print("L.A.X."); // Error, as 'X' is a not displayable character  
myLedDisp.print("36.70*"); // Valid for 5 or more digits displays  
myLedDisp.print("........");  // Valid for 8 digits displays  

Here is the caller graph for this function:

◆ resetBlinkMask()

void SevenSegDisplays::resetBlinkMask ( )

Resets the blinking mask.

The blinking mask configures which digits of the display will be affected by the .blink() method. This method resets the mask so that all the digits will be affected when blinking is active.

Code example

myLedDisp.resetBlinkMask();

◆ setBlinkMask()

void SevenSegDisplays::setBlinkMask ( const bool * newBlnkMsk )

Sets a new blinking mask for the display.

The blinking mask indicates which digits will be involved when a blink() method is invoked. Indicating true for a digit makes it blink when the method is called, indicating false makes it display steady independently of the other digits. The parameter is positional referenced to the display, and for ease of use the index numbers of the array indicate their position relative to the rightmost digit (blnkPort0). The mask might be reset to its original value (all digits set to blink) by using this method with all parameters set to true or by using the resetBlinkMask() method.

Parameters

newBlnkMsk Array of booleans of length dspDigits, indexes are positional referenced to the display, indicating each one which digits must blink after a blink() method is invoked (true) or stay steady (false). The indexes valid range is 0 <= index <= (dspDigits-1), corresponding the [0] position withe the rightmost display port, the [1] position the second from the right and so on.

Code example

bool tstMask[4]{true, true, true, true};  
testResult = myLedDisp.blink();  //Sets all the  digits to blink in a 4 digits display  
tstMask[0] = true;  
tstMask[1] = false;  
tstMask[2] = false;  
tstMask[3] = false;  
myLedDisp.setBlinkMask(tstMask); //Sets only the rightmost digit to blink in a 4 digits display  
tstMask[0] = false;  
tstMask[1] = true;  
tstMask[2] = true;  
myLedDisp.setBlinkMask(tstMask); //Sets the two central digits to blink in a 4 digits display

◆ setBlinkRate()

bool SevenSegDisplays::setBlinkRate	(	const uint32_t &	newOnRate,
		const uint32_t &	newOffRate = 0 )

Changes the time parameters to use for the display blinking of the contents it shows.

The parameters change will take immediate effect, either if the display is already blinking or not, in the latter case the parameters will be the ones used when a blink() method is called without parameters. The blinking will be symmetrical if only one parameter is passed, asymmetrical if two different parameters are passed, meaning that the time the display shows the contents and the time the display is blank will be equal (symmetrical) or not equal (asymmetrical), depending of those two parameters. The blink rate set will be kept after a noBlink() or new blink() without parameters call is done, until it is modified with a new setBlinkRate() call, or it is restarted by a blink() with parameters. Note that to restart the blinking with a blink() the service must first be stopped, as the method makes no changes if the blinking service was already running.

Parameters

newOnRate unsigned long integer containing the time (in milliseconds) the display must stay on, the value must be in the range _minBlinkRate <= onRate <= _maxBlinkRate. Those built-in values can be known by the use of the getMinBlinkRate() and the getMaxBlinkRate() methods.

newOffRate optional unsigned long integer containing the time (in milliseconds) the display must stay off, the value must be in the range _minBlinkRate <= offRate <= _maxBlinkRate. Those built-in values can be known by the use of the getMinBlinkRate() and the getMaxBlinkRate() methods. If no offRate value is provided the method will assume it's a symmetric blink call and use a value of offRate equal to the value passed by onRate.

Returns: true The parameter or parameters passed are within the valid range, The change will take effect immediately.; false One or more of the parameters passed were out of range. The rate change would not be made for none of the parameters.

Code example

myLedDisp.setBlinkRate(400);  //Returns true and sets the blinking rate to 400 millisecs on, 400 millisecs off (symmetrical blink).  
myLedDisp.setBlinkRate(800, 200);   //Returns true and sets the blinking rate to 800 millisecs on, 200 millisecs off (asymmetrical blink)  
myLedDisp.setBlinkRate(3000); //Returns false and the display blinking rate stays without change.  
myLedDisp.setBlinkRate(600, 3500);  //Returns false and the display blinking rate stays without change.  

Here is the caller graph for this function:

◆ setBrghtnssLvl()

bool SevenSegDisplays::setBrghtnssLvl ( const uint8_t & newBrghtnssLvl )

Set the brightness level for the display.

For the brightness level settin to succeed two conditions must be met:
1) The display must be dimmable (see setBrghtnssLvl() ) 2) The new brightness level must be in the valid range for the display: getMinBrghtnssLvl() <= newBrghtnssLvl <= getMaxBrghtnssLvl()

Parameters

newBrghtnssLvl The new value setting for the brightness level

Returns: true The display is dimmable, and the newBrghtnssLvl is in the valid range, the change is made; false The display is not dimmable, or the newBrghtnssLvl is outside the valid range, no change is made

Here is the call graph for this function:

◆ setWaitChar()

bool SevenSegDisplays::setWaitChar ( const char & newChar )

Sets the "Waiting" character.

The character used by the display to show the "process ongoing" a.k.a. "Waiting mode" can be changed. The default character set is the "-" (minus sign). The parameters change will take immediate effect, either if the display is already in wait mode or not. The new character will be changed for further calls of the method until a new setWaitChar is invoked with a valid argument, that means a "displayable character".

Parameters

newChar A character the display must use for symbolizing the progress, the value must be in the displayable characters group as explained in the print() method.

Returns: true The character passed is within the displayable characters range, the change will take effect immediately.; false The parameter passed was invalid, i.e. it was a non displayable character, the character change will not be made.

Code example

myLedDisp.setWaitRate('_'); // Returns true and sets the wait character to '_'.

myLedDisp.setWaitRate('#'); // Error, returns false and the display wait character stays without change.

◆ setWaitRate()

bool SevenSegDisplays::setWaitRate ( const uint32_t & newWaitRate )

Changes the timing parameter used to show the "progress ongoing bar advancement" speed.

The parameter change will take immediate effect, either if the display is already in wait mode or not, in the latter case the parameter will be the one used when a wait() method is called without parameters. The wait rate set will be kept after a noWait() or new wait() without parameters call is done, until it is modified with a new setWaitRate() call, or it is restarted by a wait() with parameters. Note that to restart the waiting with a wait() the service must first be stopped, as the method makes no changes if the waiting service was already running.

Parameters

newWaitRate unsigned long integer containing the time (in milliseconds) the display must take to advance the next character symbolizing the progress, the value must be in the range _minBlinkRate <= newWaitRate <= _maxBlinkRate. Those values can be known by the use of the getMinBlinkRate() and the getMaxBlinkRate() methods.

Return values

true	The parameter passed is within the valid range, the change takes effect.
false	The parameter passed was out of range, the rate change will not be made.

Code example

myLedDisp.setWaitRate(400); //Returns true and sets the advancement rate to 400 millisecs.

myLedDisp.setWaitRate(myLedDisp.getMinBlinkRate() - 10); //Returns false and the display wait rate stays without change.

◆ turnOff()

void SevenSegDisplays::turnOff ( )

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.

◆ turnOn() [1/2]

void SevenSegDisplays::turnOn ( )

Turns the display module on.

The display module will be turned on and it's content displayed, and will keep that status until a turnOff() is invoked.

◆ turnOn() [2/2]

void SevenSegDisplays::turnOn ( const uint8_t & newBrghtnssLvl )

Turns the display module on.

The display module will be turned on, it's brightness level set to the requested level, it's content displayed, and will keep that status until a turnOff() is invoked.

Parameters

newBrghtnssLvl The new brightness level for the display. See setBrghtnssLvl(const uint8_t &) for details

◆ wait() [1/2]

bool SevenSegDisplays::wait ( )

Makes the display enter the "Waiting mode".

While in "Waiting mode" the display shows a simple animated progress bar or "process ongoing bar" until a noWait() method is invoked. The speed rate for the progress animation starts at a parameter passed rate when the method is invoked, or the last speed set will be used, having a preset value for the first time it's invoked if no parameter is passed. The animation rate can be changed by using the setWaitRate() method. The speed rate set will be kept after a noWait() or new wait() without parameters call is done, until it is modified with a new setWaitRate() call, or it is restarted by a wait() with a parameter. Note that to restart the waiting with a wait() the service must first be stopped, as the method makes no changes if the waiting service was already running.

Returns: true The display was not already set to wait (so now the "Waiting state" was started).; false The display was already set to wait, and/or the parameter passed was out of range.

Attention: The Waiting state is considered transitory state (or situation), as in most systems a "progression bar" is used it's main target is to show the system is not stalled or crashed, it's just waiting for a process to end. As a transitory state, the value displayed before entering the "Waiting state" will be saved, and will be restored automaticaly when the "Waiting state" is ended by the use of the noWait() method.

Code example

myLedDisp.wait(); //Returns true and shows advancement animation to the already set value.  
myLedDisp.wait(800); //Returns true and sets the advancement animation rate to 800 millisecs.  
myLedDisp.wait(getMaxBlinkRate() + 10);   //Returns false and the display stays without change.  

Here is the call graph for this function:

Here is the caller graph for this function:

◆ wait() [2/2]

bool SevenSegDisplays::wait ( const uint32_t & newWaitRate )

Makes the display enter the "Waiting mode" with a specific wait rate.

The method is similar to the wait() method, the only difference is that before entering the "Waiting state" a setWaitRate() is executed, using the provided argument to set the new wait rate.

Parameters

newWaitRate A new rate for the animated progress bar or "process ongoing bar".

Returns: true The display was not already set to wait (so now the "Waiting state" was started).; false The display was already set to wait, and/or the parameter passed was out of range.

Attention: The Waiting state is considered transitory state (or situation), as in most systems a "progression bar" is used it's main target is to show the system is not stalled or crashed, it's just waiting for a process to end. As a transitory state, the value displayed before entering the "Waiting state" will be saved, and will be restored automaticaly when the "Waiting state" is ended by the use of the noWait() method.

Here is the call graph for this function:

◆ write() [1/2]

bool SevenSegDisplays::write	(	const String &	character,
		const uint8_t &	port )

Prints one character to the display, at a designated position (digit or port), without affecting the rest of the characters displayed.

Parameters

character	A single character string that must be displayable, as defined in the print() method.
port	unsigned short integer value representing the position or digit where the character will be sent, being the range of valid values 0 <= port <= (dspDigits - 1), the 0 value is the rightmost digit, the 1 value the second from the right and so on.

Return values

true	character is a displayable one char string, and port value is in the range 0 <= value <= (dspDigits - 1).
false	character was not "displayable" or the port value was out of range.

Use example

myLedDisp.write("A", 1); // Modifies the displayed data, placing a 'A' in the second digit from right to left, returns true

myLedDisp.write("X", 1); // Fails as "X" is not a displayable character, returns false.

Here is the call graph for this function:

◆ write() [2/2]

bool SevenSegDisplays::write	(	const uint8_t &	segments,
		const uint8_t &	port )

Prints one character to the display, at a designated position (digit or port), without affecting the rest of the characters displayed.

Parameters

segments An unsigned short integer value representing which segments to turn on and which off to get the graphic representation of a character in the seven segment display, the corresponding value can be looked up in the _charLeds[] array definition in the header file of the library. In the case of a common cathode display the values there listed must be complemented. Any other uint8_t (char or unsigned short int is the same here) value is admissible, but the displayed result might not be easily recognized as a known ASCII character.

port unsigned short integer value representing the position or digit where the character will be sent, being the range of valid values 0 <= port <= (dspDigits - 1), the 0 value is the rightmost digit, the 1 value the second from the right and so on.

Return values

true	The parameters are within the acceptable range, in this case 0 <= port <= (dspDigits - 1).
false	The port value was outside the acceptable range.

Code example

myLedDisp.write(0xA4, 1); // Modifies the displayed data, placing a '2' in the second digit from right to left in a common anode display.

myLedDisp.write(0xB9, 0); // Modifies the displayed data, placing a non ASCII identifiable shape, with the central horizontal (g segment) and the two vertical rightside segments (b & c) lit, in the first digit from right to left in a common anode display.

Here is the caller graph for this function:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SevenSegDisplays()

Member Function Documentation

◆ begin()

◆ blink() [1/2]

◆ blink() [2/2]

◆ clear()

◆ doubleGauge()

◆ end()

◆ gauge() [1/2]

◆ gauge() [2/2]

◆ getCurBrghtnssLvl()

◆ getDigitsQty()

◆ getDspCount()

◆ getDspIsDmmbl()

◆ getDspUndrlHwPtr()

◆ getDspValMax()

◆ getDspValMin()

◆ getIsOn()

◆ getMaxBlinkRate()

◆ getMaxBrghtnssLvl()

◆ getMinBlinkRate()

◆ getMinBrghtnssLvl()

◆ getSerialNbr()

◆ isBlank()

◆ isBlinking()

◆ isWaiting()

◆ noBlink()

◆ noWait()

◆ print() [1/3]

◆ print() [2/3]

◆ print() [3/3]

◆ resetBlinkMask()

◆ setBlinkMask()

◆ setBlinkRate()

◆ setBrghtnssLvl()

◆ setWaitChar()

◆ setWaitRate()

◆ turnOff()

◆ turnOn() [1/2]

◆ turnOn() [2/2]

◆ wait() [1/2]

◆ wait() [2/2]

◆ write() [1/2]

◆ write() [2/2]