AceSegment  0.7.0
A framework for rendering seven segment LED displays using the TM1637, MAX7219, HT16K33, or 74HC595 controller chips
Public Member Functions | Friends | List of all members
ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI > Class Template Reference

An implementation of LedModule for display modules which do not have hardware controller chips, so they require the microcontroller to perform the multiplexed scanning across the digits. More...

#include <ScanningModule.h>

Inheritance diagram for ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >:
Inheritance graph
[legend]
Collaboration diagram for ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >:
Collaboration graph
[legend]

Public Member Functions

 ScanningModule (const T_LM &ledMatrix, uint8_t framesPerSecond)
 Constructor. More...
 
void begin ()
 Configure the driver with the parameters given by in the constructor. More...
 
void end ()
 A no-op end() function for consistency with other classes.
 
uint8_t getNumDigits () const
 Get the number of digits.
 
void setPatternAt (uint8_t pos, uint8_t pattern) override
 Set the led digit pattern at position pos.
 
uint8_t getPatternAt (uint8_t pos) override
 Get the led digit pattern at position pos.
 
void setBrightness (uint8_t brightness) override
 
void setBrightnessAt (uint8_t pos, uint8_t brightness)
 Set the brightness for a given pos, leaving pattern unchanged. More...
 
uint16_t getFramesPerSecond () const
 Return the requested frames per second.
 
uint16_t getFieldsPerSecond () const
 Return the fields per second.
 
uint16_t getFieldsPerFrame () const
 Total fields per frame across all digits.
 
uint16_t getMicrosPerField () const
 Return micros per field. More...
 
bool renderFieldWhenReady ()
 Display one field of a frame when the time is right. More...
 
void renderFieldNow ()
 Render the current field immediately. More...
 
- Public Member Functions inherited from ace_segment::LedModule
 LedModule (uint8_t numDigits)
 Constructor. More...
 
uint8_t getNumDigits () const
 Return the number of digits supported by this display instance. More...
 

Friends

class ::ScanningModuleTest_displayCurrentField
 

Detailed Description

template<typename T_LM, uint8_t T_DIGITS, uint8_t T_SUBFIELDS = 1, typename T_CI = ClockInterface>
class ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >

An implementation of LedModule for display modules which do not have hardware controller chips, so they require the microcontroller to perform the multiplexed scanning across the digits.

The matrix wiring of the segment and digit pins allow only a single digit to be turned on at any given time, so multiplexing across all the digits quickly (e.g. 60 Hz) gives the appearance of activating all the digits at the same time. For LED modules with a hardware controller (e.g. TM1637), the controller chip performs the multiplexing. Note that a 74HC595 Shift Register chip does not perform the multiplexing, it only provides a conversion from serial to parallel output.

This class depends on one of the implementations of the LedMatrixBase class to multiplex the LED segments on the digits, and potentially one of the of SoftSpiInterface or HardSpiInterface classes if a 74HC595 shift register chip is used.

A frame is divided into fields. A field is a partial rendering of a frame. Normally, the one digit corresponds to one field. However if brightness control is enabled by setting T_SUBFIELDS > 1, then a single digit will be rendered for T_SUBFIELDS number of times so that the brightness of the digit will be controlled by PWM.

There are 2 ways to get the expected number of frames per second:

1) Call the renderFieldNow() in an ISR, or 2) Call renderFieldWhenReady() polling method repeatedly from the global loop(), and an internal timing parameter will trigger a renderFieldNow() at the appropriate time.

Template Parameters
T_LMthe LedMatrixBase class that provides access to LED segments (elements) organized by digit (group)
T_DIGITSnumber of LED digits
T_SUBFIELDSnumber of subfields for each digit to get brightness control using PWM. The default is 1, but can be set to greater than 1 to get brightness control.
T_CIclass that provides access to Arduino clock functions (millis() and micros()). The default is ClockInterface.

Definition at line 80 of file ScanningModule.h.

Constructor & Destructor Documentation

◆ ScanningModule()

template<typename T_LM , uint8_t T_DIGITS, uint8_t T_SUBFIELDS = 1, typename T_CI = ClockInterface>
ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >::ScanningModule ( const T_LM &  ledMatrix,
uint8_t  framesPerSecond 
)
inlineexplicit

