esp8266-oled-ssd1306

ThingPulse OLED SSD1306 (ESP8266/ESP32/Mbed-OS)

This is a driver for SSD1306 and SH1106 128x64, 128x32, 64x48 and 64x32 OLED displays running on the Arduino/ESP8266 & ESP32 and mbed-os platforms. Can be used with either the I2C or SPI version of the display.

This library drives the OLED display included in the ThingPulse IoT starter kit aka classic kit aka weather station kit. You can either download this library as a zip file and unpack it to your Arduino/libraries folder or find it in the Arduino library manager under "ESP8266 and ESP32 Oled Driver for SSD1306 display". For mbed-os a copy of the files are available as an mbed-os library.

It is also available as a PlatformIO library. Just execute the following command:

platformio lib install 2978

Service level promise

Credits

This library has initially been written by Daniel Eichhorn. Many thanks go to Fabrice Weinberg for optimizing and refactoring many aspects of the library. Also many thanks to the many committers who helped to add new features and who fixed many bugs. Mbed-OS support and other improvements were contributed by Helmut Tschemernjak.

The init sequence for the SSD1306 was inspired by Adafruit's library for the same display.

mbed-os

This library has been adopted to support the ARM mbed-os environment. A copy of this library is available in mbed-os under the name OLED_SSD1306 by Helmut Tschemernjak. An alternate installation option is to copy the following files into your mbed-os project: OLEDDisplay.cpp OLEDDisplay.h OLEDDisplayFonts.h OLEDDisplayUi.cpp OLEDDisplayUi.h SSD1306I2C.h

Usage

Check out the examples folder for a few comprehensive demonstrations how to use the library. Also check out the ESP8266 Weather Station library which uses the OLED library to display beautiful weather information.

Upgrade

The API changed a lot with the 3.0 release. If you were using this library with older versions please have a look at the Upgrade Guide.

Going from 3.x version to 4.0 a lot of internals changed and compatibility for more displays was added. Please read the Upgrade Guide.

Features

• Draw pixels at given coordinates
• Draw lines from given coordinates to given coordinates
• Draw or fill a rectangle with given dimensions
• Draw Text at given coordinates:
• Define Alignment: Left, Right and Center
• Set the Fontface you want to use (see section Fonts below)
• Limit the width of the text by an amount of pixels. Before this widths will be reached, the renderer will wrap the text to a new line if possible
• Display content in automatically side scrolling carousel
• Define transition cycles
• Define how long one frame will be displayed
• Draw the different frames in callback methods
• One indicator per frame will be automatically displayed. The active frame will be displayed from inactive once

Fonts

Fonts are defined in a proprietary but open format. You can create new font files by choosing from a given list of open sourced Fonts from this web app: http://oleddisplay.squix.ch Choose the font family, style and size, check the preview image and if you like what you see click the "Create" button. This will create the font array in a text area form where you can copy and paste it into a new or existing header file.

Hardware Abstraction

The library supports different protocols to access the OLED display. Currently there is support for I2C using the built in Wire.h library, I2C by using the much faster BRZO I2C library written in assembler and it also supports displays which come with the SPI interface.

I2C with Wire.h

…

for a SH1106:

#include <Wire.h>
#include "SH1106Wire.h"

SH1106Wire display(0x3c, SDA, SCL);  // ADDRESS, SDA, SCL
// By default SH1106Wire set I2C frequency to 700000, you can use set either another frequency or skip setting the frequency by providing -1 value
// SH1106Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, 400000); //set I2C frequency to 400kHz
// SH1106Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, -1); //skip setting the I2C bus frequency

I2C with brzo_i2c

#include <brzo_i2c.h>
#include "SSD1306Brzo.h"

SSD1306Brzo display(0x3c, SDA, SCL);  // ADDRESS, SDA, SCL

or for the SH1106:

#include <brzo_i2c.h>
#include "SH1106Brzo.h"

