Esp32 and Micropython: A match made in heaven

2018/12/02

TL;DR:

~ $ mkdir esp32 && cd esp32
~/esp32 $ wget http://micropython.org/resources/firmware/esp32-20181121-v1.9.4-684-g51482ba92.bin
~/esp32 $ export PIPENV_VENV_IN_PROJECT=1
~/esp32 $ pipenv install esptool
~/esp32 $ pipenv install -e git+https://github.com/wendlers/mpfshell#egg=mpfshell
~/esp32 $ pipenv shell
(.venv) ~/esp32 $ esptool.py -p /dev/ttyUSB0 erase_flash
...

(.venv) ~/esp32 $ esptool.py -p /dev/ttyUSB0 write_flash -z 0x1000 esp32-20181121-v1.9.4-684-g51482ba92.bin 
...

(.venv) ~/esp32 $ mpfshell -o ttyUSB0
** Micropython File SHell v0.8.1, sw@kaltpost.de **
-- Running on Python 3.7 using PySerial 3.4 --

mpfs [/]> repl

 >>>

Your ESP32 board is now ready.


Intro

I recently purchased this board:

Picture of ESP32 module with OLED display

It’s an ESP32 module combined with a SSD1306 OLED display, and on the picture above it measured humidity and temperature in my living room via a connected DHT11 sensor.

The amazing part: All of this happens in only a few lines of code, thanks to Micropython.

Micropython

MicroPython is a lean and efficient implementation of the Python 3 programming language that includes a small subset of the Python standard library and is optimised to run on microcontrollers and in constrained environments.1

Do you know what this means? This means we can use our beloved Python for all kinds of cool DIY projects. And this post should give a little introduction of how you can flash Micropython on the ESP32.

First steps

Before we start, we need a few tools to connect, flash and upload code to our board:

The firmware

Create a working directory and download the necessary tools and files:

~ $ mkdir esp32 && cd esp32
~/esp32 $ wget https://micropython.org/resources/firmware/esp32-20181121-v1.9.4-684-g51482ba92.bin

(Eventually you want to make sure that you download the latest available firmware for your module. Go to https://micropython.org/download#esp32 and download the one tagged (latest).)

~/esp32 $ export PIPENV_VENV_IN_PROJECT=1
~/esp32 $ pipenv install esptool
~/esp32 $ pipenv install -e git+https://github.com/wendlers/mpfshell#egg=mpfshell

Flashing the ESP32

Now you can activate your virtual environment and flash the Micropython firmware on your board. Connect the board via USB and look into /dev on your OS to find the correct path to your ESP32. (On my machine, it’s /dev/ttyUSB0.)

Attention! If you set up your board for the first time, or you want to start from scratch, then erase the onboard storage first:

~/esp32 $ pipenv shell
(.venv) ~/esp32 $ esptool.py -p /dev/ttyUSB0 erase_flash
...

Use esptool.py to flash the firmware on your ESP32 module:

(.venv) ~/esp32 $ esptool.py -p /dev/ttyUSB0 write_flash -z 0x1000 esp32-20181121-v1.9.4-684-g51482ba92.bin 
...

Wait for the flash process to finish (this might take a few minutes) before continuing.

After the flashing has finished, you are ready to connect a shell to your board and start playing around. Connect with mpfshell and, once connected, start a Python REPL:

(.venv) ~/esp32 $ mpfshell -o ttyUSB0

** Micropython File SHell v0.8.1, sw@kaltpost.de **
-- Running on Python 3.7 using PySerial 3.4 --

mpfs [/]> repl

>>>

How to setup WiFi

Since the ESP32 board has WiFi and Bluetooth LE onboard, the first step should be to connect to your local WLAN.

(We already started the Python REPL in the previous step)

>>> import network
>>> wlan = network.WLAN(network.STA_IF)
>>> wlan.active(True)
True
>>> wlan.connect("MyLocalSSID", "MySuperPassword")
>>> wlan.isconnected()
True
>>> wlan.ifconfig()
('192.168.0.2', '255.255.255.0', '192.168.0.1', '192.168.0.1')

You can put those lines into a file boot.py. When this file exists in the internal storage of the board, it will be executed on every boot.

(.venv) ~/esp32 $ mpfshell -o ttyUSB0

mpfs [/]> put boot.py
mpfs [/]> ls

     boot.py

That’s it so far. Next post will include a bit of code on how to use the OLED display and the DHT sensor to measure and display room temperature.


  1. https://micropython.org