OLED 2.

42” Display SSD1309 Chipset

compiled by Micro Robotics www.robotics.org.za

Table of Contents

1. Introduction
2. Quick Spec
3. Pin Functions
4. Connecting Display to Arduino Uno
5. Download U8GLIB library
6. Display Chipset and Initialization
7. Hello World Example
8. How to use the U8GLIB library
9. Best practices when using U8GLIB library
10. General Restrictions of the U8GLIB library
11. Animations
12. List of all the U8GLIB functions
13. Code Examples
14. Printing a variable
15. OLED display Gauge Meter
16. Mechanical Dimensions
17. Manufacturer Notes
OLED 2.42” Display SSD1309 Chipset
compiled by Micro Robotics www.robotics.org.za

1. Introduction
The 2.42" OLED is a 12864 pixel display that is based on COG
OLED technology. The display use the new SSD1309 display
driver and commucate via SPI (default) or I2C. The display is
also 3.3V an 5V ready.

128 x 64

Part Number: OLED-242-SSD1309-SPI-BLU Blue

Part Number: OLED-242-SSD1309-SPI-YEL Yellow
Part Number: OLED-242-SSD1309-SPI-WHI White
Part Number: OLED-242-SSD1309-SPI-GRE Green

2. Quick Spec

Type : OLED
Size : 128 x 64 Dots
Chipset : SSD1309
Interface : SPI (default) also I2C
Supply : 3.3 to 5V
3. Pin Functions

* The SPI connections are not marked properly marked on the

display and we provide this table for reference

Pin Pin Name Function SPI *

7 CS Chip Select SS - Slave Select
6 D/C Slave Address Select DC / A0
5 RES Active Low Reset RESET
4 SDA Serial Data In MOSI
3 SCLK Serial Clock SCLK
2 VDD +Supply +5V
1 VSS Ground GND
4. Connecting display to Arduino Uno - SPI

ARDUINO UNO

(SS) 10 7-CS
(DC) 9 6-DC
*
(RES) 8 5-RES
(MOSI) 11 4-SDA
(SCK) 13 3-SCL
+ 5V 2-VSS
GND 1-GND

* According to the U8GLIB the RES pin is optional, but we

had to connect it to get display working.

5. Setting up the U8GLIB library

a) Get the latest U8GLIB library from github

https://github.com/olikraus/u8glib
Click the on Download Arduino Version from Github

or for Arduino directly

https://github.com/olikraus/U8glib_Arduino/releases/tag/1.19.1

b) Import the zip library into Arduino Ide

c) Inside Arduino IDE goto -> File examples -> u8glib

and open Hello world example

u8glib_arduino_v1.18.1.zip
6 . Display Chipset and Initialization

a) Run Arduino IDE, Sketch, Add Zip Library

b) Go to Examples, Open Hello World Example

c) The example has reference to all the different

chipsets, ucomment you displays chipset, In our
case the display it use the SSD1309 driver

//U8GLIB_SH1106_128X64 u8g(13, 11, 10, 9);

//SW SPI Com: SCK = 13, MOSI = 11, CS = 10, A0 = 9
//U8GLIB_SH1106_128X64 u8g(4, 5, 6, 7);
U8GLIB_SSD1309_128X64 u8g(13, 11, 10, 9);
//SPI Com: SCK = 13, MOSI = 11, CS = 10, A0 = 9
//U8GLIB_SSD1327_96X96_GR u8g(U8G_I2C_OPT_NONE);

Driver Initialization / Reset Pin

U8GLIB_SSD1309_128X64 u8g(SCK, MOSI, CS, AO, RST)

Default is without RES pin defined

U8GLIB_SSD1309_128X64 u8g(13, 11, 10, 9);

We added Reset Pin declaration

U8GLIB_SSD1309_128X64 u8g(13, 11, 10, 9, 8);

7. Hello World Example
#include "U8glib.h"

U8GLIB_SSD1309_128X64 u8g(13, 11, 10, 9, 8);

//U8GLIB_SSD1309_128X64 u8g(13, 11, 10, 9, 8);

// SPI Com: SCK = 13, MOSI = 11, CS = 10,
// A0 = 9, RES = 8

void draw(void) {
u8g.setFont(u8g_font_unifont);
u8g.drawStr( 0,10, "Hello World!");
}

void setup(void) {
}

void loop(void) {
// picture loop
u8g.firstPage();
do {
draw();
} while( u8g.nextPage() );

// rebuild the picture after some delay

delay(10);
}
x
0 127
0,0
0 Hello World
12 = Font Height
y

63
8 . How to use the U8GLIB library
Once the display is physically connected to an
Arduino Board three steps are required to bring some
graphics on the display:

1. Call an U8glib constructor

