Adafruit SH110X: the 1.3 inch SH1106 and the SH1107 OLED
Most 1.3 inch OLED modules sold as "SSD1306 compatible" carry an SH1106 controller, and Adafruit_SH110X is the library that drives them properly. It also covers the SH1107, the square 128x128 panel on the Grove 1.12 inch OLED. The drawing calls are Adafruit_GFX’s, so a sketch written for Adafruit_SSD1306 moves over by changing the include, the class name and the color constants.
Built in on Mokxi: #include <Adafruit_SH110X.h> and it builds, with nothing to install. Free, and no account needed.
What Adafruit SH110X does
The reason a separate library exists is the controller’s memory. The SH1106 has 132 columns of RAM with the glass showing columns 2 to 129, and it has no mode that takes a whole frame in one write. display() therefore sends the frame one 8-pixel page at a time, each starting at column 2, and only the pages that changed. Run SSD1306 code on an SH1106 and the image lands two columns over with most of it piled into the top band.
Both classes keep the whole picture in the board’s RAM. The SH1106G needs 1 KB, which an Uno can spare, but the SH1107’s 128x128 frame is 2 KB, which is all of an Uno’s memory. The runnable project below puts the SH1107 on a Mega for that reason; an ESP32 or a Pico works as well.
| Library Manager name | Adafruit SH110X |
|---|---|
| Author | Adafruit |
| Include | #include <Adafruit_SH110X.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | OLED display, 1.3 inch SH1106, OLED display, 1.12 inch SH1107 |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <Adafruit_SH110X.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "Adafruit SH110X" by Adafruit from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add Adafruit SH110X to lib_deps in PlatformIO. Mokxi follows the calls of release 2.1.15, so a sketch written here builds there too.
What to know in the simulator: The SH1107 frame is 2 KB, more than an Uno has: use a Mega, an ESP32 or a Pico for it. The SPI constructors build, and begin() says on Serial that the SPI module is not simulated.
- ESP32-C3
- Arduino Uno
- Arduino Nano
- Arduino Mega 2560
- Arduino Leonardo
- SparkFun Pro Micro
- Arduino Micro
- ESP32-C6
- WCH CH32V003
- 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.
Adafruit_SH1106G display(128, 64, &Wire, -1)
Makes the 1.3 inch SH1106 panel on the I2C bus with no reset pin. The G in the name is part of the class; there is no plain Adafruit_SH1106.
Adafruit_SH1107 display(128, 128, &Wire)
Makes the square 128x128 SH1107 panel, the Grove 1.12 inch OLED. Its frame is 2 KB, so pick a board with the RAM for it.
display.begin(0x3C, true)
Starts the panel at an I2C address and sends the reset sequence. Returns false when nothing answers. The SH1107 defaults to 0x3D when no address is given, so pass the one your module uses.
if (!display.begin(0x3C, true)) {
Serial.println("SH1107 not found");
while (1) {}
}display.clearDisplay()
Clears the frame in RAM. Like every drawing call, it changes nothing on the glass until display() runs.
display.setTextColor(SH110X_WHITE)
Sets the text color for print(). SH110X_WHITE lights pixels, SH110X_BLACK clears them and SH110X_INVERSE flips them.
display.fillCircle(x, y, 5, SH110X_WHITE)
One of the Adafruit_GFX shapes, here a filled circle. Drawing it again in SH110X_BLACK is the cheap way to erase a moving object.
display.display()
Sends the frame to the panel, page by page, skipping pages that did not change since the last call.
display.setContrast(128)
Sets the panel’s brightness from 0 to 255. Lower values also save a little current on battery projects.
Example: Grove OLED
On the Arduino Mega 2560 R3. It runs in the browser exactly as printed.
// Grove OLED: the 1.12 inch 128x128 OLED on an SH1107, drawn with
// Adafruit's SH110X library on a Mega.
//
// OLED SDA -> 20 (SDA) SCL -> 21 (SCL) VCC -> 5 V GND -> GND
//
// The library keeps the whole picture in RAM, one bit a pixel: 128 x 128 / 8
// is 2048 bytes, which is all of an Uno's RAM and a quarter of a Mega's, so
// this one runs on the Mega. display() sends it as sixteen pages of 128
// bytes, each with its page address and column 0 first.
//
// A ball bounces round the square, and the page count of each frame is
// printed: only the pages that changed are sent.
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SH110X.h>
Adafruit_SH1107 display(128, 128, &Wire);
int x = 20, y = 30, dx = 3, dy = 2;
void setup() {
Serial.begin(9600);
if (!display.begin(0x3C, true)) {
Serial.println("SH1107 not found");
while (1) {
}
}
display.clearDisplay();
display.setTextSize(1);
display.setTextColor(SH110X_WHITE);
display.setCursor(16, 4);
display.print("Grove OLED 1.12");
display.drawRect(0, 16, 128, 112, SH110X_WHITE);
display.display();
Serial.println("Grove OLED ready");
}
void loop() {
display.fillCircle(x, y, 5, SH110X_BLACK);
x += dx;
y += dy;
if (x < 7 || x > 120) dx = -dx;
if (y < 23 || y > 120) dy = -dy;
display.fillCircle(x, y, 5, SH110X_WHITE);
display.display();
delay(40);
}Open it in the editor, wired and ready to run · Grove OLED: the project page
Common errors and how to fix them
The picture is shifted two pixels and has a stripe of noise down one edge
The sketch uses Adafruit_SSD1306 on an SH1106 panel. Switch the include to Adafruit_SH110X.h, the class to Adafruit_SH1106G, and SSD1306_WHITE to SH110X_WHITE; the drawing code can stay as it is.
An Uno resets or prints garbage as soon as an SH1107 sketch starts
The 128x128 frame takes 2048 bytes, the whole of an Uno’s RAM, so the stack runs into it. Move the sketch to a Mega, an ESP32 or a Pico, or use a text-only library that keeps no frame.
'SH110X_WHITE' was not declared, or 'Adafruit_SH1106' does not name a type
The color names start with SH110X_, not SSD1306_, and the 1.3 inch class is Adafruit_SH1106G with a trailing G. Fix both spellings and include Adafruit_GFX.h before Adafruit_SH110X.h.
Questions and answers
How do I tell an SH1106 from an SSD1306?
Size is the usual clue: 0.96 inch modules are nearly always SSD1306 and 1.3 inch ones nearly always SH1106. If SSD1306 code shows a shifted picture with a noisy column, it is an SH1106.
Does the SPI version work in the simulator?
The SPI constructors build, but begin() prints a note that the SPI module is not simulated. Use the I2C constructor to see the picture.
Keep going
More displays libraries
Try Adafruit SH110X without installing anything
Open the example, change the sketch, and keep your version in a free account.