IMPORTANT UPDATE:

We are launching a crowdfunding campaign for the Tinusaur OLED Kit based on the SSD1306 displays and this its page: https://www.crowdsupply.com/tinusaur/oled-display-kit.

There is also a short video explaining what is this new kit about:

Original page content below …

SSD1306xLED is a C library for working with the SSD1306 display driver to control dot matrix OLED/PLED 128×64 displays. It is intended to be used with the Tinusaur board but should also work with any other board based on ATtiny85 or similar microcontroller.

SSD1306xLED library for OLED/PLED 128x64

The 128×64 OLED is controlled by a SSD1306 circuit and could be interfaced over I²C.

The code could be divided in 3 pieces:

Communication over I²C with the SSD1306;
Sending graphical commands to the display;
High-level functions such as printing characters.

The I²C communication part is based on a code from the IIC_wtihout_ACK library that is available on the Internet but its original website (http://www.14blog.com/archives/1358) is no longer functional. Basically, the SSD1306xLED library makes SSD1306 to work with ATtiny85 and Tinusaur.

How to use it

Using this library to control an OLDE display is very easy. The necessary header files that should be included with the program could be found in the source code repository – the link is at the bottom of this document.

First, the controlling PINs should be specified in the source code:

#define SSD1306_SCL PB2 // SCL, Pin 3 on SSD1306 Board
#define SSD1306_SDA PB0 // SDA, Pin 4 on SSD1306 Board

There are defaults, of course, but make sure they work for you.

There is also I2C slave address specified in the source code but you probably don’t want to change that.

Second, the display controller should be initialized.

_delay_ms(40);
ssd1306_init();

The delay is necessary if the initialization is at the beginning of the program. This is required by the SSD1306 circuit as it needs time to initialize itself after power-on.

Then, the simplest example would be to clear the screen (fill it out with blanks) and output some text.

ssd1306_fillscreen(0x00);
ssd1306_setpos(0, 10);
ssd1306_string_font6x8("Hello World!");

The ssd1306_string_font6x8 function call will output at the specified by the ssd1306_setpos function coordinates the provided text using 6×8 character font.

Similarly, a bitmap could be output on the screen with the following code:

ssd1306_draw_bmp(0,0,128,8, img1_128x64c1);

The above function call specifies (0,0) coordinates, width of 128 pixels and height of 8 bytes – 64 pixels.

Documentation

This project often changes so more current information could be found in the source code repository – in the text files and source files as well.

Source code

The source code along with very simple example is available on Bitbucket at this address: https://bitbucket.org/tinusaur/ssd1306xled

This SSD1306xLED library still needs more work and some improvements.

65 thoughts on “SSD1306xLED”

Rodrigo says:

2017-02-19 at 15:14

Ol´á,

How do I use this SSD1306xLED library for my 6-pin display?

OLED_MOSI 9 //=> SDA
OLED_CLK 10 //=> SCK = SCL
OLED_DC 11 //=> A0 = D/C
OLED_CS 12 //=> não usa
OLED_RESET 13 //=> Reset

It is possible?
rodepedroso says:

2017-02-19 at 15:22

Olá,

How do I use this SSD1306xLED library for my 6-pin display?

OLED_MOSI 9 //=> SDA
OLED_CLK 10 //=> SCK = SCL
OLED_DC 11 //=> A0 = D/C
OLED_CS 12 //=> não usa
OLED_RESET 13 //=> Reset

It is possible?
Neven Boyanov says:

2017-03-05 at 23:24

You should first verify if your display has the I2C interface or not. The SSD1306xLED library is specifically developed for the I2C interface – that’s why it runs so fast.

You’ve got a “MOSI” pin and that may mean that it is serial OLED which means that it will not be supported by the library.
Sherm Stebbins says:

2017-07-06 at 22:21

I was able to get this working.. I’m new and would like a different larger font.. what is yhe best source?

Sherm
Neven Boyanov says:

2017-07-10 at 22:20

Check this source code: https://github.com/avitkinov/tinusaur-two-rows-led-matrix – it is a good start.
carlossilesblog says:

2017-12-24 at 22:25

I am using i2c OLED and ATtiny85; I’ve tried to use this library with Arduino IDE with no luck! IDE won’t recognize the commands, I’m guessing, since the library is written in C and not in CPP. Right?

Please let me know how could I use this library with Arduino IDE or should I just try WinAVR or similar?
Neven Boyanov says:

2017-12-31 at 12:21

Hi Carlos,
Yes, the issue is that the library is in C bu the Arduino IDE expects it to be C++.

Bellow is a fragment of code that I used in another project to make it work with Arduino IDE …

extern “C” { // BEGIN: Needed to work with Ardiuno IDE
#include “tinyavrlib/scheduler.h”
#include “max7219led8x8/max7219led8x8.h”
} // END: Needed to work with Ardiuno IDE
carlossilesblog says:

2018-01-08 at 00:34

Many thanks Neven!!

I’ll try that!
carlossilesblog says:

2018-01-13 at 03:19

Hi everyone! I must have been doing something wrong in the beginning, but as promised following my findings:

I coded it both ways: via WinAVR (using pure C programming) and via Arduino IDE. Why? You know…just for the heck of it! And it worked both ways.
Use of WinAVR is straight forward since the library is C based. For Arduino IDE I renamed the library from .c to .cpp and copied them in the libraries folder of my sketchbook usually in “..\\My documents\Arduino\libraries”.

I’ve modified: main() to setup() and for(;;) to loop(); I didn’t have to include “Arduino.h” nor included extern”C”. Beware, as Naven pointed out, that there might be sketches were you might need to do this.

At the beginning of the sketch I just included the following header files:
#include “ssd1306xled.h”
#include “ssd1306xled8x16.h”

in my sketch folder I’ve included the following files:
cpufreq.h
img0_128x64c1.h
img1_128x64c1.h

And it worked!
Thanks and happy hacking!
carlossilesblog says:

2018-01-17 at 03:20

Hi Neven! I’ve run test1 code in my attiny85 and works flawless. Now, I am trying to port the test1 code into an Arduino UNO (Atmega328P) and I’m failing to do so. This is what I tried so far:

SSD1306_SCL PC5 // Used to be PB2
SSD1306_SDA PC4//Used to be PB0

I did include a 16Mhz option in the cpufreq.h file (since it was expecting 8Mhz).

It compiles just fine but cannot see anything in the OLED display. Any ideas of what I could be missing? Do I need to change anything in the ssd1306_init() function?
erik says:

2018-02-24 at 04:52

compatibility with UTF-8 sources would be useful.
Albert says:

2018-06-27 at 14:34

Hi, I have problems compiling your code. I get this error:

sketch/num2str.c: In function ‘usint2decascii’:
num2str.c:32: error: ‘for’ loop initial declarations are only allowed in C99 mode
for (uint8_t pos = 0; pos < 5; pos++) // "pos" is index in array, so should be of type int.
^
sketch/num2str.c:32:2: note: use option -std=c99 or -std=gnu99 to compile your code
sketch/num2str.c: In function 'usint2binascii':
num2str.c:89: error: 'for' loop initial declarations are only allowed in C99 mode
for (uint8_t pos = 0; pos < USINT2BINASCII_MAX_DIGITS; pos++) { // "pos" is index in an array.
^
exit status 1
'for' loop initial declarations are only allowed in C99 mode

How can I fix this. (Board DigisparkPro)
Neven Boyanov says:

2018-08-14 at 12:02

Hi Albert,

What do you use to compile the code?
Jarnsaxa says:

2018-12-02 at 05:21

Hi. The execution gives this error in Atmel Studio7.

Done executing task “RunCompilerTask” — FAILED.
Done building target “CoreBuild” in project “GccApplication1.cproj” — FAILED.
Done building project “GccApplication1.cproj” — FAILED.

Build FAILED.
========== Build: 0 succeeded or up-to-date, 1 failed, 0 skipped ==========

And Is it necessary to include cpufreq.h file.
Neven Boyanov says:

2018-12-02 at 17:31

Hi, Jarnsaxa,

I don’t have much experience with Atmel Studio7, sorry. Bet let me see if I can help …

The “cpufreq.h” is part of this repo: https://bitbucket.org/tinusaur/tinyavrlib/src/default/tinyavrlib/

See if you need any of the definition in it. If not, just remove the include directive.