SmoothProgress

Library for displaying smooth progress bars on the character based LCD displays for Arduino

SmoothProgress is a library for displaying horizontal or vertical progress bars on a character based LCDs like Hitachi HD44780 16x2 or 20x4. Relies on the underlaying LiquidCrystal, LiquidCrystal_I2C library (and should work on any platform that supports this library or similar). The length and the position of the progress bar can be configured.

The library utilizes the user definable characters of the character LCD display and can display up to 4 independent horizontal or vertical smooth progress bars simultaneously. The progress bars can be drawn using different visual styles (distributed with the library as separate .h files or the user can define its own style). The styles are defined by bit-masks and additional data in the struct barstyle (49 bytes) that can be stored in SRAM or in flash (PROGMEM). The library also supports progress bars on multiple connected LCD displays - each display with possibly different progress bar style, 4 progress bars per display.

Connections

All interfacing to the lcd is handled by the built in Arduino LiquidCrystal, LiquidCrystal_I2C, hd44780 or simmilar library, meaning that the SmoothProgress library has no extra requirements on top of the mentioned libraries for how the display is connected. SmoothProgress should work with almost any library for the character LCD displays based on the Hitachi HD44780 or compatible controllers that implements write(uint8_t), setCursor(uint8_t, uint8_t) and createChar(uint8_t, uint8_t[]) methods. Just include SmoothProgress.h after including the LiquidCrystal library.

Getting started

Installing the library

Search for SmoothProgress in the libraries manager or copy this folder into the Arduino library folder. You may want to restart the Arduino IDE if you are using it to get syntax highlighting to update.

Including in your sketch

Add these lines to the top of your sketch: First include the LiquidCrystal library <LiquidCrystal.h> or <LiquidCrystal_I2C.h> (dependig on how your LCD is connected).

// Libraries to include
//#include <LiquidCrystal_I2C.h> 
#include <LiquidCrystal.h>

After that include the SmoothProgress library

#include <SmoothProgress.h>

Progress bar styles

SmoothProgress library supports displaying the progress bars using different visual styles. Several styles are supplied with the library as separate .h files. In order to display the smooth progress bar an appropriate style must be defined for the progress bar. The library is accompanied with a collection of several different progress bar styles - just include the appropriate header file <BarStyleXX.h> and configure the BarDisplay object. The bitmasks can be stored in memory or in flash (PROGMEM) to save space. The heared file(s) with the definition of the style(s) to be used with the progress bars should be included next. For examle to use a style for horizontal progress bar as a square frame with 1 pixel margin BarStyle1.h should be included

#include <BarStyle1.h>

LCD display object

Next define the object for the LCD display as usual (or as recommended for the used liquid crystal library depending on how it is connected) For example:

const int rs = 12, en = 11, d4 = 5, d5 = 4, d6 = 3, d7 = 2;
LiquidCrystal lcd(rs, en, d4, d5, d6, d7);

LiquidCrystal_I2C lcd(0x27, 16, 2);

if you use a LCD display with an I2C extender board.

LCD display object to progress bar style association

The library supports multiple progress bars (up to 4) on a single display. The smooth progress bars are "drawn" using the user definable characters that are appropriately programmed with appropriate image to be used in showing the progress. Since these displays have only 8 user definable characters, only 4 progress bars can be supported at a time.

Each progress bar is "drawn" by printing (in general) 5 different user defined characters:

one on the left edge
one in the middle that is completely full (left of the growing edge)
the character representing the growing edge that is partially filled
one in the middle that is completely blank (right of the growing edge)
one on the right edge
Except for the character representing the growing edge, the other 4 are common for all progress bars on the display. 4 common + 4 growing edges (one for each progress bar) = 4 independent progress bars at once. The hardware limitation of the character LCD displays dictates that all progress bars on a single display have to share the same style, so the progress bar style is linked to a single LCD display regardless of the number of progress bars (1-4) to be shown.

Next we have to create an association between the LiquidCrystal display and the progress bar style as a separate BarDisplay (LCD) object (dispA in the examle) to be used when creating the objects representing the smooth progress bars and manipulating their style

LCD dispA(lcd, barStyle1);

Creating the Smooth progress bar objects

SmoothProgressBar spb1(dispA, 10, 0, 0, 0); // progress bar 10 characters wide, at 0-th row, 0-th column, as progress bar 0
SmoothProgressBar spb2(dispA, 12, 0, 1, 1); // progress bar 12 characters wide, at 1-th row, 0-th column, as progress bar 1

SmoothProgressBar SmootProgBarObj(DisplayAssociationObject, ProgressBarSize, PositionColumn, PositionRow, id_number)

In the setup() first initialize the LiquidCrystal object as usual when usin a LCD display, and then initialize the association (style to display) object by calling its begin() function

void setup()
{
    lcd.begin(16, 2); // do the usual lcd initialization for the used liquid crystal library
...
    // also initialize the bar_display object (loads the style)
    dispA.begin();
...
}

Showing the progress bar

You can show the progress bar calling showProgressPct() and specifying the percentage [0-100] to be filled

spb.showProgressPct(p);
...
spb.showProgress(i);

or you can use showProgress() method and specifying the absolute number of columns to be filled. The length in pixel columns of the progress bar can be found by calling the size() method.

"Screenshots"

Some examples using the library:

Examples

The exmaples in the Examples folder - you can see them live in the Wokwi simulator:

Known limitations:

at most 4 independent progress bars can be shown (restricted by the limitation of only 8 user definable characters on these displays)
all progress bars on the LCD share the same style (due to hardware limitations of only 8 user definable characters on these displays)
the progress bars are "drawn" by printing over all the characters defining the progress bar on every call of showProgress (can be slow on these displays)
will interfere if used together with other libraries using the user definable characters (like BigNumbers, LCDGraph and similar).

Gjorgjevikj / SmoothProgress