I get this question every workshop week: "Should I install Adafruit SSD1306 or U8g2 for animations?" Both draw white pixels on the same 0.96" panel, and they don't differ there. Both can blink a logo, so that's not what separates them. The difference shows up when your Uno's out of SRAM, when the seller's shipped an SH1106 labeled as SSD1306, or when you want thirty tiny frames instead of three.
This is the comparison I wish I'd printed on the lab wall. It's biased toward animation work, not toward drawing a single "Hello" string. You'll get side-by-side blink sketches, migration notes, and a recommendation matrix for Uno vs ESP32.
The short answer
- Start with Adafruit SSD1306 + GFX if you're teaching beginners, following examples from Adafruit guides, or exporting from tools that target
drawBitmapand GFX primitives. - Prefer U8g2 when you need SH1106 support in one constructor name, tighter RAM options, a huge font selection, or page-buffer mode on a memory-starved AVR board.
- On ESP32 with plenty of RAM, either is fine. Pick the ecosystem your exporters and teammates already use, because that's where you'll get support.
I keep both libraries installed, and I'd suggest you do the same. Switching mid-project is a few hours of renaming calls. You won't have to rewrite your art, and that's the good news.
How they think about the screen
Adafruit SSD1306: full framebuffer by default
You allocate (or get) a 128×64 / 8 = 1024-byte RAM buffer. Every drawPixel, drawBitmap, and print edits that buffer. display.display() pushes the whole buffer over I2C/SPI. Think of it this way: you paint a canvas, then photograph it onto the glass.
It's an easy model to reason about for animation: clear → draw frame N → display → wait → next frame. But it also costs you a fixed 1 KB of precious Uno SRAM, whether your frame is busy or empty.
U8g2: constructor chooses the buffer strategy
U8g2 constructors encode the chip, resolution, bus, and buffer mode. These are the ones you'll meet most:
- Full buffer (
*fvariants), similar idea to Adafruit: large RAM, single send after drawing. - Page buffer / 1-page (
*1), only a strip of rows lives in RAM. You loop withfirstPage/nextPageand redraw the scene for each page. - 2-page (
*2), middle ground.
// examples — names vary by board/bus; check U8g2 examples
U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, /* reset=*/ U8X8_PIN_NONE);
// full buffer (~1 KB+ housekeeping)
U8G2_SSD1306_128X64_NONAME_1_HW_I2C u8g2(U8G2_R0, /* reset=*/ U8X8_PIN_NONE);
// page buffer — much less RAM, redraw per page
Page mode is why U8g2 fans love AVR, and it's a fair reason. Here's the trade-off. Any animation code that builds a complex scene has to be callable repeatedly inside the page loop, so your casual "draw once then display" habit doesn't map 1:1.
Drawing bitmaps: drawBitmap vs XBM helpers
Here's the Adafruit path that most animation tools emit, and it's the one you'll see most:
display.drawBitmap(0, 0, frame0, 128, 64, SSD1306_WHITE);
display.display();
Bytes are usually horizontal MSB packing, and that's what Adafruit / image2cpp style matches. U8g2 often wants XBM
bit order (vertical bits in classic XBM) or you use drawXBMP / drawBitmap
carefully with the right format flag. Here's a practical rule from my support emails: don't paste an Adafruit array into U8g2 and assume the image is upright. Re-export for the target library, or convert the packing once with a script you trust.
If you already generate frames in OLED Animation Maker, pick the Adafruit or U8g2 export explicitly so the bit order matches. That one choice saves you the classic "my logo is shredded spaghetti" afternoon.
Speed: what actually limits you
For 128×64 over hardware I2C, the bus and the full-buffer transfer dominate. It isn't your C++ circle math. Adafruit full buffer and U8g2 full buffer feel similar on Uno when both send ~1 KB each frame. You'll only notice a difference when:
- you redraw a huge scene inside every U8g2 page (CPU bound on AVR),
- you call Adafruit
display()every millisecond while you're also doing Serial prints, or - you run SPI OLEDs. Both libraries get faster transfers, so CPU drawing cost matters more.
In class I'd aim for 15-25 FPS for simple blinks. Above that, your eyes won't thank you on a tiny monochrome panel, and USB power noise plus long jumpers create mystery flicker that people blame on "the wrong library."
Flash and RAM: Uno vs ESP32
| Constraint | Adafruit SSD1306 (typical) | U8g2 (typical) |
|---|---|---|
| Uno RAM for frame buffer | ~1024 B full buffer (fixed) | ~1024 B full, or much less in page mode |
| Uno flash libraries + fonts | GFX + driver: moderate | Can grow fast if you pull large fonts |
| ESP32 RAM | Comfortable | Comfortable; still avoid shipping unused fonts |
| Two 128×64 panels on Uno | Often too tight | Page mode can save the project |
| PROGMEM animation frames | Same math for both, frames still cost 1 KB each full screen | Same |
Remember, choosing U8g2 does not shrink your PROGMEM art. A 12-frame 128×64 loop is still ~12 KB of flash either way. Your library choice mainly changes the live buffer and the driver feature set. If you want the frame-count math, see Uno OLED memory limits.
SH1106 and odd modules
Vendor modules mislabeled as SSD1306 but shipping SH1106 are everywhere. The symptom's an image that looks shifted by about two pixels or wraps weirdly. U8g2's strength here is a clear constructor for SH1106, so the driver maps columns correctly. If you're on Adafruit, you'll usually move to Adafruit_SH110X or hack an X offset.
If your kit is mixed (some SSD1306, some SH1106), U8g2 constructors per board spare you from shipping "magic +2" firmware variants. For the deeper hardware story, read SH1106 vs SSD1306.
Learning curve and community
- Adafruit: The beginner docs are excellent, there are CircuitPython cousins, and you'll find GFX tutorials everywhere. Function names map cleanly to what teachers already show on projectors.
- U8g2: Your first hour is steeper (the constructors look loud), then it's very powerful. The font list is unmatched. The page loop surprises you if you're coming from Adafruit.
For a first week Arduino course, I stay on Adafruit so students aren't debugging constructors while they learn I2C. For a product firmware pass on AVR, I often migrate the UI to U8g2 page mode to claw back RAM for sensors.
Side-by-side: simple 2-frame blink
It's the same idea each time, with two PROGMEM bitmaps named eyeOpen and eyeClosed (swap in your exported arrays). I time it with millis(), not delay().
Adafruit SSD1306 version
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
Adafruit_SSD1306 display(128, 64, &Wire, -1);
// placeholder — paste real PROGMEM arrays from your exporter
extern const unsigned char eyeOpen[];
extern const unsigned char eyeClosed[];
unsigned long lastSwap = 0;
bool lidClosed = false;
void setup() {
if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) for (;;);
display.clearDisplay();
display.display();
}
void loop() {
unsigned long now = millis();
if (now - lastSwap > (lidClosed ? 120UL : 900UL)) {
lastSwap = now;
lidClosed = !lidClosed;
display.clearDisplay();
display.drawBitmap(0, 0, lidClosed ? eyeClosed : eyeOpen, 128, 64, SSD1306_WHITE);
display.display();
}
}
U8g2 full-buffer version
#include <U8g2lib.h>
#include <Wire.h>
U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);
extern const unsigned char eyeOpen[];
extern const unsigned char eyeClosed[];
unsigned long lastSwap = 0;
bool lidClosed = false;
void setup() {
u8g2.begin();
}
void loop() {
unsigned long now = millis();
if (now - lastSwap > (lidClosed ? 120UL : 900UL)) {
lastSwap = now;
lidClosed = !lidClosed;
u8g2.clearBuffer();
// use the draw call that matches your export bit order
u8g2.drawXBMP(0, 0, 128, 64, lidClosed ? eyeClosed : eyeOpen);
u8g2.sendBuffer();
}
}
U8g2 page-buffer version (RAM saver)
#include <U8g2lib.h>
#include <Wire.h>
U8G2_SSD1306_128X64_NONAME_1_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);
extern const unsigned char eyeOpen[];
extern const unsigned char eyeClosed[];
unsigned long lastSwap = 0;
bool lidClosed = false;
void drawFrame() {
const unsigned char* bmp = lidClosed ? eyeClosed : eyeOpen;
u8g2.firstPage();
do {
u8g2.drawXBMP(0, 0, 128, 64, bmp);
} while (u8g2.nextPage());
}
void setup() {
u8g2.begin();
drawFrame();
}
void loop() {
unsigned long now = millis();
if (now - lastSwap > (lidClosed ? 120UL : 900UL)) {
lastSwap = now;
lidClosed = !lidClosed;
drawFrame();
}
}
Notice that the page-mode sketch redraws the bitmap inside the do…while. If your "frame" is actually fifty shape calls (robot eyes from vectors), wrap them in a function and call that function inside the page loop. That's the main architectural shift when you come from Adafruit.
Parts wiring (same for both)
| Part | Arduino Uno | ESP32 (common) |
|---|---|---|
| OLED VCC | 5V (typical) | 3.3V |
| OLED GND | GND | GND |
| SDA | A4 | 21 |
| SCL | A5 | 22 |
Your library choice won't fix swapped SDA/SCL. Run an I2C scanner once before you blame drivers. It's quick.
Migration tips (Adafruit → U8g2)
- Pick the constructor for your controller (SSD1306 vs SH1106) and your bus (HW I2C).
- Replace
clearDisplay→clearBuffer(full), or let the page loop clear it for you. - Replace
display.display()→sendBuffer(), or letnextPagedo it once it's complete. - Map your GFX calls:
drawLine/drawCircle/drawFramenames are similar but not identical, so keep a cheat sheet open for an afternoon. - Re-export your bitmaps, then verify with a single static logo before you port the animation scheduler.
- Keep your
millis()state machine. Only your paint layer should change.
Going the other way (U8g2 → Adafruit) is common when a teammate's exporter only emits Adafruit code. Budget an hour to rename the sends and confirm your SH1106 units still look aligned.
When I use each (workshop rules of thumb)
- Hour-of-code robot eyes with circles: Adafruit. It matches the shapes tutorial and most paste-ready sketches.
- Avatar blink with 8 cropped bitmaps on Uno + ultrasonic + servo: U8g2 page mode, so you reclaim RAM.
- ESP32 dashboard with Wi-Fi: Adafruit is fine. I'd use U8g2 if you need fancy fonts or you've got SH1106 kits.
- Unknown ebay OLED in a mixed bin: try the U8g2 SH1106 constructor before you declare the panel dead.
- Sharing code with MicroPython kids later: the concepts transfer either way, but Adafruit's buffer model is closer to
framebuf.
Recommendation matrix
| Project situation | Pick | Why |
|---|---|---|
| Beginner + Adafruit docs | Adafruit | Lowest friction, and the examples are great |
| Uno RAM almost full | U8g2 page | Small live buffer |
| Confirmed SH1106 hardware | U8g2 (or SH110X) | First-class constructor |
| Tool exports Adafruit arrays | Adafruit | Bit order already matched |
| Need many built-in fonts | U8g2 | Font ecosystem |
| Dual OLED animation on Uno | U8g2 page / or one panel | Two Adafruit buffers hurt |
| ESP32 + lots of RAM | Either | Team preference wins |
| Vector robot eyes only | Adafruit or U8g2 full | Page mode forces redraw boilerplate |
Common mistakes I see
- You install U8g2 but still call Adafruit APIs from a copied blog sketch.
- You use page mode but draw only outside the page loop (blank or partial updates).
- You assume U8g2 "is always faster". Full buffer transfers are still full buffer transfers.
- You link every font header "just in case" and blow your flash on Uno.
- You never call
display()/sendBuffer()after drawing, so it stays blank forever, whatever the library.
Fonts, HUDs, and mixed UI + animation
Pure bitmap animations barely care which library you pick. Mixed UIs don't get off so easily. If your robot shows a status line under the eyes, Adafruit's default font is fine and tiny in flash. If you want a readable 12-pixel UI font plus icons, U8g2's catalog saves you from shipping homemade fonts, and that's a real win. Only include the one or two faces you call, though, or the linker may still carry their tables on your setup.
Here's a pattern that works on both. Animate the eyes in the upper band, reserve a 12-14 pixel strip at the bottom for text, and redraw text only when the values change. That dirty-flag approach matters more than micro-optimizing the driver, and it's cheap. If you clear and reprint a long String every frame "because the library is slow," you'll invent your own performance problem.
Partial updates and dirty regions (expectations check)
People sometimes ask me for "only send the pupil pixels." Neither library makes true region patches trivial on classic SSD1306 I2C the way a modern GPU would. You'll usually rebuild the buffer (or pages) and send a full or page-sized chunk. If you need lower bus traffic, shrink the art (crop your sprites), drop the FPS, or move to SPI. Don't expect a library rename to give you a free partial-DMA path on Uno hardware. It won't happen.
Where U8g2 page mode helps is RAM, not magical bandwidth. You still pay CPU to recreate the scene for each page. Complex vector robot faces can feel softer in page mode on 16 MHz AVR, and full buffer may look snappier if you've still got the SRAM. Measure with a wall-clock blink period, not forum lore.
Team and toolchain considerations
If half your GitHub issues paste Adafruit snippets, staying on Adafruit cuts your support load even when U8g2 is "better" on paper. If you've already standardized on PlatformIO library specs for U8g2 across ESP boards, don't yank that for one blog sketch. Consistency beats purity, and you'll thank yourself later. Your export pipelines (maker tools, CI that checks sketch size) should name the target library explicitly, so PRs don't mix bit orders.
FAQ
Can I use both libraries in one sketch?
Technically yes, but it's a mess on Uno (two drivers, two buffers). I wouldn't do it. Pick one per firmware image, and you'll save yourself the pain.
Which library does OLED Animation Maker target?
The tool can export for Adafruit SSD1306 and U8g2, and I'd pick deliberately. Choose the matching option so the bitmap packing lines up with your sketch.
Is Adafruit_SH110X better than U8g2 for SH1106?
Both work, so don't stress. If the rest of your project is already Adafruit GFX, SH110X keeps the API familiar. If you want one library for many panel types, U8g2 is broader.
Do animations look smoother on U8g2?
Smoothness comes from frame timing and how much you transfer each update, not from the brand name on the include. With the same art and the same bus, you'll get similar FPS for full buffers.
What about SPI OLEDs?
Both libraries support SPI variants. Your wiring changes (CS/DC/RES), but the animation scheduler stays the same. SPI often frees you from I2C bandwidth complaints, which isn't a small thing.
Why is page mode slower on my robot face even though it uses less RAM?
A *1 constructor redraws the scene once per page. Eight pages means eight passes over the same circles, then eight smaller I2C bursts. Full-buffer Adafruit draws once and sends 1024 bytes once. Page mode saves you SRAM, but it doesn't reduce CPU on a vector face, and that's why it feels slower.
I pasted an image2cpp array into drawXBMP and got snow
Adafruit drawBitmap and U8g2 drawXBMP don't share bit order. Re-export the frame for the call you're making, because there's no shortcut. A length mismatch (a 1024-byte full frame drawn as 32×32) gives you the same snow even when the library is correct.
Does Wire.setClock(400000) apply to both libraries?
Yes, if both are on hardware I2C. Call it after the display begin. It shortens the 1024-byte transfer, but it doesn't change how many times page mode repaints the scene. If you've got long jumper wires, you may need to stay at the default ~100 kHz, and that's fine.
How long one frame spends on the wire
"Which library is faster?" is usually a question about one 128×64 update at address 0x3C. The payload is the same 1024 bytes either way when you're in full-buffer mode, so it isn't a library thing. Arduino Wire comes up near 100 kHz. Moving 1024 bytes with address and ACK overhead is on the order of 90-100 ms of bus time. At 400 kHz that falls toward roughly 25 ms. Those figures are bit-time arithmetic, not a certificate from one module, and library overhead adds a little on top, so don't treat them as exact. They're enough to end a debate about brand names.
| Update style | What the CPU does | What the bus does | When it wins |
|---|---|---|---|
Adafruit full buffer, display() | Draw the scene once into 1024 RAM bytes | One transfer of that buffer | Vector eyes, single sprite, ESP32 |
U8g2 full buffer (*F), sendBuffer() | Same shape: draw once | Same ~1024-byte transfer | When you want U8g2 fonts and can spare the RAM |
U8g2 1-page (*1), firstPage / nextPage | Redraw the whole scene about 8 times | Eight shorter bursts that still cover the panel | Uno SRAM is the thing that is about to run out |
Time the paint, not the legend on the box. You'll learn more from it. On either library, record micros() immediately before the send and again when it returns. Do this with a static frame so your drawing cost stays out of the number. On a default 100 kHz bus you should see a full-buffer send in the neighborhood of 100 ms. If your Adafruit and U8g2 full-buffer times match and page mode costs several times the CPU, the libraries are behaving. If your page-mode robot face feels soft on a 16 MHz Uno, that's the redraw loop the partial-update section already warned about. The stopwatch tells you whether switching to *F is worth the SRAM.
Second case: the array that worked last week
Say you export a blink from a tool as an Adafruit bitmap, then drop the same braces into a U8g2 sketch that calls drawXBMP. Hello World still prints, because text never touches that array. The eyes become a diagonal hash. The fix is to export again with the U8g2 option. Don't swap constructors, because that isn't the problem. Check three numbers before you touch timing. You'll want them in hand: the array length is
width * height / 8 (1024 for 128×64, 128 for a 32×32 crop), the width and height arguments
match that art, and the pointer is read from PROGMEM the way that library's example does. If you mix a RAM pointer with a PROGMEM array on AVR, it draws whatever happens to sit at the low address. That looks like a library bug, but it's a cast bug.
Your wiring doesn't change between the two tests: Uno SDA on A4, SCL on A5; ESP32 SDA on GPIO21, SCL on GPIO22; ESP8266 SDA on D2, SCL on D1. If both sketches miss the panel, stop comparing buffers and scan the address. If only the ported sketch misses, your constructor names a different controller or a software-I2C pin pair. Hardware I2C constructors plus an explicit Wire.setClock after
begin keep the timing table above honest. Leave the clock at 100 kHz until the static logo is clean, then raise it and look for sparkle on your longest jumper. That sparkle is electrical, and it hits both libraries on the same wires.
Related guides you might like
- Create SSD1306 animations
- PROGMEM frame limits on Uno
- SH1106 vs SSD1306
- U8g2 tutorial: constructors, fonts and buffers
- GFX / U8g2 shapes
- Robot eyes with Adafruit GFX
- ESP32 OLED animation guide
- Image to byte array
Export frames for the library you chose
Draw or import your animation frames, then download Adafruit or U8g2-ready code without hand-packing bits.
Open oledanimationmaker.com →Free tools: OLED Animation Maker for your SSD1306 and SH1106 animations, Assemble Studio for your name and logo animations, the Shadow Box Lamp Generator for your 3D-printed shadow lamps, Text to STL for your 3D-printed names and keychains, and 3MF to Web to show your 3D prints on any website. New: the Image to Byte Array converter, the OLED Robot Eyes generator and the Lithophane Maker. See all tools.