Patching the u8g2 ST7565 display driver for 'Mini 12864' panels
Some hardware problems are not solved by writing code but by correcting someone else's. esp8266-ST7565-u8g2LibFix is a two-value patch to the popular u8g2 graphics library that makes "Mini 12864" LCD panels display correctly instead of shifted or garbled.
The bug, and how it shows
u8g2's ST7565 driver (u8x8_d_st7565_64128n) supports two board variants through
a compile-time flag: "New Big Blue 12864" and "Mini". The Mini variant's baked-in values — the
display start-line command (0x040) and the default X offset (4) — do
not match at least one common Mini panel in the wild. The symptom is an image offset by a few
pixels or rolled vertically: text works, but the bottom row is missing and the top shows
garbage.
The fix
| What | Stock u8g2 | Patch |
|---|---|---|
| display start line command | 0x040 | 0x060 |
default_x_offset | 4 | 3 |
That is the entire change — but finding it meant reading the ST7565 datasheet's initialisation sequence and experimenting byte by byte until the panel aligned.
How to apply it
- Locate
Documents/Arduino/libraries/U8g2/src/clib/u8x8_d_st7565.c. - Replace it with the file from the repository.
- Construct your display with the 64128N constructor without defining
BIGBLUE12864, so the Mini path (with the fix) is used. Big Blue owners: uncomment the define and you get stock behaviour back. - Re-apply after every u8g2 library update — updates overwrite the file.
The lesson for beginners: upstream libraries are not sacred. A local patch, documented in a repository of its own, is a perfectly respectable way to keep your hardware working — as long as you record exactly what changed and why.