Have you bought yourself an OLED display for Arduino but don't know how to get started? Not as simple to use as you thought? Try this out!

You'll learn to wire up your OLED display and communicate to it over serial (I2C). We're going to cover how to 1) send text input from the serial window on the computer to the OLED display 2) customize the Adafruit binary image which appears in the standard testing sequence (i.e. the falling star flakes from the original code provided by Adafruit Industries) to any 16x16 image you like and 3) control that image on the screen with a joystick. This tutorial is intended as a learning tool to get you started with the basics.
Here's what you need:

  • 1 x Arduino UNO + USB cable
  • 1 x computer available to plug your Arduino in
  • 1 x OLED 0.96" IIC Serial 128X64 display
  • 1 x mini prototyping breadboard
  • male-to-male jumper cables
  • 1 x 3 axis joystick (z-axis push button), required parts 2 & 3 of the tutorial

NOTE: You might be able to use other models of Arduino, but you have to check for compatibility with the libraries that we're going to download and use in step 2.

Step 1: Wire Up Circuit As Shown

In case the text in the image is too small to read:

  • joystick x (white wire) goes to A0
  • joystick y (green wire) goes to A1
  • z push button (blue wire) goes to A2
  • SCL on the OLED goes to A5, SDA goes to A4, check your module carefully
  • check to verify whether your joystick should be powered from 3.3V or 5V

***NOTE: all red cables are VCC and black cables are GND, check carefully when wiring up ***

Step 2: Install Adafruit SSD1306 & GFX Libraries

To get the module working, there is some complex firmware coding required. Thankfully, Adafruit Industries has done most of the work by writing some (free) libraries of functions which integrate into the Arduino IDE and allow us to focus mostly on coding up the project rather than rack our brains just trying to get the OLED module to even work. We'll need two libraries below, follow the links and click "Download ZIP"

Adafruit SSD1306 Library:


Unzip and rename the folder to "Adafruit_SSD1306"

Adafruit GFX Library:


Unzip and rename the folder to "Adafruit_GFX"

Place both folders in the "libraries" folder of Arduino:

C:\Program Files (x86)\Arduino\libraries

Step 3: Change Default Library Settings

For Adafruit_SSD1306 Library:

  • Go to: C:\Program Files (x86)\Arduino\libraries\Adafruit_SSD1306
  • Open Adafruit_SSD1306.h (in a text editor like Notepad++ for example)
  • Find and comment out the line: #define SSD1306_128_32
  • Uncomment the line: #define SSD1306_128_64

Step 4: Tutorial 1: Testing

Open the ssd1306_128x64_i2c example in Arduino:

Change address from 0x3D to 0x3C in void setup()

Plug in your arduino, select the correct COM port and upload the sketch. The system will run through various functions such as rectangles, triangles, falling starfruit etc. Play around with the default functions for the various shapes to learn how it works.

Step 5: Tutorial 2: Displaying Text

Plug in your arduino, select the correct COM port and upload the code provided in this step. Open the serial window (magnifying glass icon on the top right).

After the Adafruit startup screen appears, it'll just wait like that until you give input text from the serial window. Type a small phrase like: "Arduino is fun". Next, how about a longer phrase that exceeds the length of the screen: "the quick brown fox jumps over the lazy dog".

To get the most learning out of this step, you need to read through the code I've provided to understand how everything works. You can even compare it with Adafruit's original code from the previous step if you're not sure how something works. If there is a new function you haven't come across before, check for it's definition or description in the downloaded Adafruit library or on the arduino website.

Step 6: Tutorial 3: Editing Binary Image & Moving It Around the Screen (joystick Required)

If you're still running the code from tutorial 2 and have a joystick attached, just press the joystick button and my HT logo will appear on the display. You can now move it around the screen with the joystick. If the logo doesn't appear at the centre of the screen when the joystick is released or doesn't move to the end when the joystick is pushed to maximum you may need to adjust the height and width values in the movingbitmap function in the code.

Now look in the original code from Adafruit for the binary object logo16_glcd_bmp[] or in the first image above. Notice that it consists of 16 rows, and each row has a pair of 8-bit binary numbers, i.e. this is the 16x16 binary image logo; each 0 corresponds to a pixel off and a 1 corresponds to a pixel on. If you look closely enough at it and ignore the 0's, you can see the 1's form a star shape.

Now looking in the code provided from tutorial 2 above (or in the second image above), notice I've changed it to HT (hence why you saw a moving HT on the screen). Here's your chance to be artistic, change the binary numbers to form something you'd like to see move around on the screen, it could be a letter, number, an abstract symbol or even a picture of mario if you're confident enough.

When you're done, upload the code and press the joystick push button to display it. You can now move it around!

Step 7: Get Creative!

Now that you've seen some of what can be done with your OLED display, there are unlimited possibilities for projects. What would you like to do with it?

  • Do you want to make a simple platform or space invaders game?
  • Or perhaps you want to use it to display temperature and climate data for an IoT project?
  • Maybe even use it on a transmitter for a drone project, i.e. display the transmitter trimmer settings or the drone motion data on your OLED?

I'll leave you to be creative.

As a final note, I'm currently making instructables on several different arduino modules (I've already done one on 433MHz RF wireless and a 6-axis gyro module) and I'm open to ideas for other modules or projects to do instructables on, so suggestions are welcome in the comments below; who knows, your suggestion might be done next. If you found this instructable useful, why not stay tuned for future projects by following me on Instructables and on Facebook / Twitter:



Your support is greatly appreciated! Happy DIY'ing!

<p>Hi, I went to the Adafruit_SSD1306.h file and uncomment the line #define SSD1306_128_64 and comment // #define SSD1306_128_32 // #define SSD1306_96_16<br>But when I try to compile and upload the code I got the following error : <br>exit status 1 <br>#error (Height incorrect, please fix Adafruit_SSD1306.h!&quot;);<br><br>But I did it ! What to do next..? <br><br>Thanks</p>
<p>I finally came back to this because in need an OLED for my new project. By simply adding </p><p> #define SSD1306_LCDHEIGHT 64</p><p>on top of <br>#if (SSD1306_LCDHEIGHT != 64)<br>#error(&quot;Height incorrect, please fix Adafruit_SSD1306.h!&quot;);<br>#endif<br><br>It works as intended !</p>
<p>Hi, did you make sure to restart the arduino application after editing the .h file? So maybe close arduino then reopen it and then compile and upload.</p>
<p>Hi, </p><p>I am having the same problem. </p><p>I have restarted the Arduino application and still no joy, just the same error message coded into the sketch, any second ideas?</p><p>Thanks</p>
<p>I've just re-downloaded the library and repeated the process outlined in my instructable and there doesn't seem to be any compilation errors. A possible reason why you are getting an error is a very subtle mistake you may have done in step 2: in renaming Adafruit-GFX-Library, make sure you have used _ instead of -.</p>

About This Instructable




More by HobbyTransform:Arduino OLED 128X64 IIC Serial Display: printing text and moving images MPU6050: Arduino 6 Axis Accelerometer + Gyro - GY 521 Test & 3D Simulation RC Multi Channel Arduino Proportional Transmitter / Receiver with Button Trimmers 
Add instructable to: