MicroPython on an ESP32 Board With Integrated SSD1306 OLED Display (WEMOS/Lolin)




There are a number of ESP32 development boards available now that also include a connected SSD1306 OLED display. These can be obtained from a number of places including BangGood and AliExpress.

This is a quick run through of one way of getting one of these boards, including the display, working with MicroPython. I use Python 2.7 and a Windows 10 PC but other routes are available for a number of the steps using other version of Python and OS's. I will give some pointers if I can but you may have to do some independent research.

Step 1: Connect the Board and Determine Port Number

Connect your board to the PC via a suitable USB to micro USB cable.

On the board you may see some text and images being displayed depending on what comes installed on the ESP32.

Open your device manager (simple search for 'device' in the windows search box). When expanded the ports section should show something like the above. Make a note of the port number, e.g. in my case COM3.

Step 2: Downloading and Installing Required Software.


If you do not have it already installed install Python by downloading from the official site. I use Python 2.7, but 3.x should be fine, though you may need to change some instructions.


Pip is a installer for python modules that both downloads and installs the modules. Latest versions of Python include pip but if you are using an older version you can install it using this guide. To see if you have pip look in the Scripts folder of your Python installation, e.g. if you installed in C:\Python27 then look in C:\Python27\Scripts.


This is the recommended tool for installing the firmware on the chip. You use pip to install it as follows:

pip install esptool

If you have an old version you almost certainly need to upgrade to the latest version as follows:

pip install esptool --upgrade

Note that some old versions were actual Python py files, i.e. esptool.py, on windows but the latest versions are executables, though, I assume to maintain compatibility with previous scripts or instructions they are called esptool.py.exe.


Ampy allows you to interact with the file system created on the chip. I use the adafruit version that can be installed as follows:

pip install adafruit-ampy

For information on installing on other OS's or version of Python look here.

Terminal Program

You will need a terminal program to connect you to the serial port. I use PuTTY which you can download from here.

Step 3: Obtain MicroPython and Install It.

Get the Bin File

MicroPython for the ESP32 chips can be obtained from here. Note that at the time of writing this port is under development and only daily builds are available.

Download the bin file and make a note of its location.

Get to a command prompt. On Windows simply type CMD in the search box and select 'Command Prompt'.

In the command prompt change directory to the Python scripts directory. So, for example, if you have installed Python in C:\Python27 enter the following:

cd c:\Python27\Scripts

If installed on another disk, e.g. d:\Python27 you will have to change the active disk first.


cd d:\Python27\Scripts

Check Connection

We can now use esptool.py to initially check the connection to the ESP32. The quickest way to do this is the command:

esptool.py --port COMX flash_id

Where you replace the COMX with your port identifier, e.g. COM3 in my case. This command should produce a log similar to the first above that includes 'Detected Flash Size'. If it does all is going well.

Erase Flash

Before installing the bin file we need to erase the flash on the chip. To do this enter the following command

esptool.py --port COMX erase_flash

Again replacing COMX with your port identifier. You should get a output like the image above containing 'Chip erase completed successfully'.

Program with the MicroPython file.

Enter the following command, replacing COMX with your serial port and X:\somewhere\micropython.bin with the location of the downloaded bin file.

esptool.py --chip esp32 --port COMX write_flash -z 0x1000 X:\somewhere\micropython.bin

This will take a few seconds at the end you should get an output as above containing 'Hash of data verified'.

Check Installation using Terminal program.

Open your terminal program, I use PuTTY and connect to the port via a serial connection at 115200 baud. On connecting you should get something like the PuTTY window shown. Do not worry about the error, we shall fix that shortly. In time honoured tradition enter the following line at the prompt.

print("Hello World")

Step 4: Fixing the Error and Uploading the OLED Library.

Fixing the Error

The error comes from missing a main.py file (see here for report). For now we do as suggest in the report and create a main.py that just acknowledges its own existence.

At the prompt enter the following lines.

