Arduino Nano ESP32 - SSD1309 OLED Display
This tutorial provides instructions on how to use the SSD1309 OLED 128×64 (2.42-inch / 2.4-inch) with an Arduino Nano ESP32 via the I2C interface and the DIYables_OLED_SSD1309 library. In detail, we will learn:
- How to connect the 2.42-inch SSD1309 OLED to Arduino Nano ESP32 over I2C
- How to program Arduino Nano ESP32 to display text and numbers on the SSD1309 OLED
- How to center text vertically and horizontally on the SSD1309 OLED
- How to draw geometric shapes on the SSD1309 OLED
- How to display monochrome bitmap images on the SSD1309 OLED
- How to use hardware scrolling in four directions
- How to adjust contrast and dim the display
- How to use custom fonts from the Adafruit GFX font collection
Hardware Preparation
Or you can buy the following kits:
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Disclosure: Some of the links provided in this section are Amazon affiliate links. We may receive a commission for any purchases made through these links at no additional cost to you.
Additionally, some of these links are for products from our own brand, DIYables .
Additionally, some of these links are for products from our own brand, DIYables .
Overview of the SSD1309 2.42-Inch OLED Display
The SSD1309 is a single-chip CMOS OLED driver IC for 128×64 dot-matrix panels. It is register-compatible with the SSD1306, so many existing code examples port over with minimal changes. Notable hardware details:
- No built-in charge pump — the SSD1309 requires an external VCC rail, though virtually all breakout boards (including 2.42-inch modules) ship with an onboard boost converter, making this transparent to the user.
- Higher voltage tolerance — the SSD1309 accepts up to 16 V VCC, versus the SSD1306's ~4.2 V limit.
I2C communication requires only two signal wires (SDA and SCL), and the bus can be shared with other I2C peripherals at the same time.
SSD1309 OLED Pinout (I2C Module)
- GND pin: Connect to GND on the Arduino Nano ESP32.
- VCC pin: Power supply for the display. Connect to 3.3V.
- SCL pin: Serial clock for I2C. Connect to A5.
- SDA pin: Serial data for I2C. Connect to A4.
※ NOTE THAT:
- The pin layout of the OLED module can differ depending on the manufacturer. Always use the labels printed on the module itself.
- This tutorial uses the SSD1309 I2C OLED from DIYables, which has been tested and confirmed to work.
Wiring Diagram
- Wiring diagram between Arduino Nano ESP32 and SSD1309 OLED 128x64
This image is created using Fritzing. Click to enlarge image
The wiring table between Arduino Nano ESP32 and SSD1309 OLED display:
| OLED Module | Arduino Nano ESP32 |
|---|---|
| VCC | 3.3V |
| GND | GND |
| SDA | A4 |
| SCL | A5 |
How to Program Arduino Nano ESP32 for SSD1309 OLED
Install the DIYables_OLED_SSD1309 Library
- Click to the Libraries icon on the left bar of the Arduino IDE.
- Search for DIYables_OLED_SSD1309, then find the DIYables OLED SSD1309 library by DIYables.
- Click Install to install the DIYables_OLED_SSD1309 library.
- You will be asked to install dependencies for the library.
- Click Install All to install all required dependencies.
Programming Steps
- Include the required libraries
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <DIYables_OLED_SSD1309.h>
- Define the screen dimensions
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
- Declare the display object
#define OLED_RESET -1 // Reset pin not used on most I2C modules
#define SCREEN_ADDRESS 0x3C
DIYables_OLED_SSD1309 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
- Initialize the OLED in setup()
if (!display.begin(SSD1309_SWITCHCAPVCC, SCREEN_ADDRESS)) {
Serial.println(F("SSD1309 allocation failed"));
for (;;); // halt
}
- Display content
display.clearDisplay();
display.setTextSize(2);
display.setTextColor(SSD1309_PIXEL_ON);
display.setCursor(0, 20);
display.println(F("Hello ESP32"));
display.display(); // push buffer to screen
Arduino Nano ESP32 Code — Hello World on SSD1309 OLED
The simplest starting point: print a few lines of text at different sizes.
/*
* This Arduino Nano ESP32 code was developed by newbiely.com
*
* This Arduino Nano ESP32 code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-nano-esp32/arduino-nano-esp32-ssd1309-oled-display
*/
/*
* DIYables OLED SSD1309 – Hello World
* Prints text in two sizes on the 2.42 inch 128x64 I2C OLED with Arduino Nano.
*/
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <DIYables_OLED_SSD1309.h>
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C
DIYables_OLED_SSD1309 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
void setup() {
Serial.begin(9600);
if (!display.begin(SSD1309_SWITCHCAPVCC, SCREEN_ADDRESS)) {
Serial.println(F("SSD1309 allocation failed"));
for (;;);
}
display.clearDisplay();
display.setTextSize(1); // 6x8 pixels per character
display.setTextColor(SSD1309_PIXEL_ON); // turn pixels on
display.setCursor(0, 0);
display.println(F("Hello, World!"));
display.println();
display.setTextSize(2); // 12x16 pixels per character
display.println(F("DIYables"));
display.setTextSize(1);
display.println();
display.println(F("SSD1309 OLED 128x64"));
display.display(); // push buffer to screen
}
void loop() { }
Arduino Nano ESP32 Code — Display Text on SSD1309 OLED
The following example demonstrates more text features — multiple sizes, number formatting, and the F() macro for saving RAM.
/*
* This Arduino Nano ESP32 code was developed by newbiely.com
*
* This Arduino Nano ESP32 code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-nano-esp32/arduino-nano-esp32-ssd1309-oled-display
*/
/*
* DIYables OLED SSD1309 – Display Text
* Displays text in various sizes and formats on the 2.42" SSD1309 OLED with Arduino Nano.
*/
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <DIYables_OLED_SSD1309.h>
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C
DIYables_OLED_SSD1309 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
void setup() {
Serial.begin(9600);
if (!display.begin(SSD1309_SWITCHCAPVCC, SCREEN_ADDRESS)) {
Serial.println(F("SSD1309 allocation failed"));
for (;;);
}
display.clearDisplay();
// Various text sizes
display.setTextSize(1);
display.setTextColor(SSD1309_PIXEL_ON);
display.setCursor(0, 0);
display.println(F("Size 1 - DIYables"));
display.setTextSize(2);
display.println(F("Size 2"));
display.setTextSize(3);
display.println(F("Sz3"));
display.display();
delay(3000);
// Number formatting
display.clearDisplay();
display.setTextSize(1);
display.setCursor(0, 0);
int value = 42;
float pi = 3.14159;
display.print(F("Integer: "));
display.println(value);
display.print(F("Float: "));
display.println(pi, 2); // 2 decimal places
display.print(F("Hex: 0x"));
display.println(value, HEX);
display.print(F("Binary: 0b"));
display.println(value, BIN);
display.display();
}
void loop() { }
Useful Display Functions Reference
- oled.clearDisplay() — wipe the frame buffer (all pixels off).
- oled.display() — transfer the buffer to the OLED so changes become visible.
- oled.drawPixel(x, y, color) — set or clear an individual pixel.
- oled.setTextSize(n) — scale the font by factor *n* (1 = 6×8, 2 = 12×16, …).
- oled.setCursor(x, y) — move the text cursor to pixel coordinates *(x, y)*.
- oled.setTextColor(SSD1309_PIXEL_ON) — text foreground only (transparent background).
- oled.setTextColor(SSD1309_PIXEL_OFF, SSD1309_PIXEL_ON) — text with explicit background colour.
- oled.println("message") — print a string and advance to the next line.
- oled.println(number) — print an integer in decimal.
- oled.println(number, HEX) — print an integer in hexadecimal.
- oled.startscrollright(start, stop) — hardware-scroll right between page *start* and *stop*.
- oled.startscrollleft(start, stop) — hardware-scroll left.
- oled.startscrolldiagright(start, stop) — hardware-scroll diagonally right.
- oled.startscrolldiagleft(start, stop) — hardware-scroll diagonally left.
- oled.stopscroll() — halt any active hardware scroll.
- oled.setContrast(value) — adjust display brightness (0–255).
- oled.dim(true/false) — quickly dim or restore the display.
- oled.invertDisplay(true/false) — hardware-level colour inversion.
How to Vertically and Horizontally Center Text on the SSD1309 OLED
Arduino Nano ESP32 Code — Draw Shapes on SSD1309 OLED
The DIYables_OLED_SSD1309 library extends Adafruit_GFX, giving you a full set of shape-drawing primitives: pixels, lines, rectangles, filled rectangles, circles, filled circles, triangles, filled triangles, and rounded rectangles.
/*
* This Arduino Nano ESP32 code was developed by newbiely.com
*
* This Arduino Nano ESP32 code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-nano-esp32/arduino-nano-esp32-ssd1309-oled-display
*/
/*
* DIYables OLED SSD1309 – Draw Shapes
* Demonstrates drawing pixels, lines, rectangles, circles, and triangles on the 2.42" OLED with Arduino Nano.
*/
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <DIYables_OLED_SSD1309.h>
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C
DIYables_OLED_SSD1309 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
void setup() {
Serial.begin(9600);
if (!display.begin(SSD1309_SWITCHCAPVCC, SCREEN_ADDRESS)) {
Serial.println(F("SSD1309 allocation failed"));
for (;;);
}
display.clearDisplay();
display.display();
}
void loop() {
// Draw pixels
display.clearDisplay();
for (int i = 0; i < 20; i++) {
display.drawPixel(random(SCREEN_WIDTH), random(SCREEN_HEIGHT), SSD1309_PIXEL_ON);
}
display.display();
delay(2000);
// Draw lines
display.clearDisplay();
for (int y = 0; y < SCREEN_HEIGHT; y += 8) {
display.drawLine(0, 0, SCREEN_WIDTH - 1, y, SSD1309_PIXEL_ON);
}
display.display();
delay(2000);
// Draw rectangles
display.clearDisplay();
display.drawRect(10, 10, 40, 30, SSD1309_PIXEL_ON); // outline
display.fillRect(60, 10, 40, 30, SSD1309_PIXEL_ON); // filled
display.drawRoundRect(10, 45, 40, 15, 5, SSD1309_PIXEL_ON); // rounded corners
display.display();
delay(2000);
// Draw circles
display.clearDisplay();
display.drawCircle(32, 32, 20, SSD1309_PIXEL_ON); // outline
display.fillCircle(96, 32, 20, SSD1309_PIXEL_ON); // filled
display.display();
delay(2000);
// Draw triangles
display.clearDisplay();
display.drawTriangle(20, 10, 10, 50, 30, 50, SSD1309_PIXEL_ON); // outline
display.fillTriangle(90, 10, 70, 50, 110, 50, SSD1309_PIXEL_ON); // filled
display.display();
delay(2000);
}
Arduino Nano ESP32 Code — Hardware Scrolling on SSD1309 OLED
The SSD1309 includes a hardware scrolling engine that shifts display contents without CPU load. Four scroll directions are available: right, left, diagonal-right, and diagonal-left. Each function takes start and stop page numbers (pages are 8-pixel-high strips numbered 0–7).
※ NOTE THAT:
Call display() to push your content to the OLED before starting a scroll. Stop scrolling with stopscroll() before drawing new content.
/*
* This Arduino Nano ESP32 code was developed by newbiely.com
*
* This Arduino Nano ESP32 code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-nano-esp32/arduino-nano-esp32-ssd1309-oled-display
*/
/*
* DIYables OLED SSD1309 – Scroll Text
* Demonstrates all four hardware scroll directions on the 2.42" OLED with Arduino Nano.
*/
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <DIYables_OLED_SSD1309.h>
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C
DIYables_OLED_SSD1309 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
void setup() {
Serial.begin(9600);
if (!display.begin(SSD1309_SWITCHCAPVCC, SCREEN_ADDRESS)) {
Serial.println(F("SSD1309 allocation failed"));
for (;;);
}
display.clearDisplay();
display.setTextSize(2);
display.setTextColor(SSD1309_PIXEL_ON);
display.setCursor(10, 24);
display.println(F("DIYables"));
display.display();
delay(2000);
}
void loop() {
// Scroll right across all pages
display.startscrollright(0x00, 0x07);
delay(3000);
display.stopscroll();
delay(500);
// Scroll left
display.startscrollleft(0x00, 0x07);
delay(3000);
display.stopscroll();
delay(500);
// Diagonal scroll right
display.startscrolldiagright(0x00, 0x07);
delay(3000);
display.stopscroll();
delay(500);
// Diagonal scroll left
display.startscrolldiagleft(0x00, 0x07);
delay(3000);
display.stopscroll();
delay(500);
}
Arduino Nano ESP32 Code — Display Bitmap Image on SSD1309 OLED
To display a bitmap you must first convert your image into a C byte array. Use the free image2cpp online tool:
- Upload your image (PNG, JPG, BMP, etc.).
- Set the canvas size to 128×64 (or smaller).
- Choose Arduino code as the output format.
- Copy the generated array into your sketch.
/*
* This Arduino Nano ESP32 code was developed by newbiely.com
*
* This Arduino Nano ESP32 code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-nano-esp32/arduino-nano-esp32-ssd1309-oled-display
*/
/*
* DIYables OLED SSD1309 – Display Bitmap Image
* Shows a 16x16 heart icon and 128x64 DIYables logo on the 2.42" OLED with Arduino Nano.
*/
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <DIYables_OLED_SSD1309.h>
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C
DIYables_OLED_SSD1309 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
// 16x16 heart icon bitmap
const unsigned char heart_icon[] PROGMEM = {
0x00, 0x00, 0x0c, 0x30, 0x1e, 0x78, 0x3f, 0xfc, 0x7f, 0xfe, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0x7f, 0xfe, 0x3f, 0xfc, 0x1f, 0xf8, 0x0f, 0xf0, 0x03, 0xc0, 0x00, 0x00
};
// 128x64 DIYables logo bitmap
const unsigned char diyables_logo[] PROGMEM = {
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0xff, 0xff, 0xf0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0f, 0xff,
0xff, 0xff, 0xff, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0xff,
0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff,
0xff, 0xff, 0xfe, 0x00, 0x07, 0xff, 0xc1, 0xff, 0xe0, 0x7f, 0xf0, 0x1f, 0xfc, 0x03, 0x00, 0x7f,
0xff, 0xff, 0xfc, 0x00, 0x1f, 0xff, 0xf7, 0xff, 0xf9, 0xff, 0xfc, 0x7f, 0xff, 0x0f, 0x80, 0x3f,
0xff, 0xff, 0xf8, 0x00, 0x3f, 0xff, 0xff, 0xff, 0xfd, 0xff, 0xfe, 0xff, 0xff, 0x9f, 0xc0, 0x1f,
0xff, 0xff, 0xf8, 0x00, 0x7f, 0x80, 0xff, 0x00, 0x7f, 0xc0, 0x3f, 0xf0, 0x0f, 0xfc, 0x00, 0x1f,
0xff, 0xff, 0xf0, 0x00, 0xfe, 0x00, 0x7f, 0x00, 0x3f, 0x80, 0x1f, 0xe0, 0x07, 0xf8, 0x00, 0x0f,
0xff, 0xff, 0xe0, 0x01, 0xfc, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x0f,
0xff, 0xff, 0xe0, 0x03, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x07,
0xff, 0xff, 0xc0, 0x07, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x03,
0xff, 0xff, 0xc0, 0x0f, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x03,
0xff, 0xff, 0x80, 0x0f, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x01,
0xff, 0xff, 0x80, 0x1f, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x01,
0xff, 0xff, 0x00, 0x3f, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x00,
0xff, 0xff, 0x00, 0x3f, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x00,
0xff, 0xfe, 0x00, 0x7f, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x00,
0xff, 0xfe, 0x00, 0x7f, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x00,
0xff, 0xfc, 0x00, 0xff, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x00,
0xff, 0xfc, 0x00, 0xff, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x00,
0xff, 0xfc, 0x01, 0xff, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x00,
0xff, 0xf8, 0x01, 0xff, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x00,
0xff, 0xf8, 0x03, 0xff, 0xf8, 0x00, 0x3e, 0x00, 0x1f, 0x00, 0x0f, 0xc0, 0x03, 0xf0, 0x00, 0x00,
0xff, 0xf0, 0x03, 0xff, 0xfc, 0x00, 0x7e, 0x00, 0x1f, 0x80, 0x1f, 0xe0, 0x07, 0xf8, 0x00, 0x00,
0xff, 0xf0, 0x07, 0xff, 0x7f, 0x80, 0xff, 0x00, 0x7f, 0xc0, 0x3f, 0xf0, 0x0f, 0xfc, 0x00, 0x00,
0xff, 0xf0, 0x07, 0xfe, 0x3f, 0xff, 0xff, 0xff, 0xfd, 0xff, 0xfe, 0xff, 0xff, 0x9f, 0xc0, 0x00,
0xff, 0xe0, 0x0f, 0xfc, 0x1f, 0xff, 0xf7, 0xff, 0xf9, 0xff, 0xfc, 0x7f, 0xff, 0x0f, 0x80, 0x00,
0xff, 0xe0, 0x0f, 0xf8, 0x07, 0xff, 0xc1, 0xff, 0xe0, 0x7f, 0xf0, 0x1f, 0xfc, 0x03, 0x00, 0x00,
0xff, 0xe0, 0x1f, 0xf0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0xff, 0xc0, 0x1f, 0xe0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0xff, 0xc0, 0x3f, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0xff, 0xc0, 0x3f, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0xff, 0x80, 0x7f, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0x80, 0x7f, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0x80, 0xfe, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0x00, 0xfc, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0x01, 0xf8, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xff, 0x01, 0xf0, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xfe, 0x03, 0xe0, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xfe, 0x07, 0xc0, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xfc, 0x0f, 0x80, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xf8, 0x1f, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xf0, 0x3e, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xe0, 0x7c, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0xc0, 0xf8, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0x81, 0xf0, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
0x03, 0xe0, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
};
void setup() {
Serial.begin(9600);
if (!display.begin(SSD1309_SWITCHCAPVCC, SCREEN_ADDRESS)) {
Serial.println(F("SSD1309 allocation failed"));
for (;;);
}
display.clearDisplay();
display.display();
}
void loop() {
// Display small heart icon centered
display.clearDisplay();
display.drawBitmap((SCREEN_WIDTH - 16) / 2, (SCREEN_HEIGHT - 16) / 2, heart_icon, 16, 16, SSD1309_PIXEL_ON);
display.display();
delay(3000);
// Display full-screen DIYables logo
display.clearDisplay();
display.drawBitmap(0, 0, diyables_logo, SCREEN_WIDTH, SCREEN_HEIGHT, SSD1309_PIXEL_ON);
display.display();
delay(3000);
// Invert display
display.invertDisplay(true);
delay(2000);
display.invertDisplay(false);
delay(1000);
}
※ NOTE THAT:
- Bitmap dimensions must not exceed 128×64 for this module.
Arduino Nano ESP32 Code — Contrast and Dim on SSD1309 OLED
The SSD1309 supports 256 contrast levels (0–255). Use setContrast() for fine control and dim() for a quick toggle between minimum brightness and the previously configured level.
/*
* This Arduino Nano ESP32 code was developed by newbiely.com
*
* This Arduino Nano ESP32 code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-nano-esp32/arduino-nano-esp32-ssd1309-oled-display
*/
/*
* DIYables OLED SSD1309 – Contrast & Dim
* Sweeps contrast from 0→255→0 then toggles dim mode on the 2.42" OLED with Arduino Nano.
*/
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <DIYables_OLED_SSD1309.h>
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C
DIYables_OLED_SSD1309 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
void setup() {
Serial.begin(9600);
if (!display.begin(SSD1309_SWITCHCAPVCC, SCREEN_ADDRESS)) {
Serial.println(F("SSD1309 allocation failed"));
for (;;);
}
// Draw a test pattern so the contrast changes are visible
display.clearDisplay();
display.fillRect(0, 0, 64, 32, SSD1309_PIXEL_ON);
display.fillRect(64, 32, 64, 32, SSD1309_PIXEL_ON);
display.setTextSize(1);
display.setTextColor(SSD1309_PIXEL_INVERSE);
display.setCursor(16, 28);
display.println(F("Contrast Demo"));
display.display();
delay(2000);
}
void loop() {
// Ramp up
for (int c = 0; c <= 255; c += 5) {
display.setContrast((uint8_t)c);
delay(30);
}
delay(1000);
// Ramp down
for (int c = 255; c >= 0; c -= 5) {
display.setContrast((uint8_t)c);
delay(30);
}
delay(1000);
// Quick dim toggle
display.dim(true); // minimum brightness
delay(2000);
display.dim(false); // restore
delay(2000);
}
Arduino Nano ESP32 Code — Custom External Fonts on SSD1309 OLED
The Adafruit GFX library includes dozens of scalable FreeFont typefaces (Serif, Sans, Mono — Regular, Bold, Italic, four sizes each). Activate any of them by including the corresponding header and calling setFont().
※ NOTE THAT:
- When an external font is active, the cursor Y coordinate refers to the text baseline, not the top-left corner.
- External fonts are stored in flash (PROGMEM). Use them thoughtfully to stay within the Arduino Nano ESP32 flash budget.
/*
* This Arduino Nano ESP32 code was developed by newbiely.com
*
* This Arduino Nano ESP32 code is made available for public use without any restriction
*
* For comprehensive instructions and wiring diagrams, please visit:
* https://newbiely.com/tutorials/arduino-nano-esp32/arduino-nano-esp32-ssd1309-oled-display
*/
/*
* DIYables OLED SSD1309 – External Fonts
* Cycles through three FreeFont typefaces on the 2.42" SSD1309 OLED with Arduino Nano.
*/
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <DIYables_OLED_SSD1309.h>
#include <Fonts/FreeSerif9pt7b.h>
#include <Fonts/FreeSansBold12pt7b.h>
#include <Fonts/FreeMono9pt7b.h>
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C
DIYables_OLED_SSD1309 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
void setup() {
Serial.begin(9600);
if (!display.begin(SSD1309_SWITCHCAPVCC, SCREEN_ADDRESS)) {
Serial.println(F("SSD1309 allocation failed"));
for (;;);
}
display.clearDisplay();
display.display();
}
void loop() {
// ── Built-in 5×7 font ──
display.clearDisplay();
display.setFont(NULL);
display.setTextSize(1);
display.setTextColor(SSD1309_PIXEL_ON);
display.setCursor(0, 0);
display.println(F("Built-in 5x7 font"));
display.println();
display.setTextSize(2);
display.println(F("DIYables"));
display.display();
delay(3000);
// ── FreeSerif 9pt ──
display.clearDisplay();
display.setFont(&FreeSerif9pt7b);
display.setTextSize(1);
display.setTextColor(SSD1309_PIXEL_ON);
display.setCursor(0, 14); // Y = baseline
display.println(F("FreeSerif 9pt"));
display.setCursor(0, 38);
display.println(F("DIYables OLED"));
display.setCursor(0, 58);
display.println(F("Hello World!"));
display.display();
delay(3000);
// ── FreeSansBold 12pt ──
display.clearDisplay();
display.setFont(&FreeSansBold12pt7b);
display.setTextSize(1);
display.setTextColor(SSD1309_PIXEL_ON);
display.setCursor(0, 20);
display.println(F("SansBold"));
display.setCursor(0, 52);
display.println(F("DIYables"));
display.display();
delay(3000);
// ── FreeMono 9pt ──
display.clearDisplay();
display.setFont(&FreeMono9pt7b);
display.setTextSize(1);
display.setTextColor(SSD1309_PIXEL_ON);
display.setCursor(0, 14);
display.println(F("FreeMono 9pt"));
display.setCursor(0, 34);
display.println(F("0123456789"));
display.setCursor(0, 54);
display.println(F("!@#$%^&*()"));
display.display();
delay(3000);
}
SSD1309 OLED Troubleshooting with Arduino Nano ESP32
If nothing appears on the 2.42-inch SSD1309 OLED after uploading your sketch, work through these checks:
- Verify wiring — confirm SDA→A4, SCL→A5, VCC→3.3V, and GND→GND are all correctly connected.
- Confirm the driver chip — this library targets the SSD1309. Modules with a different controller (e.g. SH1106) will not respond correctly.
- Check the I2C address — most SSD1309 modules default to 0x3C, but some use 0x3D. Use the I2C scanner sketch below to find the actual address:
// I2C address scanner — prints every detected device to the Serial Monitor
#include <Wire.h>
void setup()
{
Wire.begin();
Serial.begin(9600);
Serial.println("I2C Scanner");
}
void loop()
{
byte error, address;
int nDevices = 0;
Serial.println("Scanning...");
for (address = 1; address < 127; address++)
{
Wire.beginTransmission(address);
error = Wire.endTransmission();
if (error == 0)
{
Serial.print("I2C device found at address 0x");
if (address < 16)
Serial.print("0");
Serial.print(address, HEX);
Serial.println(" !");
nDevices++;
}
else if (error == 4)
{
Serial.print("Unknown error at address 0x");
if (address < 16)
Serial.print("0");
Serial.println(address, HEX);
}
}
if (nDevices == 0)
Serial.println("No I2C devices found");
else
Serial.println("done");
delay(5000);
}
Expected Serial Monitor output when the SSD1309 is detected:
COM6
Scanning...
I2C device found at address 0x3C !
done
Autoscroll
Clear output
9600 baud
Newline
- Ensure display() is called — the SSD1309 uses a frame buffer. Drawing functions modify RAM only; nothing appears on screen until you call oled.display().
- Check power supply — the 2.42-inch module draws more current than smaller OLEDs. Confirm that 3.3V can supply sufficient current (typically 20–40 mA at full brightness).