2. Add the "picture loop"
3. Write a graphics "draw" procedure

1. Use the correct constructor to setup the display

2. Place graphics commands inside the picture loop.
3. Group your graphics commands in procedure(e.g. draw()).
4. Please note the restrictions for the picture loop.

More info on the “picture loop” and “draw”

https://github.com/olikraus/u8glib/wiki/thelloworld

9 . U8GLIB library best Practices

Best practice is to place all graphics commands into

one procedure (draw()):

void draw(void) {
// graphic commands to redraw the complete
// screen should be placed here
u8g.setFont(u8g_font_unifont);
u8g.drawStr( 0, 20, "Hello World!");
}
10 . General Restrictions of the U8GLIB library

There are some restrictions on this draw() procedure

(picture loop). This restrictions are explained in
more detail here. From a programming perspective this
means for the draw() procedure (picture loop):

a) Do not modify global variables from inside the draw()

procedure.
b) Do not declare static variables inside the draw()
procedure.
c) Assume a cleared and empty screen at the beginning
of the draw() procedure.
d) Internal values like draw color or current font
should be set at the beginning of the draw()
procedure.
e) Internal values like draw color or current font
can be set outside the picture loop, if they are not
changed within the picture loop. On the other hand,
the following is fine (and often required):
f) Read values from global variables or use arguments
to the draw() procedure.
g) Use local variables, if conditions and loops
(for, while) within the draw() procedure.

For example, do NOT do the following:

int y_pos = 0; // global variable

void draw(void) {
// graphic commands should be placed here
u8g.setFont(u8g_font_unifont);
u8g.drawStr( 0, y_pos, "Hello World!");
y_pos++; // Wrong: Global variable modified
} // inside picture loop / draw()
11 . Animations
If you would like to program an animation which increases
the y-position for each picture, then increase y_pos
outside the picture loop:

int y_pos = 0; // global variable

void draw(void) {
// graphic commands to redraw screen must be placed here
u8g.setFont(u8g_font_unifont);
u8g.drawStr( 0, 12, "Hello World!");
}

void loop(void) {
// picture loop
u8g.firstPage();
do {
draw();
} while( u8g.nextPage() );

// Correct: Increase y_pos outside the picture loop

y_pos++;
// rebuild the picture after some delay
delay(1000);
}

x
0 127
0,0
0 Hello World
12 = Font Height
y

63
12 . List if U8GLIB Functions

A list of all the latestg functions can be found here

https://github.com/olikraus/u8glib/wiki/userreference

begin setCursorColor
disableCursor setCursorFont
drawBitmap setCursorPos
drawBitmapP setCursorStyle
drawBox, drawCircle setDefaultBackgroundColor
drawDisc, drawEllipse setDefaultForegroundColor
drawFilledEllipse getFontLineSpacing
drawFrame, drawHLine getHeight
drawLine, drawPixel getMode
drawRBox, drawRFrame getWidth
drawStr getStrWidth
drawStr90, drawStr180 InitSPI, InitHWSPI
drawStr270, drawStrP Init8Bit InitComFn
drawStr90P, drawStr180P setDefaultMidColor
drawStr270P, drawTriangle setFont
drawVLine setFontLineSpacingFactor
drawXBM, drawXBMP setFontPosBaseline
define u8g_logo_width 38 setFontPosBottom
define u8g_logo_height 24 setFontPosCenter
enableCursor setFontPosTop
firstPage setFontRefHeightAll
getColorIndex setFontRefHeightExtendedText
getFontAscent setFontRefHeightText
getFontDescent setPrintPos
nextPage setRGB
print setRot90, setRot180,
setColorIndex setRot270, setScale2x2
setContrast sleepOn, sleepOff
undoRotation
undoScale
U8GLIB
13 . U8GLIB Examples
u8g.drawPixel(0,0); u8g.drawPixel(127,0);

u8g.drawPixel(0,63); u8g.drawPixel(127,63);

80
12
80,12 30

20

u8g.drawFrame(80,12,30,20);

80
12
80,12
30

20
14 . Printing a variable
u8g.drawBox(80,12,20,30);

//Printing a variable value

u8g.setPrintPos(54,60);
u8g.print(x);

For a more complete list of functions, visit

https://github.com/olikraus/u8glib/wiki/u8glib

User Reference

https://github.com/olikraus/u8glib/wiki/userreference

Available Fonts

https://github.com/olikraus/u8glib/wiki/fontgroup

Font Size

https://github.com/olikraus/u8glib/wiki/fontsize
15. OLED display Gauge Meter

Very good example of OLED Gauge meter

https://steemit.com/utopian-io/@pakganern/
oled-display-gauge-meter-using-potentiometer-arduino
16. Mechanical Dimensions
16. Manufacturer Notes