f = open("main.py", "w")

f.write("print(\"main.py: Hello\")\n")


Next time you reboot the board the error will be replaced by the above printed remark.

Uploading the OLED Library

I used the adafruit MicroPython ssd1306.py module that can be found here. Download the ZIP and then just extract the ssd1306.py file to a known location on your machine.

To upload this we are going to use ampy but before we can do so we must close the terminal program as only one of the programs can use the connection at a time.

Once it has been closed enter the following on the command prompt, still in the Scripts directory.

ampy --port COMX --baud 115200 put x:\location\ssd1306.py

Where you replace COMX with the port you are using and x:\location\ where you downloaded the python file.

Open the terminal program again, you may need to press enter once connected to get the >>> prompt. Check the existence of the new file by entering:

import os


The result of which should be:

 ['boot.py', 'main.py', 'ssd1306.py']

Step 5: Displaying Some Text.


These commands are all done when connected to the board via the terminal server.

First import the libraries we need

import machine, ssd1306

Now we create the I2C connector object and use that to create the screen object

i2c = machine.I2C(scl=machine.Pin(4), sda=machine.Pin(5))

oled = ssd1306.SSD1306_I2C(128, 64, i2c)

Note that unlike the adafruit example for connecting micropython to an ssd1306 here the pin numbers are the otherway round.

Finally we can output to the screen, first by clearing to black, then adding some text and finally showing it on the screen.

oled.text('MicroPython on', 0, 0)
oled.text('an ESP32 with an', 0, 10)
oled.text('attached SSD1306', 0, 20)
oled.text('OLED display', 0, 30)

After which the text, as the image above, should be displayed on the screen.

Other tutorial are available for other elements of using MicroPython but hopefully this will be of use for this particular situation.

8 People Made This Project!


  • Pets Challenge

    Pets Challenge
  • Fandom Contest

    Fandom Contest
  • Backyard Contest

    Backyard Contest

12 Discussions


6 months ago

Run well, Note: in my case I had to push down Boot button while running esptool to get it working


7 months ago

My very first test !! thank you
I had to modify the pyboard.py and add a "time.sleep(2)' here :

def enter_raw_repl(self):
# Brief delay before sending RAW MODE char if requests
if _rawdelay > 0:
self.serial.write(b'\r\x03\x03') # ctrl-C twice: interrupt any running program
# flush input (without relying on serial.flushInput())
n = self.serial.inWaiting()
while n > 0:
n = self.serial.inWaiting()


1 year ago

Very good post, Thank you very much!! :)

Very well explained


1 year ago

For anyone that is having problems seeing the oled as an i2c device (such as `i2c.scan()` comes back empty) the oled's reset pin must be set HIGH before declaring `oled = ssd1306.SSD1306_I2C(128, 64, i2c)`.

In my case, my code looked like:

pin = machine.Pin(16, machine.Pin.OUT)
pin.value(0) // set GPIO16 low to reset OLED
pin.value(1) // while OLED is running, must set GPIO16 in high
oled = ssd1306.SSD1306_I2C(128, 64, i2c)

Although, I was using a different board (HelTec TTGO ESP32 Lora) so maybe this is not a problem on others


1 year ago on Step 5

Brilliant! many thanks..


1 year ago

Muito bom o tutorial, funcionou corretamente...

1 reply

Reply 1 year ago

Traceback (most recent call last):
File "main.py", line 1
SyntaxError: invalid syntax
MicroPython v1.9.3-240-ga275cb0f on 2018-01-12; ESP32 module with ESP32
Type "help()" for more information.


1 year ago

Many thanks, worked perfectly.
Vielen Dank


1 year ago

Worked perfectly! Thank you.


1 year ago

I had a problem uploading the .bin file as listed but got it working using the following: esptool.py --chip esp32 --port COMX write_flash -z 0x1000 firmware_filename_here.bin

1 reply

Great first Instructable. Thanks for sharing with the community.