These mini monochrome OLED screens make great displays for projects — perfect for data readout, simple UIs or monochrome games.
|Wemos D1 v2.2+ or good imitations.||amazon|
|0.91in OLED Screen 128x32 pixels, I2c interface.||amazon|
|Breadboard Any size will do.||amazon|
|Wires Loose ends, or jumper leads.|
MicroPython provides some built-in support for these displays, and a simple framebuffer which can be used as a drawing surface. However, we still need a driver to interface the buffer to the display.
There is a Python ssd1306 module for OLED displays available
in the MicroPython repository.
Click Raw format and save the file with a
You can then use the ampy tool (or the WebREPL) to upload the file to your device's filesystem:
ampy --port /dev/tty.wchusbserial141120 put ssd1306.py
ssd1306.py file on your Wemos D1, you can import it as any other Python module. Connect to your device,
and then in the REPL enter:
:::python from machine import I2C, Pin import ssd1306
warning: Both I2C and SPI-controlled displays are available — these instructions will only work for I2C displays.
import ssd1306 succeeds, the package is correctly uploaded and you're good to go.
Wire up the OLED display, connecting pins
Provide power from
Using the interface
note: The following instructions are based on a 0.91in monochrome 128x32 OLED, but other displays using the same chipset can be used with this library.
To use the display you first need to create an I2C interface. In MicroPython I2C is via a software implementation so you can put it on any GPIO pins you like.
:::python i2c = I2C(-1, Pin(5), Pin(4)) display = ssd1306.SSD1306_I2C(128, 32, i2c)
The SSD1306 module makes use of the MicroPython
framebuf frame buffer, an efficient in-memory buffer for working with
a simple graphics view. The methods for drawing text and primitives are from this framebuffer implementation.
For a complete overview of what's available, check the MicroPython documentation.
note: The setup of the framebuffer format (monochrome, bit ordering, etc.) is also handled by the SSD1306 library. Check the framebuf documentation for more info on available options for other displays.
To test your I2C connection to the display, fill the display in solid colour.
:::python display.fill(1) # Fill the entire display with 1="on" display.show()
tip: You need to call
display.show() to actually send the current
framebuf to the device.
.fill() method can be used to fill the entire display with a specified colour.
Note that this changes all pixels to the given colour, and does not perform a flood
fill of matching regions.
:::python # Fill the entire display with colour 0 display.fill(0)
note: For filling specific regions of the display see
Setting individual pixels can be accomplished using
.pixel(). This is only a good idea
when you area setting relatively few pixels as it is much slower than using other methods.
:::python # Set the pixel at 3, 4 (x, y) to 1 # .pixel(x, y, c) display.pixel(3, 4, 1) # 3rd param is the colour display.show()
If you don't provide a color via parameter c, this method returns the colour of the pixel at the specified coordinates.
:::python # Return the value at 3, 4 (x, y) # .pixel(x, y) c = display.pixel(3, 4)
note: This is not a particularly nice API. In other cases (e.g. text) omitting
c will use 1 as a default.
Horizontal and vertical lines can be drawn with
respectively, providing a starting x,y location and line length and colour.
:::python # Draw a horizontal line, starting from 2, 3 (x, y), 4 pixels wide # .hline(x, y, w, c) display.hline(2, 3, 25, 1) display.show()
:::python # Draw a vertical line, starting from 5, 0 (x, y), 6 pixels high # .vline(x, y, h, c) display.vline(5, 0, 15, 1) display.show()
For diagonal lines, the
.line() method can be used to draw lines
between between two sets of points x1,y1 and x2,y2 specified in order.
The parameter c controls the colour of the line drawn.
:::python # Draw a short diagonal line down to the right. # .line(x1, y1, x2, y2, c) display.line(0, 0, 50, 25, 1) display.show()
note: There is no antialiasing, so diagonal lines will probably look pretty jaggy.
.draw_rect() method allows you to draw a unfilled rectangle, starting at x,y and
with a specified width w and height h. The specified colour c is used to draw
the boundary of the rectangle, but it is not filled.
:::python # Draw an unfilled rectangle of 8, 5 pixels, starting at 1,1 in colour 1. # .rect(x, y, w, h, c) display.rect(5, 5, 100, 20, 1) display.show()
You can also draw filled rectangles, using
.fill_rect(). The parameters are the same
.rect() but all pixels within the boundary will be set.
:::python # Draw a filled rectangle of 10x5 pixels, starting at 3,3 in colour 1 # .fill_rect(x, y, w, h, c) display.fill_rect(9, 9, 25, 25, 1) display.show()
The framebuffer class provides support for writing text using a simple 8x8 bitmap font. The pixel x,y positions are relative to the top-left of the 8x8 character, so positioning at 0,0 will give the absolute top left of the screen.
:::python # Print "Hello world!" 1 pixel from top left, in colour 1 (on) # .text(text, x, y, c) display.text("Hello world!", 1, 1, 1) display.show()
.text() method takes an optional 4th parameter color, which gives the colour to draw text in. On
a mono screen this can be either
0 (off) or
:::python # Print "Hello world!" at 2,2 in colour 0 (off) display.text("Hello world!", 2, 2, 0) display.show()
# Print "Hello world!" at 3,3 in colour 1 (on) display.text("Hello world!", 3, 3, 1) display.show()
You can shift the contents of the entire framebuffer around using
.scroll, which takes
y parameters to specify
the scroll (positive/negative) in each dimension.
:::python # .scroll(x, y) display.scroll(-10, 0)
note: There is no support for scrolling a portion of the framebuffer. You can however keep a separate framebuffer which you scroll and then blit to your main display — see the next section.
For very simple graphics that do not update often you can get away with writing bitmap graphics to the framebuffer pixel by pixel. For example, in the following code block we draw an icon from a list-of-lists of binary colour data, iterating over with simple loops:
:::python ICON = [ [ 0, 0, 0, 0, 0, 0, 0, 0, 0], [ 0, 1, 1, 0, 0, 0, 1, 1, 0], [ 1, 1, 1, 1, 0, 1, 1, 1, 1], [ 1, 1, 1, 1, 1, 1, 1, 1, 1], [ 1, 1, 1, 1, 1, 1, 1, 1, 1], [ 0, 1, 1, 1, 1, 1, 1, 1, 0], [ 0, 0, 1, 1, 1, 1, 1, 0, 0], [ 0, 0, 0, 1, 1, 1, 0, 0, 0], [ 0, 0, 0, 0, 1, 0, 0, 0, 0], ] display.fill(0) # Clear the display for y, row in enumerate(ICON): for x, c in enumerate(row): display.pixel(x, y, c) display.show()
urandom we can scatter images over the display, like in the following example:
import urandom def random_heart(): xofs = urandom.getrandbits(8) yofs = urandom.getrandbits(5) for y, row in enumerate(ICON): for x, c in enumerate(row): display.pixel(x + xofs, y + yofs, c) for n in range(100): random_heart() display.show()
tip: If you can add an
if c around the
display.pixel call to only output
pixels which are on — effectively masking, and avoiding the black square.
For bigger graphics or where you need faster updates, you can instead blit your bitmap images from one framebuffer
to another. Pass the
framebuf to blit, and the coordinates
y to blit at.
:::python # Blit a framebuffer at the pixel position 1, 1. # display.blit(fbuf, x, y) display.blit(fbuf, 1, 1)
blit method takes an optional 4th parameter key which is a colour to
considered 'transparent' when blitting. Pixels with this value won't be copied over
onto the target display.
:::python # Blit except pixels with value 0 (i.e. only pixels with value 1) # .blit(fbuf, x, y, key) display.blit(fbuf, 1, 1, key=0)
See this follow up for details on how to display images on OLED screens, including animated graphics.
The drawing methods so far are inherited from the the MicroPython
object, which is written to the display on
.update(). But the
ssd1306 object itself
also provides methods for direct control of the display component.
The display can be turned on and off using
You can set the contrast for the display using
.contrast() passing in parameter
c which is a value between
255. This controls the contrast between
the foreground, active colour
1 and the background
:::python # Set the display contrast to half (127/255 = 0.5) # .contrast(c) display.contrast(50)
To invert the display, switching foreground and background colours, call
.invert(0) will return the display to how it was originally. You can
use this for display-flashing visual effects:
:::python import time while True: display.invert(0) time.sleep(0.01) display.invert(1) time.sleep(0.01)
Enjoyed this? Support me on Patreon for behind the scenes extras!
We've previously covered the basics of driving OLED I2C displays from MicroPython, including simple graphics commands and text. Here we look at displaying monochrome 1 bit-per-pixel images and animations using MicroPython on a Wemos D1. Processing the images and correct choice of image-formats is important to get the most detail … More