SSD1306 on ESP8266

I recently completed some work on the 240*320 ILI-based boards on my kitchen-sink ESP8266 code which is designed to work with the home control system but basically is an ESP8266 board that responds to MQTT commands.

I’m very pleased with the display code but it came to my attention that the price has gone up recently – £4 - £7 depending where you go.  So having completed some work on the tiny but beautiful 128x32 OLED displays which are DIRT cheap, (see also the 64 pixel versions)  I thought I’d revisit the ESP code which already supports a number of I2c peripherals including my new Nano peripheral – and added in the SSD1306.


I’ve only used one font as you can’t do too much with 32 characters – but having already cracked using the GLCD fonts I’ve added in the ability to add a large weather icon. Everything happens instantly.

I can take this a lot further as I’ve now shoved all the font information into FLASH. For now, a good range of symbols accessed as ASCII characters. So basically 3 lines, the ability to put a border around the lot and to wipe any line – and to add a large weather icon over on the right.

All my commands are close to but not identical to simple JSON – so the command to set up and clear the screen for example is:


The 0 is for 32 pixel high displays, 1 for 64 pixel high displays. The example you see above is as follows…

{oled:"$s0$c0$r$l1A rainy day$l2today with a$l3little sun.$gH"}

Breaking that down – $s0 sets up the screen ($s1 for 64-pixel high displays)  $c0 clears the screen – a different number might’ve cleared just one line.  $r puts up the rectangle (32 high if set up for 32-pixel-high displays, 64 high if set up as 64-pixel-high displays) , $1 sets the cursor to line 1 – etc. At the end $gH puts up the graphic character for position H in the font.

And that’s it – send that as an MQTT message – instant result – or separate it up.

Links as follows:

Original VT100 terminal project -

Updates with new fonts etc… to make the screen more general purpose…

So now the software for the ESP8266 which talks via WIFI and MQTT, handles:

  • Dallas DS18b20 temperature chips directly
  • DHT11 and 22 chips directly
  • Digital I/O
  • Analog input
  • RGB serial LEDs including colour fades, sequences, HSV and much more
  • White level controls for the above – 1000-4000K
  • PWM LEDs including colour fades etc
  • Nextion displays directly
  • Various 7-segment displays
  • Debounced inputs and input counting with auto responses
  • Internal RTC
  • OTA
  • Twin SSIDs
  • I2C devices including:
    • My own Nano peripheral with pwm, analog inputs and digital I/O
    • ADC1115 AD convertor
    • BMP280 temperature and pressure
    • BME280 temperature,pressure, humidify
    • Seeed OLED
    • SD1136 OLED
    • PCA9685 multi-channel PWM
    • Port expanders
  • 60-LED clock display
  • RGB status indicator (or normal LED – or nothing)

In the process of updating the documentation this weekend for the new SSD1306 commands.


2 thoughts on “SSD1306 on ESP8266

  1. Hi Peter, I got some of these 128x32 OLED displays after reading this (I'm very suggestible) but I struggle to use them with a couple of my libraries that I use with the 128x64 OLEDs (ie the Squix library) [NOTE: Arduino]. It works ok with the U8G2 library but now I'm having trouble with creating fonts for that library. I'm keen to know which library you have been using.

    Cheers and thx for creating this awesome blog.

    1. Hi there

      Sorry but I don't use Arduino (except occasionally to back-convert some C# stuff to C. I use the latest SDK from Espressif and code in C in the "unofficial CHERTS environment. If you look at my code you'll see I've adopted GLCD format fonts - and also in the blog is a description of how to make them from TTF fonts on a PC. So now I can make just about anything... I have a 5x7 array which needed manually converting but the rest all the way up to 32+ pixels high were generated by GLCD Font Creator (and sometimes tweaked). Once you get the knack of it the format is simple.

Leave a Reply

Your email address will not be published. Required fields are marked *