128×64

The framebuffer

Nothing you draw touches the screen. You are painting a 1024-byte block of RAM, and once per frame you shove the whole thing down the wire.

This single idea explains almost every confusing thing about this display.

128 × 64 pixels, one bit each, is 1024 bytes living in your ESP32's memory. drawLine, print, fillCircle — all of them flip bits in that array and nothing else. The screen stays exactly as it was until you call display.display(), which transmits all 1024 bytes over I²C.

Coordinates

(0, 0) is the top-left. X runs right to 127. Y runs down to 63. If you've done any maths plotting, Y is upside down from what you expect, and you will get this wrong at least twice.

Off-screen coordinates are silently clipped, not errors. That's useful — it's how scrolling works — but it also means a typo that puts your text at y = 200 just shows you a blank screen with no complaint.

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

Adafruit_SSD1306 display(128, 64, &Wire, -1);

void setup() {
  Wire.begin(8, 9, 400000);
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) for(;;);

  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);

  // corners, to prove where the edges are
  display.drawPixel(0,   0,  SSD1306_WHITE);
  display.drawPixel(127, 0,  SSD1306_WHITE);
  display.drawPixel(0,   63, SSD1306_WHITE);
  display.drawPixel(127, 63, SSD1306_WHITE);

  display.drawRect(0, 0, 128, 64, SSD1306_WHITE);
  display.setCursor(4, 4);   display.print("0,0");
  display.setCursor(88, 52); display.print("127,63");

  display.display();   // <-- without this: nothing
}

void loop() {}

Clear, draw, push

Every frame is the same three beats: clearDisplay(), then your drawing calls, then display(). If you skip the clear, last frame's pixels stay — which is a bug most of the time and a technique occasionally.

Text

The built-in font is 5×7 in a 6×8 cell. That's not a limitation to work around — it's the entire typographic system, and it's worth knowing exactly.

At setTextSize(1) every character occupies 6 pixels across and 8 down, including its spacing. Which gives you hard numbers:

Sizes above 1 are integer-scaled — every pixel becomes a 2×2 or 3×3 block. There's no smoothing and no separate font file. That chunkiness is the aesthetic; fighting it looks worse than leaning into it.

display.clearDisplay();
display.setTextColor(SSD1306_WHITE);

display.setTextSize(1);
display.setCursor(0, 0);
display.print("TEMPERATURE");

display.setTextSize(3);
display.setCursor(0, 14);
display.print("28.4");

display.setTextSize(1);
display.setCursor(74, 26);
display.print("degC");

// inverted text: white bg, black glyphs
display.setTextColor(SSD1306_BLACK, SSD1306_WHITE);
display.setCursor(0, 48);
display.print(" LIVE  vizag  ");

display.display();

Two colour arguments

setTextColor(fg) draws glyphs and leaves the background untouched — so new text draws on top of old text and turns into mush. setTextColor(fg, bg) paints the whole cell, which erases what was underneath. For anything that updates in place, use the two-argument form or explicitly fillRect the area black first.

Primitives

Eleven drawing functions. Everything you will ever build on this display is a composition of these, and at 1-bit there are no gradients to hide behind.

