LionFastLcd

Change-tracked, buffered character-LCD layer on top of marcoschwartz/LiquidCrystal_I2C.

FastLcd keeps a RAM shadow of the whole display and, on every write, pushes only the cells that actually changed to the controller. Consecutive changed cells are coalesced into a single setCursor() followed by back-to-back write()s, which roughly halves the I²C traffic of naive per-character drawing. It implements Arduino Print, so print() / println() and everything built on them work as usual.

It also supports stacked / overlay screens: Clone() a display, draw into it off-screen, then Activate() it to bring it to the front and Deactivate() to pop back to what was underneath (a z-order is maintained for you).

• Platforms: ESP8266 + AVR (Arduino framework). On ESP32 use Esp32FastLcd.
• License: 0BSD.

Install

lib_deps =
    leva/LionFastLcd
    ; pulled in automatically as dependencies:
    ; marcoschwartz/LiquidCrystal_I2C @ ^1.1.4
    ; leva/LionArray

Important contract / limitations

• Non-copyable. FastLcd holds a LiquidCrystal_I2C& and owns a raw shadow buffer; the copy constructor and assignment are = deleted. Pass it around by pointer (that is what CreateMain() / Clone() hand you).
• Create only through the factories. The constructor is protected. Call FastLcd::CreateMain(lcd, cols, rows) once before any Clone(), Activate() or Deactivate(). Displays register themselves in an internal static list and are meant to live for the lifetime of the program — do not delete one while it is still referenced by the z-order.
• Shadow buffer is cols * rows bytes.
• Verbose tracing is opt-in: build with -DDETAILED_FLCD_LOG to get serial logs of create/refresh/activate. Off by default (no serial spam).

Optional: scrolling long messages (ESP8266 only)

Lines longer than the display width can be auto-scrolled by a background leva/LionTask. This is off by default because it uses String and only makes sense where there is spare RAM. To enable:

build_flags = -DFLCD_LONG_MESSAGES
lib_deps =
    leva/LionFastLcd
    leva/LionTask          ; required only when FLCD_LONG_MESSAGES is set

Then ShowLongMessage(row, text) scrolls automatically; pump LionTask::Loop() from your loop(). Not available on AVR.

Usage

#include <FastLcd.h>
#include <LiquidCrystal_I2C.h>

LiquidCrystal_I2C lcd(0x27, 20, 4);
FastLcd *display;

void setup() {
    lcd.init();
    lcd.backlight();
    display = FastLcd::CreateMain(lcd, 20, 4);

    display->setCursor(0, 0);
    display->print(F("Hello, LionFastLcd!"));
}

void loop() {
    static uint32_t last = 0;
    if (millis() - last >= 1000) {
        last = millis();
        display->setCursor(0, 1);
        display->print(F("Uptime: "));
        display->print(millis() / 1000);
        display->print(F("s   "));   // only the digits that change are redrawn
    }
}

API (brief)

• static FastLcd *CreateMain(LiquidCrystal_I2C &lcd, int8_t cols, int8_t rows) — create the root display (call once).
• FastLcd *Clone() — create an inactive overlay of the same geometry.
• void Activate() / static void Deactivate() — push/pop the z-order and repaint.
• void setCursor(int8_t x, int8_t y) — move the logical cursor (clamped).
• Print interface — print(), println(), write(); printSeveral(c, n) repeats a character.
• void VScroll(int8_t n, int8_t x = 0, int8_t w = -1, const char *newData = NULL) — scroll a column band vertically by one row and feed in a new line.
• int8_t width() / int8_t height().
• void ShowLongMessage(int y, const char *msg, long timeout = 0) / void StopShowLongMessage() — only with -DFLCD_LONG_MESSAGES (ESP8266).

License

0BSD — see LICENSE.