# CircuitPython Hardware: SSD1306 OLED Display

## Overview

Danger: 

![](https://cdn-learn.adafruit.com/assets/assets/000/046/461/medium800/micropython_IMG_5892.jpg?1505431976)

https://www.youtube.com/watch?v=lbd9M7fY4mw

Info: 

Small OLED (organic light emitting diode)&nbsp;displays are&nbsp;an easy way to add text and graphics to your project. &nbsp;These displays have beautifiul high contrast black and white graphics which are perfect for making simple interfaces, displaying sensor readings, creating a retro game, and much more. &nbsp;Even better you can now use OLED displays with CircuitPython and MicroPython! &nbsp;This guide explores how to use SSD1306-based monochrome OLED displays with CircuitPython and MicroPython.

The&nbsp;[FeatherWing OLED](https://www.adafruit.com/product/2900)&nbsp;in particular is a simple way to add an OLED display to a Feather-based board like the&nbsp;[Feather HUZZAH ESP8266](https://www.adafruit.com/product/2821)&nbsp;or&nbsp;[Feather M0](https://www.adafruit.com/product/2772). &nbsp;Simply plug in the the FeatherWing to the Feather board and you're all set to control it from Python. &nbsp;No need for messy or confusing wiring!

Be sure to&nbsp;check out&nbsp;[the OLED breakout guide](../../../../monochrome-oled-breakouts/overview)&nbsp;for more details on OLED displays and the available boards&nbsp;in the shop.

# CircuitPython Hardware: SSD1306 OLED Display

## Hardware

Danger: 

# Parts

You'll need the following parts to follow this guide:

 **CircuitPython board.** &nbsp;&nbsp;This guide focuses on the&nbsp;[ESP8266](https://www.adafruit.com/product/2821)&nbsp;and&nbsp;[Feather M0/SAMD21-based boards](https://www.adafruit.com/products/2772), but any CircuitPython board that supports I2C should work.

&nbsp;

If your board doesn't come with CircuitPython running on it already then check out your board's guide for how to load CircuitPython firmware. &nbsp;For example the&nbsp;[Feather M0 express guide](../../../../adafruit-feather-m0-express-designed-for-circuit-python-circuitpython/circuitpython)&nbsp;is a good reference.

&nbsp;

If you're using a Feather board and FeatherWing you probably want a&nbsp;[Feather female header set](https://www.adafruit.com/products/2886)&nbsp;or&nbsp;[Feather stacking female header set](https://www.adafruit.com/products/2830).

![micropython_3403-00.jpg](https://cdn-learn.adafruit.com/assets/assets/000/046/436/medium640/micropython_3403-00.jpg?1505427817)

 **SSD1306-based OLED display.** &nbsp;&nbsp;If you're using a Feather board&nbsp;the&nbsp;[FeatherWing OLED](https://www.adafruit.com/products/2900)&nbsp;is a perfect option.

![micropython_2900-02.jpg](https://cdn-learn.adafruit.com/assets/assets/000/046/437/medium640/micropython_2900-02.jpg?1505427895)

**[Breadboard&nbsp;](https://www.adafruit.com/products/64)**and&nbsp;**[jumper wires](https://www.adafruit.com/products/153)**. &nbsp;If you aren't using a Feather and FeatherWing you'll need a breadboard and jumper wires to connect the components.

&nbsp;

**[Soldering tools](https://www.adafruit.com/products/136)**. &nbsp;You'll need to solder headers to the boards &nbsp;Check out the&nbsp;[guide to excellent soldering](../../../../adafruit-guide-excellent-soldering/tools)&nbsp;if you're new to soldering.

![micropython_136-01.jpg](https://cdn-learn.adafruit.com/assets/assets/000/046/438/medium640/micropython_136-01.jpg?1505427945)

Make&nbsp;sure to follow the board and OLED display product guides to&nbsp;assemble&nbsp;and verify they work before continuing.

# Wiring

There are two ways to wire the SSD1306 OLED to a board, either with an I2C or SPI connection. &nbsp;Some displays only support one connection type&nbsp;so be sure to read the product page and associated guide to understand how your display works.

For a Feather and FeatherWing OLED connecting them together is as easy as sliding the FeatherWing into the headers of the Feather. &nbsp;The wing will use an I2C connection to the board--nothing else is necessary to do. &nbsp;Skip to the next page on setting up the software!

![](https://cdn-learn.adafruit.com/assets/assets/000/046/439/medium800/micropython_IMG_5571.jpg?1505428023)

For an OLED with an&nbsp; **I2C interface** &nbsp;you'll want to wire it to the board's I2C and power pins, and the reset pin, if it's available. &nbsp;For example with a Feather M0 the connections might look like:

![](https://cdn-learn.adafruit.com/assets/assets/000/049/848/medium800/micropython-ssd1306-samd-i2c_bb.png?1515182462)

[Fritzing Source](https://cdn-learn.adafruit.com/assets/assets/000/049/849/original/micropython-ssd1306-samd-i2c.fzz?1515182485)
- **Board SCL / I2C clock** &nbsp;to&nbsp; **display SCL**.
- **Board SDA / I2C** &nbsp; **data** &nbsp;to&nbsp; **display SDA**.
- **Board digital #5 to display RST (reset). This can be any available digital pin.**
- **Board 3.3V power** &nbsp;to&nbsp; **display VIN / voltage input**.
- **Board GND / ground** &nbsp;to&nbsp; **display GND / ground**.

For an OLED with a&nbsp; **SPI interface** &nbsp;you'll need to wire it to a few more pins on the board. &nbsp;For example with a Feather HUZZAH ESP8266&nbsp;the connections might look like:

![](https://cdn-learn.adafruit.com/assets/assets/000/046/441/medium800/micropython-ssd1306-spi-esp8266_bb.png?1505428129)

[Fritzing Source](https://cdn-learn.adafruit.com/assets/assets/000/046/443/original/micropython-ssd1306-spi-esp8266.fzz?1505428206)
- **Board SCK / SPI clock** &nbsp;to&nbsp; **display CLK / clock**.
- **Board MOSI / data out** &nbsp;to&nbsp; **display Data / data in**.
- **Board 3.3V power** &nbsp;to&nbsp; **display Vin / voltage input**.
- **Board ground** &nbsp;to&nbsp; **display ground**.
- **Board digital input 15** &nbsp;(or any other digital IO pin) to&nbsp; **display DC / data/command**.
- **Board digital input 0** &nbsp;(or any other digital IO pin) to&nbsp; **display Rst / reset**.
- **Board digital input 16** &nbsp;(or any other digital IO pin) to&nbsp; **display CS / chip select**.

Once your board is wired to the display continue on to learn how to use&nbsp;a CircuitPython module to control the display!

# CircuitPython Hardware: SSD1306 OLED Display

## CircuitPython

Danger: 

# Adafruit CircuitPython Module Install

To use the SSD1306&nbsp;with your&nbsp;Adafruit CircuitPython&nbsp;board you'll need to install the&nbsp;[Adafruit\_CircuitPython\_SSD1306](https://github.com/adafruit/Adafruit_CircuitPython_SSD1306)&nbsp;module on your board.

First make sure you are running the&nbsp;[latest version of Adafruit CircuitPython](../../../../welcome-to-circuitpython/installing-circuitpython)&nbsp;for your board.

## Bundle Install

Next you'll need to install the necessary libraries&nbsp;to use the hardware--carefully follow the steps to find and install these libraries from&nbsp;[Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle).&nbsp; Our introduction guide has&nbsp;[a great page on how to install the library bundle](../../../../welcome-to-circuitpython/circuitpython-libraries)&nbsp;for both express and non-express boards.

Remember for non-express boards like the, you'll need to manually install the necessary libraries from the bundle:

- **adafruit\_ssd1306**
- **adafruit\_bus\_device**
- **adafruit\_register**

If your board supports USB mass storage, like the M0-based boards, then simply drag the files to the board's file system.

If your board doesn't support USB mass storage, like the ESP8266, then&nbsp;[use a tool like ampy to copy the file to the board](../../../../micropython-basics-load-files-and-run-code). You can use the latest version of ampy and its&nbsp;[new directory copy command](../../../../micropython-basics-load-files-and-run-code/file-operations#copy-directories-to-board)&nbsp;to easily move module directories to the board.

Furthermore, **CircuitPython for smaller M0 boards like the Trinket and Gemma do not have the framebuf module built in** to save flash space. So, please download and install the&nbsp;[pure Python implementation of framebuf](https://github.com/adafruit/micropython-adafruit-framebuf/releases)&nbsp;and copy it to lib folder of the board as well. You do not need to do this for **Express** CircuitPython boards (they have enough space for framebuf!)

Before continuing make sure your board's&nbsp; **lib** &nbsp;folder or root filesystem has at least the&nbsp; **adafruit\_ssd1306** ,&nbsp; **adafruit\_bus\_device** ,&nbsp; **adafruit\_register,** and if necessary **framebuf** &nbsp;folders/modules copied over.

![](https://cdn-learn.adafruit.com/assets/assets/000/046/457/medium800/micropython_Screen_Shot_2017-09-14_at_4.17.51_PM.png?1505431098)

# Usage

The following section will show how to control the LED backpack&nbsp;from the board's Python prompt / REPL. &nbsp;You'll walk through how to control the LED display and learn how to use the CircuitPython module built for the display.

Next&nbsp;[connect to the board's serial REPL&nbsp;](../../../../welcome-to-circuitpython/the-repl)so you are at the CircuitPython&nbsp; **\>\>\>** &nbsp;prompt.

## I2C Initialization

If your display is connected to the board using I2C (like if using a Feather and the FeatherWing OLED) you'll first need to initialize the I2C bus. &nbsp;First import the necessary modules:

```auto
import board
import busio as io
```

Note if you're using the ESP8266 or other boards which do not support hardware I2C you need to import from the bitbangio module instead of busio:

```auto
import board
import bitbangio as io
```

Now for either board run this command to create the I2C instance using the default SCL and SDA pins (which will be marked on the boards pins if using a Feather or similar Adafruit board):

```auto
i2c = io.I2C(board.SCL, board.SDA)
```

After initializing the I2C interface for your firmware as described above you can create an instance&nbsp;of the SSD1306 I2C driver by running:

```auto
import adafruit_ssd1306
oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)
```

Note that the first two parameters to the SSD1306\_I2C class initializer are the&nbsp; **width** &nbsp;and&nbsp; **height** &nbsp;of the display in pixels. &nbsp;Be sure to use the right values for the display you're using!

### 128 x 64 size OLEDs (or changing the I2C address)

If you are using a 128x64 display, the I2C address&nbsp;is probably&nbsp;different (`0x3d`), unless you've changed it by soldering some jumpers:

```auto
oled = adafruit_ssd1306.SSD1306_I2C(128, 64, i2c, addr=0x3d)
```

### Adding hardware reset pin

If you have a reset pin (which may be required if your OLED does not have an auto-reset chip like the FeatherWing) also pass in a reset pin like so:

```auto
from digitalio import DigitalInOut

reset_pin = DigitalInOut(board.D5) # any pin!
oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c, reset=reset_pin)
```

At this point your&nbsp;I2C bus and display are initialized, skip down to the drawing&nbsp;section.

## SPI Initialization

If your display is connected to the board using SPI you'll first need to initialize the SPI bus.&nbsp;Run the following commands:

```auto
import adafruit_ssd1306
import board
import busio
from digitalio import DigitalInOut

spi = busio.SPI(board.CLK, MOSI=board.MOSI, MISO=board.MISO)
dc_pin = DigitalInOut(board.D5)    # any pin!
reset_pin = DigitalInOut(board.D6) # any pin!
cs_pin = DigitalInOut(board.D9)    # any pin!

oled = adafruit_ssd1306.SSD1306_SPI(128, 32, spi, dc_pin, reset_pin, cs_pin)
```

Note the first two parameters to the SSD1306\_SPI class initializer are the&nbsp; **width** &nbsp;and&nbsp; **height** &nbsp;of the display in pixels. &nbsp;Be sure to use the right values for the display you're using!

The next parameters to the initializer are the pins connected to the display's&nbsp; **DC** ,&nbsp; **reset** , and&nbsp; **CS** &nbsp;lines in that order. &nbsp;Again make sure to use the right pin names as you have wired up to your board!

## Drawing

The SSD1306 module currently supports a basic set of commands to draw on the display. &nbsp;You can set individual pixels, fill the screen, and write lines of text. &nbsp;There aren't yet more advanced functions like line drawing, etc. but check the&nbsp;[module GitHub repository](https://github.com/adafruit/micropython-adafruit-ssd1306)&nbsp;for future releases which might include more functions.

To fill or clear the entire screen use the **fill** function. &nbsp;This function takes a parameter which specifies the color to fill with, either 0 for black or 1 for white. &nbsp;For example to fill the screen white:

```auto
oled.fill(1)
oled.show()
```

![](https://cdn-learn.adafruit.com/assets/assets/000/046/444/medium800/micropython_IMG_5561.jpg?1505429502)

Notice the&nbsp; **fill** &nbsp;function doesn't actually change the display. &nbsp;You must call&nbsp; **show** &nbsp;after making drawing commands to send the updated pixel data to the display!

To clear the screen to black just call&nbsp; **fill** &nbsp;again but with the color 0:

```auto
oled.fill(0)
oled.show()
```

![](https://cdn-learn.adafruit.com/assets/assets/000/046/445/medium800/micropython_IMG_5563.jpg?1505429547)

To set a pixel use the&nbsp; **pixel** &nbsp;function. &nbsp;This function takes the following parameters:

- **Pixel X position**
- **Pixel Y position**
- **Pixel color** &nbsp;(0 = black, 1 = white)

For example to set the first pixel white:

```auto
oled.pixel(0, 0, 1)
oled.show()
```

![](https://cdn-learn.adafruit.com/assets/assets/000/046/446/medium800/micropython_IMG_5565.jpg?1505429592)

Try setting other pixels white by changing the X and Y position. &nbsp;Remember you have to call&nbsp; **show** &nbsp;after setting pixels to see them appear!

You can write a line of text with the&nbsp; **text** &nbsp;function. &nbsp;This function takes the following parameters:

- **String of text**
- **Text X position**
- **Text Y position**
- **Optional text color** &nbsp;(0 = black, 1 = white, the default)

For example to clear the screen and then write two lines of text:

```auto
oled.fill(0)
oled.text('Hello', 0, 0)
oled.text('World', 0, 10)
oled.show()
```

![](https://cdn-learn.adafruit.com/assets/assets/000/046/447/medium800/micropython_IMG_5567.jpg?1505429644)

**Note that not all boards support built-in text rendering. &nbsp;In particular the non-express boards like Gemma and Trinket M0 don't have the memory to build in text drawing. &nbsp;You can however on those boards load a separate Python text drawing library to draw text. &nbsp;See the [Drawing Text](../../../../micropython-displays-drawing-text) guide!**

Notice the second line of text starts at Y position 10, this moves it down the display 10 pixels so it's below the first line of text. &nbsp;The font used by the text function is 8 pixels tall so a size of 10 gives a bit of room between the lines.

Finally you can invert the display colors with the&nbsp; **invert** &nbsp;function:

```auto
oled.invert(True)
```

![](https://cdn-learn.adafruit.com/assets/assets/000/046/458/medium800/micropython_IMG_20170914_162226455.jpg?1505431508)

Note that the invert function doesn't need to have show called after it to see the change.

To go back to a non-inverted display run:

```auto
oled.invert(False)
```

![](https://cdn-learn.adafruit.com/assets/assets/000/046/459/medium800/micropython_IMG_20170914_162238010.jpg?1505431517)

That's all there is to drawing on the SSD1306 OLED display with CircuitPython! &nbsp;The drawing functions are basic but provide building blocks for more advanced usage. &nbsp;For example you can display text with sensor readings or other state, or even program a simple game like pong!

You can find more drawing functions for basic shapes and text by following these guides (which work with both CircuitPython and MicroPython):

- [Drawing Shapes](../../../../micropython-displays-drawing-shapes)
- [Drawing Text](../../../../micropython-displays-drawing-text)

# CircuitPython Hardware: SSD1306 OLED Display

## MicroPython

Danger: 

Warning: 

In addition to CircuitPython there's an older MicroPython version of the SSD1306&nbsp;library that you can use with some MicroPython boards. &nbsp;Before you get started it will help to be familiar with these guides for working with MicroPython:

- [MicroPython Basics: What is MicroPython?](../../../../micropython-basics-what-is-micropython)
- [MicroPython Basics: How to Load MicroPython on a Board](../../../../micropython-basics-how-to-load-micropython-on-a-board)
- [MicroPython Basics: Load Files & Run Code](../../../../micropython-basics-load-files-and-run-code)

See&nbsp;[all the MicroPython guides in the learning system](../../../../category/micropython)&nbsp;for more information.

# MicroPython&nbsp;Module Install

To use the display with your MicroPython board you'll need to install the&nbsp;[micropython-adafruit-ssd1306&nbsp;MicroPython module](https://github.com/adafruit/micropython-adafruit-ssd1306)&nbsp;on your board.&nbsp; **Remember this module is for MicroPython.org firmware and not Adafruit CircuitPython!**

First make sure you are running the latest version of MicroPython for your board. &nbsp;If you're using the&nbsp; **ESP8266 MicroPython** &nbsp;port you&nbsp; **must** &nbsp;be running version&nbsp;**[1.8.5 or higher](http://micropython.org/download#esp8266)**&nbsp;as earlier versions do not support using .mpy modules as shown in this guide. &nbsp;

Next download the latest&nbsp; **ssd1306.mpy** &nbsp;file from the&nbsp;[releases page](https://github.com/adafruit/micropython-adafruit-ssd1306/releases)&nbsp;of the&nbsp;[micropython-adafruit-ssd1306 GitHub repository](https://github.com/adafruit/micropython-adafruit-ssd1306). &nbsp;Once the **ssd1306.mpy** file is on your computer you'll need to copy it to your MicroPython board's file system&nbsp;and can&nbsp;[use a tool like ampy to copy the files to the board](../../../../micropython-basics-load-files-and-run-code/overview).

# Usage

The following section will show how to control the SSD1306&nbsp;from the board's Python prompt / REPL. &nbsp; First&nbsp;[connect to the board's serial REPL&nbsp;](../../../../micropython-basics-how-to-load-micropython-on-a-board/serial-terminal)so you are at the MicroPython&nbsp; **\>\>\>** &nbsp;prompt.

## I2C Initialization

If your display is connected to the board using I2C (like if using a Feather and the FeatherWing OLED) you'll first need to initialize the I2C bus. &nbsp;On MicroPython.org firmware which uses the machine API you can initialize I2C like&nbsp;[the MicroPython I2C guide mentions](../../../../micropython-hardware-i2c-devices).

For example on a board like the ESP8266 you can run&nbsp;(assuming you're using the default SDA gpio #4 and SCL gpio #5 pins like on a Feather & SSD1306&nbsp;FeatherWing):

```auto
import machine
import ssd1306
i2c = machine.I2C(-1, machine.Pin(5), machine.Pin(4))
oled = ssd1306.SSD1306_I2C(128, 32, i2c)
```

Note that the first two parameters to the SSD1306\_I2C class initializer are the&nbsp; **width** &nbsp;and&nbsp; **height** &nbsp;of the display in pixels. &nbsp;Be sure to use the right values for the display you're using!

## SPI Initialization

If your display is connected to the board using SPI you'll first need to initialize the SPI bus. &nbsp;On MicroPython.org firmware which uses the machine API you can initialize SPI&nbsp;like&nbsp;[the MicroPython SPI guide mentions](../../../../micropython-hardware-spi-devices):

```auto
import machine
import ssd1306
spi = machine.SPI(1, baudrate=8000000, polarity=0, phase=0)
oled = ssd1306.SSD1306_SPI(128, 32, spi, machine.Pin(15), machine.Pin(0), machine.Pin(16))
```

Note the first two parameters to the SSD1306\_SPI class initializer are the&nbsp; **width** &nbsp;and&nbsp; **height** &nbsp;of the display in pixels. &nbsp;Be sure to use the right values for the display you're using!

The next parameters to the initializer are the pins connected to the display's&nbsp; **DC** ,&nbsp; **reset** , and&nbsp; **CS** &nbsp;lines in that order.

# Drawing

Once the display is initialized using the code above you're ready to start drawing on it. &nbsp;Follow the [drawing section on the CircuitPython page](../../../../micropython-hardware-ssd1306-oled-display/circuitpython#drawing) for all the details on pixel, fill, and other drawing functions. &nbsp;The usage of the library between CircuitPython and MicroPython is exactly the same!


## Related Guides

- [Sewable NeoPixels](https://learn.adafruit.com/flora-rgb-smart-pixels.md)
- [Adafruit Feather M0 Adalogger](https://learn.adafruit.com/adafruit-feather-m0-adalogger.md)
- [Adafruit Feather M0 Bluefruit LE](https://learn.adafruit.com/adafruit-feather-m0-bluefruit-le.md)
- [Adafruit OLED FeatherWing](https://learn.adafruit.com/adafruit-oled-featherwing.md)
- [Adafruit Feather M0 Express](https://learn.adafruit.com/adafruit-feather-m0-express-designed-for-circuit-python-circuitpython.md)
- [Adafruit Metro M0 Express](https://learn.adafruit.com/adafruit-metro-m0-express.md)
- [Adafruit Trinket M0](https://learn.adafruit.com/adafruit-trinket-m0-circuitpython-arduino.md)
- [Adafruit Circuit Playground Express](https://learn.adafruit.com/adafruit-circuit-playground-express.md)
- [Stepper Motor Turntable](https://learn.adafruit.com/stepper-motor-turntable.md)
- [Professor Bubbleton’s Breathing Head in a Jar](https://learn.adafruit.com/professor-bubbleton-s-breathing-head-in-a-jar.md)
- [Ping Pong Ball Launcher](https://learn.adafruit.com/ping-pong-ball-launcher-with-cpx.md)
- [Scratch 3 Walkthrough and Demo](https://learn.adafruit.com/guide-to-scratch-3.md)
- [Making oscilloscope images with DACs](https://learn.adafruit.com/dac-oscilloscope-images.md)
- [Adafruit BME680](https://learn.adafruit.com/adafruit-bme680-humidity-temperature-barometic-pressure-voc-gas.md)
- [USB Foot Switch Controller in CircuitPython](https://learn.adafruit.com/usb-foot-switch-circuit-python.md)
- [Game Clock with Circuit Playground & MakeCode](https://learn.adafruit.com/game-clock-with-circuit-playground-makecode.md)
- [AdaBox 007](https://learn.adafruit.com/adabox007.md)
- [Hanukkah MakeCode Menorah Sweater](https://learn.adafruit.com/hanukkah-menorah-sweater.md)
- [FruitBox Sequencer: Musically Delicious Step Pattern Generator ](https://learn.adafruit.com/circuitpython-fruitbox-sequencer-musically-delicious-step-pattern-generator.md)
- [Crickit Lab Shaker](https://learn.adafruit.com/crickit-lab-shaker.md)
- [Circuit Playground Express Laser Tag](https://learn.adafruit.com/circuit-playground-express-laser-tag.md)
- [Monitor Your Greenhouse with a No-Code Environmental Sensor](https://learn.adafruit.com/monitor-your-greenhouse-with-a-no-code-environmental-sensor.md)
- [Circuit Playground Express Spinner Game in MakeCode](https://learn.adafruit.com/circuit-playground-makecode-spinner-game.md)
