This tutorial may be outdated. It is no longer recommended for beginners, and may need modifications to code or hardware that is not indicated in the tutorial.

MicroPython

The examples in this guide are no longer supported. Check out this OLED guide for CircuitPython usage: https://learn.adafruit.com/adafruit-oled-featherwing/python-circuitpython
Note this page describes how to use a MicroPython.org version of this library with MicroPython boards. Skip back to the previous page if you're using a CircuitPython board like the Feather M0 express!

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

See all the MicroPython guides in the learning system for more information.

MicroPython Module Install

To use the display with your MicroPython board you'll need to install the micropython-adafruit-ssd1306 MicroPython module on your board. 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.  If you're using the ESP8266 MicroPython port you must be running version 1.8.5 or higher as earlier versions do not support using .mpy modules as shown in this guide.  

Next download the latest ssd1306.mpy file from the releases page of the micropython-adafruit-ssd1306 GitHub repository.  Once the ssd1306.mpy file is on your computer you'll need to copy it to your MicroPython board's file system and can use a tool like ampy to copy the files to the board.

Usage

The following section will show how to control the SSD1306 from the board's Python prompt / REPL.   First connect to the board's serial REPL so you are at the MicroPython >>> 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.  On MicroPython.org firmware which uses the machine API you can initialize I2C like the MicroPython I2C guide mentions.

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

Download: file
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 width and height of the display in pixels.  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.  On MicroPython.org firmware which uses the machine API you can initialize SPI like the MicroPython SPI guide mentions:

Download: file
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 width and height of the display in pixels.  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 DCreset, and CS lines in that order.

Drawing

Once the display is initialized using the code above you're ready to start drawing on it.  Follow the drawing section on the CircuitPython page for all the details on pixel, fill, and other drawing functions.  The usage of the library between CircuitPython and MicroPython is exactly the same!

This guide was first published on Oct 21, 2016. It was last updated on Oct 21, 2016. This page (MicroPython) was last updated on Jun 25, 2019.