SH1106Brzo display(0x3c, SDA, SCL);  // ADDRESS, SDA, SCL

SPI

#include <SPI.h>
#include "SSD1306Spi.h"

SSD1306Spi display(D0, D2, D8);  // RES, DC, CS

or for the SH1106:

#include <SPI.h>
#include "SH1106Spi.h"

SH1106Spi display(D0, D2, CS);  // RES, DC, CS

In case the CS pin is not used (hard wired to ground), pass CS as -1.

API

Display Control

…

Pixel drawing

…

Text operations

…

Arduino Print functionality

Because this class has been "derived" from Arduino's Print class, you can use the functions it provides. In plain language, this means that you can use print, println and printf to the display. Internally, a buffer holds the text that was printed to the display previously (that would still fit on the display) and every time you print something, this buffer is put on the screen, using the functions from the previous section.

What that means is that printing using print and "manually" putting things on the display are somewhat mutually exclusive: as soon as you print, everything that was on the display already is gone and only what you put there before with print, println or printf remains. Still, using print is a very simple way to put something on the display quickly.

One extra function is provided: cls()

// cls() will clear the display immediately and empty the logBuffer, meaning
// the next print statement will print at the top of the display again.
// cls() should not be confused with clear(), which only clears the internal
// graphics buffer, which can then be shown on the display with display().
void cls();

> _Note that printing to the display, contrary to what you might expect, does not wrap your lines, so everything on a line that doesn't fit on the screen is cut off._

Ui Library (OLEDDisplayUi)

The Ui Library is used to provide a basic set of user interface elements called Frames and Overlays. A Frame is used to provide information to the user. The default behaviour is to display a Frame for a defined time and than move to the next Frame. The library also provides an Indicator element that will be updated accordingly. An Overlay on the other hand is a piece of information (e.g. a clock) that is always displayed at the same position.

…

Creating and using XBM bitmaps

If you want to display your own images with this library, the best way to do this is using a bitmap.

There are two options to convert an image to a compatible bitmap:

1. Using Gimp. In this case exporting the bitmap in an 1-bit XBM format is sufficient.
2. Using a converter website. You could also use online converter services like e.g. https://javl.github.io/image2cpp/. The uploaded image should have the same dimension as the screen (e.g. 128x64). The following output settings should be set:
   • Draw Mode: Horizontal - 1 bit per pixel
   • Swap bits in byte: swap checkbox should be checked.

The resulting bitmap can be put into a header file:

const unsigned char epd_example [] PROGMEM = {
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, ... 
    ...
};

Subsequently, it can be used like this:

display.clear();
display.drawXbm(0, 0, 128, 64, epd_example); // assuming your bitmap is 128x64
display.display();

Example: SSD1306Demo

Frame 1

This frame shows three things:

• How to draw an XMB image
• How to draw static text which is not moved by the frame transition
• The active/inactive frame indicators

Frame 2

Currently there are one fontface with three sizes included in the library: Arial 10, 16 and 24. Once the converter is published you will be able to convert any ttf font into the used format.

Frame 3

This frame demonstrates the text alignment. The coordinates in the frame show relative to which position the texts have been rendered.

Frame 4

This shows how to use define a maximum width after which the driver automatically wraps a word to the next line. This comes in very handy if you have longer texts to display.

SPI version

This shows the code working on the SPI version of the display. See demo code for ESP8266 pins used.

Selection of projects using this library

• QRCode ESP8266 (by @anunpanya)
• Scan I2C (by @hallard)
• ThingPulse Weather Station
• Meshtastic - an open source GPS communicator mesh radio
• OpenMQTTGateway - OpenMQTTGateway aims to unify various technologies and protocols into a single firmware. This reduces the need for multiple physical bridges and streamlines diverse technologies under the widely-used MQTT protocol.
• OpenAstroTracker - Open source hardware and software for Astrophotography. The firmware for the mounts supports displays and uses this library to drive them.
• Yours?