326

Monochrome OLED Breakouts Created by lady ada https://learn.adafruit.com/monochrome-oled-breakouts Last updated on 2022-09-20 03:02:00 PM EDT ©Adafruit Industries Page 1 of 77 Table of Contents Overview 5 Power Requirements 7 • OLED Power Requirements • 5V- ready 128x64 and 128x32 OLEDs • 0.96" 128x64 OLED Arduino Library & Examples • • • • Install Arduino Libraries Run Demo! Create Bitmaps with LCD Assistant Create Bitmaps with image2cpp Wiring 128x64 OLEDs • • • • • • 9 14 Solder Header I2C or SPI Using with I2C Converting From I2C to SPI Mode Wiring It Up! Using with SPI Wiring 128x32 SPI OLED display 30 • 128x32 SPI OLED Wiring 128x32 I2C Display 32 • 128x32 I2C OLED Wiring OLD 0.96" 128x64 OLED 40 • 128x64 Version 1.0 OLED CircuitPython Wiring • • • • • • Adafruit Adafruit Adafruit Adafruit Adafruit Adafruit 42 OLED FeatherWing 128x32 I2C OLED Display 128x32 SPI OLED Display 0.96" 128x64 OLED Display STEMMA QT Version - I2C Wiring 0.96" or 1.3" 128x64 OLED Display Original Version - I2C Wiring 0.96" or 1.3"  128x64 OLED Display - SPI Wiring CircuitPython Setup 46 • CircuitPython Installation of DisplayIO SSD1306 Library • Code Example Additional Libraries CircuitPython Usage • • • • • • 47 I2C Initialization 128 x 64 size OLEDs (or changing the I2C address) Adding hardware reset pin SPI Initialization Example Code Where to go from here ©Adafruit Industries Page 2 of 77 Python Wiring • • • • • • • Adafruit Adafruit Adafruit Adafruit Adafruit Adafruit Adafruit 56 PIOLED 128x64 OLED Bonnet for Raspberry Pi 128x32 I2C OLED Display 0.96" 128x64 OLED Display STEMMA QT Version - I2C Wiring 0.96" or 1.3" 128x64 OLED Display Original Version - I2C Wiring 128x32 SPI OLED Display 0.96" or 1.3" 128x64 OLED Display - SPI Wiring Python Setup • • • • 61 Python Installation of SSD1306 Library Pillow Library NumPy Library Speeding up the Display on Raspberry Pi Python Usage • • • • • 62 I2C Initialization 128 x 64 size OLEDs (or changing the I2C address) Adding hardware reset pin SPI Initialization Example Code Troubleshooting 69 Downloads 70 • • • • • • • • • • Software Datasheets Files Schematic & Schematic & Schematic & Schematic & Schematic & Schematic & Schematic & Fabrication Fabrication Fabrication Fabrication Fabrication Fabrication Fabrication ©Adafruit Industries Print Print Print Print Print Print Print for for for for for for for 0.96" OLED - STEMMA QT version 0.96" OLED - Original version 1.3" OLED 1.3" OLED STEMMA QT 0.91" 128x32 I2C 0.91" 128x32 I2C STEMMA QT 0.91" 128x32 SPI Page 3 of 77 ©Adafruit Industries Page 4 of 77 Overview This is a quick tutorial for our 128x64 and 128x32 pixel monochrome OLED displays. These displays are small, only about 1" diagonal, but very readable due to the high contrast of an OLED display. Each OLED display is made of 128x64 or 128x32 individual white OLEDs, each one is turned on or off by the controller chip. Because the display makes its own light, no backlight is required. This reduces the power required to run the OLED and is why the display has such high contrast; we really like this miniature display for its crispness! ©Adafruit Industries Page 5 of 77 The driver chip, SSD1306 can communicate in multiple ways including I2C, SPI and 8bit parallel. However, only the 128x64 display has all these interfaces available. For the 128x32 OLED, only SPI is available. Frankly, we prefer SPI since its the most flexible and uses a small number of I/O pins so our example code and wiring diagram will use that. For the 0.96" STEMMA QT version, we've updated the design to add auto-reset circuitry so that the reset pin is optional, since it speaks I2C you can easily connect it up with just two wires (plus power and ground!).  We've even included SparkFun qwiic (https://adafru.it/Fpw) compatible STEMMA QT (https://adafru.it/Ft4) connectors for the I2C bus so you don't even need to solder!  ©Adafruit Industries Page 6 of 77 Power Requirements OLED Power Requirements The OLED and driver require a 3.3V power supply and 3.3V logic levels for communication. The power requirements depend a little on how much of the display is lit but on average the display uses about 20mA from the 3.3V supply. Built into the OLED driver is a simple switch-cap charge pump that turns 3.3v-5v into a high voltage drive for the OLEDs. You can run the entire display off of one 3.3V supply or use 3.3V for the chip power and up to 4.5V for the OLED charge pump or 3.3V for the chip power and a 7-9V supply directly into the OLED high voltage pin. 5V- ready 128x64 and 128x32 OLEDs Unless you have the older v1 128x64 OLED, you can rest assured that your OLED is 5V ready. All 1.3" 128x64 and the small 128x32 SPI and I2C are 5V ready, if you have a v2 0.96" 128x64 OLED with the 5V ready mark on the front, it's also 5V safe. If you have an older 0.96" OLED (see below) you'll need to take extra care when wiring it to a 5V micontroller. The OLED is designed to be 5V compatible so you can power it with 3-5V and the onboard regulator will take care of the rest. All OLEDs are safe to use with 3.3V logic and power. ©Adafruit Industries Page 7 of 77 Simply connect GND to ground, and Vin to a 3 to 5V power supply. There will be a 3.3V output on the 3Vo pin in case you want a regulated 3.3V supply for something else. 0.96" 128x64 OLED The older 0.96" 128x64 OLED is a little more complex to get running as it is not 5V compatible by default, so you have to provide it with 3.3V power. • VDD is the 3.3V logic power. This must be 3 or 3.3V ©Adafruit Industries Page 8 of 77 • VBAT is the input to the charge pump. If you use the charge pump, this must be 3.3V to 4.2V • VCC is the high voltage OLED pin. If you're using the internal charge pump, this must be left unconnected. If you're not using the charge pump, connect this to a 7-9V DC power supply. For most users, we suggest connecting VDD and VBAT together to 3.3V and then leaving VCC unconnected. Arduino Library & Examples For all of the different kinds of small OLED monochrome displays, you'll need to install the Arduino libraries. The code we have is for any kind of Arduino, if you're using a different microcontroller, the code is pretty simple to adapt, the interface we use is basic bit-twiddling SPI or I2C Install Arduino Libraries Using these OLEDs with Arduino sketches requires that two libraries be installed: Ada fruit_SSD1306, which handles the low-level communication with the hardware, and Ad afruit_GFX, which builds atop this to add graphics functions like lines, circles and text. In recent versions of the Arduino IDE software (1.6.2 and later), this is most easily done through the Arduino Library Manager. Open up the Arduino library manager: Search for the Adafruit SSD1306 library and install it ©Adafruit Industries Page 9 of 77 Search for the Adafruit GFX library and install it If using an earlier version of the Arduino IDE (prior to 1.8.10), also locate and install Ad afruit_BusIO (newer versions will install this dependency automatically). We also have a great tutorial on Arduino library installation here: http://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use (https:// adafru.it/aYM) Run Demo! After installing the Adafruit_SSD1306 and Adafruit_GFX library, restart the Arduino IDE. You should now be able to access the sample code by navigating through menus in this order: File→Examples→Adafruit_SSD1306→SSD1306... After you've finished wiring the display as indicated on the following pages, load the example sketch to demonstrate the capabilities of the library and display. The OLED SSD1306 driver is based on the Adafruit GFX library which provides all the underlying graphics functions such as drawing pixels, lines, circles, etc. For more ©Adafruit Industries Page 10 of 77 details about what you can do with the OLED check out the GFX library tutorial (https:/ /adafru.it/aPx) Create Bitmaps with LCD Assistant You can create bitmaps to display easily with the LCD assistant software (https:// adafru.it/aPs). First make your image using any kind of graphics software such as photoshop or Paint and save as a Monochrome Bitmap (bmp) ©Adafruit Industries Page 11 of 77 Select the following options (You might also want to try Horizontal if Vertical is not coming out right) and import your monochrome bitmap image. Save the output to a cpp file ©Adafruit Industries Page 12 of 77 You can use the output directly with our example code Create Bitmaps with image2cpp image2cpp was created by GitHub user javl and provides a handy way to create bitmaps without installing any additional software. Just visit https://javl.github.io/ image2cpp/, (https://adafru.it/11bI) upload an image, put in any settings that you would like to use, select a format and generate the code. You can copy the code right into your sketch. If you're interested, you can view the source in their GitHub repository (ht tps://adafru.it/11bJ). ©Adafruit Industries Page 13 of 77 Wiring 128x64 OLEDs Solder Header Before you start wiring, a strip of header must be soldered onto the OLED. It is not possible to "press-fit" the header, it must be attached! Start by placing an 8-pin piece of header with the long ends down into a breadboard for stability Place the OLED on top so all the short ends of the header stick thru the header pads Finish by soldering each of the 8 pins to the 8 pads! ©Adafruit Industries Page 14 of 77 I2C or SPI The nice thing about the 128x64 OLEDs is that they can be used with I2C (+ an optional reset line) or SPI. SPI is generally faster than I2C but uses more pins. It's also easier for some microcontrollers to use SPI. Anyways, you can use either one with this display Using with I2C The display can be used with any I2C microcontroller. Because the I2C interface is for 'writing' to the display only, you'll still have to buffer the entire 512 byte frame in the microcontroller RAM - you can't read data from the OLED (even though I2C is a bidirectional protocol). If you have the older non-STEMMA version of the OLED, you'll need to solder the two jumpers on the back of the OLED. Both must be soldered 'closed' for I2C to work! For the new STEMMA-capable version, the J1 and J2 jumpers are closed so that the display is by default in I2C mode! There's a typo on the board, to put it into SPI, open the two jumpers (as they're closed by default) ©Adafruit Industries Page 15 of 77 Converting From I2C to SPI Mode The original version of this display was SPI by default, and you could convert to I2C with some light soldering. Many folks using these displays did not know how to solder, didn't own an iron or were not comfortable with soldering, so we converted the board to STEMMA QT 'plug and play' I2C so no soldering is required to use in I2C mode. To convert it back to SPI is very easy, and requires a thin screwdriver or other sharptipped item be careful not to cut towards you as always so you do not accidentally cut yourself! Wiring It Up! For the STEMMA QT version of this board, you do not need to connect RST - this revision added auto-reset circuitry so the RESET pin is not required. For some microcontrollers with on-board STEMMA QT, such as the Adafruit ESP32-S2 feathers, you may need to enable the STEMMA QT pins first. Refer to the guide for the specific board you are using. Finally, connect the pins to your Arduino • GND goes to ground (black wire on STEMMA QT version) • Vin goes to 5V (red wire on STEMMA QT version) • Data to I2C SDA (on the Uno, this is A4 on the Mega it is 20 and on the Leonardo digital 2) (blue wire on STEMMA QT version) • Clk to I2C SCL (on the Uno, this is A5 on the Mega it is 21 and on the Leonardo digital 3) (yellow wire on STEMMA QT version) • RST to digital 4 (you can change this pin in the code, later) (Not necessary on 0.96" STEMMA QT version) This matches the example code we have written. Once you get this working, you can try a different Reset pin (you can't change the SDA and SCL pins). Finally you can run the File→Sketchbook→Libraries→Adafruit_SSD1306→SSD1306_12 8x64_i2c example. If you wired the RST pin to a GPIO pin, change #define OLED_RESET     -1   to the new pin number. ©Adafruit Industries Page 16 of 77 /************************************************************************** This is an example for our Monochrome OLEDs based on SSD1306 drivers Pick one up today in the adafruit shop! ------> http://www.adafruit.com/category/63_98 This example is for a 128x64 pixel display using I2C to communicate 3 pins are required to interface (two I2C and one reset). Adafruit invests time and resources providing this open source code, please support Adafruit and open-source hardware by purchasing products from Adafruit! Written by Limor Fried/Ladyada for Adafruit Industries, with contributions from the open source community. BSD license, check license.txt for more information All text above, and the splash screen below must be included in any redistribution. **************************************************************************/ #include #include #include #include #define SCREEN_WIDTH 128 // OLED display width, in pixels #define SCREEN_HEIGHT 64 // OLED display height, in pixels // Declaration for an SSD1306 display connected to I2C (SDA, SCL pins) // The pins for I2C are defined by the Wire-library. // On an arduino UNO: A4(SDA), A5(SCL) // On an arduino MEGA 2560: 20(SDA), 21(SCL) // On an arduino LEONARDO: 2(SDA), 3(SCL), ... #define OLED_RESET -1 // Reset pin # (or -1 if sharing Arduino reset pin) #define SCREEN_ADDRESS 0x3D ///< See datasheet for Address; 0x3D for 128x64, 0x3C for 128x32 Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET); #define NUMFLAKES 10 // Number of snowflakes in the animation example #define LOGO_HEIGHT 16 #define LOGO_WIDTH 16 static const unsigned char PROGMEM logo_bmp[] = { 0b00000000, 0b11000000, 0b00000001, 0b11000000, 0b00000001, 0b11000000, 0b00000011, 0b11100000, 0b11110011, 0b11100000, 0b11111110, 0b11111000, 0b01111110, 0b11111111, 0b00110011, 0b10011111, 0b00011111, 0b11111100, 0b00001101, 0b01110000, 0b00011011, 0b10100000, 0b00111111, 0b11100000, 0b00111111, 0b11110000, 0b01111100, 0b11110000, 0b01110000, 0b01110000, 0b00000000, 0b00110000 }; void setup() { Serial.begin(9600); // SSD1306_SWITCHCAPVCC = generate display voltage from 3.3V internally if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) { Serial.println(F("SSD1306 allocation failed")); for(;;); // Don't proceed, loop forever } ©Adafruit Industries Page 17 of 77 // Show initial display buffer contents on the screen -// the library initializes this with an Adafruit splash screen. display.display(); delay(2000); // Pause for 2 seconds // Clear the buffer display.clearDisplay(); // Draw a single pixel in white display.drawPixel(10, 10, SSD1306_WHITE); // Show the display buffer on the screen. You MUST call display() after // drawing commands to make them visible on screen! display.display(); delay(2000); // display.display() is NOT necessary after every single drawing command, // unless that's what you want...rather, you can batch up a bunch of // drawing operations and then update the screen all at once by calling // display.display(). These examples demonstrate both approaches... testdrawline(); // Draw many lines testdrawrect(); // Draw rectangles (outlines) testfillrect(); // Draw rectangles (filled) testdrawcircle(); // Draw circles (outlines) testfillcircle(); // Draw circles (filled) testdrawroundrect(); // Draw rounded rectangles (outlines) testfillroundrect(); // Draw rounded rectangles (filled) testdrawtriangle(); // Draw triangles (outlines) testfilltriangle(); // Draw triangles (filled) testdrawchar(); // Draw characters of the default font testdrawstyles(); // Draw 'stylized' characters testscrolltext(); // Draw scrolling text testdrawbitmap(); // Draw a small bitmap image // Invert and restore display, pausing in-between display.invertDisplay(true); delay(1000); display.invertDisplay(false); delay(1000); testanimate(logo_bmp, LOGO_WIDTH, LOGO_HEIGHT); // Animate bitmaps } void loop() { } void testdrawline() { int16_t i; display.clearDisplay(); // Clear display buffer for(i=0; i=0; i-=4) { display.drawLine(display.width()-1, display.height()-1, 0, i, SSD1306_WHITE); display.display(); delay(1); } delay(250); display.clearDisplay(); for(i=0; i