esp8266-oled-ssd1306

The library abstracted hardware connections into specific subclasses of OLEDDisplay. Depending on your connection type, you should instantiate one of the following:

• SSD1306Wire: For I2C using the standard Arduino Wire library.
• SSD1306Brzo: For I2C using the faster brzo_i2c library.
• SSD1306Spi: For SPI connections.

Note: SSD1306 is maintained as an alias for SSD1306Wire for backwards compatibility if you are not using UI components.

To display custom images, convert them to 1-bit XBM format.

Conversion Steps:

1. Gimp: Export as 1-bit XBM.
2. Online (e.g., image2cpp):
   • Upload image (matching screen dimensions, e.g., 128x64).
   • Draw Mode: Horizontal - 1 bit per pixel.
   • Swap bits in byte: Check the swap checkbox.

Usage: Store the resulting array in a header file and use drawXbm() to render it.

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

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

You can install this library using several methods depending on your development environment:

Arduino IDE

Search for ESP8266 and ESP32 Oled Driver for SSD1306 display in the Arduino Library Manager.

PlatformIO

Execute the following command in your terminal:

platformio lib install 2978

mbed-os

Copy the following files directly into your mbed-os project:

• OLEDDisplay.cpp
• OLEDDisplay.h
• OLEDDisplayFonts.h
• OLEDDisplayUi.cpp
• OLEDDisplayUi.h
• SSD1306I2C.h

The OLEDDisplayUi class provides a high-level abstraction for managing multiple screens (frames) on an OLED display. It supports automatic or manual frame switching, animated transitions (sliding), and overlay drawing.

To use it, you must provide an array of FrameCallback functions via setFrames(). Each callback is responsible for drawing the content of a specific frame.

Key Concepts

• Frames: Individual screens that you define via FrameCallback functions.
• Transitions: Animations used when switching between frames (e.g., SLIDE_UP, SLIDE_LEFT).
• Overlays: Drawing functions that run independently of the current frame, useful for persistent UI elements like status bars.
• Indicators: A visual bar (often used to show progress through a menu) that can be configured with custom symbols and positions.

The OLEDDisplay class includes a log buffer mechanism that allows you to use print() and println() to create a scrolling log on the screen.

• cls(): Clears the display immediately and empties the logBuffer. This is different from clear(), which only clears the graphics buffer. After calling cls(), the next print() will start at the top of the display.
• drawLogBuffer(uint16_t x, uint16_t y): Manually draws the contents of the log buffer at the specified position. This is automatically called when using print(), println(), or printf().

To use the SSD1306 driver with the BRZO I2C abstraction, instantiate the SSD1306Brzo class. You must provide the I2C address, the SDA pin, the SCL pin, and optionally the display geometry.

Constructor Parameters:

• address: The I2C address of the SSD1306 display.
• sda: The GPIO pin number for the SDA line.
• scl: The GPIO pin number for the SCL line.
• g: The display geometry (defaults to GEOMETRY_128_64).

After instantiation, you must call connect() to initialize the BRZO I2C hardware.

To use a 64x48 pixel display with the standard Wire.h library, initialize the SSD1306Wire class and pass GEOMETRY_64_48 as the fourth argument to the constructor. This configuration has been tested with a WEMOS D1 mini Lite and a WEMOS OLED shield.

#include <Wire.h>
#include <SSD1306Wire.h>
SSD1306Wire display(0x3c, D2, D1, GEOMETRY_64_48 ); // WEMOS OLED shield

To use a 64x48 pixel display with the brzo_i2c library, initialize the SSD1306Brzo class and pass GEOMETRY_64_48 as the fourth argument to the constructor. This configuration has been tested with a WEMOS D1 mini Lite and a WEMOS OLED shield.

#include <SSD1306Brzo.h>
SSD1306Brzo display(0x3c, D2, D1, GEOMETRY_64_48 ); // WEMOS OLED Shield

The OLEDDisplay class implements the Arduino Print class, allowing you to use it like Serial. You can set up a LogBuffer to manage scrolling text lines.

1. Initialize the buffer with setLogBuffer(lines, chars), where lines is the number of lines and chars is the average characters per line. This returns false if memory is insufficient.
2. Write to the buffer using standard print() or println() methods.
3. Draw the buffer at a specific location using drawLogBuffer(x, y).
4. Call display() to refresh the screen.

Due to the renaming of the base class to OLEDDisplay and the UI library to OLEDDisplayUi, you must update the type definitions in your drawing callbacks.

Frame drawing callbacks must change from:

bool frame1(SSD1306 *display,  SSD1306UiState* state, int x, int y);

to:

void frame1(OLEDDisplay *display,  OLEDDisplayUiState* state, int16_t x, int16_t y);

Overlay drawing callbacks must change from:

bool overlay1(SSD1306 *display,  SSD1306UiState* state);

to:

void overlay1(OLEDDisplay *display,  OLEDDisplayUiState* state);