Arduino library · Displays

SSD1306Ascii: OLED text on an Uno without the 1 KB buffer

Adafruit_SSD1306 keeps a copy of the whole 128x64 picture in RAM, which costs 1 KB of an Uno’s 2 KB before your sketch has done anything. Bill Greiman’s SSD1306Ascii skips that. It writes each character straight into the panel’s own memory, a column at a time, so it uses a few bytes. The price is that it only does text: no lines, circles or bitmaps.

Open the example in the editor See the calls

Built in on Mokxi: #include <SSD1306Ascii.h> and it builds, with nothing to install. Free, and no account needed.

What SSD1306Ascii does

Positions work differently from a graphics library. The screen is divided into rows of 8 pixels (the controller’s pages), and setCursor(col, row) takes the column in pixels but the row in those 8-pixel rows, so a 128x64 panel has rows 0 to 7. clearToEOL() blanks from the cursor to the end of the row, which is how you overwrite a changing number without clearing the screen.

The library is a good fit for data loggers and sensor readouts on an Uno or Nano that also need RAM for an SD card or a buffer. In Mokxi it draws one font of Mokxi’s own, 5 by 8 with lower case, and the big font names draw it at double size, so layouts come out the right size. Text that runs past the last row starts again at the top, because the scroll mode that moves the panel’s start line is not modeled.

Library Manager name	SSD1306Ascii
Author	Bill Greiman
Include	`#include <SSD1306Ascii.h>` `#include <SSD1306AsciiWire.h>` `#include <SSD1306AsciiAvrI2c.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

Install it

It builds on every board Mokxi compiles for but ATtiny85.

In Mokxi it is built in: #include <SSD1306Ascii.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "SSD1306Ascii" by Bill Greiman from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add SSD1306Ascii to lib_deps in PlatformIO. Mokxi follows the calls of release 1.3.5, so a sketch written here builds there too.

What to know in the simulator: One font of Mokxi’s own, 5 by 8 with lower case; the large font names draw it twice as big. Text past the last row starts again at the top: the panel’s start line, which upstream’s auto scroll uses, is not modeled.

The calls you will use

In the order a sketch meets them.

`SSD1306AsciiWire oled`

Makes the display on the Wire library. SSD1306AsciiAvrI2c is the alternative with its own small I2C code for AVR boards.

`oled.begin(&Adafruit128x64, 0x3C)`

Starts the panel. Use &Adafruit128x32 for the short 0.91 inch module and &SH1106_128x64 for a 1.3 inch SH1106. Call Wire.begin() first.

`oled.setFont(Adafruit5x7)`

Chooses the font. There is no default, so nothing prints until a font is set.

`oled.set2X()`

Doubles the size of everything printed after it, two rows tall. set1X() returns to normal.

`oled.setCursor(48, 4)`

Moves to column 48 in pixels and row 4 in 8-pixel rows, the middle of a 64-pixel-tall screen.

`oled.clearToEOL()`

Clears from the cursor to the end of the row. Print a value, then call it, and a shorter value leaves no old digits behind.

oled.setCursor(48, 4);
oled.print(millis());
oled.clearToEOL();

`oled.clear()`

Blanks every row and puts the cursor at the top left.

`oled.displayRows()`

How many 8-pixel rows the panel has: 8 on a 128x64, 4 on a 128x32.

Example: Big and small text on an OLED with no frame buffer

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3

#include <Wire.h>
#include "SSD1306Ascii.h"
#include "SSD1306AsciiWire.h"

#define I2C_ADDRESS 0x3C

SSD1306AsciiWire oled;

void setup() {
  Serial.begin(9600);
  Wire.begin();
  Wire.setClock(400000L);
  oled.begin(&Adafruit128x64, I2C_ADDRESS);
  oled.setFont(Adafruit5x7);
  oled.clear();
  oled.set2X();
  oled.println("Hello!");
  oled.set1X();
  oled.println("A frame buffer costs");
  oled.println("1 KB. This uses none.");
  oled.print("millis: ");
  Serial.print("rows ");
  Serial.println(oled.displayRows());
}

void loop() {
  oled.setCursor(48, 4);
  oled.print(millis());
  oled.clearToEOL();
  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

Open it in the editor, wired and ready to run

Common errors and how to fix them

`Nothing appears although begin() and print() run`

No font was set. Unlike Adafruit_GFX there is no built-in default, so call oled.setFont(Adafruit5x7) or another font after begin() and before the first print().

`Text lands at the wrong height after setCursor(0, 32)`

The row is in 8-pixel rows, not pixels. Row 32 does not exist on a 64-pixel screen; divide the pixel height by 8 and use setCursor(0, 4).

`drawLine() or fillRect() is not a member of SSD1306AsciiWire`

This library draws text only. For shapes and graphics use Adafruit_SSD1306 or U8g2, which keep a frame buffer, or draw simple bars from characters.

Projects that use SSD1306Ascii

Built-in projects that include it. Each page has the full sketch and opens in the editor, already wired.

GPS speedometer with a trip odometerA NEO-6M and NeoGPS show speed, heading and satellites on an OLED, and a trip and total distance saved in EEPROM survive a reset.

Keep going

Learn

Arduino OLED Display (SSD1306) Tutorial

Parts

More displays libraries

Every built-in library · Open the editor

Try SSD1306Ascii without installing anything

Open the example, change the sketch, and keep your version in a free account.

Start building free

Open the editor