Seven Segments Displays Agnostic Library for ESP32 (Arduino) v3.1.0 A library that provides a class that models a Seven Segment Display and provides an unified API through it's members independently of the display technology.

Loading...
Searching...
No Matches
Public Member Functions | Protected Attributes | List of all members
SevenSegDispHw Class Referenceabstract

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

`#include <sevenSegDispHw.h>`

Inheritance diagram for SevenSegDispHw:
[legend]
Collaboration diagram for SevenSegDispHw:
[legend]

## Public Member Functions
| SevenSegDispHw ()
| Default class constructor.
| SevenSegDispHw (uint8_t *ioPins, uint8_t dspDigits=4, bool commAnode=true)
| 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.
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.
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.

## 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 )

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).

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, SevenSegMax7219, 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, 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.

## ◆ 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)

Here is the caller graph for this function:

## ◆ 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.

## ◆ 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 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 SevenSegMax7219, and SevenSegTM163X.

Here is the caller graph for this function:

## ◆ setDigitsOrder()

bool SevenSegDispHw::setDigitsOrder | ( | uint8_t * | newOrderPtr | ) |

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!!

Here is the caller graph for this function:

## ◆ 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.

Todo
  For the seven segment displays without controller components to implement On and Off commands, the class will provide a propietary solution to achieve similar features. While there are not implemented the turnOff(), turnOn() and turnOn(const uint8_t &) will be ignored and will produce no effect in the object behavior.

Reimplemented in SevenSegDynDummy, 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, 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 SevenSegMax7219, and SevenSegTM163X.

Here is the call graph for this function: