Link Search Menu Expand Document
Invention Bootcamp 2021

Micro-OLED Display

Small Organic Light-Emitting Diode (OLED) displays are relatively inexpensive devices for text and graphical output from an Arduino board. This web page demonstrates how to connect a 128 x 64 micro OLED display from Adafruit to the Adafruit Circuit Playground Express.

  1. Breadboard Connections
  2. Install the Adafruit SSD1306 Library
  3. Run the ssd1306_128x64_i2c.ino sketch from the Adafruit Library
  4. Run OLEDdisplayFunctions.ino to display internal clock time
  5. Coordinate system for the OLED display
  6. Using the F macro to save SRAM

Breadboard Connections

Use the STEMMA/QT connector with alligator clips to connect to the I2C pads on the Circuit Playground Express, as shown in the following image.

CPX connected to 128x64 OLED

Carefully insert the plug end of the STEMMA/QT connector into one of the sockets on the micro-OLED breakout board. Refer to this page for details on using STEMMA/QT cables

The following images shows the plug and socket for the OLED.

STEMMA/QT connections for 128x64 OLED Click to enlarge

Install the Adafruit SSD1306 Library

To use the monochrome 128 x 64 micro OLED, you first need to install the Adafruit SSD1306 Library and the Adafruit GFX Library. The following steps with the Library Manager assume that you have properly configured the board support via the Arduino IDE Preferences.

From menu at the top of the Arduino IDE, select Sketch –> Include Library –> Manage Libraries…

  1. Enter “ssd” in the search box to narrow the range of choices. Or, if you prefer, scroll through the entire list of libraries (not recommended).
  2. Choose the “Adafruit SSD1306” panel, which will cause the Install button to become visible.
  3. Click Install.
    • The installer should ask if you want to install other dependent libraries, and you should check all the boxes of dependent libraries.
  4. After installing the SSD1306 library, check to see that the GFX library was also installed. If not, repeat steps 1 - 3 with these exceptions
    • Search for “GFX”
    • Install the “Adafruit GFX Library”

Select and install the Adafruit SSD1306 library

Run the ssd1306_128x64_i2c.ino sketch from the Adafruit Library

The Adafruit SSD1306 library includes example sketches to demonstrate features of the micro OLED display. The variants of the examples are appropriate for different types of connections and different size OLED displays.

Using the menus at the top of the Arduino IDE, select File –> Examples –> Adafruit SSD1306 –> ssd1306_128x64_i2c. Upload that sketch to the Feather board.

If you have connected the STEMMA QT cable to the correct pads on the Circuit Playground Express, the ssd1306_128x64_i2c.ino should run and display graphical and text images on the OLED board.

Run OLEDdisplayFunctions.ino to display internal clock time

The OLEDdisplayFunctions.ino displays the internal clock time in milliseconds and microseconds on the 128x32 OLED. The internal clock is restarted each time the microcontroller board is reset, or supplied with power after being disconnected from power.

Download the OLEDdisplayFunctions.ino sketch

The purpose of OLEDdisplayFunctions is simply to show how to start the OLED display and dynamically update that display with new data. The internal clock time is just a convenient data source.

The Functions in OLEDdisplayFunctions refers to the use of C++ functions in the sketch to isolate the OLED-related tasks. The setupOLED function starts the connection between the external OLED panel and the running sketch. The updateOLED function accepts the time in milliseconds and seconds as inputs, and creates a display of those values on the OLED screen. The use of functions to compartmentalize tasks is strongly encouraged.

Coordinate system for the OLED display

The OLED display is an addressable grid that is 128 pixels wide by 64 pixels high. Before adding a character or number (converted to characters) to the buffer, you will need to specify the starting position of the upper left corner of the character (or number).

Pixel locations on the OLED display are specified as (x,y) coordinates where x is the horizontal position and y is the vertical position measured downward

Coordinate system for OLED displays Source: learn.adafruit.com/adafruit-gfx-graphics-library

To locate a character on the display, specify the (x,y) coordinates of the upper left corner of that character.

Locating a character in the OLED display coordinate system Source: learn.adafruit.com/adafruit-gfx-graphics-library

The letter “A” in the preceding image would be added to the display buffer with the following code

OLED.setCursor(3,4);
OLED.display("A");

Using the F macro to save SRAM

Throughout the sample codes are expressions like

OLED.print(F("OLED is ready"));

What is the F( ) expression? Why does it appear in code related to the OLED display?

A string to be displayed on the OLED is wrapped in a F( ... ) expression. The F() is a macro (acts somewhat like a function, but it’s not a function) that copies the enclosed string to the same memory space on the Arduino board that is used by the program code. The net effect is to preserve memory (on-board SRAM) for use by Arduino sketch while it is running.

Just treat the F( ) construct as a necessary way of writing fixed strings to the OLED display. By ‘‘fixed’’ strings we mean a string that does not change while the sketch is running.

Recommendations

  • As general practice, use the F( ) macro to reduce memory consumption.
  • The Circuit Playground Express has sufficient memory that the F( ) macro is usually not critical for codes on the Circuit Playground Express. However, if you move your code to another Arduino board that has less RAM, you may experience bugs that are very hard to understand and fix.
  • Do not use F( ) around numerical variables. The benefit of F( ) comes from moving strings that do not change into PROGMEM, thereby preserving SRAM.

References