ssd1306: an OLED display driver built for 25 bytes of RAM

Written backwards from the memory budget

The ssd1306 library is an Arduino style C and C++ library for OLED displays, and its defining constraint is stated in the README: it was intended for very small microcontrollers with very little RAM, developed to use as few resources as possible while keeping powerful capabilities. The stated goals are four, to use as little RAM as possible, as little Flash as possible, to be as fast as possible, and to fit the Arkanoid game example onto an Attiny85. The number that makes this concrete is in the feature list: an Attiny85 with the Damellis package needs a minimum of 25 bytes of RAM to communicate with the OLED. The library has a modular structure and some modules can be excluded from compilation altogether, which is how a project on that hardware keeps its footprint down.

A dozen controllers behind one API

The controller list is long for a driver this small. It covers sh1106, ssd1306 in 128x64 and 128x32, ssd1325, ssd1327, ssd1331, ssd1351, il9163, st7735, ili9341, and the pcd8544 used in the Nokia 5110. It also drives VGA monitors, at 96x40 colour or 128x64 black and white, with direct D-sub output, and the README marks those as atmega328p only. The transport is i2c or SPI, and the i2c side has four implementations, a software one, the Arduino Wire library, AVR Twi and the Linux i2c-dev driver, while SPI covers the four wire Arduino SPI library, AVR Spi and the AVR USI module. The graphics primitives are the usual lines, rectangles, pixels and bitmaps, and text is printed with fonts of different sizes, with GLCD Font Creator named as the tool for making new ones.

The NanoEngine is what makes animation possible on a tiny chip

On a microcontroller with kilobytes of RAM, a full frame buffer is not an option, so the library ships a graphics engine, the NanoEngine, that supports double buffering on tiny microcontrollers. The README links a wiki page on using it for systems with low resources, and the effect is visible in the examples directory, which has a nano_engine folder with a snowflakes demo alongside the games folder. The games are the proof that the approach works. There is an Arkanoid implementation in the old API style and another in the new API style, and a simple Lode Runner game. The library can also be used on more capable hardware, the README says it works on anything from a Raspberry Pi to an ESP32, and that it can be ported to new platforms easily.

The same code runs on a desktop through SDL

One of the most useful features for a developer is that the demo code can be run without any OLED hardware. The library has a debug mode that executes code on a PC using SDL 2.0, and the platform table lists SDL emulation under both Linux, where the demo can run without real hardware via the SDL library, and Windows, via MinGW32 plus SDL. There is also an online simulation of one of the library's examples hosted on Wokwi. The practical consequence is that the drawing code, the fonts and the game logic can be developed on a laptop with a window and a mouse, and only the final hardware-specific wiring needs the real panel. Note the limits the README gives, that calculating non-ASCII display width is complicated, so the library includes simple heuristics for common cases.

Platforms, pins and the odd toolchain requirement

The supported platform table is extensive. Arduino covers Attiny85 and 45, Attiny84 and 44, Atmega328p and 168, Atmega32u4, Atmega2560, Digispark including the PRO version, ESP8266, ESP32, STM32 through stm32duino, Arduino Zero and Nordic nRF5 boards, either standard Arduino nRF52 or the Sandeep Mistry package. There is also plain AVR without the Arduino IDE, ESP32-IDF where the library can be used as an IDF component, Linux on Raspberry Pi through i2c-dev, spidev and sys/class/gpio, Energia on the MSP432P401R, the RP2040 through Arduino-Pico or Mbed, and the WCH32V003 over i2c only. Two details catch people out. Digispark users are told to check compilation options, because the library needs at least C++11 and C99 and the Digispark package misses the -std=gnu11 and -std=gnu++11 flags by default. Nordic users are told to enable C++11 in platform.txt with -std=gnu++11. The I2C pins can be changed through API functions, and the default SPI SCLK and MOSI pins come from the SPI library while DC, RST and CS are configurable.

Where the project stands, and the newer library to look at

The repository is not archived and the last push was on 2026-04-04. Tagged releases are v1.8.6 from 2025-09-07, v1.8.5 from 2024-03-09 and v1.8.3 from 2021-10-28, so the version line moves slowly and the recent work is mostly maintenance rather than new controllers. The licence is MIT with the licence text in the root and in the Makefile header, and the author is Alexey Dynda. The first line of the README is a pointer rather than a greeting: it asks you to check the newer C++ library lcdgfx, which it says consumes less memory and has a simple C++ API. That is an honest signal about where this code is heading. The repository itself carries a CMakeLists.txt, a component.mk for ESP-IDF, a library.properties for the Arduino IDE, a resources_consumption.txt, doxygen configuration and a set of example makefiles for AVR, ESP32, Linux, MinGW32 and STM32, and a Makefile whose targets build the documentation and run cppcheck over the sources with warnings, style, performance and portability checks enabled.

Editorial conclusion

ssd1306 suits a maker building a small OLED gadget on an Attiny or an ESP32 who needs text, bitmaps and animation without a heavy framework, and it suits anyone who wants to develop the display code on a desktop before flashing hardware. It does not suit a C++ project that wants a modern API, because the README points to the author's newer lcdgfx library, which consumes less memory and has a simpler C++ interface. Before adopting, check your controller against the supported display table, since the ssd1331, il9163, st7735 and ili9341 entries are SPI only.

Frequently asked questions

Official sources

1. Issues
2. lexus2k/ssd1306 on GitHub
3. License: MIT
4. README
5. Releases