Small OLED displays are very popular in Arduino, ESP32, ESP8266, RP2040 and CANABLOX projects. They are bright, compact, inexpensive and easy to connect with only a few wires.
But they can also be surprisingly frustrating. A display may be detected by an I2C scanner, but still show nothing, random pixels, shifted text, broken graphics or only part of the screen.
In many cases, the display is not defective. The real problem is usually the wrong display controller, wrong library, wrong screen size, wrong reset setting, unstable power, or an I2C wiring issue.
Typical Symptoms
- The OLED stays completely blank.
- The display shows random dots or noise.
- Text appears shifted to the left or right.
- Only part of the screen updates.
- The image looks wrapped, duplicated or cut off.
- The I2C scanner finds 0x3C or 0x3D, but the example sketch does not work.
- The same code works with one OLED module but not with another.
First Important Point: The I2C Address Is Not the Controller Type
Many users see address 0x3C in the I2C scanner and assume the display must be an SSD1306. That is not safe.
The I2C address only tells you that something answered on the bus. It does not tell you which display controller is inside the OLED module.
Several OLED controllers can use the same or similar I2C addresses, including:
- SSD1306
- SH1106
- SSD1315
- Other compatible or semi-compatible OLED controller variants
If the library expects one controller but the module uses another, the display may still answer on I2C, but the screen output will be wrong.
SSD1306 vs SH1106
The most common OLED confusion is between SSD1306 and SH1106.
Both are used in small monochrome OLED modules. Both can appear in 128x64 displays. Both can use I2C. Both are often sold with very similar product descriptions.
But they are not identical. Their internal display memory layout is different. This is why a sketch written for SSD1306 may not display correctly on an SH1106 module.
| Feature | SSD1306 | SH1106 |
|---|---|---|
| Common use | Very common on 0.96 inch 128x64 OLEDs | Very common on 1.3 inch 128x64 OLEDs |
| Typical I2C address | 0x3C or 0x3D | 0x3C or 0x3D |
| Memory layout | Matches most SSD1306 libraries directly | Different offset/layout; needs SH1106 support |
| Typical wrong-library symptom | Usually works with SSD1306 examples | Shifted image, random pixels, partial display or blank screen |
| Fix | Use SSD1306 library/constructor | Use SH1106-compatible library/constructor |
Common Cause: Wrong Library
If your display is detected by the scanner but shows garbage or nothing, the library is one of the first things to check.
For example, an SSD1306 library may not properly drive an SH1106 display. A library for one screen size may not work correctly with another screen size. A library example may also use a different address or reset pin than your module requires.
Common OLED library problems include:
- The library supports SSD1306, but your display uses SH1106.
- The library example is for 128x32, but your display is 128x64.
- The wrong I2C address is used in the sketch.
- The wrong constructor is selected.
- Multiple display libraries are installed and the wrong one is being compiled.
Common Cause: Wrong Display Size
OLED modules may look similar but have different resolutions.
- 128x64
- 128x32
- 96x16
- 64x48
- Other small graphic OLED formats
If the sketch initializes a 128x32 display as 128x64, or a 128x64 display as 128x32, the result may be blank output, cut-off text, or graphics drawn outside the visible area.
Always set the display width and height to match the actual display module.
Common Cause: Wrong I2C Address
Most small I2C OLED displays use address 0x3C, but some use 0x3D. Some boards also have address solder jumpers.
If the scanner finds 0x3D, but the sketch uses 0x3C, the display will not initialize.
Run an I2C scanner first and use the address it reports in the display initialization code.
display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
Change 0x3C to the address found by the scanner if needed.
Common Cause: Reset Pin Setting
Some OLED libraries ask for a reset pin. Some OLED modules expose a reset pin, while others do not.
If your module does not have a reset pin, many libraries allow using -1 for the reset pin.
#define OLED_RESET -1
If the reset setting is wrong, the display may not initialize reliably. It may stay blank until power is cycled or reset manually.
Common Cause: Power Problems
OLED displays do not usually draw huge current, but they still need stable power. A display may behave strangely if the supply voltage drops, if the breadboard contact is poor, or if the ground connection is weak.
Power-related OLED problems can look like software problems:
- Random pixels during startup.
- Screen flickering.
- Display works when touched or moved.
- Display works on USB power but not on battery power.
- Display works alone but fails when other modules are connected.
Check the voltage at the OLED module itself, not only at the microcontroller board.
Common Cause: Loose Wires or Breadboard Contacts
OLED displays often use small jumper wires, breadboards and pin headers. A loose SDA, SCL, GND or VCC connection can cause random behavior.
This is especially common when the display:
- Works only when pressed by hand.
- Changes output when wires are moved.
- Works for a while and then freezes.
- Shows random pixels after reset.
Try shorter wires, another breadboard location, or direct Dupont wires from the controller to the display.
Common Cause: Wrong Voltage Level
Many OLED modules can run from either 3.3V or 5V because they include a regulator or level shifting. Others are 3.3V only.
ESP32, ESP8266, RP2040 and most modern microcontrollers use 3.3V GPIO. Classic Arduino Uno and Nano boards use 5V GPIO.
Problems can happen when:
- A 3.3V-only OLED is connected to a 5V Arduino without level shifting.
- A 5V OLED module does not reliably recognize 3.3V logic.
- The OLED module pulls SDA and SCL up to 5V while connected to a 3.3V microcontroller.
- The module’s onboard regulator needs more voltage than the system provides.
Check the module description and measure the idle voltage on SDA and SCL. On a 3.3V system, the I2C pull-ups should normally pull the lines up to 3.3V, not 5V.
Common Cause: I2C Pull-Ups
I2C requires pull-up resistors on SDA and SCL. Many OLED modules already include them, but not all do.
If there are no pull-ups, the OLED may not be detected. If the pull-ups are too weak, communication may be unstable. If too many modules with onboard pull-ups are connected, the combined pull-up resistance may become too low.
A typical starting value for small I2C projects is 4.7kΩ from SDA to VCC and 4.7kΩ from SCL to VCC.
Common Cause: I2C Bus Speed Too High
Some OLED displays work reliably at 400 kHz. Others are happier at 100 kHz, especially with longer wires or breadboard setups.
If the display is detected but unstable, try lowering the I2C clock speed.
Wire.setClock(100000); // 100 kHz
Use this after Wire.begin().
Common Cause: Display Not Cleared or Updated
Some libraries draw graphics into a memory buffer first. The buffer is not automatically visible on the display until you send it to the screen.
Depending on the library, you may need a command such as:
display.display();
or:
u8g2.sendBuffer();
If the code draws text but never sends the buffer, the display may stay blank.
Common Cause: Text Color Not Set Correctly
For monochrome OLED libraries, text color still matters. If the text color is set incorrectly, text may be drawn as black on a black background.
For many SSD1306-style examples, the text color is set like this:
display.setTextColor(SSD1306_WHITE);
If this line is missing or changed, the display may appear blank even though the code is running.
Common Cause: Multiple Libraries with Similar Names
The Arduino IDE may have several OLED libraries installed at the same time. Some examples are written for one specific library and will not work correctly with another.
If the compiler says “Multiple libraries were found for...” check which library is actually being used.
During troubleshooting, use the example sketches included with the exact library you want to use. Do not mix examples from one library with another library unless you understand the differences.
Recommended Troubleshooting Steps
- Disconnect all other I2C devices.
- Connect only the OLED display.
- Run an I2C scanner and write down the address.
- Confirm the display size: 128x64, 128x32 or another size.
- Try both possible addresses if the scanner result is uncertain.
- Confirm whether the display is SSD1306, SH1106 or another controller.
- Use a library that supports the actual controller.
- Check the reset pin setting.
- Lower the I2C speed to 100 kHz.
- Try shorter wires and a stable power supply.
Simple SSD1306 Test Checklist
- I2C scanner finds 0x3C or 0x3D.
- Sketch uses the same address.
- Display is actually SSD1306-compatible.
- Width and height match the module.
- Reset pin is set correctly.
- Text color is set to white/on.
- The display buffer is sent to the screen.
Simple SH1106 Test Checklist
- I2C scanner finds the OLED address.
- The module is likely a 1.3 inch 128x64 OLED.
- An SH1106-compatible library is used.
- The constructor is for SH1106, not SSD1306.
- Display size is set to 128x64.
- The display is cleared and the buffer is sent after drawing.
When the OLED May Actually Be Defective
OLED modules are not immune to defects, but a defective display should be the last assumption, not the first.
A display may be defective if:
- It is not detected by any controller board.
- It gets unusually hot.
- It pulls SDA or SCL permanently low.
- It has visible physical damage.
- The exact same wiring and sketch work with another identical OLED.
Before throwing it away, test it with one controller, one known-good cable set, one simple example sketch and no other connected modules.
CANABLOX Practical Note
In a CANABLOX system, OLED and other I2C display modules are easier to isolate because the wiring is standardized. This removes many of the usual breadboard and jumper wire mistakes.
When troubleshooting an OLED in a CANABLOX setup, connect only the controller module and the OLED module first. Run the I2C scanner, confirm the address, then test the correct library for the display controller. After the display works by itself, add other CANABLOX modules one at a time.
Conclusion
If an OLED display shows random pixels, shifted text or nothing at all, do not assume it is broken. First check whether the library matches the actual display controller.
The most common trap is using SSD1306 code with an SH1106 display. The I2C scanner may still find the display, but the screen output will not be correct.
Start with the address, then confirm the controller, display size, reset setting, power, wiring and library. Once those match, small OLED displays are usually very reliable.