Constructor.

Parameters
ledMatrixinstance of LedMatrixBase that understanding the wiring
framesPerSecondthe rate at which all digits of the LED display will be refreshed
numDigitsnumber of digits in the LED display
patternsarray of segment pattern per digit, not nullable
brightnessesarray of brightness for each digit (default: nullptr)

Definition at line 93 of file ScanningModule.h.

Member Function Documentation

◆ begin()

template<typename T_LM , uint8_t T_DIGITS, uint8_t T_SUBFIELDS = 1, typename T_CI = ClockInterface>
void ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >::begin ( )
inline

Configure the driver with the parameters given by in the constructor.

Normally, this should be called only once after construction. Unit tests will sometimes change a parameter of FakeDriver and call this a second time.

Definition at line 108 of file ScanningModule.h.

◆ getMicrosPerField()

template<typename T_LM , uint8_t T_DIGITS, uint8_t T_SUBFIELDS = 1, typename T_CI = ClockInterface>
uint16_t ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >::getMicrosPerField ( ) const
inline

Return micros per field.

This is how often renderFieldNow() must be called from a timer interrupt.

Definition at line 210 of file ScanningModule.h.

◆ renderFieldNow()

template<typename T_LM , uint8_t T_DIGITS, uint8_t T_SUBFIELDS = 1, typename T_CI = ClockInterface>
void ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >::renderFieldNow ( )
inline

Render the current field immediately.

If modulation is off (i.e. T_SUBFIELDS == 1), then the field corresponds to the single digit. If modulation is enabled (T_SUBFIELDS > 1), then each digit is PWM modulated over T_SUBFIELDS number of renderings.

This method is intended to be called directly from a timer interrupt handler.

Definition at line 241 of file ScanningModule.h.

◆ renderFieldWhenReady()

template<typename T_LM , uint8_t T_DIGITS, uint8_t T_SUBFIELDS = 1, typename T_CI = ClockInterface>
bool ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >::renderFieldWhenReady ( )
inline

Display one field of a frame when the time is right.

This is a polling method, so call this slightly more frequently than getFieldsPerSecond() per second.

Returns
Returns true if renderFieldNow() was called and the field was rendered.

Definition at line 220 of file ScanningModule.h.

◆ setBrightness()

template<typename T_LM , uint8_t T_DIGITS, uint8_t T_SUBFIELDS = 1, typename T_CI = ClockInterface>
void ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >::setBrightness ( uint8_t  brightness)
inlineoverridevirtual

See the documentation for setBrightnessAt() for information about the range of values of brightness and how it is interpreted.

Implements ace_segment::LedModule.

Definition at line 151 of file ScanningModule.h.

◆ setBrightnessAt()

template<typename T_LM , uint8_t T_DIGITS, uint8_t T_SUBFIELDS = 1, typename T_CI = ClockInterface>
void ace_segment::ScanningModule< T_LM, T_DIGITS, T_SUBFIELDS, T_CI >::setBrightnessAt ( uint8_t  pos,
uint8_t  brightness 
)
inline

Set the brightness for a given pos, leaving pattern unchanged.

Not all implementation of LedClass can support brightness for each digit, so this is implemented at the ScanningModule class.

The maximum brightness should is exactly T_SUBFIELDS which turns on the LED 100% of the time. The minimum brightness is 0, which turns OFF the digit. For example, if T_SUBFIELDS==16, the the maximum brightness is 16 which turns ON the digit 100% of the time. The relative brightness of each brightness level is in units of 1/T_SUBFIELDS.

The brightness scale is not normalized to [0,255]. A previous version of this class tried to do that, but I found that this introduced discretization errors which made it difficult to control the brightness at intermediate values. For example, suppose T_SUBFIELDS=16. If we changed the normalized brightness value from 32 to 40, it was impossible to determine without actually running the program if the 2 values actually differed in brightness. Instead, the calling program is expected to keep track of the value of T_SUBFIELDS, and create an array of brightness values in these raw units. The side benefit of using raw brightness values is that it makes displayCurrentFieldModulated() easier to implement.

Definition at line 185 of file ScanningModule.h.


The documentation for this class was generated from the following file: