Using FTOLED

Connecting the OLED128

See the OLED128 QuickStart Guide
for information on physically connecting the OLED128 and installing the FTOLED library.

Before you try and follow the rest of this guide, try uploading and running some of the example sketches as described in the Quickstart guide. This will confirm the hardware is working correctly, and also give you a feel for how the OLED128 module works.

Including, defining and Initialising the Display

The first step in using the FTOLED display is including the FTOLED.h header file. You'll need a line like this near the top of your sketch:

#include <FTOLED.h>

After this, you want to define an instance of a variable that you can use to refer to your OLED display. Usually you'll want to define this as a global variable, outside of any method like setup() or loop(), so that you can use it from anywhere in your sketch. For example:

const byte pin_cs = 7;
const byte pin_dc = 2;
const byte pin_reset = 3;

OLED oled(pin_cs, pin_dc, pin_reset);

Here we define our sketch to contain a new OLED display stored in a variable called oled (we've used an obvious name but you can call it anything you want instead of oled - for example frontpanel or display or even fred.)

The three arguments shown in the parentheses are pin numbers for the three configurable pins on the OLED128 - CS (also called nCS), DC and RESET (also called RST or nRST.)

The pin numbers shown are the ones that are used if you wired the OLED128 as shown in the Quick Start guide, but you can use any pins you like.

Now you have an OLED instance defined, the last step is to initialise it as part of your setup() method. This sends commands to the OLED128 to set it up for normal operation, and activates the internal circuitry that drives the screen. The intitialisation command is oled.begin()

void setup()
{
    oled.begin();
}

(Of course if you named your OLED instance fred, it'd be fred.begin() here instead.)

Here's a minimal sketch that just includes, defines and initialises the OLED display but doesn't do anything:

#include <FTOLED.h>

const byte pin_cs = 7;
const byte pin_dc = 2;
const byte pin_reset = 3;

OLED oled(pin_cs, pin_dc, pin_reset);

void setup()
{
    oled.begin();
}

void loop()
{
    // Our display named 'oled' is ready for use here
}

Pro Tip: An easy way to get started is to just open one of the FTOLED example sketches, then "Save As..." and start editing it to make it your own!

First drawing operation

Let's start by drawing a line. The OLED display is 128x128, so let's draw a diagonal line from row 32 and column 32 (32,32) to row 96 and column 96 (96,96). The way to do this is the drawLine method:

void drawLine( int x1, int y1, int x2, int y2, OLED_Colour colour );

Where x1 and x2 are the column numbers, and y1 and y2 are the row numbers.

Here's code to draw a red diagonal line:

oled.drawLine(32, 32, 96, 96, RED);

If you've done anything with computer graphics before, you may be surprised to see that this line goes from the bottom left (32,32) to the top right, instead of top left to bottom right.

This is because row 0 is at the bottom of the screen:

Colours

Where did the colour "RED" come from? If you look into the file FTOLED_Colours.h you'll see that there are constants predefined for many colours, a list of colours known as the X11 Colour Names. So if you see a colour listed in that file, you can just use it by name.

You can look at the above links to see what colours are available, or here's a full list:

ALICEBLUE, ANTIQUEWHITE, AQUAMARINE, AZURE, BEIGE, BISQUE, BLACK,
BLANCHEDALMOND, BLUE, BLUEVIOLET, BROWN, BURLYWOOD, CADETBLUE,
CHARTREUSE, CHOCOLATE, CORAL, CORNFLOWERBLUE, CORNSILK, CYAN,
DARKBLUE, DARKCYAN, DARKGOLDENROD, DARKGRAY, DARKGREEN, DARKGREY,
DARKKHAKI, DARKMAGENTA, DARKOLIVEGREEN, DARKORANGE, DARKORCHID,
DARKRED, DARKSALMON, DARKSEAGREEN, DARKSLATEBLUE, DARKSLATEGRAY,
DARKSLATEGREY, DARKTURQUOISE, DARKVIOLET, DEEPPINK, DEEPSKYBLUE,
DIMGRAY, DIMGREY, DODGERBLUE, FIREBRICK, FLORALWHITE, FORESTGREEN,
GAINSBORO, GHOSTWHITE, GOLD, GOLDENROD, GRAY, GREEN, GREENYELLOW,
GREY, HONEYDEW, HOTPINK, INDIANRED, IVORY, KHAKI, LAVENDER,
LAVENDERBLUSH, LAWNGREEN, LEMONCHIFFON, LIGHTBLUE, LIGHTCORAL,
LIGHTCYAN, LIGHTGOLDENROD, LIGHTGOLDENRODYELLOW, LIGHTGRAY,
LIGHTGREEN, LIGHTGREY, LIGHTPINK, LIGHTSALMON, LIGHTSEAGREEN,
LIGHTSKYBLUE, LIGHTSLATEBLUE, LIGHTSLATEGRAY, LIGHTSLATEGREY,
LIGHTSTEELBLUE, LIGHTYELLOW, LIMEGREEN, LINEN, MAGENTA, MAROON,
MEDIUMAQUAMARINE, MEDIUMBLUE, MEDIUMORCHID, MEDIUMPURPLE,
MEDIUMSEAGREEN, MEDIUMSLATEBLUE, MEDIUMSPRINGGREEN,
MEDIUMTURQUOISE, MEDIUMVIOLETRED, MIDNIGHTBLUE, MINTCREAM,
MISTYROSE, MOCCASIN, NAVAJOWHITE, NAVY, NAVYBLUE, OLDLACE,
OLIVEDRAB, ORANGE, ORANGERED, ORCHID, PALEGOLDENROD, PALEGREEN,
PALETURQUOISE, PALEVIOLETRED, PAPAYAWHIP, PEACHPUFF, PERU, PLUM,
POWDERBLUE, PURPLE, RED, ROSYBROWN, ROYALBLUE, SADDLEBROWN,
SALMON, SANDYBROWN, SEAGREEN, SEASHELL, SIENNA, SKYBLUE,
SLATEBLUE, SLATEGRAY, SLATEGREY, SNOW, SPRINGGREEN, STEELBLUE,
TAN, THISTLE, TOMATO, TURQUOISE, VIOLET, VIOLETRED, WHEAT,
WHITE, WHITESMOKE, YELLOW, YELLOWGREEN.

Custom Colours

Colours are defined via a custom data structure (struct) called "OLED_Colour" (you can also use "OLED_Color" interchangeably, if you're American!)

const OLED_Colour FAVOURITE_GREEN = { 11, 60, 3 };

The three numbers in the curly braces are the red intensity (range 0-31), green intensity (range 0-63) and blue intensity (range 0-31.) The curly braces are shortcuts for filling in the fields of the structure, but you can also have colours stored in variables like this:

OLED_Colour my_green;
my_green.red = 11;
my_green.green = 60;
my_green.blue = 3;

Colour Naming Collisions

In older versions of the FTOLED library, OLED_Colour was simple called Colour. It was renamed to avoid collisions. If your sketch was designed or an older version and uses "Colour", you can either change the sketch or add a typedef near the top:

typedef OLED_Colour Colour;

It is also possible for another library to collide on the colour names defined in FTOLED_Colours.h (for example, if another library also calls something RED). If you're getting errors because multiple libraries define the same colour names, look for the #include "FTOLED.h line at the top of your sketch and add a line above it, like so:

#define FTOLED_NO_COLOUR_PRESETS
#include "FTOLED.h"

This causes none of the predefined colours to be included in the sketch. You won't be able to use those predefined colour names in your sketch any more, though.

More Drawing Operations

Now you understand the basic concepts behind FTOLED drawing, learn about the other drawing commands in the Function Reference or see our introductions to Displaying Bitmap images and Displaying Text.

Don't forget to explore the example sketches (under File -> Examples -> FTOLED in the Arduino IDE.)