SSD1306 OLED display library

Arduino SSD1306 i2c OLED display Beside Windows programming I also do some embedded programming as well, often I use the Arduino or Wemos boards. For these projects I often use a cheap and easy to control 16x2 or 16x4 lcd display module and for most applications this is also suitable. Disadvantages are that they are quite large and that they have limited graphical capabilities. A large OLED screen is usually quite expensive but there are also cheaper OLED displays for sale with nice small screens, in two colors with a built-in controller based on I2C or SPI with a resolution of 128 x 64 or 64 x 48 pixels. First I went looking for a library but as usual, these are very extensive libraries for multiple types of displays and a lot of code that I don't actually need. Also, I am often not so satisfied with the quality of the code of these libraries and they are often bad on code size and used a lot of memory (which we don't have that much of on the Arduino anyway). After a few experiments I thought I would like to use these OLED displays in multiple projects and so I decided to write a very compact library myself for the Arduino with all basic functions and for two type OLED displays in all orientations. And because I believe in sharing knowledge and code, I also put this on this page online. Connecting the display was also a bit of a puzzle and I also describe this on this page. These OLED displays use the SSD1306 controller and I also found the datasheet and of course you can download that too. All in all, this page is a kind of general knowledge page about these SSD1306 based OLED displays. The code is clearly written and I think easily customizable. I wish you much success with your projects. Regards, Hein Pragt.

Different versions

Wemos D1 mini OLED display 64x48 The first display I used was the WeMos D1 mini OLED shield that’s 64x48 pixels and a size of 0.66inch with an I2C interface. The shield has many more pins because it can also be controlled differently but of course we like to use I2C because it only uses two I / O lines. With a size of 0.66inch it is a pretty small display but is very clear to read because it has a very high contrast. It uses the SSD1306 as an interface chip and uses the I2C address 0x3C or 0x3D which can be selected by a soldering bridge on the back of the pcb board, I leave them at the default value. The voltage is 3.3Volt but the I2C pins can be connected to the 5V Arduino without adjustment. However, the shield itself must be powered from the 3v3 connection of the Arduino. The display came with separate header pins and since you only have 4 connections anyway you can also solder the wires directly to the pcb board. The advantage of this display is that it is 64x48 pixel and it does not require that much memory in the Arduino processor.
Link: Website van de leverancier.

SSD1306 i2c OLED display 128x64 The second display I used is a fairly standard available OLED display with white pixels, a resolution of 128x64 and controlled by means of I2C and the SSD1306 driver IC. This shield also only needs two data lines and it consumes minimal current so it can be used fine in projects that need to be powered by a battery. The size of this screen is slightly larger than the previous one and is 26.0 x 15.0mm. The module also works on 3v3 Volt and can be powered by the 3v3 output of the Arduino where the I2C lines can simply be connected to the 5V Arduino pins. The I2C address of this OLED shield is standard 0x3C. The screen is very clear due to a very high contrast. Because it uses 128x64 pixels with the Arduino it uses 1 Kb of valuable sram.

The SSD1306 display controller

The SSD1306 is a single-chip CMOS OLED/PLED driver with controller for displays with a maximum resolution of 128 x 64. The IC contains a display controller with display RAM and a built-in oscillator so that it can be used with minimal external components. It has a built-in 256 steps brightness control. It has a 6800/8000 series compatible Parallel Interface, I2C interface or a Serial Peripheral Interface.

Link: Datasheet of the SSD1306 controller.

Link: Website SSD1306 controller.

Connecting the display

Although it says on the Internet in various places that you can also connect the displays to the 5V output, I prefer to stick to the specicfications and if there is 3v3 available on the Arduino I connect the vcc of the displays to this.

Connecting 128x64 display

SclA5 (SCL)
SdaA4 (SDA)

Connecting wemos 64x48 OLED display

D1A5 (SCL)
D2A4 (SDA)

Libray code and example

First download the libray here, this is my library for the Arduino, you can install it with the Arduino IDE in your own Arduino environment. Restart the IDE and look at the examples and see "oledtest128.ino" and the "oledtest64.ino". The library Works for both boards, When you want to save memory when using the 64x48 display you can reduce the buffer by installing in the libraries folder and in the SSD1306 folder the file SSD1306.cpp, change the defines to 64 and 48 and then compile the sketch again. I also use this library without any adjustment for the Wemos D1 mini board where standard the 64x48 OLED display module can be pinned up. Again, you can compile the "oledtest64.ino" sketch without any modification and go to upload your Wemos D1 mini board.

The code of this libray is compact and contains only a number of basic functions

    Ssd1306(uint8_t i2caddr,uint8_t width,uint8_t height,uint8_t orientation);
    void begin(void); 
    void oledSetPixel(int16_t x, int16_t y, uint16_t color);
    void oledDrawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint16_t color);
    void oledDrawRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color);
    void oledFillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color);
    void oledDrawCircle(int16_t x0, int16_t y0, int16_t r,uint16_t color);
    void oledDrawChar(int16_t x, int16_t y, unsigned char c, uint16_t color);
    void oledPrintLine(int16_t x, int16_t y, unsigned char *c, uint16_t color);
    void oledPrintLineP(int16_t x, int16_t y, unsigned char *c, uint16_t color);    
    void oledInvert(void); 
    void oledNormal(void);
    void oledCopyDisplayBuffer(void);
    void oledClearDisplayBuffer(uint8_t value);

These basic features allow you to create extensions in your own code yourself, I like libraries that only offer basic functions because I usually want to make things myself in my own way, that are just not in a default library or just different so that I have a large amount of code from a library that makes my code grow in size and is of no use to me. I wish you a lot of success with this code. The displays can actually display a few lines of text, with a font of 5x7 this is the distribution on the screen.

rows and colums oled screen

Attention! There is also a similar 1.3" OLED display that can be controlled by I2C but apparently this display uses a SH1106 controller instead of the SSD1306 that us used on the 0.96" OLED displays. My code only works with the SSD1306 controller.

Last update: 12-12-2021

Disclaimer: All pages on this Web site are copyrighted by Hein Pragt, unless otherwise noted. I strive for accuracy but cannot be held responsible for any errors in the content. For questions about the content of this site or persmission to copy you can contact me at: (email: is registered under KvK number: 73839426.