ESP8266 OLED display library release

Do you like this post? A regular project like the PlaneSpotter Color takes many hours of my free time to develop and maintain. Would you offer me a beer for my hard work if I was your neighbour? Modern technology called teleportation makes it easy to send me a beer. Just click here. Thank you!

Recently I released a new version of the esp8266-oled-ssd1306 library. This library allows you to control these wonderful little displays from a ESP8266 with little effort. When I first wrote the library for the WeatherStation I had the problem that 128×64 pixels never seemed enough space to display all the information. Then I added a feature set which allows you to describe the information in an number of frames which will then be side scrolled and displayed one after the other, just like a photo carousel often used on web pages.

Shifted Display Fix

With this new release I fixed a few very annoying issues. The most important (and also most annoying) issue was the shifting of the display content after reprogramming. I had suspected the init sequence for a long time but never had time to analyze it properly. It now turns out: I was completely wrong. The SSD1306 has various memory modes. In the mode I used you have to set the writing pointer to the used display memory. This pointer will be increased automatic with every write in to the memory. While this implicitly happens when you power cycle the display omitting this calibration can lead to unexpected results, such as shifted or distorted display content. Long story short: I fixed it and it seems to work now. This means while developing an application for the OLED display you no longer will have to unplug the ESP8266 to get a properly placed content!

More ASCII characters

Another fix was not really in the library but in my hacky Java program which I wrote to convert TTF fonts to a proprietary format used in the library. Out of considerations for space I had initially decided to include fonts only containing the charachters 32-127 of the ASCII table. But it so happens the the degree symbol “°” is in the extended ASCII table at charachter 176. Since I use the library and the fonts in the WeatherStation this character is very useful. So in the new release I added the full printable character set from 32-255.
In this picture you can see its use:

Using the new extended character set, containing the “°” character among others.
Displaying data from my balcony, measured with the ClimateNode
To update the library go to the library manager, search for “esp8266-oled-ssd1306” and click update.

One last thing…

Ok, maybe my announcement is not comparable to those of late Steve but still I’m happy to have a new product in my small shop: the ClimateNode. It contains a NodeMCU V1.0, a DHT22 to measure temperature and humidity and a USB cable. To get it to run you’ll need 3 female-female dupont jumpers which are part of the WeatherStation Kit. How you can set the hole thing up, soon, on this channel;-). So stay tuned! You can order it now here: 
The new ClimateNode to measure temperature and humidity on
your balcony, basement, bathroom, etc.

Posted by squix78


    • Have you updated to the latest version 1.0.1 of the ssd1306 oled library? I extended the char range to the upper ASCII table, where in my oppinion the umlauts reside? How does "not properly" look like? Can you create an issue in the github repository with "new issue"?

    • I have also noticed this problem with the "äöåÄÖÅ" characters, however, the display also always shows a "Â" sign in front of the degree sign. This could maybe also be an encoding issue or something like that. I am using a call like this for example: "display.drawString(65 + x, 0 + y, "Tänään");"

    • I had troubles with the degree symbol too.
      I found the answer in the method SSD1306::utf8ascii(). An initial extended "code switch character" has to be sent before the actual degree symbol.

      Here, I declare the degree symbol and then assemble a display string:
      char degSymbol[3] = { 0xC2, 0xB0, 0x00 }; // degree symbol(0xB0 or 176) in the extended ascii set
      // 0xC2 is shift/table selector character
      String comfy = "23";
      comfy.concat( degSymbol );
      comfy.concat( "C" );

      Now comfy prints in the serial terminal as: 23°C
      But it displays correctly in drawString(x,y, comfy )

      Then I found Dani had explained this in a subsequent post on 12Dec2015 – "ESP8266: Fixing extended ASCII issues in SSD1306 OLED library"

      Thank you for this work Dani. It's been put to good use!

  1. I noticed that there is no longer support for the "void setFontScale2x2(bool isFontScaling2x2);" method in the library. Why is that and could that be fixed? Thanx for a great piece of code BTW.

    • Hi Juho. Looks I missed your question for almost a month. Well in the meantime I have a good answer: I removed it since now you can add font sizes and styles as you want. You can create fonts by using this tool here:
      For me the 2×2 font scaling was a bad workaround to have big characters. Now you can use nicely rendered characters in any font that is available. I might extend the tool in the future to use any font you like…

  2. Я пытаюсь повторить ваш проект уже 3 недели, но ничего не получается! Мой OLED Display – Sh1106, А Ваши библиотеки с ним не работают! Могли бы Вы Исправить библиотеки так, чтобы они работали с дисплеями Sh1106 и SSD1306? Спасибо. Николай из России.

  3. First of all: thank you for making this nice library. It is the only one that lets me use my I2C-based OLED screens on my WeMos D1 Minis. But I have one question: could you add an extra example? A super-simple example with no frames or overlays. To use when you simply want to access and write to the screen from the loop with simple commands?

    All the examples I can find includes several frames. And some times I only want a display to show a distance, the time or something else. I am fairly new to arduino coding and all my attempts to simplify the code ends in a black screen…

  4. I'd like to second the previous post. I'm trying to pair down your example, but frankly it's a bit over my head. If you can point me to a basic Hello World, it would be greatly appreciated.

    I've been searching for a nice ESP/OLED lib and your's looks like it. Not to mention the font converter.

    In any case, wonderful work! I bought you a well deserved beer.
    Thanks, John

  5. To follow up on previous, I did figure out how to do a basic Hello World display (missed display.display :).

    It may interest you that your lib seems to work with ATmega chips with a small change. I have it working with the Pro Mini. Basically it's an "#ifdef ESP8266" around the 2 calls to Wire.begin() to not pass the SDA & SCL. Of course there is not much memory left – ~12k with 2 fonts used.

    Again, thanks for a great library.

  6. Love your work on this library – and it’s fast! How hard would a scrolling display capability be? ie a print/println capability with smooth scrolling on reaching the bottom of the display. John

    • Hi John. Based on your idea Fabrice Weinberg has implemented this in the new 3.0.0 release of the library!

  7. Hi. Could you post some sample code showing a scrolling using the new logBuffer? I’ve tried but all I get are characters that overwrite each other on the screen & never scroll.
    for (int i=0; i<10; i++) {

Leave a Reply