MicroPython is a programming language that is derived from his big brother Python and is optimised to run on microcontrollers. In this blog we will focus how to get it running on ESP32 with a SSD1306 OLED display.
I have bought my board in a Chinese webshop. Just search on "esp32 vroom oled" and you will be able to find it. After powering it on I was surprised to see a Hello World demo app that was showing some texts and images. However this needed to go because the goal was to install MicroPython.
This was easier that I expected and after after a couple of minutes it was up and running. Let me take you through the steps that I did to install it.
First I visited the website of MicroPython and went to the download section. There was a link to download the firmware for the ESP32. The steps below describe how to flash this firmware to the microcontroller board.
Install the driver so the board will get recognised. This driver is from Silicon Labs and is called CP210x USB to UART Bridge VCP Driver. Initially I have installed in on a Windows 7 machine, but these driver is also available for Mac and Linux. After you plug in your device you will be able to see it inside your Windows Device Manager. It is important to check on which COM port it is running. In my case it was COM9.
If you have installed the driver on an OSX machine you can execute ls /dev/tty* inside the terminal window to see the port name. In my case it was:
/dev/tty.SLAB_USBtoUART
It is time to download and install Python on your computer (If you haven't done so already). I used Python 2, but I believe it will also work well using Python 3. You will now need to open a cmd box and go to the location where Python was installed, then enter the Scripts/ directory. This is by default C:\Python27\Scripts. You can also add this to your path. To install Python on a Mac you can run: brew install python
Using the PIP (Python package manager) you need to install esptool and ampy tool.
pip install esptool pip install adafruit-ampy
Now you are ready to flash the MicroPython firmware on your ESP32 microcontroller.
Check if your board is recognised with the esptool. In order to do this you will need to press and hold the Boot button on your board and execute the command mentioned below. Note that you will need to enter the correct port number. In my case it was COM9 and for Mac /dev/tty.SLAB_USBtoUART
esptool.py --port COM9 flash_id
After you get a positive response you will have to erase the flash memory on the chip. To do that execute the command below:
esptool.py --port COM9 erase_flash
We are now ready to flash the MicroPyhon firmware. Don't forget to use your COM port number and the filename that you have downloaded inside the parameters.
esptool.py --chip esp32 --port COM9 write_flash -z 0x1000 esp32-20180317-v1.9.3-470-ge37b8ba5.bin
To check if everything went ok, you can use puTTY on Windows and try to connect to the COM port. Select the Serial radio button and use the connection speed of 115200.
On a Mac you can use the screen command.
screen /dev/tty.SLAB_USBtoUART 115200
You will now enter the REPL command mode and will be able to execute Python commands.
MicroPython has it's own filesystem and it is possible to upload files. For that we can use the ampy tool. Let's create our own Hello World app that will show some text on the OLED display.
In order to address the screen we need to download the Adafruit SSD1306 library. Copy the ssd1306.py file to your ESP32 with this command:
ampy --port COM9 --baud 115200 put ssd1306.py
To check if the file is uploaded you can run:
ampy --port COM9 --baud 115200 ls
Alternatively you can connect to the REPL console and type these lines:
import os os.listdir()
Create a file called main.py and pase these contents inside it. It will be executed after powering up the board.
import machine, ssd1306
i2c = machine.I2C(scl=machine.Pin(4), sda=machine.Pin(5))
oled = ssd1306.SSD1306_I2C(128,64, i2c)
oled.fill(0)
oled.text('MicroPython', 10, 10)
oled.text('on ESP32', 10, 30)
oled.show()
Now reboot the board or press Ctrl-D for soft reset inside REPL.
Don't forget to check our some online tutorials on the Adafruit website and Youtube.
Also try out this GFX libary that will let you draw lines, circles and rectangles. Upload the gfx.py like you did with the ssd1206.py and place this code inside main.py file.
import machine, ssd1306, gfx i2c = machine.I2C(scl=machine.Pin(4), sda=machine.Pin(5)) oled = ssd1306.SSD1306_I2C(128,64, i2c) graphics = gfx.GFX(128, 64, oled.pixel) oled.fill(0) oled.show() graphics.line(0, 0, 127, 63, 1) oled.show()
I have also measured the power usage of the ESP32 board. It is around 150 mA. It should run around 20 hours on a 3000 mAh power pack.
Below I have summed up some handy commands and tricks:
To delete a file inside REPL:
Press Ctrl-B
import os
os.remove('main.py')
Set default ampy port in OSX (add to .bash_profile)
export AMPY_PORT=/dev/tty.SLAB_USBtoUART
To quit screen session (OSX):
Ctrl-A, Ctrl-\ Y
Press tab while writing command inside REPL to autocomplete functions.
Please let me know what kind of cool things you are creating with MicroPython on your ESP32 board.