# Adafruit_SSD1306: driving SSD1306 OLEDs from Arduino, the interface choices, and the MCU gaps > Adafruit_SSD1306 is a C++ Arduino library for monochrome 128x64, 128x32 and 64x32 OLEDs over I2C or SPI. ATtiny85 is confirmed not to work, and the Adafruit GFX library must be installed as a separate step before any sketch will compile. **adafruit/Adafruit_SSD1306** — Arduino library for SSD1306 monochrome 128x64 and 128x32 OLEDs - Repository: https://github.com/adafruit/Adafruit_SSD1306 - Website: http://www.adafruit.com/category/63_98 - Stars: 2,109 · Forks: 1,035 - Language: C++ - License: NOASSERTION - Published: 2026-10-09 · Updated: 2026-10-09 · Language: en - Canonical page: https://hysenlabs.com/projects/adafruit-adafruit-ssd1306 ## I2C or SPI: pin count and the shared-bus trade-off The SSD1306 communicates with its host microcontroller through one of two buses. I2C needs 2 pins. SPI requires between 3 and 5 pins, depending on whether the chip select and hardware reset lines are wired separately or shared. The README states 2 to 5 pins as the interface requirement, which covers both buses across the common wiring schemes. Choosing between them comes down to a few practical constraints. I2C lets you share two wires with other devices, which is useful when a sensor or real-time clock is already on the bus. SPI handles higher frame rates, since the bus speed is not limited by the I2C clock ceiling. The WICED platform is an exception: the compatibility table marks it as tested and working, but with a note that no hardware SPI is available there, so the library falls back to bitbang mode. Bitbang SPI works, but it drives the clock in software rather than hardware, which is slower and occupies the CPU more fully during each transfer. The library depends on Adafruit GFX. That library provides geometric drawing operations such as lines, circles, bitmaps and text rendering, and the SSD1306 driver calls into it when drawing to the screen. It is available through the same Arduino IDE Library Manager, but installation of Adafruit_SSD1306 does not pull it in automatically. A project that installs only the SSD1306 library will fail to compile until the GFX library is added as a separate step. ## ATtiny85 is the one MCU in the doesn't-work column The compatibility table covers 15 MCU families. Fourteen of them appear in the tested-works column; one appears in the doesn't-work column. That one is ATtiny85, which covers the Adafruit Gemma, the Arduino Gemma and the Adafruit Trinket. Those boards are popular for wearable projects, because they are small and coin-cell-friendly. A wearable design that pairs one of them with an SSD1306 display will not work with this library. Among the boards that do work, the range spans from ATmega328-based Arduinos like the UNO to the RP2350 on a Raspberry Pi Pico 2W. ESP32 sits in the tested-works column without any special notes, and the CH32 RISC-V CH32V203 is listed alongside it. RTduino appears as a separate entry rather than a chip name: it is an Arduino-compatibility layer for the RT-Thread RTOS, so the library reaches whatever RT-Thread BSPs that layer supports. Nothing in the README covers microcontrollers that were not tested. A new board that shares its MCU family with a listed entry is a reasonable bet, but not a documented claim, and the table is the only reference available. ## Library Manager versus ZIP: the installation path and the rename the IDE requires The README describes the preferred method as installing through the Arduino IDE Library Manager. The library appears there by name, and installing it through that route adds it to the IDE library folder without any manual steps. The ZIP alternative starts with downloading the source from GitHub, unzipping it, and renaming the resulting folder to Adafruit_SSD1306 before placing it in the libraries folder. The rename is not cosmetic: the Arduino IDE requires that the folder name match the library name exactly, and a ZIP download from GitHub produces a folder with the branch name appended. After either method, the README recommends checking that the library folder contains Adafruit_SSD1306.cpp and Adafruit_SSD1306.h. That check catches a failed rename and confirms the library is where the IDE will look for it. The example sketches under examples/ are organized by display size and bus type. Six directories cover the common configurations: ssd1306_128x64_i2c, ssd1306_128x64_spi, ssd1306_128x32_i2c, ssd1306_128x32_spi, ssd1306_64x32_i2c and OLED_featherwing. Opening the matching example for your display and wiring before writing any custom code confirms that the library is installed correctly and that the display responds. ## Constructor-based display dimensions since v1.2, replacing per-sketch header edits Before version 1.2, selecting a display size required editing the library header file directly. Every project that used a different screen from the one set in the header needed a fresh edit of that shared file, which could break other sketches depending on the previous value. Version 1.2, released in November 2018, moved the display dimensions into the constructor. A sketch now declares its display geometry in its own code, so the shared library file does not change between projects. The same version added SPI transaction support and the option to specify the SPI bitrate, both requiring Arduino 1.6 or later. Non-default SPI and Wire (I2C) interfaces also became supported at that point, which matters for platforms that expose more than one hardware bus, or for boards where the default pins are occupied by other hardware. Old sketches written before v1.2 can continue to work through the header-based approach, according to the README. New code should use the constructor arguments. The 64x32 display size was added later in version 2.5.15, released on 2025-06-24, alongside a fix for the PICO_RISCV include on RP2350. ## SSD1306_NO_SPLASH trims PROGMEM on boards where flash is scarce Every call to begin() in the default configuration stores a splash image in PROGMEM and draws it to the display at startup. The SSD1306_NO_SPLASH preprocessor define, added in November 2021, removes both behaviors. A sketch that defines it before including the library header compiles without the image data and without the boot-time drawing call. The splash image data lives in splash.h at the repository root. On a board with limited flash and SRAM, such as an ATmega328-based board with 32 KB of flash and 2 KB of SRAM, the image data and the draw call each take a measurable share of the available space. Most SSD1306 applications do not display the Adafruit logo at startup by design, so the cost is often paid for nothing. Adding the following line before the library include in the sketch removes that cost: ```cpp #define SSD1306_NO_SPLASH ``` It is a compile-time choice, not a runtime option, so it applies to every build that includes the define and has no effect on builds that do not. ## Color define names changed in 2019, with a backward-compatibility opt-out In September 2019 the library replaced the color constants BLACK, WHITE and INVERSE with SSD1306_BLACK, SSD1306_WHITE and SSD1306_INVERSE. The change aimed to avoid name collisions with other libraries that define those same bare names. The old names were kept as aliases for backward compatibility, so existing sketches compile without changes. If a project brings in another library that also defines BLACK, WHITE or INVERSE, the aliases would create a conflict. Removing the aliases entirely requires adding this before the library include: ```cpp #define NO_ADAFRUIT_SSD1306_COLOR_COMPATIBILITY ``` After that, only the SSD1306_-prefixed names are defined, and the bare names are left to whatever the other library sets. This is a narrow issue, but it bites in specific configurations. Graphics libraries, LED matrix drivers and color-sensor libraries are common sources of conflicting name definitions. A compile error about a redefinition of BLACK or WHITE points to this option directly. ## ESP8266 pin conflict with I2C and the 500ms delay added for ESP32-C6 in v2.5.16 Two chip-specific problems are documented in the compatibility table and the release notes. For ESP8266, the OLED_RESET pin assignment matters when the sketch also uses I2C. The compatibility table note says to change OLED_RESET to a different pin if using default I2C pins D4/D5. Those two functions overlap at the same physical pins, and leaving OLED_RESET at its default while using I2C on D4 and D5 causes a conflict. ESP8266 is marked tested and working, so the fix works, but it requires a change to the sketch. Version 2.5.16, released on 2025-12-05, added a 500 millisecond delay at initialization specifically to fix the example sketches on the ESP32-C6. The release note gives this as the entire change in that version. ESP32 sits in the tested-works column without any qualification notes, so the ESP32-C6 issue was specific to that chip revision rather than a general ESP32 problem. ## BSD attribution requirement and three releases since mid-2025 The README calls the licence BSD and refers to license.txt for the full terms, adding that the attribution text at the top of the file must be included in any redistribution. GitHub classifies the licence as Other rather than a named BSD variant, which means reading license.txt is the only way to confirm the exact terms. That classification is relevant when a project has compliance requirements that match against SPDX identifiers. Three releases have shipped since mid-2025. Version 2.5.15 arrived on 2025-06-24 with 64x32 display support and a PICO_RISCV include fix for RP2350. Version 2.5.16 followed on 2025-12-05 with the ESP32-C6 initialization delay. Version 2.5.17 was released on 2026-05-29, and the last push to the repository was also on 2026-05-29. The library is not archived. Its scope is limited to the SSD1306 driver, so the API surface is stable: version 1.2 brought the last significant structural change, and the releases since then have been compatibility fixes and platform additions rather than redesigns. ## Conclusion Adafruit_SSD1306 fits any project where the MCU appears in the tested-works table and is not an ATtiny85. The Adafruit GFX library must be installed separately before the first compile. Before laying out a display, check whether the PROGMEM budget on the target board justifies keeping the splash image, and add SSD1306_NO_SPLASH if it does not. On ESP8266, verify that OLED_RESET is not assigned to D4 or D5 when also using I2C. The licence requires including the attribution text in any redistribution, and the terms sit in license.txt, not in a standard SPDX identifier. ## FAQ ### Does Adafruit_SSD1306 work with ATtiny85? The compatibility table marks ATtiny85 under Doesn't Work. This covers the Adafruit Gemma, the Arduino Gemma and the Adafruit Trinket, all of which use the ATtiny85 microcontroller. ### Does installing Adafruit_SSD1306 also install the Adafruit GFX library? The README states that the Adafruit GFX library must also be installed. It provides the graphics primitives the SSD1306 driver calls, and it is available through the Arduino IDE Library Manager under its own name. ### What display sizes does Adafruit_SSD1306 support? The library supports 128x64, 128x32 and 64x32 OLEDs. Support for 64x32 was added in version 2.5.15, released on 2025-06-24. Display dimensions are set in the constructor rather than in the header file, a change introduced in version 1.2. ### What does SSD1306_NO_SPLASH do? Defining SSD1306_NO_SPLASH before the library include removes the splash image from PROGMEM and skips drawing it during begin(). The option was added in November 2021 and is a compile-time switch. ### Can Adafruit_SSD1306 use both I2C and SPI? The library supports both interfaces. I2C requires 2 pins, while SPI requires between 3 and 5 pins. On WICED, only bitbang SPI is available since that platform has no hardware SPI. ## Sources - [adafruit/Adafruit_SSD1306 on GitHub](https://github.com/adafruit/Adafruit_SSD1306) - [Issues](https://github.com/adafruit/Adafruit_SSD1306/issues) - [Project website](http://www.adafruit.com/category/63_98) - [README](https://github.com/adafruit/Adafruit_SSD1306/blob/master/README.md) - [Releases](https://github.com/adafruit/Adafruit_SSD1306/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/adafruit-adafruit-ssd1306