thingpulse / esp8266-oled-ssd1306

Driver for the SSD1306 and SH1106 based 128x64, 128x32, 64x48 pixel OLED display running on ESP8266/ESP32

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

This is a ThingPulse prime project. See our open-source commitment declaration for what this means.

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

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

// for 128x64 displays:
SSD1306Wire display(0x3c, SDA, SCL);  // ADDRESS, SDA, SCL
// for 128x32 displays:
// SSD1306Wire display(0x3c, SDA, SCL, GEOMETRY_128_32);  // ADDRESS, SDA, SCL, GEOMETRY_128_32 (or 128_64)
// for using 2nd Hardware I2C (if available)
// SSD1306Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_TWO); //default value is I2C_ONE if not mentioned
// By default SD1306Wire set I2C frequency to 700000, you can use set either another frequency or skip setting the frequency by providing -1 value
// SSD1306Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, 400000); //set I2C frequency to 400kHz
// SSD1306Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, -1); //skip setting the I2C bus frequency

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

// Initialize the display
void init();

// Free the memory used by the display
void end();

// Cycle through the initialization
void resetDisplay(void);

// Connect again to the display through I2C
void reconnect(void);

// Turn the display on
void displayOn(void);

// Turn the display offs
void displayOff(void);

// Clear the local pixel buffer
void clear(void);

// Write the buffer to the display memory
void display(void);

// Inverted display mode
void invertDisplay(void);

// Normal display mode
void normalDisplay(void);

// Set display contrast
// really low brightness & contrast: contrast = 10, precharge = 5, comdetect = 0
// normal brightness & contrast:  contrast = 100
void setContrast(uint8_t contrast, uint8_t precharge = 241, uint8_t comdetect = 64);

// Convenience method to access
void setBrightness(uint8_t);

// Turn the display upside down
void flipScreenVertically();

// Draw the screen mirrored
void mirrorScreen();

Pixel drawing

/* Drawing functions */
// Sets the color of all pixel operations
// color : BLACK, WHITE, INVERSE
void setColor(OLEDDISPLAY_COLOR color);

// Draw a pixel at given position
void setPixel(int16_t x, int16_t y);

// Draw a line from position 0 to position 1
void drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1);

// Draw the border of a rectangle at the given location
void drawRect(int16_t x, int16_t y, int16_t width, int16_t height);

// Fill the rectangle
void fillRect(int16_t x, int16_t y, int16_t width, int16_t height);

// Draw the border of a circle
void drawCircle(int16_t x, int16_t y, int16_t radius);

// Fill circle
void fillCircle(int16_t x, int16_t y, int16_t radius);

// Draw an empty triangle i.e. only the outline
void drawTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2);

// Draw a solid triangle i.e. filled
void fillTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2);

// Draw a line horizontally
void drawHorizontalLine(int16_t x, int16_t y, int16_t length);

// Draw a lin vertically
void drawVerticalLine(int16_t x, int16_t y, int16_t length);

// Draws a rounded progress bar with the outer dimensions given by width and height. Progress is
// a unsigned byte value between 0 and 100
void drawProgressBar(uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t progress);

// Draw a bitmap in the internal image format
void drawFastImage(int16_t x, int16_t y, int16_t width, int16_t height, const uint8_t *image);

// Draw a XBM
void drawXbm(int16_t x, int16_t y, int16_t width, int16_t height, const uint8_t *xbm);

Text operations

// Draws a string at the given location, returns how many chars have been written
uint16_t drawString(int16_t x, int16_t y, const String &text);

// Draws a String with a maximum width at the given location.
// If the given String is wider than the specified width
// The text will be wrapped to the next line at a space or dash
// returns 0 if everything fits on the screen or the numbers of characters in the
// first line if not
uint16_t drawStringMaxWidth(int16_t x, int16_t y, uint16_t maxLineWidth, const String &text);

// Returns the width of the const char* with the current
// font settings
uint16_t getStringWidth(const char* text, uint16_t length, bool utf8 = false);

// Convencience method for the const char version
uint16_t getStringWidth(const String &text);

// Specifies relative to which anchor point
// the text is rendered. Available constants:
// TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT, TEXT_ALIGN_CENTER_BOTH
void setTextAlignment(OLEDDISPLAY_TEXT_ALIGNMENT textAlignment);

