Seven Segments Displays Agnostic Library for ESP32 (Arduino) v3.2.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
SevenSegTM163X Class Referenceabstract

Abstract class that models Seven Segments LEDs static displays hardware using Titan Micro TM163X series chips as display controller component More...

`#include <SevenSegDispHw.h>`

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

## Public Member Functions
| SevenSegTM163X ()
| Default class constructor.
| SevenSegTM163X (uint8_t *ioPins, uint8_t dspDigits, bool commAnode, uint8_t dspDigitsQtyMax=0)
| Class constructor.
| ~SevenSegTM163X ()
| Class destructor.
bool | begin (uint32_t updtLps=0)
| Turns On the display to be ready to receive data.
bool | end ()
| Turns Off the display.
virtual uint8_t | getBrghtnssLvl ()
| Returns the current brightness level setting for the display module.
virtual void | ntfyUpdDsply ()
| See SevenSegDispHw::ntfyUpdDsply() for description.
virtual bool | setBrghtnssLvl (const uint8_t &newBrghtnssLvl)
| Sets the Brightness level of the display.
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.
Public Member Functions inherited from SevenSegStatic
Public Member Functions inherited from SevenSegDispHw
| 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 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 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.

## Protected Attributes
uint8_t * | _lclDspBuffPtr {nullptr}
| Pointer to an array of size equal to or less than display module component digits ports, will be equal to or less than display controller component maximum digits/ports. The need for a divided display buffer comes from the fact that some Seven Segment display hardware use controllers with larger digits management capabilities than the display module digits, and the exceeding digits are used for proprietary amenities, as colons, icons, etc.
Protected Attributes inherited from SevenSegDispHw
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

Abstract class that models Seven Segments LEDs static displays hardware using Titan Micro TM163X series chips as display controller component

As TM163X series chips have some differences among them, this class implements the base common characteristics, the differences are implemented in corresponding subclasses.

Common attributes include:

- Communications protocol (a non standard variation of the I2C protocol).
- Commands structure.
- Read/Write commands.
- Brightness commands, capabilities and values.
- Start and Stop commands.

Different attributes include:

- Maximum number of ports addressable.
- Keyscaning services

Note
  As the communications protocol doesn't completely comply with the I2C protocol, the communications must be implemented in software. For that reason, for resources saving sake, the CLK speed will be reduced from the data sheet Maximum clock frequency stated as 500KHz to a less demanding time slices, managed by `delayMicroseconds()` function keyword, (or a timer interrupt set at 100KHz for other implementations, enabling the timer interrupt service only while transmitting data, and disabling it while idle).

Warning
  While the TM1636, TM1637, TM1639 (at least these are our most known members of this "family" that includes other chips) are stable and well documented devices, the parts sold as "TM1637 Display Modules", "TM1638 Display Modules" etc, breakboards that include the TM163X display driver, supporting electronics and one or several 7 segments display modules are not all created equal. A well known example: having the TM1637 modules the ability to drive 6 display ports, some breakboards present 4 display ports and a center colon, as is standard to time displaying modules. The big issue is the lack of a standard for those display modules, not all displays have the same disposition, not all of them are internally wired the same, and that not all the manufacturers wire the TM1637 modules to the 7 segments display modules in the same way. For example, some will attach the colon to the DP (decimal point) segment of the third port (RtL), some will attach them to ALL the DP segment, some will attach each of the dots of the colon independently, one to the 5th display port, the other to the 6th display port, and then some other manufacturer in some other way.
  Whenever is possible to get a specific module for testing, a SevenSegTM163X subclass might be added to manage it correctly, please read the subclasses' description for correct display module oriented class identification.

## Constructor & Destructor Documentation

## ◆ SevenSegTM163X()

SevenSegTM163X::SevenSegTM163X | ( | uint8_t * | ioPins,
|  | uint8_t | dspDigits,
|  | bool | commAnode,
|  | uint8_t | dspDigitsQtyMax = 0 )

Class constructor.

Parameters

  ioPins | A pointer to an array holding the identifiers for the 2 GPIO pins required to send the data to the Seven Segment display hardware to be displayed. The correlation between the array positions and the pin function is given as in-class defined constants: 0->clk, 1->dio
  dspDigits | Quantity of digits/ports of the display module component. This parameter acceptable values are directly related to the TM163X family specific member.
  commAnode | Boolean indicating if the hardware uses a display module component wired as common anode (true) or common cathode (false).
  dspContMaxDigits | Maximum quantity of digits/ports the display controller component can handle, is a value that in this case depends on the TM163X family module member selected.

## Member Function Documentation

## ◆ begin()

bool SevenSegTM163X::begin | ( | uint32_t | updtLps = 0 | ) |
| virtual

Turns On the display to be ready to receive data.

Turning on a TM163X display implies sending a command to the display and saving in an object attribute the isOn state, as the display controller does not provide any means to read it's state.

Returns
  true Always

Note
  The class constructor invokes the begin() method as it's last statement, the begin() method is kept for ease of modifications to developers interested in modifying the class.

Reimplemented from SevenSegDispHw.

Here is the call graph for this function:

## ◆ end()

bool SevenSegTM163X::end | ( |  | ) |
| virtual

Turns Off the display.

Returns
  true Always

Reimplemented from SevenSegDispHw.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ getBrghtnssLvl()

uint8_t SevenSegTM163X::getBrghtnssLvl | ( |  | ) |
| virtual

Returns the current brightness level setting for the display module.

The TM163X series display drivers have the capability of changing the led display brightness level by using PWM on it's output pins. The resulting brightness levels are not perceived as linear, and the minimum and maximum brightness values don't reach the levels of totally turning the display off, neither turning the display to it's maximum possible brightness.

Note
  The SevenSegTM163X abstract class is instrumented so that any subclass must incorporate the minimum and maximum values for that specific display subclass. All the members of the TM163X family currently checked at this point share the minimum and the maximum brightness values: 0 for the minimum, 7 for the maximum, resulting in 8 brightness levels. But this is not taken for granted. See setBrghtnssLvl(const uint8_t &) for more details.

Returns
  The current brightness level setting.

Reimplemented from SevenSegDispHw.

## ◆ setBrghtnssLvl()

bool SevenSegTM163X::setBrghtnssLvl | ( | const uint8_t & | newBrghtnssLvl | ) |
| virtual

Sets the Brightness level of the display.

Parameters

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

Returns
  true The parameter was in the acceptable 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)
  false The parameter was outside the acceptable range, no brightness level changes will be done.

Reimplemented from SevenSegDispHw.

Here is the caller graph for this function:

## ◆ turnOff()

void SevenSegTM163X::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.

Reimplemented from SevenSegDispHw.

Here is the caller graph for this function:

## ◆ turnOn() [1/2]

void SevenSegTM163X::turnOn | ( |  | ) |
| virtual

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.

Reimplemented from SevenSegDispHw.

Here is the caller graph for this function:

## ◆ turnOn() [2/2]

void SevenSegTM163X::turnOn | ( | const uint8_t & | newBrghtnssLvl | ) |
| virtual

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. The value must be in the range getBrghtnssMinLvl() <= newBrghtnssLvl <= getBrghtnssMaxLvl()

Reimplemented from SevenSegDispHw.

Here is the call graph for this function: