U8g2: one library for almost every monochrome display
U8g2, by olikraus, supports hundreds of monochrome displays: SSD1306 and SH1106 OLEDs, the SSD1309, the 128x128 SH1107, the Nokia 5110 and many LCD controllers. Its strengths are a huge font collection and memory modes that let even an Uno drive a display it could not otherwise buffer.
Built in on Mokxi: #include <U8g2lib.h> and it builds, with nothing to install. Free, and no account needed.
What U8g2 does
The display is chosen by the constructor鈥檚 long name, and every part of it means something. U8G2_SSD1306_128X64_NONAME_F_HW_I2C is the SSD1306 controller, 128 by 64 pixels, the generic module, a full frame buffer (F) and hardware I2C. Swap F for 1 or 2 and you get a page buffer of 128 or 256 bytes; swap HW_I2C for SW_I2C and you choose the pins yourself.
In full buffer mode you clear the buffer, draw and call sendBuffer(). In page mode the drawing code runs once for every strip of the screen inside a firstPage() and nextPage() loop. U8g2 also includes U8x8, a text-only interface that needs no buffer at all.
| Library Manager name | U8g2 |
|---|---|
| Author | olikraus |
| Include | #include <U8g2lib.h>#include <U8x8lib.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, OLED display, 1.12 inch SH1107, Nokia 5110 display, PCD8544 |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <U8g2lib.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "U8g2" by olikraus from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add U8g2 to lib_deps in PlatformIO. Mokxi follows the calls of release 2.35.30, so a sketch written here builds there too.
What to know in the simulator: Every u8g2_font_* and u8x8_font_* name builds, but draws Mokxi鈥檚 5x8 characters at the nearest whole size, so icon and non-Latin glyphs are '?'. The OLED SPI constructors and controllers with no Mokxi part (ST7920 and the rest) build and say so at begin(). MUIU8g2.h and U8g2's C API 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.
U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE)
A 128x64 SSD1306 on the hardware I2C pins with a full 1 KB buffer and no reset pin. U8G2_R2 rotates it 180 degrees.
u8g2.begin()
Starts the bus and wakes the display. It does not clear the buffer for you.
u8g2.clearBuffer()
Clears the frame buffer in full buffer mode before drawing the next frame.
u8g2.setFont(u8g2_font_ncenB08_tr)
Chooses a font. The suffix says which characters it holds: _tr is the printable ASCII range, _tn numbers only, which saves flash.
u8g2.drawStr(0, 10, "Hello")
Draws a string with its baseline at y = 10. It takes text only; for numbers use setCursor() and print().
u8g2.setCursor(0, 30);
u8g2.print(analogRead(A0));u8g2.drawFrame(0, 0, 128, 64)
An outlined rectangle; drawBox() is the filled one, drawCircle() and drawDisc() the outlined and filled circles.
u8g2.sendBuffer()
Sends the full buffer to the display. Nothing appears in full buffer mode until this is called.
u8g2.firstPage()
Starts the page loop for the _1_ and _2_ constructors. All drawing goes inside the do-while, which runs once a page.
u8g2.firstPage();
do {
u8g2.drawStr(0, 24, "Hi");
} while (u8g2.nextPage());Example: Hello World on an OLED with U8g2
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <U8g2lib.h>
#include <Wire.h>
U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);
void setup() {
Serial.begin(9600);
u8g2.begin();
}
void loop() {
u8g2.clearBuffer();
u8g2.setFont(u8g2_font_ncenB08_tr);
u8g2.drawStr(0, 10, "Hello World!");
u8g2.drawFrame(0, 20, 60, 30);
u8g2.drawDisc(96, 40, 12);
u8g2.setCursor(0, 62);
u8g2.print(millis() / 1000);
u8g2.print(" s");
u8g2.sendBuffer();
Serial.println("frame sent");
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 shows noise or a picture shifted by two pixels
The constructor names the wrong controller. Most 1.3 inch modules are SH1106, so use U8G2_SH1106_128X64_NONAME_F_HW_I2C; the 0.96 inch ones are usually SSD1306.
Global variables use 95% of dynamic memory and the sketch misbehaves
The _F_ constructor reserves 1 KB on an Uno. Switch to the _1_ or _2_ page buffer version and move the drawing into a firstPage() and nextPage() loop.
drawStr() prints nothing for a number
drawStr() expects a C string. Use setCursor() with print(), which formats numbers like Serial, or build the text with snprintf() first.
Nothing is drawn although the code runs
In full buffer mode sendBuffer() is missing; in page mode the drawing calls sit outside the do-while loop. Either way nothing reaches the panel.
Questions and answers
Do the U8g2 fonts look the same on Mokxi?
Every u8g2_font name builds and sets a size, but Mokxi draws its own 5x8 characters scaled to the nearest whole size, not U8g2鈥檚 typefaces. Positions follow your sketch, so layout carries over to the real display.
Keep going
Parts
Try U8g2 without installing anything
Open the example, change the sketch, and keep your version in a free account.