Picoweb Setup for ESP-32 boards

Picoweb's setup has diverged a bit from the standard MicroPython configuration we see in most tutorials.

In this Gist I present the setup instructions used in November 2020 to setup Picoweb in a ESP-32 board. The library itself was developed by PFalcon and he deserves all credit for it.

Dependencies

• Pycopy: is PFalcon's fork for assyncronous MicroPython communication - a brief recap of their divergencies is in this thread.
• ESP-IDF 3.x
• Xtensa cross-compiler
• Optional: ulogging: you will also need to specifically install PFalcon's version of the logging application.

Downloading Dependencies

Pycopy

First we need to build and flash the MicroPython fork compatible with picoweb. Be sure to checkout to the latest release (v3.3.2) to avoid nightly version issues.

mkdir esp32 && cd esp32
git clone git@github.com:pfalcon/pycopy.git
git checkout tags/v3.3.2

The installation instructions are presented in the repository itself pycopy/ports/esp32/Readme.md. The following modules are installed almost precisely as described in Pycopy documentation. For simplicity, the instruction will be copied over here with a few important modifications.

ESP-IDF 3.x

The ESP-IDF changes quickly and MicroPython only supports certain versions. The git hash of these versions (one for 3.x, one for 4.x) can be found by running make without a configured ESPIDF. Then you can fetch the required IDF using the following command:

$ cd pycopy/ports/esp32
$ make ESPIDF=  # This will print the supported hashes, copy the one you want.
$ export ESPIDF=$HOME/esp32/esp-idf  # Or any path you like.
$ mkdir -p $ESPIDF
$ cd $ESPIDF
$ git clone https://github.com/espressif/esp-idf.git $ESPIDF
$ git checkout <Current supported ESP-IDF commit hash>
$ git submodule update --init --recursive

[Important]: replace the standard mbedutils for PFalcon's one to prevent compilation errors.

cd esp-idf/components/mbedtls/
rm -rf mbedtls
git clone -b mbedtls-2.16.5-idf-pycopy https://github.com/pfalcon/mbedtls/

To install its Python dependencies, it's reccomended to use a virtual environment. To set up a Python virtual environment from scratch:

$ cd pycopy/ports/esp32
$ python3 -m venv build-venv
$ source build-venv/bin/activate
$ pip install --upgrade pip
$ pip install -r $HOME/esp32/esp-idf/requirements.txt

To re-enter this virtual environment in future sessions, you only need to source the activate script, i.e.:

$ cd pycopy/ports/esp32
$ source build-venv/bin/activate

Xtensa cross-compiler 3.x

Download cross compiler and add it to the system PATH.

cd esp32
curl -L https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz | tar zxf -
export PATH=$(pwd)/xtensa-esp32-elf/bin:$PATH

Build

First build Pycopy cross compiler.

cd pycopy/mpy-cross
make

And then compile the complete library into the board configuration.

cd pycopy/ports/esp32

The default compilation options can be overwitten by the creation of a file named makefile at this directory. Here is an example of such a file.

ESPIDF ?= $(HOME)/esp32/esp-idf/
BOARD ?= GENERIC
#PORT ?= /dev/ttyUSB0
#FLASH_MODE ?= qio
#FLASH_SIZE ?= 4MB
#CROSS_COMPILE ?= xtensa-esp32-elf-

include Makefile

Finally compile the Pycopy library.

make submodules
make

Flash into ESP-32

To flash the firmware you must have your ESP32 module in the bootloader mode and connected to a serial port on your PC. Refer to the documentation for your particular ESP32 module for how to do this. The serial port and flash settings are set in the Makefile, and can be overridden in your local makefile; see above for more details.

You will also need to have user permissions to access the /dev/ttyUSB0 device. On Linux, you can enable this by adding your user to the dialout group, and rebooting or logging out and in again. (Note: on some distributions this may be the uucp group, run ls -la /dev/ttyUSB0 to check.)

$ sudo adduser <username> dialout

If you are installing MicroPython to your module for the first time, or after installing any other firmware, you should first erase the flash completely:

$ make erase

To flash the MicroPython firmware to your ESP32 use:

$ make deploy

This will use the esptool.py script (provided by ESP-IDF) to flash the binary images to the device.

Test Installation

Using Thonny, one can easyly open a REPL terminal in the ESP-32 and upload Python scripts into it's flash memory. After uploading the python scripts and template attached to this gist, you shoud see the following file structure:

.
├── boot.py
├── deps.py
├── example.py
├── templates
│   └── squares.tpl
└── wifi.py

If you run example.py you should see an example web application when accessing the ESP-32 IP address, port 8081 from an web browser on your local network.

import wifi
# connect to your local wifi
wifi.connect('My SSID', 'My-Password')

import deps
# install dependencies
deps.install()

exec(open("example.py").read())

References:

• CI Travis installation of picoweb (link)
• Pycopy as a hard requirement of picoweb (link)
• mbedTLS dependency specification (link)