Tutorial on I2C OLED Display with Arduino/NodeMCU

The very first program you write when you start learning a new programming language is Hello World. The program itself does nothing more than printing a Hello World text on the screen. So, how do we get our Arduino to display Hello World? In this video, I'll be showing you how to get started with the small 0.91 or 128 by 32 and 0.96 or 128 by 64 I2C OLED display. There are hundreds of tutorials on the web explaining the same thing in different ways. But I couldn't find one that tells me all about OLED display and how to use them in different scenarios. It took me some time to work it all out. So, I thought I should create a tutorial on what I have learned and combine all the features and ways that OLED displays can be used in our projects. In this video, we'll be talking about what is an OLED display. Then we'll have a closer look at the 0.91 or 128 by 32 and 0.96 or 128 by 64 I2C OLED displays. Next, we'll talk about installing the Adafruit library to our Arduino IDE. Then we'll connect NodeMCU and Arduino to an OLED display. Next, we'll have a closer look at the code and display some text and graphics on it. We'll also talk about applying custom fonts and displaying images. Then we'll connect multiple OLEDs to a microcontroller using I2C multiplexer. And finally, we'll talk about a few common errors people make while using the OLED displays. For this tutorial, we need a breadboard, a 0.91 or 128 by 32, and a 0.96 or 128 by 64 I2C OLED display, Arduino UNO, Nano, whatever is handy, NodeMCU, TCA 9548A I2C multiplexer, few connecting cables, and a USB cable to upload the code. OLED or organic light emitting diode is a light emitting diode in which the emissive electroluminescent layer is a film of organic compound which consists of millions of small LED lights that emits light in response to electric current. OLEDs are used to create digital displays in devices such as television screens, computer monitors, portable systems such as mobile phones, handheld gaming consoles, and PDAs. An OLED display works without a backlight because it emits visible light. There are many types of OLED displays available in the market based on their size, color, brand, protocol, SPI or I2C, passive matrix or active matrix, and many more. In this tutorial, I'm going to talk about connecting 0.91 or 128 by 32 and 0.96 or 128 by 64 I2C OLED display to an Arduino Nano and NodeMCU. I2C bus technology uses only two pins of the MCU, so we have heaps available for other sensors. Let's have a closer look at these two displays. At the back of these displays, there are heaps of SMD capacitors and resistors soldered on the board. But, since it's an I2C device, we only care about these two pins. The display connects to Arduino using only four wires. Two for power, VCC and ground, and two for data, serial clock, and serial data, making the wiring very simple. The data connection is I2C, and the interface is also called two-wire interface. The onboard pins can be in different order, so always triple check before hooking it up to your project. Operational voltage is between 3 volt to 5 volts, but it is best to use the guidance from the manufacturer's data sheet. Sometimes we need to use two displays in our project. So, how can we achieve this? The trick is to have configurable address on the display. This unit has configurable address between 0x78 and 0x7A. Just by unsoldering the zero-ohm resistor from one side and hooking it up to the other side, or just by putting a global solder, we can change the address. We'll talk about it in depth when we hook up multiple displays to an Arduino in the later section of this tutorial. In pictures, these displays look very big, but practically speaking, they are tiny. They are made of 128 by 32 or 64 individual OLED pixels and do not require a backlight. Just have a look at this and see how small it is. Even though they are very small, they can be very useful in an electronic project. There are several libraries available to control these displays. In past, I've used the U8GLib library, but I find the Adafruit library very easy to understand and use in our projects. So, I'm going to use the Adafruit library in this tutorial. To control the OLED displays, you need the AdafruitGFX.h and the AdafruitSSD1306.h library. There are two ways you can download and install the library to your Arduino IDE. Method 1. Go to the library manager and search for Adafruit underscore SSD1306 and Adafruit underscore GFX. Select the latest version and hit the install button. Once installed, you can use the libraries in your program. Method 2. These two libraries can also be downloaded from GitHub. I'll provide the links in the description below. Once downloaded, copy the Adafruit underscore SSD1306-master folder from the downloaded zip file into the Arduino libraries folder. This folder is usually found at Documents, Arduino, Libraries on Windows system. On Linux, it's usually found at the home folder, Arduino, Libraries. Finally, in the Arduino library folder, rename the Adafruit underscore SSD1306-master folder to Adafruit underscore SSD1306. Even if you don't rename, that's fine. Now, let's have a look at the Adafruit underscore SSD1306.h file. Two things we need to know in this library. One, if you want to use the smaller display, use the default 128 underscore 32. Otherwise, for bigger display, comment the 128 underscore 32 and uncomment the 128 underscore 64. Pretty self-explanatory. Number two, if you have soldered the hex 7a address on the board, which we'll talk about later, then use the 7-bit hex 3d address for the bigger displays. Otherwise, use the default hex 3c address. For the smaller displays, the address is hex 3c. Let's start by connecting the NodeMCU to the display. The first and the most important thing to note is that some of the display may have the ground and VCC power pins swapped around. Check your display to make sure that it is in the same order as in the image. If the pins are swapped, make sure to change the connections to the Arduino or NodeMCU. Now connect the VCC to 3V, GND to GND, SLC to D1 of NodeMCU and SDA to D2. In case of Arduino, connect the VCC to 5V, GND to GND, SCL to A5, SDA to A4. Now if you are using an Arduino Mega, use pin 21 for SCL and 20 for SDA. Adafruit library comes with really good examples for both 128x32 and 128x64 displays. The library is located under File, Examples, Adafruit SSD1306 and then the display type. We are going to use the 128x32 i2c example and we'll modify it to work with both 128x64 and 128x32 displays. First by hooking it up to an Arduino and then to a NodeMCU board. The code starts by including both the Adafruit libraries. In this tutorial, I am going to stress on only those parts of the code which are necessary for us to load on both boards and displays. If you want to know more about the code, please drop a comment on my blog or in the comment section below and I'll endeavour to get back to you. First we are going to load the code to an Arduino Nano connected to a 128x32 display. We can use the code as is without making any modifications. 128x32 uses 0x3C address, so this bit looks all good here. Let's double check the header file. Yes, it is also using the 0x3C address and the display type is 128x32. Now let's connect the 128x64 display. As we know, it uses the 0x3C address by default, so we don't need to update the address in either the code or the library. We just need to comment the 128x32 and uncomment the 128x64 in the header library and change the LCD height to 64 in our code. Now to run the same code on a NodeMCU, we need to change one more line in our code. The hash define OLED underscore reset 4 will change to LED underscore built in. Rest of the code is same as what we saw in Arduino. Pretty much to display anything, we need to first clear out the previous screen. Then we need to draw the object, show it on the hardware, then we need to wait for some time before displaying the next item. In this example, we are displaying few items like text, line, circles, scrolling text, triangles and more. Go ahead and use your imagination and display whatever you want on these tiny displays. Sometimes your code need to display custom fonts and images. If you are very good in bitmapping, then you just need to create a byte array by turning on or off the tiny LEDs of the display to create a custom font or an image. However, I am not very good in doing these mappings and don't want to spend hours creating the bitmap table. So, what are my options? I generally use two websites to generate custom fonts and images. The links are provided in the description below. Go to the font converter website, select the font family, style, size, library version as Adafruit GFX font and then hit the create button. On the right hand side of the page, you can see how your font is gonna look like on the actual display. Based on your selection, the web page generates the font's header file. Create a file called modified underscore font dot h in the same folder where your code is and copy and save the generated code into it. Then you just need to include this header file in your code to use the font. To use the font in your code, you just need to add display dot set font with the name of the font in your code. You can get the name of the font from the header file you just added to your project. That's it. Easy. Memory is always a concern while using custom fonts. So, always consider the bytes that will be consumed by the memory. Just remember, Arduino Uno has only 32k of memory. To display a bitmap image on your screen, you first need to create a I'm using the good old MSPaint to create a 128 by 64 bitmap image which I'll then upload to this image converter website. The website converts the image into byte string which can be used with the Arduino and OLED display. Start by uploading the image to the website. Then put a check on the invert image color checkbox and change the output code format to Arduino code. Next, select the orientation and hit the generate code button. The preview section shows you how your image will look like on the actual display. I have included the code with this tutorial which you can use to display your image. You just need to replace the byte array in my code with the one you just generated and then load it to your Arduino. Connecting 228 by 64 displays to your project is easy. You just need to unsolder the 0 ohm resistor from the hex 78 address and put it on the hex 7a and then use the hex 3d address in your code instead of the hex 3c. You must be wondering why we are using the hex 3c and hex 3d addresses and not the actual hex 7a and 78 addresses. Arduino accepts 7-bit address and not the 8-bit hardware addresses. So, we first need to convert the 8-bit address to binary and then chop off the least significant bit to get the 7-bit address. Then convert the 7-bit to hex to get the hex 3c or hex 3d addresses which you then enter in your code. We first need to initialize the display by giving it a unique name. Then in your code use the display 1 and display 2 to call the begin statement with the device addresses in them. That's it. You can now go ahead and do whatever you want using the display 1 or display 2 in the rest of the code. I have provided an example with this tutorial which you can use for your reference. Wiring is exactly the same as what we have done before. Pretty much you just need to add another display to the same I2C pin of either the Arduino or the NodeMCU. Based on the addresses, the microcontroller then sends the data onto the I2C data line. Now, what if you want to hook up more than two displays to your project? Arduino has limited number of pins and hence you cannot have more than a certain amount of shields attached to it. Moreover, it has only one pair of I2C buses. So, how can we attach more than two I2C displays to an Arduino? The trick is to use a TCA9548 multiplexer. TCA9548 allows a single microcontroller to communicate with up to 64 sensors all with the same or different I2C addresses by assigning a unique channel to each sensor slave sub-bus. When we talk about sending data over two wires to multiple devices, we then need a way to address them. It's same as the postman coming on a single road and dropping the mail packets to different houses because they have different addresses written on them. Connect VIN to 5V, GND to GND, SCL to I2C clock and SDA to I2C data line. Then wire up the OLEDs to VIN, GND and use one of the SCL and SDA multiplexed buses. The channels are selected by sending the TCA9548 its I2C address followed by the channel number. You could have at the max eight of these multiplexers connected together on 0x70 to 0x77 addresses in order to control 64 of the same I2C address parts. By connecting the three address bits A0, A1 and A2 to VIN, you can get different combination of addresses. I'll explain this in depth in my next tutorial on TCA9548 breakout board. For now, let's just hook up eight OLEDs to this board and have a quick look at the code. In the code, let's start by including the wire library and by defining the multiplexers addresses. Then we need to select the port we want to communicate to and send the data on it using this function. Next, we'll initialize the display in the setup section by calling the uatg.begin function for each display attached to the MUX. Once initialized, we can then do whatever we want just by calling the function tcaselect where i is the value of the multiplexed Advantages include, OLED displays don't need a backlight, displays are very thin and lightweight, they consume low power, viewing angle are wider than LCDs, brightness and contrast are great, they're high speed and have low response time, and they have a deep black color. The image of an OLED display is beautiful. However, OLED displays also have disadvantages. Because OLED screen contains organic material, their lifespan is shorter than LCD displays. Additionally, OLED displays get burn-ins after showing the same image for a long time. After a burn-in, the image stays on the screen even after showing another image. Water can instantly damage the organic material of these displays. To conclude this tutorial, let's talk about a few common errors people make while using these displays. Always triple check the pins before using it in your project. Pick up the right library address in the header file and in your code. If address is wrong, the OLED will not display anything. The display size must be changed in the driver before it can be used in your project. If it's not changed, you'll get an error message when attempting to verify the code. If using NodeMCU, make sure you replace the OLED underscore reset from 4 to LED underscore built-in. I have seen people making all sorts of crazy things using these OLED displays. Some have even made video games and all. I'm really not interested in making a video game using this tiny display. However, I will now leave you to explore your imaginations and come out with amazing ideas. Thanks again for watching this video. I hope it helps you. If you want to support me, you can subscribe to my channel and watch my other videos. Thanks. See you again in my next video. Bye now.