U8glib Arduino OLED Tutorial 1: Hello World on Steroids

Getting Started

The assumption here is that you’ve already downloaded the U8glib library and have properly installed it into your Arduino folder.  If you haven’t, you can get the download HERE.

The next assumption is that you’ve figured out what constructor to use.   I’ve been testing a few and if you’re lucky, you can find it listed on my home page.   The way to know if you’ve got the right constructor is if you can run the graphics test.  If you find that you have to hunt and peck a little, don’t get discouraged.  The best of us have.

Your Display – Width and Height,  X and Y

When you purchased your display, it was offered with a resolution that was expressed by something like “128 x 64”.   That description tells you the number of pixels (or tiny LEDs) across and the number of pixels down.

In the case of a ‘128 x 64’ display, it means we have 128 pixels going from left to right, and 64 pixels going up and down.  In other words there are 8192 total pixels in a display of this type.

This is important because nearly everything you will draw on your display will require you to reference these tiny LEDs known as pixels.  You will reference these pixels by first identifying it’s position horizontally ( or the X position) and it’s position vertically (or Y Position).  These pixels are numbered as follows:

  • Pixels going across the width of the display begin with the zero.   In the case of a display that is 128 pixels wide,  the  numbering begins with zero and ends with 127.  Zero is in the columns of left most pixels and 127 is in the column of right most pixels.
  • Pixels going up and down, also begin with zero.  In the case of a display that is 64 pixels high, numbering begins with zero and ends with 63.  Zero is in the row of top pixels and 63 is in the row of bottom pixels.
  • Pixels are generally referenced in the format (x,y) where x is the pixel number in the horizontal direction and y is the number in the vertical direction.

Take a moment and study the drawing below.

Pixel Width and Height3

Don’t worry if you’re struggling to wrap your head around this.  After a few examples, this will become second nature.

U8glib ‘Hello World’  Tutorial

The Hello World Sketch Version A

We’ll discuss the details of this sketch in a minute, but for now, let’s light some OLEDs.

Copy and paste this into your Arduino IDE (program).   Be sure to change the constructor to match your display and set up.

// Henry's Bench Hello World - for use with Monochrome OLEDs

include "U8glib.h"


//**************************************************
// Change this constructor to match your display!!!
U8GLIB_SH1106_128X64 u8g(4, 5, 6, 7);
//**************************************************

void setup() {  
  u8g.setFont(u8g_font_unifont);
  u8g.setColorIndex(1); // Instructs the display to draw with a pixel on. 
}

void loop() {  
  u8g.firstPage();
  do {  
    draw();
  } while( u8g.nextPage() );
  delay(1000);   
}
  
void draw(){
  u8g.drawStr( 0, 20, "Hello World");
    
}

Run Your Sketch

The sketch will start immediately after upload.  If you are successful, the output will look like the picture below.

UGglib Hello World Tutorial A Output

Basic Program Flow – The Picture Loop

In ‘setup’ we first select the font we want to use.  The library supports many different fonts and we will experiment with another later.

After selecting the font,  we establish that drawing something means that we want to turn a pixel on.  We did this with ‘u8g.setColorIndex(1)‘.

The U8glib graphic library uses something called a picture loop.   The picture loop begins with ‘u8g.firstPage()‘ and  ends with ‘u8g.nextPage()‘.

The picture loop is a requirement within the graphics library.

Within this picture loop, you can use a variety of graphics commands.  In our loop we make a call to ‘draw()‘.   In this function we instruct the display to print ‘Hello World’.

Hello World Annotated

A Note on the Text Position

When you make a call to drawStr(),  you provided an X position value and a Y position value.  In the case of ‘Hello World’  we provide 0 and 20.

What we instructed the display to do is position the text so that the lower left hand corner of our text is at 0,20.

 

Hello World with Off Screen Text

Open your sketch and modify the drawStr function to read:  u8g.drawStr(-10,20, “Hello World”).     Upload the sketch and observe your OLED screen.  If you’ve done things correctly, it should look like this.

U8glib Offscreen Text Tutorial

Several of the U8glib functions accept coordinates that are off screen.   This feature is especially useful when you are animating text or objects  (you’ll see this in the next section).   The affects of going off screen can be summarized as follows:

  • An X position that is less than zero, will shift text or objects off screen to the left.
  • An X position that is greater than the width (127 on a screen 128 pixels wide)  will shift objects off screen to the right
  • A Y position that is less than zero, will shift text or objects off the top of the screen.
  • A Y position that is greater the  height (63 on screen 64 pixels high) will shift objects off of the bottom of screen.

If you have your Arduino IDE still open, go ahead and experiment.

Scrolling Hello World

As mentioned,  being able to set coordinates outside the view screen is useful when you want to animate.   One from of animation is to scroll text.  Lets try it.

Copy and paste the sketch below into your Arduino program.  Remember to change your constructor

 

// Henry's Bench Hello World Scrolling - for use with Monochrome OLEDs

#include "U8glib.h"

//**************************************************
// Change this constructor to match your display!!!
U8GLIB_SH1106_128X64 u8g(4, 5, 6, 7);
//**************************************************

int yPos = 0;

void setup() {  
  
  u8g.setFont(u8g_font_unifont);
  u8g.setColorIndex(1); // Instructs the display to draw with a pixel on. 
}

void loop() {  
  u8g.firstPage();
  do {  
    draw();
  } while( u8g.nextPage() );
  
  // If its too fast, you could add a delay
  if(yPos < 83){
    // if it's too slow, you could increment y by a greater number
    yPos++;  }
  else{
    // When the yPos is off the screen, reset to 0.
    yPos = 0;
  }  
}  
void draw(){
  u8g.drawStr( 0, yPos, "Hello World");    
}

Run the Scrolling Sketch

If you did things correctly,  it should look like this.

Part of the magic here has to do with the picture loop (which will be examined in more detail later).   But suffice to say,  the loop erased the previous display and and created a new display every cycle.

Take a minute and study the code.  Tinker with it.  Instead from top to bottom, try scrolling from bottom to top.  Now try to tinker with the X position and move the display from left to write.

18 Comments

  1. Tibs November 16, 2017
  2. dave August 24, 2017
  3. capnfatz@gmail.comAuthor March 1, 2017
  4. Andrew M March 1, 2017
  5. Andrew M February 24, 2017
  6. capnfatz@gmail.comAuthor February 10, 2017
  7. Seth Rogers February 10, 2017
  8. capnfatz@gmail.comAuthor November 21, 2016
  9. Pallavi November 21, 2016
  10. Roberto Carlos June 27, 2016
  11. capnfatz@gmail.comAuthor March 4, 2016
  12. AIRPOPCIE March 4, 2016
  13. david sondak October 22, 2015
  14. Hans October 8, 2015
  15. capnfatz@gmail.comAuthor September 23, 2015
  16. Dirk Eisner September 23, 2015
  17. Ryan September 3, 2015

Add a Comment

Your email address will not be published. Required fields are marked *