U8glib: the picture loop older OLED tutorials use
U8glib is the library U8g2 replaced. Its author stopped developing it years ago, but a great many OLED and 12864 LCD projects from before 2017 are written for it, and they still turn up first in searches. If you have one of those sketches, this page is about making it run; for anything new, U8g2 does the same job with more displays and more ways to draw.
Built in on Mokxi: #include <U8glib.h> and it builds, with nothing to install. Free, and no account needed.
What U8glib does
Its one idea is the picture loop. U8glib never keeps the whole screen in memory. Instead the sketch puts its drawing in a function and calls it inside firstPage() and nextPage(), which run the function once for each horizontal band of the screen and send each band as it is done. That is how it fit a 128x64 display on an Uno with RAM to spare.
Because the drawing code runs several times per frame, anything it does besides drawing (reading a sensor, counting, printing to Serial) also runs several times. Read your values before firstPage() and only draw inside the loop.
| Library Manager name | U8glib |
|---|---|
| Author | Oliver Kraus |
| Include | #include <U8glib.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Runs, with a gap the note below names. |
| Parts it drives | OLED display, 128x64, OLED display, 128x32, OLED display, 1.3 inch SH1106, Nokia 5110 display, PCD8544 |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <U8glib.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "U8glib" by Oliver Kraus from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add U8glib to lib_deps in PlatformIO. Mokxi follows the calls of release 1.19.1, so a sketch written here builds there too.
What to know in the simulator: Every u8g_font_* draws Mokxi鈥檚 5x8 at the nearest size. The SPI OLED constructors and the ST7920 build and say so at begin(). The built-in chess engine (the Chess example), custom device drivers and the u8g C structure's internals are not here.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
U8GLIB_SSD1306_128X64 u8g(U8G_I2C_OPT_NONE)
A 128x64 SSD1306 OLED on hardware I2C. U8GLIB_SH1106_128X64 is the 1.3 inch module鈥檚 version.
u8g.firstPage()
Begins a new frame. Follow it with a do-while loop that ends on nextPage().
u8g.firstPage();
do {
draw();
} while (u8g.nextPage());u8g.nextPage()
Sends the band just drawn and returns nonzero while there are more bands to draw.
u8g.setFont(u8g_font_unifont)
Selects one of U8glib鈥檚 fonts (u8g_font_6x10, u8g_font_helvB10 and many more) for the drawing calls that follow.
u8g.drawStr(0, 22, "Hello World!")
Draws text with its baseline at y. For numbers, set the position with setPrintPos() and use print().
u8g.setPrintPos(0, 40);
u8g.print(temperature, 1);u8g.drawBox(x, y, w, h)
A filled rectangle in the current color; drawFrame() outlines one and drawCircle() draws a circle.
u8g.getStrWidth("Hello")
The width of a string in the current font, in pixels, for centering or right-aligning text.
Example: Hello World with the U8glib picture loop
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include "U8glib.h"
U8GLIB_SSD1306_128X64 u8g(U8G_I2C_OPT_NONE);
void draw(void) {
u8g.setFont(u8g_font_unifont);
u8g.drawStr(0, 22, "Hello World!");
u8g.drawFrame(0, 30, 128, 20);
u8g.drawBox(4, 34, 40, 12);
}
void setup(void) {
Serial.begin(9600);
if (u8g.getMode() == U8G_MODE_BW) u8g.setColorIndex(1);
Serial.println("U8glib ready");
}
void loop(void) {
u8g.firstPage();
do {
draw();
} while (u8g.nextPage());
delay(500);
}Wiring
- Arduino Uno R3 A4 to OLED display, 128x64 SDA
- Arduino Uno R3 A5 to OLED display, 128x64 SCL
- Arduino Uno R3 5V to OLED display, 128x64 VCC
- Arduino Uno R3 GND to OLED display, 128x64 GND
Common errors and how to fix them
The screen stays blank although the sketch compiles
Drawing calls outside the firstPage() and nextPage() loop are thrown away. Move every draw call into the function the loop runs.
A counter jumps by eight on every frame
The counting happens inside the picture loop, which runs once per band. Update values before firstPage() and keep the loop to drawing only.
U8glib will not compile for an ESP32 or other newer board
Upstream U8glib was written for AVR and ARM boards of its time and is no longer updated. Port the sketch to U8g2: the drawing calls keep the same names and the page loop works the same way.
Keep going
Parts
More displays libraries
Try U8glib without installing anything
Open the example, change the sketch, and keep your version in a free account.