How to Drive An OLED display with MicroPython

In this article we will look at at connecting an OLED display to a Micropython supported board.

For ease of use I have selected the Wemos Mini which is an ESP8266 based module and an OLED shield

Hardware

The Wemos mini as stated is the ESP8266 board, if you haven’t seen one it looks like this

• 11 digital IO, interrupt/pwm/I2C/one-wire supported(except D0)
• 1 analog input(3.2V max input)
• a Micro USB connection
• Compatible with MicroPython, Arduino, nodemcu

There are actually 3 different versions of the hardware with slightly different features and they also use a different ESP chip – wemos mini info

The OLED shield

This is a 64×48 pixels (0.66”) OLED Shield which uses the I2C pins, it looks like this

Screen Size: 64×48 pixels (0.66” Across)
Operating Voltage: 3.3V
Driver IC: SSD1306 (I2C Address: 0x3C or 0x3D)
2x I2C Button (customizable I2C Address, default:0x31)

Connection

I use another shield called a base shield, I connect the Wemos Mini to this then the OLED shield fits onto the Wemos mini. The base allows you to connect other sensors and shields easily.

This is not necessary but for the relatively low cost I use it to make prototyping easier

Parts

You can pick up all of this for about $4 not including shipping

Code

This is the most basic example, I used uPycraft which has an SSD1306 library already available making this easier.

Example 1 : Hello World

The first part you need to do is import the libraries required

from machine import I2C, Pin
import ssd1306

You then need to create an to create an I2C interface stating the SCL and SDA pins and then the size of the display, for the OLED shield this as follows

i2c = I2C(-1, Pin(5), Pin(4))
display = ssd1306.SSD1306_I2C(64, 48, i2c)

Now that you have done this you simply need to add in any of the supported OLED functions, so in this example we will leave the display pixels switched off and print hello world on 2 lines

display.fill(0)
display.text("Hello", 0, 0) 
display.text("world!", 0, 8)

You can see tehre are 2 parameters after the text to be displayed, these are the x, y co-ordinates.

We are not finished yet though, you still need to actually display the text and use the show() method like this

display.show()

Now for all of this in the first example

[codesyntax lang=”python”]

import ssd1306
from machine import I2C, Pin

i2c = I2C(-1, Pin(5), Pin(4))

display = ssd1306.SSD1306_I2C(64, 48, i2c)
display.fill(0)
display.text("Hello", 0, 0)
display.text("world!", 0, 8)
display.show()

[/codesyntax]

Example 2 : drawing some pixels and lines

There are a wide range of methods available which allow you to draw a pixel or some basic line. Lets look at these

You can use the .pixel() method to draw a pixel, it takes 3 parameters. The X co-ordinate, the Y co-ordinate and the color

display.pixel(5, 10, 1)

Horizontal and vertical lines can be craeted esily by using the .hline() and .vline() methods You need to provide a starting x,y co-ordinate and then specify the line length and color.

display.hline(22, 22, 25, 1)
display.vline(30, 32, 15, 1)

What about diagonal line, we line in this case you can use the .line() method which allows you to specify to points x1,y1 and x2,y2 specified and the draw a line between them. The C parameter again is used to specify the color

display.line(0, 0, 25, 25, 1)

Now lets put this together

[codesyntax lang=”python”]

import ssd1306
from machine import I2C, Pin

count = 0

i2c = I2C(-1, Pin(5), Pin(4))
x = 0
display = ssd1306.SSD1306_I2C(64, 48, i2c)
display.fill(0)

# Set the pixel at 5, 10 (x, y) to 1
# .pixel(x, y, c)
display.pixel(5, 10, 1)
# Draw a horizontal line, starting from 22, 22 (x, y), 25 pixels wide 
# .hline(x, y, w, c)
display.hline(22, 22, 25, 1)  
# Draw a vertical line, starting from 30, 32 (x, y), 15 pixels high
# .vline(x, y, h, c)
display.vline(30, 32, 15, 1)
# Draw a diagonal line
# .line(x1, y1, x2, y2, c)
display.line(0, 0, 25, 25, 1)


display.show()

[/codesyntax]

Example 3 : rectangles

You can also draw some rectangles, there are a couple of methods for this .

The first one is the .rect() method which draws an unfilled rectangle which starts at x,y and with a specified width w and height h. The colour c is used to draw the boundary of the rectangle.

# Draw an unfilled rectangle of 8, 5 pixels, starting at 1,1 in colour 1.
display.rect(10, 10, 15, 15, 1)

You can also draw filled rectangles, using the .fill_rect() method. The parameters are exactly the same as for the .rect() method but all pixels within the boundary will be set.

# Draw a filled rectangle of 10×5 pixels, starting at 3,3 in colour 1
display.fill_rect(30, 30, 15, 15, 1)

[codesyntax lang=”python”]

import ssd1306
from machine import I2C, Pin

count = 0

i2c = I2C(-1, Pin(5), Pin(4))
x = 0
display = ssd1306.SSD1306_I2C(64, 48, i2c)
display.fill(0)

# Draw an unfilled rectangle of 15x15 pixels, starting at 10,10
display.rect(10, 10, 15, 15, 1)

# Draw a filled rectangle of 15x15 pixels, starting at 30,30
display.fill_rect(30, 30, 15, 15, 1)

display.show()

[/codesyntax]