# SSD1306 OLED Displays with Raspberry Pi and BeagleBone Black ## Overview Danger: https://www.youtube.com/watch?v=TZUc0T1FQkk Are you looking for a bright graphical display to use with you Raspberry Pi or BeagleBone Black project? Consider using one of the [SSD1306-based OLED displays](https://learn.adafruit.com/monochrome-oled-breakouts "Link: https://learn.adafruit.com/monochrome-oled-breakouts"), with the [SSD1306 Python library](https://github.com/adafruit/Adafruit_Python_SSD1306 "Link: https://github.com/adafruit/Adafruit\_Python\_SSD1306")! Although they're small (only an inch or so in size), these displays produce a beautiful and crisp 128x32 or 128x64 pixel image. Connecting the display to a Raspberry Pi or BeagleBone Black is easy too thanks to the display's 3.3 volt support, and I2C or SPI interface. This guide will walk you through how to connect the display to a Raspberry Pi or BeagleBone Black, and how to install and use the SSD1306 Python library. Before you get started it will help to [read the guide on their usage](https://learn.adafruit.com/monochrome-oled-breakouts) so you know how the displays are assembled and configured. Make sure your Raspberry Pi is running the latest [Raspbian](http://www.raspberrypi.org/downloads/ "Link: http://www.raspberrypi.org/downloads/") or [Occidentalis](https://learn.adafruit.com/adafruit-raspberry-pi-educational-linux-distro/occidentalis-v0-dot-2 "Link: https://learn.adafruit.com/adafruit-raspberry-pi-educational-linux-distro/occidentalis-v0-dot-2") operating system, or your BeagleBone Black is running the [official Debian](http://beagleboard.org/project/debian/ "Link: http://beagleboard.org/project/debian/") or a Debian-based operating system like Ubuntu. # SSD1306 OLED Displays with Raspberry Pi and BeagleBone Black ## Wiring Danger: # Raspberry Pi You can hook up an OLED to the Raspberry Pi using either the Pi's I2C or SPI interface. If your OLED supports both I2C and SPI, make sure to [check how the solder jumpers are configured to expose the right interface](../../../../monochrome-oled-breakouts/wiring-1-dot-3-128x64 "Link: https://learn.adafruit.com/monochrome-oled-breakouts/wiring-1-dot-3-128x64"). **In general, I2C uses fewer pins but is slower. SPI is way fast, but requires a bunch extra pins. Choose your adventure based on your needs!** ## I2C To use the Pi with an I2C display wire it up as follows: **NOTE:** Make sure to [enable I2C on your Pi](../../../../adafruits-raspberry-pi-lesson-4-gpio-setup/configuring-i2c) before wiring it up! ![](https://cdn-learn.adafruit.com/assets/assets/000/017/603/medium800/raspberry_pi_RaspberryPi_I2C_bb.png?1403634461) - Connect **display ground** to **Raspberry Pi ground** (black wire). - Connect **display VIN** to **Raspberry Pi 3.3 volt** (red wire). - Connect **display RST** to **Raspberry Pi GPIO 24** (blue wire). You can alternatively use any free digital GPIO pin for the reset pin. - Connect **display SCL** to **Raspberry Pi SCL** (purple wire). - Connect **display SDA** to **Raspberry Pi SDA** (orange wire). ## SPI To use the Pi with an SPI display, wire it up as follows: ![](https://cdn-learn.adafruit.com/assets/assets/000/017/604/medium800/raspberry_pi_RaspberryPi_SPI_bb.png?1403634623) - Connect **display ground** to **Raspberry Pi ground** (black wire). - Connect **display VIN** to **Raspberry Pi 3.3 volt** (red wire). - Connect **display CS** to **Raspberry Pi CE0** (yellow wire). - Connect **display RST** to **Raspberry Pi GPIO 24** (blue wire). You can alternatively use any free digital GPIO pin for the reset pin. - Connect **display DC** to **Raspberry Pi GPIO 23** (cyan wire). You can alternatively use any free digital GPIO pin for the DC pin. - Connect **display CLK** to **Raspberry Pi SCLK** (orange wire). - Connect **display Data** to **Raspberry Pi MOSI** (purple wire). Note that the wiring above will use the Raspberry Pi's hardware SPI bus to communicate with the display. If you haven't done so already with your Pi, make sure to [edit the blacklist.conf file](http://raspi.tv/how-to-enable-spi-on-the-raspberry-pi) to comment the line which disables SPI. Reboot your Pi and you should see the files **/dev/spidev0.0** and **/dev/spidev0.1** are now available. Using hardware SPI is great for getting the fastest response from the display, however if you need more flexibility with pin usage you can use a software-based SPI implementation with any 5 free digital GPIO pins. See the example code usage on the next page for more information about configuring software SPI. # BeagleBone Black Just like with the Raspberry Pi, you can use an OLED display with the BeagleBone Black over either the SPI or I2C interface. ## I2C To use the BeagleBone Black with an I2C display, wire it up as follows: ![](https://cdn-learn.adafruit.com/assets/assets/000/017/605/medium800/raspberry_pi_BBB_I2C_bb.png?1403635332) - Connect **display ground** to **BeagleBone Black ground** (black wire). - Connect **display VIN** to **BeagleBone Black 3.3 volt** (red wire). - Connect **display RST** to **BeagleBone Black P9\_12** (blue wire). You can alternatively use any free digital GPIO pin for the reset pin. - Connect **display SCL** to **BeagleBone Black I2C2\_SCL pin P9\_19** (purple wire). - Connect **display SDA** to **BeagleBone Black I2C2\_SDA pin P9\_20** (orange wire). Note that the BeagleBone Black has two I2C interfaces and this wiring will use the **/dev/i2c-1** interface. Make sure there aren't any [device tree overlays loaded](https://learn.adafruit.com/introduction-to-the-beaglebone-black-device-tree/overview) which use these I2C pins for other purposes. The default BeagleBone Black device tree configuration with no overlays loaded will expose the necessary I2C interface for the wiring above. ## SPI To use the BeagleBone Black with an SPI display, wire it up as follows: ![](https://cdn-learn.adafruit.com/assets/assets/000/017/606/medium800/raspberry_pi_BBB_SPI_bb.png?1403636131) - Connect **display ground** to **BeagleBone Black ground** (black wire). - Connect **display VIN** to **BeagleBone Black 3.3 volt power** (red wire). - Connect **display CS** to **BeagleBone Black SPI0\_CS0 pin P9\_17** (yellow wire). - Connect **display RST** to **BeagleBone Black P9\_12** (blue wire). You can alternatively use any free digital GPIO pin for the reset pin. - Connect **display DC** to **BeagleBone Black P9\_15** (cyan wire). You can alternatively use any free digital GPIO pin for the DC pin. - Connect **display CLK** to **BeagleBone Black SPI0\_SCLK pin P9\_22** (orange wire). - Connect **display Data** to **BeagleBone Black SPI0\_D1 pin P9\_18** (purple wire). Like with the Raspberry Pi, the wiring above assumes using a hardware SPI interface on the BeagleBone Black, specifically **/dev/spidev1.0**. Before you can use this SPI interface you must [enable a device tree overlay](https://learn.adafruit.com/introduction-to-the-beaglebone-black-device-tree/overview "Link: https://learn.adafruit.com/introduction-to-the-beaglebone-black-device-tree/overview") to turn on the SPI pin functionality. The easiest way to enable this device tree overlay is to configure the BeagleBone Black to load the overlay automatically on boot. With the BeagleBone Black connected to your computer over USB, open the USB mass storage drive named 'boot' and edit the file uEnv.txt on the drive. Add the following line to the file: **optargs=capemgr.enable\_partno=BB-SPIDEV0** **NOTE: Be careful editing the uEnv.txt file on Windows, as changing the line endings can cause your BeagleBone Black not to boot and require an OS reinstall!** The safest option is to connect to the BeagleBone Black in a command window and [follow the steps at the end of this page to mount and edit uEnv.txt on the BeagleBone Black](https://learn.adafruit.com/introduction-to-the-beaglebone-black-device-tree/exporting-and-unexporting-an-overlay "Link: https://learn.adafruit.com/introduction-to-the-beaglebone-black-device-tree/exporting-and-unexporting-an-overlay"). Reboot your device and you should see the files **/dev/spidev1.0** and **/dev/spidev1.1** now exist. # SSD1306 OLED Displays with Raspberry Pi and BeagleBone Black ## Usage Danger: # Dependencies Before using the library you will need to make sure you have a few dependencies installed. Connect to your device using SSH and follow the steps below. ## If you're using a Raspberry Pi, install the RPi.GPIO library by executing: > **sudo apt-get update > sudo apt-get install build-essential python-dev python-pip** > **sudo pip install RPi.GPIO** ## If you're using a BeagleBone Black, install the Adafruit\_BBIO library by executing: > **sudo apt-get update > sudo apt-get install build-essential python-dev python-pip** > **sudo pip install Adafruit\_BBIO** Finally, on both the Raspberry Pi and Beaglebone Black install the [Python Imaging Library](http://effbot.org/imagingbook/pil-index.htm) and smbus library by executing: > **sudo apt-get install python-imaging python-smbus** Now to download and install the SSD1306 python library code and examples, execute the following commands: > **sudo apt-get install git** > **git clone** **[https://github.com/adafruit/Adafruit\_Python\_SSD1306.git](https://github.com/adafruit/Adafruit_Python_SSD1306.git)** > **cd Adafruit\_Python\_SSD1306** > **sudo python setup.py install** # Usage Inside the examples subdirectory you'll find python scripts which demonstrate the usage of the library. To help you get started, I'll walk through the **shapes.py** code below: ```auto import time import Adafruit_GPIO.SPI as SPI import Adafruit_SSD1306 import Image import ImageDraw import ImageFont ``` First a few modules are imported, including the Adafruit\_SSD1306 module which contains the OLED display driver classes. You can also see some of the Python Imaging Library modules like Image, ImageDraw, and ImageFont being imported. ```auto # Raspberry Pi pin configuration: RST = 24 # Note the following are only used with SPI: DC = 23 SPI_PORT = 0 SPI_DEVICE = 0 # Beaglebone Black pin configuration: # RST = 'P9_12' # Note the following are only used with SPI: # DC = 'P9_15' # SPI_PORT = 1 # SPI_DEVICE = 0 ``` Next some configuration values are set depending on the platform.  If you're using the BeagleBone Black you'll need to comment the Raspberry Pi pin configuration lines and uncomment the BeagleBone Black configuration lines. If you want to change to a different RST or DC pin, you can update the RST and DC pin values respectively. You can also change the SPI port and device, but I recommend sticking with those interfaces above as they've been tested and are known to work. ```auto # 128x32 display with hardware I2C: disp = Adafruit_SSD1306.SSD1306_128_32(rst=RST) # 128x64 display with hardware I2C: # disp = Adafruit_SSD1306.SSD1306_128_64(rst=RST) # Alternatively you can specify an explicit I2C bus number, for example # with the 128x32 display you would use: # disp = Adafruit_SSD1306.SSD1306_128_32(rst=RST, i2c_bus=2) # 128x32 display with hardware SPI: # disp = Adafruit_SSD1306.SSD1306_128_32(rst=RST, dc=DC, spi=SPI.SpiDev(SPI_PORT, SPI_DEVICE, max_speed_hz=8000000)) # 128x64 display with hardware SPI: # disp = Adafruit_SSD1306.SSD1306_128_64(rst=RST, dc=DC, spi=SPI.SpiDev(SPI_PORT, SPI_DEVICE, max_speed_hz=8000000)) # Alternatively you can specify a software SPI implementation by providing # digital GPIO pin numbers for all the required display pins. For example # on a Raspberry Pi with the 128x32 display you might use: # disp = Adafruit_SSD1306.SSD1306_128_32(rst=RST, dc=DC, sclk=18, din=25, cs=22) ``` Below the configuration values is the display class setup. There are two classes you can create, **SSD1306\_128\_32** or **SSD1306\_128\_64**. The **SSD1306\_128\_32** class represents a **128x32** pixel display, and the **SSD1306\_128\_64** class represents a **128x64** pixel display. Along with the size of the display you also configure what interface the display uses in these lines. The first couple examples use the I2C interface and only need to specify an RST pin. Internally the SSD1306 library will look up the default I2C bus number for the platform and use it--if you've followed the wiring in this guide you should be all set! However if you need to explicitly control the I2C bus number, the third example shows how to specify it with an i2c\_bus parameter. The last three examples show how to configure the SPI interface. For hardare-based SPI you only need to specify the RST pin, DC pin, and hardware SPI device. Use one of these examples if you've followed the wiring in this guide. However if you want to use a software-based SPI interface, the last example shows how to specify each SPI pin for a Raspberry Pi (for a BeagleBone Black just change the pin values based on the pins you're using). Uncomment the appropriate display line based on the size of your display and the interface you're using to talk to the display.  The code assumes you're using a 128x32 pixel display that's communicating over hardware I2C, however if you're using a different display or protocol **uncomment the appropriate line**.  Make sure to **comment all the other lines** that aren't being used! ```auto # Initialize library. disp.begin() # Clear display. disp.clear() disp.display() # Create blank image for drawing. # Make sure to create image with mode '1' for 1-bit color. width = disp.width height = disp.height image = Image.new('1', (width, height)) # Get drawing object to draw on image. draw = ImageDraw.Draw(image) # Draw a black filled box to clear the image. draw.rectangle((0,0,width,height), outline=0, fill=0) ``` The next bit of code will initialize the display library, clear the display, and configure a PIL drawing class to prepare for drawing graphics. Notice that the image buffer is created in 1-bit mode with the '1' parameter, this is important because the display only supports black and white colors. ```auto # Draw some shapes. # First define some constants to allow easy resizing of shapes. padding = 2 shape_width = 20 top = padding bottom = height-padding # Move left to right keeping track of the current x position for drawing shapes. x = padding # Draw an ellipse. draw.ellipse((x, top , x+shape_width, bottom), outline=255, fill=0) x += shape_width+padding # Draw a rectangle. draw.rectangle((x, top, x+shape_width, bottom), outline=255, fill=0) x += shape_width+padding # Draw a triangle. draw.polygon([(x, bottom), (x+shape_width/2, top), (x+shape_width, bottom)], outline=255, fill=0) x += shape_width+padding # Draw an X. draw.line((x, bottom, x+shape_width, top), fill=255) draw.line((x, top, x+shape_width, bottom), fill=255) x += shape_width+padding ``` Once the display is initialized and a drawing object is prepared, you can draw shapes and graphics using [PIL's drawing commands](http://effbot.org/imagingbook/imagedraw.htm). The code first does a little work to scale drawings based on the display size, then it moves left to right drawing each shape. ```auto # Load default font. font = ImageFont.load_default() # Alternatively load a TTF font. # Some other nice fonts to try: http://www.dafont.com/bitmap.php #font = ImageFont.truetype('Minecraftia.ttf', 8) # Write two lines of text. draw.text((x, top), 'Hello', font=font, fill=255) draw.text((x, top+20), 'World!', font=font, fill=255) ``` Next the code loads a built-in default font and draws a few lines of text. You can also load your own TrueType font and use it to render text! ```auto # Display image. disp.image(image) disp.display() ``` Finally the image that was created is written to the display buffer, and the display is told to show its buffer. Remember, every time you make a change to the image that you want it to be visible on the display you need to call the image and display functions! That's all there is to the shapes.py code! You can run the code by executing this command in the examples directory: > **sudo python shapes.py** Make sure to run as root with the sudo command so the program has access to the hardware. If you run the shapes.py example you should see something like this (on a 128x64 display): ![](https://cdn-learn.adafruit.com/assets/assets/000/017/607/medium800/raspberry_pi_DSC00468_copy.jpg?1403645755) Check out the other examples included in the library, such as **animate.py** which displays an animated text scroller and **image.py** which displays an image loaded from a file. Modify the configuration at the top of each example just like you did for the **shapes.py** example above, then run them just like running **shapes.py** but substituting the appropriate file name. Enjoy using your OLED display with a Raspberry Pi or BeagleBone Black! If you have issues or want to contribute to the library, feel free to do so on [the library's GitHub home](https://github.com/adafruit/Adafruit_Python_SSD1306). ## Related Guides - [4x4 Rotary Encoder MIDI Messenger](https://learn.adafruit.com/4x4-rotary-encoder-midi-messenger.md) - [CircuitPython 101: Basic Builtin Data Structures](https://learn.adafruit.com/basic-datastructures-in-circuitpython.md) - [LoRa and LoRaWAN Radio for Raspberry Pi](https://learn.adafruit.com/lora-and-lorawan-radio-for-raspberry-pi.md) - [CircuitPython Powered Sip & Puff with ST LPS33HW Pressure Sensor](https://learn.adafruit.com/st-lps33-and-circuitpython-sip-and-puff.md) - [Digital Circuits 6: An EPROM Emulator](https://learn.adafruit.com/digital-circuits-6-eprom-emulator.md) - [Adafruit CAN Bus BFF](https://learn.adafruit.com/adafruit-can-bus-bff.md) - [Generating Text with ChatGPT, Pico W & CircuitPython](https://learn.adafruit.com/generating-text-with-chatgpt-pico-w-circuitpython.md) - [Faderwave Synthesizer](https://learn.adafruit.com/faderwave-synthesizer.md) - [Arcade Fightstick](https://learn.adafruit.com/arcade-fightstick.md) - [CircuitPython OLED and Dual Knob Sketcher](https://learn.adafruit.com/circuitpython-oled-knob-sketcher.md) - [IoT Temperature Logger with Analog Devices ADT7410, Raspberry Pi, and Adafruit IO](https://learn.adafruit.com/iot-temperature-logger-with-python-and-adafruit-io.md) - [Gravity Falls Memory Gun](https://learn.adafruit.com/gravity-falls-memory-gun.md) - [Stepper Motor Turntable](https://learn.adafruit.com/stepper-motor-turntable.md) - [USB MIDI Keyset Controller](https://learn.adafruit.com/midi-keyset.md) - [Using the TRRS Trinkey as an Assistive Technology Device](https://learn.adafruit.com/using-the-trrs-trinkey-as-an-assistive-technology-device.md)