// Sets the current font. Available default fonts
// ArialMT_Plain_10, ArialMT_Plain_16, ArialMT_Plain_24
// Or create one with the font tool at http://oleddisplay.squix.ch
void setFont(const uint8_t* fontData);

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.

/**
 * Initialise the display
 */
void init();

/**
 * Configure the internal used target FPS
 */
void setTargetFPS(uint8_t fps);

/**
 * Enable automatic transition to next frame after the some time can be configured with
 * `setTimePerFrame` and `setTimePerTransition`.
 */
void enableAutoTransition();

/**
 * Disable automatic transition to next frame.
 */
void disableAutoTransition();

/**
 * Set the direction if the automatic transitioning
 */
void setAutoTransitionForwards();
void setAutoTransitionBackwards();

/**
 *  Set the approx. time a frame is displayed
 */
void setTimePerFrame(uint16_t time);

/**
 * Set the approx. time a transition will take
 */
void setTimePerTransition(uint16_t time);

/**
 * Draw the indicator.
 * This is the default state for all frames if
 * the indicator was hidden on the previous frame
 * it will be slided in.
 */
void enableIndicator();

/**
 * Don't draw the indicator.
 * This will slide out the indicator
 * when transitioning to the next frame.
 */
void disableIndicator();

/**
 * Enable drawing of all indicators.
 */
void enableAllIndicators();

/**
 * Disable drawing of all indicators.
 */
void disableAllIndicators();

/**
 * Set the position of the indicator bar.
 */
void setIndicatorPosition(IndicatorPosition pos);

/**
 * Set the direction of the indicator bar. Defining the order of frames ASCENDING / DESCENDING
 */
void setIndicatorDirection(IndicatorDirection dir);

/**
 * Set the symbol to indicate an active frame in the indicator bar.
 */
void setActiveSymbol(const uint8_t* symbol);

/**
 * Set the symbol to indicate an inactive frame in the indicator bar.
 */
void setInactiveSymbol(const uint8_t* symbol);

/**
 * Configure what animation is used to transition from one frame to another
 */
void setFrameAnimation(AnimationDirection dir);

/**
 * Add frame drawing functions
 */
void setFrames(FrameCallback* frameFunctions, uint8_t frameCount);

/**
 * Add overlays drawing functions that are draw independent of the Frames
 */
void setOverlays(OverlayCallback* overlayFunctions, uint8_t overlayCount);

/**
 * Set the function that will draw each step
 * in the loading animation
 */
void setLoadingDrawFunction(LoadingDrawFunction loadingDrawFunction);

/**
 * Run the loading process
 */
void runLoadingProcess(LoadingStage* stages, uint8_t stagesCount);

// Manual control
void nextFrame();
void previousFrame();

/**
 * Switch without transition to frame `frame`.
 */
void switchToFrame(uint8_t frame);

/**
 * Transition to frame `frame`. When the `frame` number is bigger than the current
 * frame the forward animation will be used, otherwise the backwards animation is used.
 */
void transitionToFrame(uint8_t frame);

// State Info
OLEDDisplayUiState* getUiState();

// This needs to be called in the main loop
// the returned value is the remaining time (in ms)
// you have to draw after drawing to keep the frame budget.
int8_t update();

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?

esp8266-oled-ssd1306's Issues

Font Converter with Dialog font - 2 issues

I made the following font - Dialog, Bold, 10pts, >=3.0

