Micro OLED Breakout Hookup Guide

Contributors: jimblom

Using the Arduino Library

Now that you've loaded up the example, and proven out your display and hookup, it's time to get started writing your own application! Before you get started, here's a quick rundown of the SFE_MicroOLED library.

Including, Initializing, and Beginning

At the top of your code, of course, you'll need to include the SFE_MicroOLED library. On top of that, you'll also need to include the SPI and Wire libraries so the SFE_MicroOLED library has access to those interfaces.

language:c
#include <SPI.h>
#include <Wire.h>
#include <SFE_MicroOLED.h>

After you've included the library, you can create a MicroOLED object in the global variable area of your code. This is where you'll tell the library whether you're using SPI or I²C, and which pins are driving the display.

language:c
#define PIN_RESET 9  // Connect RST to pin 9 (req. for SPI and I2C)
#define PIN_DC    8  // Connect DC to pin 8 (required for SPI)
#define PIN_CS    10 // Connect CS to pin 10 (required for SPI)
//#define DC_JUMPER 0 // Set to either 0 (default) or 1 based on jumper, matching the value of the DC Jumper
// Also connect pin 13 to SCK and pin 11 to MOSI

// Declare a MicroOLED object. The parameters include:
// 1 - Reset pin: Any digital pin
// 2 - D/C pin: Any digital pin (SPI mode only)
// 3 - CS pin: Any digital pin (SPI mode only, 10 recommended)
MicroOLED oled(PIN_RESET, PIN_DC, PIN_CS); //Example SPI declaration, comment out if using I2C
//MicroOLED oled(PIN_RESET, DC_JUMPER); //Example I2C declaration, uncomment if using I2C 

If you're using SPI to talk to the display, define three parameters to tell the library which pins you have RST, D/C and CS connected to, respectively.

In the example above we've called our MicroOLED object oled, but you can call it anything you'd like. You can even create more than one, if you have more displays connected to your Arduino.

The last step to the OLED setup should occur in the setup() function. Stick a oled.begin() function in there, which will initialize the display and update all sorts of behind-the-scenes settings for you.

language:c
setup()
{
    delay(100);
    //Wire.begin(); //set up I2C bus, uncomment if you are using I2C
    // Before you can start using the OLED, call begin() to init
    // all of the pins and configure the OLED.
    oled.begin();
}

#define DC_JUMPER 0 // Set to either 0 (default) or 1 based on jumper, matching the value of the DC Jumper

//MicroOLED oled(PIN_RESET, PIN_DC, PIN_CS); //Example SPI declaration, comment out if using I2C
MicroOLED oled(PIN_RESET, DC_JUMPER); //Example I2C declaration, uncomment if using I2C

delay(100);
Wire.begin(); //set up I2C bus, uncomment if you are using I2C

Drawing Pixels and Displaying

Let's begin by drawing the simplest shape out there -- a pixel. Drawing anything requires at least two steps. First you have to tell the screen what you want to draw, then you have to tell it to draw it.

To draw a pixel, start by calling the pixel(int x, int y) function.

language:c
// Draw a pixel in the middle of the screen
oled.pixel(LCDWIDTH/2, LCDHEIGHT/2); // Add a pixel to the display buffer.

Then, after you've told the screen what to draw, use the display() function to execute.

language:c
oled.display(); // Draw whatever is in the display buffer.

The display() function re-draws the entire screen -- all 3072 pixels. It takes a relatively long time to execute the command, so try not to do it too much.

Lines, Rectangles, Circles, Oh My!

Now that we know how to draw pixels, it'll be easy to draw all sorts of shapes.

To draw a line, you need two sets of x/y coordinates, the line will be drawn between them. Here's an example:

language:c
int x0 = 7; int y0 = 7;   // (x0,y0) = (7, 7)
int x1 = 42; int y1 = 24; // (x1,y1) = (42, 24)
oled.line(x0, y0, x1, y1);  // Draw a line from (x0,y0) to (x1,y1);
oled.display(); // Draw to the screen

Things are a little different if you want to draw a rectangle. In this case, you give it a x/y coordinate to start at, then a width and a height.

language:c
int x0 = 7; int y0 = 5;
int width = 24;
int height = 13;
oled.rect(x0, y0, width, height);  // Draw a rectange from (7,5) to (31,18)
oled.display(); // Draw to the screen

The rectangle will be drawn from (x0, y0) to (x0+width, y0+height).

Want to fill that rectangle? Use the rectFill function instead!

language:c
oled.rectFill(7, 5, 35, 5); // Fill a rectangle from (7, 5) to (42, 10)
oled.display(); // Draw to the screen

Circles require a set of coordinates for the middle, and then a radius.

language:c
int radius = 13;
// Draw a 13-pixel radius (26-pixel diameter) 
// circle centered in the middle of the display:
oled.circle(LCDWIDTH/2, LCDHEIGHT/2, radius);   

As with the rectangle function, you can also fill the circle with circleFill:

language:c
oled.circleFill(42, 20, 7); // Fill a circle, 7 radius, centered at (42, 20)
oled.display(); // Draw to the screen

Drawing Text

In addition to basic shapes, you can also draw text with the SFE_MicroOLED library. There are a few settings to adjust before you get to texting, though. First, set the font type with setFontType(type). The parameter in this function can be either 0, 1, 2, or 3, each size gets progressively larger.

language:c
oled.setFontType(0);  // Set the text to small (10 columns, 6 rows worth of characters).
oled.setFontType(1);  // Set the text to medium (6 columns, 3 rows worth of characters).
oled.setFontType(2);  // Set the text to medium/7-segment (5 columns, 3 rows worth of characters).
oled.setFontType(3);  // Set the text to large (5 columns, 1 row worth of characters).

Here's a quick overview of each of the four font types:

Next, after setting the font type, define your text cursor with setCursor(x, y). This will define the top-left corner of the first character you print.

language:c
oled.setCursor(0, 0);  // Set the text cursor to the upper-left of the screen.

Finally, you can use the print(String/int/float) command to print whatever you want.

language:c
oled.print("Hello, world"); // Print a const string
oled.print(analogRead(0));  // Print an integer
oled.print(42.07);  // Print a float
oled.display(); // Draw to the screen

That covers the basics of the library, but it can do more. Check out the library's readme for a complete overview of the MicroOLED class. There you'll find more functions, like invert(boolean) flipVertical(boolean), flipHorizontal(boolean), and scrollRight(start, stop).