Colour is 1 (SSD1306_WHITE, pixel on), 0 (BLACK, off), or 2 (INVERSE, flip whatever's there). INVERSE is genuinely useful — it's how you highlight a menu row without redrawing it.

display.clearDisplay();

// a signal-strength meter from fast vlines
for (uint8_t i = 0; i < 5; i++) {
  uint8_t h = 4 + i * 5;
  display.fillRect(4 + i * 7, 28 - h, 5, h, SSD1306_WHITE);
}

// a rounded card
display.drawRoundRect(46, 4, 78, 26, 4, SSD1306_WHITE);
display.setCursor(52, 9);
display.print("ESP32-S3");
display.setCursor(52, 19);
display.print("240 MHz");

// a progress bar
display.drawRect(4, 40, 120, 10, SSD1306_WHITE);
display.fillRect(6, 42, 74, 6, SSD1306_WHITE);

// INVERSE flips whatever is underneath
display.fillRect(60, 38, 30, 14, SSD1306_INVERSE);

display.display();

Motion without delay()

The moment you want two things moving at once, delay() stops being a tool and becomes the bug. This lesson is the single most transferable idea in the whole course.

delay(100) freezes the entire chip. No button reads, no WiFi servicing, no sensor polling, no second animation. It works for exactly one demo and then never again.

The replacement is a timestamp comparison. You keep a last variable, check millis() - last >= interval, and if it's time, do the thing and update last. Everything else in loop() keeps running at full speed.

// three independent timers, one loop, zero delay()

uint32_t tBounce = 0, tBlink = 0, tClock = 0;
int      ballX = 0, ballDir = 2;
bool     dotOn = false;
uint16_t secs = 0;

void loop() {
  uint32_t now = millis();

  if (now - tBounce >= 16) {          // ~60 fps
    tBounce = now;
    ballX += ballDir;
    if (ballX <= 4 || ballX >= 123) ballDir = -ballDir;
  }
  if (now - tBlink >= 500) {          // 2 Hz
    tBlink = now;
    dotOn = !dotOn;
  }
  if (now - tClock >= 1000) {         // 1 Hz
    tClock = now;
    secs++;
  }

  display.clearDisplay();
  display.fillCircle(ballX, 40, 4, SSD1306_WHITE);
  if (dotOn) display.fillRect(120, 2, 5, 5, SSD1306_WHITE);
  display.setCursor(0, 0);
  display.print(secs);
  display.print("s");
  display.display();
}

Bitmaps

Primitives get you geometry. For anything with character — a logo, an icon, an eyebrow — you draw it in a real tool and ship it as bytes.

A monochrome bitmap is a byte array where each bit is a pixel, packed left-to-right, 8 pixels per byte, row by row. A 16×16 icon is 32 bytes. You store it in flash with PROGMEM so it doesn't eat your precious 320KB of RAM, and blit it with drawBitmap.

Rows pad to whole bytes, so a 12px-wide bitmap still costs 2 bytes per row. Design at multiples of 8 when you can.

// 16x16 icon = 32 bytes, stored in flash not RAM
const unsigned char PROGMEM iconBolt[] = {
  0x00,0x60, 0x00,0xC0, 0x01,0x80, 0x03,0x00,
  0x06,0x00, 0x0F,0xF0, 0x1F,0xE0, 0x00,0xC0,
  0x01,0x80, 0x03,0x00, 0x06,0x00, 0x0C,0x00,
  0x18,0x00, 0x30,0x00, 0x20,0x00, 0x00,0x00
};

void setup() {
  // ...init...
  display.clearDisplay();
  display.drawBitmap(8, 12, iconBolt, 16, 16, SSD1306_WHITE);
  display.setTextSize(2);
  display.setCursor(34, 14);
  display.print("4.2V");
  display.display();
}

Making it feel alive

Two rounded rectangles read as eyes. What makes them read as alive is timing, not shape — and that's a design problem, not a graphics one.

This is the most-copied thing people do with these displays, and most implementations get the drawing right and the behaviour wrong. Four mechanics do almost all the work:

• Interpolation. Never snap between states. Move a fraction of the remaining distance each frame and everything reads as intentional.
• Autoblink with jitter. A blink every 3.0s reads as a machine. Every 3s ± a random 0–2s reads as a creature.
• Idle drift. Eyes that never move look dead. Small random saccades during idle do more than any expression set.
• Asymmetry. Offset one eye by a pixel, or blink them 30ms apart. Perfect symmetry is uncanny.

// hand-rolled, ~40 lines, no library
struct Eye { float h; float tgt; int x; };
Eye L = {26, 26, 28}, R = {26, 26, 84};
uint32_t tBlink = 0, tIdle = 0;
int      gaze = 0, gazeTgt = 0;
uint16_t nextBlink = 3000;

void loop() {
  uint32_t now = millis();

  if (now - tBlink > nextBlink) {
    tBlink = now;
    nextBlink = 2200 + random(2400);   // jitter
    L.tgt = R.tgt = 2;                 // close
  }
  if (now - tBlink > 110) L.tgt = R.tgt = 26;   // reopen

  if (now - tIdle > 1400) {
    tIdle = now;
    gazeTgt = random(-9, 10);          // saccade
  }

  // interpolate -- this is what sells it
  L.h   += (L.tgt - L.h) * 0.35;
  R.h   += (R.tgt - R.h) * 0.30;       // slightly slower = asymmetry
  gaze  += (gazeTgt - gaze) * 0.18;

  display.clearDisplay();
  display.fillRoundRect(L.x + gaze - 17, 32 - L.h/2, 34, (int)L.h, 8, SSD1306_WHITE);
  display.fillRoundRect(R.x + gaze - 17, 32 - R.h/2, 34, (int)R.h, 8, SSD1306_WHITE);
  display.display();
}

Scrolling and marquee

21 characters per line is not many. Sooner or later you have text that doesn't fit, and there are three completely different ways to deal with it.

1. Hardware scroll

The SSD1306 has scrolling built into the controller — startscrollleft(), startscrollright(), and the diagonal variants. It costs zero CPU and zero I²C traffic once started, because the chip does it. But it scrolls the whole framebuffer, you can't scroll one region, and you can't draw while it runs. Use it for a splash screen, not a UI.

2. Software marquee

You redraw text at a moving x offset each frame. Full control, works per-region, composes with everything else on screen. Costs a full display() per frame. This is what you want 90% of the time.

3. Don't scroll

Page the text instead — show 21 characters, hold for 1.5s, show the next 21. Reading a marquee is genuinely harder than reading static text, and on a 128px screen paging is usually the better UX. Worth trying before you reach for motion.

const char* msg = "devsforfun studio -- hardware from first principles -- ";
int      scrollX = 128;
uint32_t tScroll = 0;
// display.setTextWrap(false); in setup() -- required

void loop() {
  uint32_t now = millis();
  if (now - tScroll >= 40) {          // 25 px/sec
    tScroll = now;
    scrollX -= 1;
    int wpx = strlen(msg) * 6;        // 6px per char at size 1
    if (scrollX < -wpx) scrollX = 128;
  }

  display.clearDisplay();

  // static header stays put while the band scrolls
  display.setCursor(0, 0);
  display.print("STATUS");
  display.drawFastHLine(0, 10, 128, SSD1306_WHITE);

  display.setCursor(scrollX, 26);
  display.print(msg);

  display.drawFastHLine(0, 40, 128, SSD1306_WHITE);
  display.display();
}

Real constraints

Everything above works on the bench. These are the four things that break it in a real build, and knowing them is most of what separates a demo from a product.

RAM

Adafruit_SSD1306 allocates the full 1024-byte framebuffer. On your S3 with 320KB that's nothing. On an ATmega328 with 2KB it's half your memory — which is why the original RoboEyes notes that Serial can misbehave on 328P boards from exhausted memory. If you ever port down, switch to U8g2's page-buffer mode, which trades CPU for a fraction of the RAM.

Bandwidth

1024 bytes per full refresh. At 100kHz that's ~100ms — 10fps ceiling. At 400kHz, ~25ms, so 30–40fps. Long jumper wires and a 400kHz clock is a classic intermittent-failure combination: it works on the bench and dies on the desk. If it's flaky, drop to 100kHz before you suspect anything else.

Burn-in is real

These are OLEDs, not LCDs. Static pixels degrade permanently. A label that sits in the same place for a week will ghost. Mitigations: shift the whole UI by a few pixels every few minutes, invert periodically, dim with display.dim(true), and blank the screen when nobody's looking.

It might not be an SSD1306

The SH1106 is pin-compatible, visually identical, and answers on the same address — but its RAM is 132 pixels wide, so an SSD1306 driver renders it with a 2px offset and garbage at the edges. If your display is almost right, that's the reason. Switch to U8g2 with the SH1106 constructor.

What to build

The display is an output device. On its own it's a toy. Paired with something that produces real data, it becomes a product — and that pairing is the whole point.

Projects that teach you something new

What this course deliberately left out

• Custom fonts. GFX supports them; they cost flash and they're a rabbit hole. Learn the 5×7 grid first.
• SPI wiring. Faster, more pins, worth it above ~40fps. Your 4-pin module can't do it anyway.
• U8g2 in depth. Better fonts, lower RAM, worse documentation. Go there when Adafruit_GFX stops fitting.
• Colour. ST7735 and ST7789 at 16-bit change every constraint in Lesson 08 — the framebuffer alone becomes 100KB+. That's a different course.