ESP8266: SSD1306 Oled Library Release

Do you like this post? Writing posts, developing libraries and programming online font creators is actually hard work. I order most of my electronics from a Chinese website called Banggood. It is save and the items usually arrive in good quality. With every order you do there by following this link you are supporting the blog. Thank you!

The “ESP8266 OLED SSD1306″ is an open source library which allows you to control those pretty OLED modules from our beloved ESP8266 module. Fabrice Weinberg cleaned up all the ugly pieces of code which I initially wrote caused by my near C/C++ illiteracy. He also added support for Pasko’s BRZO I2C library which is partially written in assembler and allows a much higher throughput over the I2C channel.

Fabrice’s video below compares the the two I2C implementations:

Other changes:

  • The font format was refactored for better memory efficiency and the web based font generator ( now lets you generate font files for the older library versions or the new ones
  • The hardware protocol level implementations (SPI, I2C) have been separated from the low level graphical functions. This affects how you instantiate the display classes
  • To be open for future support of similar displays the core classes were renamed to Oled* instead of SSD1306
  • More graphical functions have been added, including drawing of circles, non-vertical lines and a progress bar
  • In case you want to use the display for simple log output you can now use print(..) and println(..) and the library will take care of scrolling. See Fabrice’s video below:



For a full list of new features and how to upgrade your existing code please have a look at the comprehensive upgrade guide:

Please note: this release will break with your code based on the older 2.0.0 version. In case you have created fonts you’ll have to re-generate them as well. This also affects the Weather Station library!

Many thanks again to Fabrice Weinberg and all other contributors to make this release possible!

Posted by squix78


  1. Hi Daniel,
    I love your post.
    From first video I’ve noticed that you half way through (about 16.sec) you are uploading the firmware (OTA). I cannot find that sketch containing the world clock and OTA function. Would you be able to share the code?
    Thanks in advance.

  2. Hi Daniel,

    I am using your lib really for just basic text output (because the font support is great!). Is there a way to clear text on a line or erase a single line? The only way I have found is by setting the color to black and displaying the exact same text again. This is not convenient when you have no idea what that text might have been (like webpage data).

    Displaying space characters in either black or white does nothing, and displaying new text on the same line acts as an OR, and merges the new text into the old data.

    Ideally, just using space characters would be the best solution. I would hate to have to do a rectfill or something like that as I imagine that would require more CPU time.


    • Hi Jim. All your drawing should be between a display.clear() and a display.display() statement. The clear statement will clear the screen buffer and you can draw again whatever you want. So instead of clearing lines you should rather take care of what you want to keep for the next loop iteration. In case you are using the UI class then your code will be within a drawFrame function. There you won’t have to do the display.clear/display stuff, since the UI class takes care of it. Please check out the examples provided by the oled library:

  3. Hi Daniel,

    Many thanks for your hard work with the weather station project!. I am currently using the previous version of the weather station code in a home built clock/weather station project of my own. I have tried upgrading to the new weather station version but for whatever reason it does not seem to work correctly at the moment – probably a bug on my side! I was wondering though, do you have, or could you make available, a <3.0.0 version of the meteocons font – this would allow me to at least continue with my project until I have worked out why I cannot upgrade. Many thanks again James Vowles

  4. Daniel,

    OK, thanks for the explanation. So, it looks like this won’t work for my application because I don’t want to be clearing and re-drawing the display. I don’t have access to what was displayed previously, and I need to update just certain lines. I also have a limited amount of CPU time available. I guess I will look at spinning my on routines to poke at the OLED hardware. Rats… I really liked your font setup and tools.

    • Why not just putting the text into line variables and draw the variables in the drawing routines? Is there a repo or gist where I could understand better what you are trying to do? The library is using a buffer which gets “committed” to the display at once…

  5. Hi Daniel,
    Thank you for the quick reply – have installed the fonts and all working really well. Not sure what the problem is with the new version, again think its my end rather than your code. Unlike your system I’m multiplexing the I2C across 6 individual OLEDs – hrs/mins/secs across three, with the other three screens displaying date, weather information, emails connectivity status etc. I suspect the problem may be connected with the I2C speed in the new version – the circuit capacitance may be such that it requires different pull up resistor values on each of the 6 data lines? The version I’m using may be slower? Ive tried the new version out on a single screen with no problems. I’ll get the scope out and check whats happening at the I2C level.

  6. Daniel…yes tried the brzo driver also – same sort of symptoms when I ran it – screens flashed solid, text corrupt etc.. Again – I think the problem I’m having is due to me multiplexing the I2C signal. Everything works fine with the version of SSD1306Ui i’m using – looks really good in fact. I’ll track the problem down and let you know when I find the cause. Thanks again!

  7. Daniel…thanks for the great work on the OLED library for the ESP8266 (and your other postings). I’ve successfully implemented your weather station project using a .96 in. SSD1306 OLED, but also wanted to try out a 1.3 in. SH1106 I had. Unfortunately in converting the code I received an error in compiling when referencing the SH1106Spi.h header file, as per the example in the README; it doesn’t seem to exist in the library? Am I missing something, or is this a future — as yet to be implemented?

    • Hi Keith. Please make sure that you have the latest (and greatest;-)) version installed, which is currently 3.2.3. support for SH1101 was just added recently. That would bemy first suspect…

      • Daniel…thanks for the quick response, and yes, I checked the installed library version and it is 3.2.3. When I look at the GitHub page, the referenced header file isn’t there (SH1106Spi.h, though SSD1306Spi.h is), so when I downloaded the zip library, it isn’t included.

        • You are totally right, that was my mistake to put it on the readme page. We just didn’t have a device for testing yet and I just assumed (for symmetric reasons:-)) that we had also implemented that one… I will order one now for Fabrice and me and hopefully in a few days/weeks we will have one for testing…

  8. Ah, good, I’m not (quite) as crazy as I feared ;). I believe there are other lib’s available that support it, but was looking for a quick and easy change. I’ll stay tuned for the update…thanks again.

  9. Hi Daniel,
    I had been using your weather station for over a year. I wanted to make some changes but could not get it to compile. i have updated the source and the libraries but get the following error “/home/depand/sketchbook/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.cpp: In function ‘void wifi_wps_status_cb(wps_cb_status)’:
    /home/depand/sketchbook/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.cpp:593:14: error: ‘WPS_CB_ST_UNK’ was not declared in this scope
    case WPS_CB_ST_UNK:
    Error compiling.”
    Could you please advise what my problem is?

  10. Daniel…I’ve made quite a few changes to your original Weather Station code, and as part of this
    effort would like to re-generate the Meteocons font at various other sizes. Can your font generator do this, and if so, can you give me some hints at getting started? Also, can it be used to generate other open-source fonts than those included in your generator’s pull-down selection?

  11. Is it possble to run multilpe displays at once with the library? Example would be to combine the weather and planespotter on one esp with two displays.

    • Hi Sean. This worked for me in the past. I had the two displays running on different pins, since their I2C address is kind of hard coded. It reduced the performance a little but was still OK. You’ll have to instantiate to display objects. Let me know if it worked out!

  12. I’m using your library and it’s working beautifully for my esp8266-based thermostat. i’m using an array of small XBM images to animate a screen icon, and it looks great, but the images are the inverse of how they appear elsewhere (browser, image apps) i.e. black pixels are white, and vice versa. is there a switch somewhere in the library to invert an image, or should i try reconverting my images? thanks for the great work btw…

    • You can invert the hole display, but that’s probably not what you want. In the end the xbm format is just pixels, if I remember correctly so in theory you could just invert all the bytes and get the inverted image. Inverting can be done by XORing every byte with 0xff… But no satisfaction guaranteed;-)

  13. Hi Daniel,

    First of all, thanks a lot for sharing your code, is really great!!!
    I’ve been playing with the weather station kit for a couple of weeks. Currently I’m trying to display stock market information. Something like a stock market ticker. I want to display the values for different stocks in the same frame but at different times. Let me explain. I want to know the last price for the stock Apple and Netflix. Therefore I get the info from makitondemand and store it in an array. I added an additional frame (lets call it frame5). The first time frame5 is drawn I want to display the last price of Apple that is the first element in the array. The second time frame5 is drawn I want to display the last price of Netflix, that is the second element in the array. The third time frame5 is drawn I want to display again the first element of the array and so on…
    Is there a way to do that?


Leave a Reply