arduino-lcdHelper-library

This Arduino library aims to make your life easier when using LCD (HD44780) displays and improves support for UTF-8 chars (like ä, ö, ü, ß etc.).

It inherits all functions from your LCD library and provides additional functions, especially with UTF-8 fixes, like clearLine(), centerPrint() or movingPrint().
All functions are documented below.

 

The library is made for LiquidCrystal_I2C but was mainly developed using a fork called NoiascaLiquidCrystal to support German UTF-8 chars.

The library only supports C char arrays, no Arduino or C++ Strings, to be more efficient on these low memory devices.
You can still pass Strings to functions provided by LiquidCrystal as they are inherited.

 

Usage

Simply clone this repository, add the folder to your project (for example into a lib folder), include the library in your code (#include <lcdHelper.h>) and include it when compiling (depends on what dev env you are using, see below for a PIO example).

Init the library by calling lcdHelper<LiquidCrystal_I2C> lcd(addr, cols, rows) (replace LiquidCrystal_I2C with the lcd lib you are using).
Remove any initialization of LiquidCrystal_I2C itself if you have one. lcdHelper does this for you.
You can now access all LiquidCrystal and lcdHelper functions from lcd.

 

Example when using PlatformIO:
Download, extract and then put the arduino-lcdHelper-library folder into the lib folder of your project, which was generated by PlatformIO.
Include the library in your main code file by adding #include <lcdHelper.h>.
PlatformIO will automatically compile included libraries that are in the lib folder.
You can now initialize the lib just like shown above by calling the lcdHelper constructor with the address, columns and rows of your display.

 

Functions added by lcdHelper

Check out the example sketch showcasing every function here!
I included an example PIO config and a copy of LiquidCrystal_I2C in the examples/lib folder so you can quickly compile & upload the example inside an PIO environment to try it out.

 

lcdHelper<YOUR_LCD_LIBRARY> objectName(uint8_t addr, uint8_t cols, uint8_t rows)

• addr - Address of your display, usually 0x27 I think
• cols - The amount of columns your display has. When you have a 4x20 display for example, provide 20 here
• rows - The amount of rows your display has. When you have a 4x20 display for example, provide 4 here

Constructor which creates a lcdHelper and YOUR_LCD_LIBRARY object and inherits all functions from YOUR_LCD_LIBRARY.

Example:

#include <lcdHelper.h>

lcdHelper<LiquidCrystal_I2C> lcd(0x27, 20, 4);

void clearLine(uint8_t row)

• row - The row to clear (counted from 0)

Clears a specific line on your display.

void centerPrint(const char *str, uint8_t row, bool callClearLine = false)

• str - The char array to print
• row - The row to print the char array in
• callClearLine - Optional: Set to true if line should be cleared before printing

Print a char array centered in a row on your display.

void movingPrint(const char *str, uint8_t *moveOffset, uint8_t width)

• str - The char array to print
• moveOffset - Pointer to int tracking offset
• width - Width of the space on screen the char array will be moved across

Prints a char array that will be moved across a row by one char each time the function is called.

Example:

uint8_t moveOffset = 0; // Define a var tracking the current offset somewhere at the top scope

// Call movingPrint() each time you want to move your char array, for example in your arduino loop
void loop()
{
    // Message shall appear on row 2
    lcd.setCursor(0, 1);

    // Pass char array, pointer to moveOffset and the width to move across
    lcd.movingPrint("This is a test message which will move across the screen", *moveOffset, 20);

    // Example delay so you can actually read what is happening on your display
    delay(250);
}

void animationPrint(const char **animationArray, uint8_t animationSize, uint8_t *animationFrame, uint8_t col, uint8_t row)

• animationArray - Pointer to an array containing char arrays for each animation frame
• animationSize - Amount of frames your animation has, counting from 1
• animationFrame - Pointer to int tracking animation progress
• col - The column to print the animation at
• row - The row to print the animation in

Print an animation frame by frame each time the function is called.
I provided a few default animations (loading, waiting, bounce, progress, arrows, bouncearrow), accessible like so:

uint8_t animationFrame = 0; // Define a var tracking the current frame somewhere at the top scope

void loop()
{
    // Print loading animation in row 2 at column 10
    lcd.animationPrint(lcd.animations.loading, 8, &animationFrame, 10, 1);

    // Example delay
    delay(250);
}

The size of each default animation is written as a comment behind each definition, your IntelliSense should display it for you.
Feel free to check out lcdHelper.h to take a look at all default animations which are defined in a struct.

void alignedPrint(const char *align, const char *str, uint8_t width)

• align - "left", "center" or "right"
• str - The char array to print
• width - The fixed width of the resulting char array, which str will be aligned to

Print a char array aligned left, center or right to a fixed width.

void limitedPrint(const char *str, uint8_t length)

• str - The char array to print
• length - The length to limit str to

Prints a char array to the display with a limited length (UTF-8 aware) without making a copy.

size_t utf8_strlen(const char *str)

• str - The char array to get the length of

Returns the length of str.
Custom strlen function to correctly count chars that are two bytes long (like ä ö or ü).

char* toFixedLengthNumber(char *dest, int num, uint8_t len)

• dest - Pointer to destination char array
• num - The number to convert
• len - The length the resulting char array will have. Zeroes will be added infront of num until it matches this length

Returns pointer to dest so that you can use it directly inside another function.
Converts num to char array and precedes it with zeroes to match length.
Make sure buf is at least len bytes long!

Example, showing uptime in minutes, with values <10 having a preceding 0:

unsigned long uptime = millis() / 1000; // Current uptime in seconds
char temp[3] = ""; // Buffer char array

// Uptime in minutes, 5 will be written as 05 into temp to match len 2
lcd.toFixedLengthNumber(temp, (uptime % 3600) / 60, 2);
lcd.print(temp); // Print "05" to display

// ...or make use of return to print directly
lcd.print(lcd.toFixedLengthNumber(temp, (uptime % 3600) / 60, 2));