The first problem is that the array name comes out as:
const char Dialog.bold_Bold_10[] PROGMEM = {
(The dot after "Dialog" causes a compile error.)

Changing the line to "Dialog_Bold_10" allows it to compile.

Second problem:
This font worked fine when I made it for v2.0 of the SSD1306 lib.
However when made for the 3.0 lib, it fails to display an uppercase 'M'.
(Widest letter?)

Thanks for a great lib!

FWIW the lib seems to work with ATmega chips if you make the following change in the init()

ifdef ESP8266 // wire args only if ESP

Wire.begin(mySda, mySdc);

else

Wire.begin();

endif

feature request, turn off indicator

A useful addition would be allowing 'NONE' to be included in the following setting which would prevent display of the any indicators. This would leave more space for other screen content in frames, if needed.

// TOP, LEFT, BOTTOM, RIGHT, NONE
ui.setIndicatorPosition(NONE);

As an extension of the above, allow a list of frame numbers which should include indicators, as in:

// TOP, LEFT, BOTTOM, RIGHT, NONE. [int frame1, int frame2, ... int framen]
ui.setIndicatorPosition(BOTTOM, 1, 3, 4);

The above example would show the frame indicators at the bottom for frames 1, 3, and 4 only.
if only TOP, LEFT, BOTTOM or RIGHT were included, the frame indicators would be shown on all frames. if NONE were included, there would be no frame indicators.

Improving the text performance

I am experimenting with improving the rendering performance of text. To archive better performance I had to change the font definition to include a direct jump table, so there is no need to calculate the address each time you need to jump to the correct char. I also added a flag to the jump table (eg. 0xFF, 0xFF) to signal that the char is not printable, removing it completely from the font table.
This jump table consist of 3 bytes. The first two are used for the jump (giving us 2^16 addressable bytes) and the last byte is used to define the width of the char. You can see the usage in the new drawString function.

After doing all that I investigated a bit in how the display buffer is structured and noticed that it has a curious layout in which each byte corresponds to 8 pixel in height. To get the best performance I designed an image format which is basically a flipped XBM to have a better 1:1 mapping to each pixel in height. I added an internal function called drawInternal which takes such an image an draws it in as little buffer modifications as possible.

Due to the optimisation the new font definitions are a little smaller too. (approx. 2kb)

If you are interested in investigating further in this direction I would create a pull request to discuss how we can further improve text render performance (I think there are some opportunity to cache some calculations).

These improvements could also be made for drawing calls like drawRect and fillRect.

Use multiple OLEDs via I2C

When trying to use multiple OLEDs I get the following error:

Linking .pioenvs\nodemcuv2\firmware.elf
.pioenvs\nodemcuv2\src\main.o:(.text._ZN11OLEDDisplayC2Ev[_ZN11OLEDDisplayC5Ev]+0x0): undefined reference to `vtable for OLEDDisplay'

Code:
SH1106 display(0x3c, D1, D2);
SH1106 display2(0x3c, D3, D4);

The same happens when using different i2c addresses:
SH1106 display(0x3c, D1, D2);
SH1106 display2(0x3d, D1, D2);

drawString with Umlauts are not working

When I use a Umlaut in a display.drawString-Function inside a frameCallback it shows Garbage on the Display.

display.drawString(0 + x, 25 + y, "äöüÄÖÜ");

gives me something like:

Happens with v1.0.1 of the ssd1306 oled library.

OverLays are written on top of each other

While using the SSD1306UiDemo, I've modified this one in order to have:

`void msOverlay1(OLEDDisplay display, OLEDDisplayUiState state) {
display->setTextAlignment(TEXT_ALIGN_RIGHT);
display->setFont(ArialMT_Plain_10);
display->drawString(128, 0, String(millis()));
}

void msOverlay2(OLEDDisplay display, OLEDDisplayUiState state) {
display->setTextAlignment(TEXT_ALIGN_RIGHT);
display->setFont(ArialMT_Plain_10);
display->drawString(128, 0, String("TESTTESTTEST"));
}`

Then:

// Overlays are statically drawn on top of a frame eg. a clock OverlayCallback overlays[] = { msOverlay1,msOverlay2 }; int overlaysCount = 2;

Running the example with these modifications, and you can see that "TESTTESTTEST" is written on top of the current milliseconds.

disableIndicator() doesn't disable indicators

Following sequence the indicators are still displayed:

ui.setTargetFPS(30);
ui.disableIndicator(); <- no effect
ui.setFrameAnimation(SLIDE_LEFT);
ui.setFrames(frames, numberOfFrames);
ui.setOverlays(overlays, numberOfOverlays);
ui.init();

drawFastImage internal format question

I am using version 3, but have problems with the internal format. Please could you help me with an example of such a file and the way to do the call, so I can start playing around with it?

Add/Link to more examples

We should have a section where we link to more advanced examples. And add some more examples covering all the functions of this library.

SSD1306Demo.ino typos

This:

// You can change the transition that is used
// SLIDE_LEFT, SLIDE_RIGHT, SLIDE_TOP, SLIDE_DOWN

should be (TOP should be UP):

// You can change the transition that is used
// SLIDE_LEFT, SLIDE_RIGHT, SLIDE_UP, SLIDE_DOWN

This:

display->setFont(ArialMT_Plain_16);
display->drawString(0 + x, 20, "Arial 16");

should be (missing '+ Y'):

display->setFont(ArialMT_Plain_16);
display->drawString(0 + x, 20 + y, "Arial 16");

This:

display->setFont(ArialMT_Plain_24);
display->drawString(0 + x, 34, "Arial 24");

should be (missing '+ Y'):

display->setFont(ArialMT_Plain_24);
display->drawString(0 + x, 34 + y, "Arial 24");

Also, the images here: https://github.com/squix78/esp8266-oled-ssd1306
do not match what the current version of SSD1306Demo.ino displays.

(Thanks for a fantastic SSD1306 driver, BTW.)

Cyrillic fonts

Hello. I really like you project WeatherClock, but i cannot use cyrillic fonts. and i don't know to do this. Thanks.

Black text on white background.

I have recently upgraded from V2.0.2 to the latest code and have issues when rendering black text on a white background. This used to work as expected in version 2 but now the rendering results in garbage. Is this a bug or am I missing something in the changes?

Best Practice to go to a transition on event ?

Hi there,
Sorry, it's more a question then an issue. If there is other channel for this type of request, just let me know.

I'm using UI with automatic transition (4 callbacks) with great success, but in some case (external event) I need to go immediately to a specific transition whatever where I am (for example I'm in # 1 and I want to go immediately to # 3)
Then let the others continue as usual -> # 4, # 1, # 2, # 3 ...
I do not need to go back the one "interrupted" just continue.
What's the best practice to achieve this ?
Thanks for your help

Compiler error "redefinition of 'const char ArialMT_Plain_10 []'"

This is caused by the multiple inclusion of SSD1306Fonts.h. If I choose Sketch->Include Library->ESP8266 Oled Driver... in the Arduino IDE, this is included in my sketch:

#include <SSD1306.h>
#include <SSD1306Fonts.h>
#include <SSD1306Ui.h>

But SSD1306Fonts.h is also included in SSD1306Ui.h. So either the include of SSD1306Fonts.h in the sketch is unnecessary, or a #pragma once should be added to SSD1306Fonts.h.

But really, the file should be split into a .h and a .cpp file. The definitions should go in the .h file, the implementation should go in the .cpp file.

Can't draw Bitmap

I'm trying to draw a bitmap using the drawBitmap() function, but I can't show the image correctly.
I created the array using LCD Assistant (http://en.radzio.dxp.pl/bitmap_converter) and replaced the one in the demo project but the image is messed up. I also tried drawXbm() without results. How did you prepared the array for the WiFi logo in the demo?

contributing & naming conventions

I am an experienced C++ programmer (embedded). I love the work you have done and would like to participate. However, I noticed that the naming conventions are not ideal. Would you allow me to update the naming of the variables? I also have a few other updates in mind after this.

sprintf format

Hi Daniel,

I must say firstly awesome work you have done, great examples.

I am trying to get the full digits of a clock to display, initial values are int's using sprintf to format so that leading zero is not truncated and displayed. for example 07:01 and not 7 : 1

Any ideas on where I may be going wrong?

char bufHR[3] = "";
sprintf(bufHR, "%2d", RTC_Hour); // format to 2 decimal places for display output
display.drawString(15, 20, bufHR);

Display works but still only displays single digit and not leading zero.

Thanks

Dans

PS: I will try different formats such as: "%02d" any other suggestions please let me know.

Arduino Uno - error: '_min' was not declared

Hi, i'm using esp8266-oled-ssd1306 library for may project.
But while loading the sketch to the Arduino, I got the following error?

error: '_min' was not declared in this scope
minBoundY = _min(minBoundY, y);

The same happens to _max?

Could you explain to me how to get around this problem, please?
Thank you!

Compile Error

Hi, Trying to compile the example. Ubuntu 14.04 VM, generic esp-12.

Arduino: 1.6.6 (Linux), Board: "Generic ESP8266 Module, Serial, 80 MHz, 40MHz, DIO, 115200, 4M (1M SPIFFS), ck"

SSD1306Demo:55: error: 'drawFrame1' was not declared in this scope
void (_frameCallbacks[])(int x, int y) = {drawFrame1, drawFrame2, drawFrame3, drawFrame4};
^
SSD1306Demo:55: error: 'drawFrame2' was not declared in this scope
void (_frameCallbacks[])(int x, int y) = {drawFrame1, drawFrame2, drawFrame3, drawFrame4};
^
SSD1306Demo:55: error: 'drawFrame3' was not declared in this scope
void (_frameCallbacks[])(int x, int y) = {drawFrame1, drawFrame2, drawFrame3, drawFrame4};
^
SSD1306Demo:55: error: 'drawFrame4' was not declared in this scope
void (_frameCallbacks[])(int x, int y) = {drawFrame1, drawFrame2, drawFrame3, drawFrame4};
^
exit status 1
'drawFrame1' was not declared in this scope

This report would have more information with
"Show verbose output during compilation"
enabled in File > Preferences.

remove or add frames during runtime

Is it possible to remove or add frames during runtime?

support for SH1106

Hi,
Any chance of supporting the SH1106 as well?
The only difference seems to be the size of the memory buffer, like described here
https://forum.arduino.cc/index.php?topic=256374.0

There is only one small difference between SSD1306 and SH1106: The SH1106 controller has an internal RAM of 132x64 pixel. The SSD1306 only has 128x64 pixel.
First problem for standard 128x64 OLEDs with SH1106 controller is: How is the 128x64 window mapped into the 132x64 RAM?
It seems, that the 128x64 OLED is centered in most cases within the 132x64 area, that means pixel (2,0) in ram is pixel (0,0) on the display.
For u8glib, the update for the SH1106 was very small. I just had to shift the display by 2 pixel. This is more complicated with the Adafruit lib.

Cheers

/edit ebay 1.3" oled's seem to use this chip. i don t actually know if it displays all pixels or it s just cropped to the center 128 px.

This new version will cause your sketches to crash

The new naming conventions in Ver 3.0 in combination with the Arduino automatic Library Manager will cause all sketches using esp8266-oled-ssd1306 Ver 2.0 to crash.

You should rename your library, call the new one Ver 1.0 and restore esp8266-oled-ssd1306 to Ver 2.0.2

Don't close this issue without doing something to warn users of this problem.

Roger

Dual displays

Hi! I though to be smart and connect two 0.96" oled displays to my EPS8266, each with the same address but each with different SDA and SDC ports (as I still have sufficient of them in the flight tracker..)

So this is part of the code:
.......
const int I2C_display_ADDRESS = 0x3c;
const int SDA_PIN = 4;
const int SDC_PIN = 2;
const int SDA_PIN2= 12;
const int SDC_PIN2= 13;
SSD1306Wire display1(I2C_display_ADDRESS, SDA_PIN, SDC_PIN);
SSD1306Wire display2(I2C_display_ADDRESS, SDA_PIN2, SDC_PIN2);**
......
Compiling the program however gave the following error:

.....
sketch\flightscan_test3.ino.cpp.o: In function __static_initialization_and_destruction_0': C:\Users\Hans\AppData\Local\Temp\arduino_modified_sketch_472887/flightscan_test3.ino:195: undefined reference tovtable for OLEDDisplay'
collect2.exe: error: ld returned 1 exit status
exit status 1
.....

My question: is it possible to have dual displays without changing the I2C addresses in this way?

Name changes are a terrible idea

Changing the names of files from SSD1306xxxxx to OLEDDisplayxxxxx without changing the name of the library itself is a terrible thing to do.

Arduino has a pop-up that opens whenever you open the program. It urges you to update libraries and boards. Anyone in the world who has used your "esp8266-oled-ssd1306" and has clicked on update will have their sketches blown up.

This caused me two hours of grief.

Luckily i had Ver 2.0.2 in a backup.

Please fix this quickly.

Roger
Oldmicroguy

brzo_i2c not included

Installed in PlatformIO and trying to use SSD1306Brzo.
I get an error message indicating that <brzo_i2c.h> cannot be included (from SSD1306Brzo.h).
Brzo i2c is not a separate library for PlatformIO. How do I best install that? Or should it be included in the ESP8266_SSD1306 library?

single frame with no indicators

hi,

how would you got about using this great lib for just a single frame without indicators and no switchover animations?

cheers

Support for 64x48 OLED ?

Hello,
It will be very helpful if you add support for 64x48 OLED like the official display for Wemos 👍 http://www.wemos.cc/Products/oled_shield.html

Here they did almost the same :
https://github.com/mcauser/Adafruit_SSD1306/tree/esp8266-64x48

Regards!

unnecessary #include <ArduinoJson.h> inside example

please remove unnecessary #include <ArduinoJson.h> from example

Mangled display with SH1106 1.3" SPI OLED

Hi, great work on this library, thanks much for your efforts. I tried converting existing code that worked for an SPI SSD1306 .96" display to use an SH1106 1.3" (SPI) one. Though I do get some recognizable display elements, the overall result is quite mangled. Some random overwrites, some reverse display elements. I know the code is new for the SH1106...has this been tested on the SPI version?

library is not installing correctly?

Hi,
I have just downloaded all the libraries and added them to the libraries folder.
When I try to compile the example "WeatherStationDemo", the compilation fails with due to the following:

WeatherStationDemo.ino:29:21: fatal error: SSD1306.h: No such file or directory
compilation terminated.
Error compiling.

If I click on adding the library to the project, these headers are included:

#include <SSD1306Fonts.h>
#include <ssd1306_i2c.h>

Still, no success with compilation, even after removing these:

//#include "SSD1306.h"
//#include "SSD1306Ui.h"

I noticed the sentence on the home page: "SSD1306.h Renaming ssd1306_i2c to SSD1306 "

Could it be a mistake related to this, or I am doing something wrong? Thanks.

screen misaligned after reflash

when flashing the wather code a second time the display is usually misaligned to some random x/y and only recovers after a complete power cycle

i don t know if this could be just my display doing it... got it from banggood

How to add new fonts?

I have been trying to add new font with The Dot Factory Tool, but rendering is not proper,
How do you add fonts?

Simple example...

Please provide a simple/minimalist example.

You may want to do something with keywords or something, to help make this library easier to find.

setContrast

hello,

i don't understand how use to setContrast,

thx

drawStringMaxWidth can cut off words

First, thanks for an awesome library!

In some cases the drawStringMaxWidth call can cut off words at the right edge of the screen. In this case 'diam' is cut off, and 'tempor' could have wrapped to the next line as well.

Here is Roboto 12 with this code:

display.setFont(Roboto_12);
display.setTextAlignment(TEXT_ALIGN_LEFT);
display.drawStringMaxWidth(0, 0, 128,
      "Lorem ipsum\n dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore." );

Are the 128x32 displays supported, too?

problem with text and negative y values

Hi,
I am trying to minimize lost space around a text by trying to put it a few pixels off screen on the vertical.

At the bottom, it works fine, at the top, o big chunk of the text seems to be missing with 10px font and -2 y position.

In screenshot, middle and right hand text on overlay had -2 as y.

Cheers

Non Latin Characters

Hi,

hi i tried to send some Non Latin Characters (Arabic letters) and nothing was displayed on the screen.
is this a limitation of Added font , or a library limitation.

thanks

Internal image format

Hi,
what a great, fast Library! I Just have fun with some random graphics.
I just wonder what the drawFastImage() is about.
Where can I find a converter for this datatype:

Draw a bitmap in the internal image format
void drawFastImage(int16_t x, int16_t y, int16_t width, int16_t height, const char *image);

Thank you!
Felix

Is it possible to add \n?

Is it possible to add \n for breaking text into a new line for method drawString or drawStringMaxWidth?

Add progress bar function to UI class

Add a function that simply lets the user draw a progress bar.

No free remainingTimeBudget

Hi,

Just created a program based on your example for WeMos D1 and noticed that part of loop() inside if (remainingTimeBudget > 0) doesn't run.
Is it safe to run some code outside this condition?

One more thing: changing fps to 25 or lesser makes insane frames switching, like 3-5 frames in one second.

Does dev 3.0 branch work with newest Arduino IDE?

Problems with ESP8266 201

I'm trying to configure a ESP 201 as a DHT sensor and I want it to show values on an OLED.
I'm having troubles with it: I can't make the ssd1306 work with the simplest example code provided with the library.

First, is this library compatible with the 201 version?

What are the most suitable pins for I2C interface?

Thank you

How to use ui.switchToFrame();

Hi Guys,

I spent some time to test my request to be able to switch to a specific frame (thanks for coding this part by the way).
I'm trying to use switchToFrame without success but may by I'm doing wrong, here below the code (only part of)

void loop() {

  // bla bla check RF packet received

  if (packet_received) {
    // display immediately data received
    ui.switchToFrame(RF_FRAME_INDEX);
    ui.update();

    // Here I'm doing approx 2 second long stuff blocking
    Post_Data();
  }

  ui.update();

  // Handle Web server
  web_server.handleClient();

  // Handle OTA
  ArduinoOTA.handle();

}

Frame are scrolling OK but it never switch to the correct one (it does nothing) when I call switchToFrame()
If there any example on how do use it ?

Thanks

drawRect and fillRect produce rects of different size

Currently the code in OLEDDisplay::drawRect is as follows:

  drawHorizontalLine(x, y, width);
  drawVerticalLine(x, y, height);
  drawVerticalLine(x + width, y, height);
  drawHorizontalLine(x, y + height, width);

Compared to fillRect function, this draws a rectangle which is 1 pixel wider and 1 pixel higher. Also it lacks a pixel at the lower-right corner.

If I change that to x + width - 1 and y + height - 1, i get same size as for fillRect.
I'm not sure if such a "fix" qualifies as a change in API though :)

And by the way, why is fillRect using drawHorizontalLine? Isn't drawVerticalLine faster because it can set up to 8 pixels at a time?

Add print() and println() to UI class

• Allow a self-scrolling ui e.g. for debug output
• add print() and println()

feature request, multiple oled displays

Feature request or example.. would be good to run multiple displays, ie. weather on one and the time on the other.

128x32 not working (but I got it to work, what now?)

Hi, I have a 128x32 display, got it to work, but noticed that there were issues. I fixed them (on the main branch code), and was wondering if you would like me to commit those changes to the main branch.

It's a quick fix, not a cleanup like the 3.0 branch. So I'd recommend to put these quick fixes in the main branch. And then I could test and (if necessary) fix the 3.0 branch as well.

What do you think?

Corrupted display UI Frame with drawProgressBar

Hi there,

I think I discovered a bug with drawProgressBar when using UI to scroll frames containing a bargraph. The problem occurs only during scroll, once frame is fixed all is fine!

When scrolling coming frame containing bargraph there are some line draw on display during scroll, I circled them in red on screenshot below

Did some of you noticed this ?

here the frame code just in case

void drawFrameRF(OLEDDisplay *display, OLEDDisplayUiState* state, int16_t x, int16_t y) {
  char buff[32];
  int16_t percent;
  volatile uint8_t * p;
  int16_t yidx = 0;
  byte n;

  n = data.size;
  p = data.buffer;

  display->clear();
  display->setFont(Roboto_Condensed_Bold_Bold_16);

  if (!got_first) {
    display->setTextAlignment(TEXT_ALIGN_CENTER);
    display->drawString(x + 64, 14, "No radio data");
    display->drawString(x + 64, 34, "received yet");
  } else {
    display->setTextAlignment(TEXT_ALIGN_LEFT);
    if (data.type == RF_MOD_RFM69) {
      sprintf_P(buff, PSTR("NODE %d"), data.nodeid );
      display->drawString(x + 0, 0, buff);

      // rssi for RFM69B is -115 (0%) to 0 (100%)
      percent = (int16_t) data.rssi;
      // rssi range now 0 (0%) to 115 (100%)
      percent += 115;

      // now calc percentage
      percent = (percent * 100) / 115;

      if (percent > 100) percent = 100;
      if (percent < 0  ) percent = 0;

      // display bargraph on lcd
      display->drawProgressBar( x + 60, 4, 64 , 12, 50 /*percent*/);

      display->setFont(Roboto_Condensed_12);
      display->setTextAlignment(TEXT_ALIGN_CENTER);
      display->drawString(x + 64, 48, timeAgo(g_second-packet_last_seen));
    }
  }

  ui.disableIndicator();
}