Parola for Arduino  1.0
Text effects for Parola modular hardware
 All Classes Functions Enumerations Enumerator Pages
Parola Software

The Parola Library

The Parola library is implemented using the MD_MAX72xx library for hardware control. The library implements functions to simplify the implementation of text special effects on the LED matrix.

  • Text left, right or center justification in the display
  • Text scrolling, appearance and disappearance effects
  • Control display parameters and animation speed
  • Support for hardware SPI interface

External Dependencies

  • Parola uses the MD_MAX72xx library for hardware level control primitives. The latest copy of this library can be found here.

Implementing New Text Effects

Each of the selected text effects is implemented as a function. This makes it easy to add new effects:

  • Choose a name for the effect and add it to the textEffect_t enumerated type.
  • Clone an existing method and modify it according to the guidelines below.
  • Add the function prototype for the new effect to the class definition (at the bottom of the MD_Parola.h file).
  • Modify the displayAnimate() method in MD_Parola.cpp to invoke the new method.

New Text Effects

The effects functions are implemented as finite state machines that are called with the frequency set by the setSpeed() method. The class variable _fsmState holds the state from the last invocation of an effect method.

An effect method can work in one of 2 ways:

  • Additive: where the animation frames are incrementally built up to the initial display. With this method, the function will need to use the getFirstChar() and getNextChar() methods to build up the displayed text, column by column.
  • Subtractive: where the final displayed text is placed in the buffer using the commonPrint() method and the elements that are not visible at that stage of the animation are removed.

Which algorithm is used depends on the type animation and what is convenient for the coder. Examples of both are found in the supplied library text effects.

Each effect method is implemented in 2 parts. One part implements the text move IN to the display (method parameter bIn is true) and the other when the text is moving OUT of the display (bIn false). Because the IN and OUT effects can be different for a display cycle, the method must not assume that the first part was ever called. The first phase should always end with the text in its display position (depending on the alignment specified) and the second phase should assume the text is in that position when called. Text position parameters are held in the class variables _limitLeft and _limitRight found in the library header file.

The first phase starts with _fsmState set to INITIALISE and ends when the state is set to PAUSE within the effect method. The second phase starts with a PAUSE state and ends when the state is set to END by the method. Aside from the INITIALISE state (set by the displayReset() method), all other state changes are under the control of the effect functions. Delays between frames and the pause between IN and OUT are handled outside of the effect method.

Coding Tips

  • The MD_MAX72XX library sets the origin for the LED matrix at the top right of the display. This makes the leftmost text column a higher column number that the far right column. Sometimes this is not intuitive when coding and is worth remembering. Rows are numbered from top to bottom, 0-7.
  • Ensure that a new effect is tested in combination with other effects to make sure that transitions are smooth and the IN and OUT effects combine well. Common errors are misaligned entry compared to exit, with causes a small jump in the text position when the effects are combined.
  • Display update times grow proportionally to the number of modules in a display, so some timing parameters may need to adapt. Hardware SPI runs approximately 10 times faster and the delay increase is not appreciable with up to 12 modules in length. For the aribtrary pinouts, using shiftout(), a 6 module chain updates in approximately 14ms on an Uno, while a 12 module display takes around 25ms. Most of the time taken is to physically update the display, as animating frames takes about 1-2ms to update in the MD_MAX72XX display buffers.