Introduction: Arduino OLED 128X64 IIC Serial Display: Printing Text and Moving Images
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.
What you need can be found on eBay (links below):
- 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 / Google+.
If you enjoyed this instructable and would like to see more like this, please consider supporting me by purchasing your materials for this project through the affiliate links in the materials section or donating below:
Your support is greatly appreciated! Happy DIY'ing!
5 years ago
do 32 in if line instead of 64
5 years ago
Hi Thanks for a very clear "instructable" for the "Arduino" but I am using a NodeMcu Development Board ESP8266 12E WIFI CH340 v3 USB ESP12 I understand the Arduino code is compatible but I may have use different connections for SLK & SDA any comments would be appreciated.
Reply 5 years ago
Hi, I'm not sure how to help you there. I haven't used the board you mentioned, so you may have to refer to the data sheet and support forums and websites relating to the device.
5 years ago
6 years ago
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
But when I try to compile and upload the code I got the following error :
exit status 1
#error (Height incorrect, please fix Adafruit_SSD1306.h!");
But I did it ! What to do next..?
Reply 6 years ago
I finally came back to this because in need an OLED for my new project. By simply adding
#define SSD1306_LCDHEIGHT 64
on top of
#if (SSD1306_LCDHEIGHT != 64)
#error("Height incorrect, please fix Adafruit_SSD1306.h!");
It works as intended !
Reply 6 years ago
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.
Reply 6 years ago
I am having the same problem.
I have restarted the Arduino application and still no joy, just the same error message coded into the sketch, any second ideas?
Reply 6 years ago
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 -.