build

Building MicroPython for ESP32

Install Prerequisites

To compile with ESP-IDF you need to get the following packages:

CentOS 7:
sudo yum install git wget make ncurses-devel flex bison gperf python pyserial

Ubuntu and Debian:
sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial

openSUSE:
sudo zypper install gcc git wget make ncurses-devel flex bison gperf python python-serial

Arch:
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python-pyserial

Mac OS:
sudo easy_install pip
sudo pip install pyserial

---

Clone the MicroPython repository

git clone https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo.git

Xtensa toolchains and esp-idf are provided as tar archives. They will be automatically unpacked on first run of BUILD.sh script

Warning:
If running on Windows, you may get false error unpacking 'esp-idf' FAILED.
Run ./BUILD.sh again, the toolchain will be unpacked successfully.

Change the working directory to MicroPython_BUILD directory

To change some ESP32 & Micropython options or to create initial sdkconfig run:

./BUILD.sh menuconfig

To build the MicroPython firmware, run:

./BUILD.sh

You can use -jn option to make the build process faster. If using too high n the build may fail because of race condition, if that happens, run build again or run without the -j option.

If no errors are detected, you can now flash the MicroPython firmware to your board. Run:

./BUILD.sh flash

The board stays in bootloader mode. Run your terminal emulator and reset the board.

You can also run ./BUILD.sh monitor to use esp-idf's terminal program, it will reset the board automatically if the hardware supports that feature.

After changing sdkconfig.h (via menuconfig) it is recommended to run ./BUILD.sh clean before new build

---

BUILD.sh

Included BUILD.sh script makes building MicroPython firmware easy.

Usage:

.BUILD.sh <options> <commands>

Options

Option	Function
-jn	use multicore build, runs much faster. Replace n with the number of cores on your system
-v --verbose	verbose output
-f8 --flashsize8	build for 8MB Flash
-f16 --flashsize16	build for 16MB Flash
-fs N --fssize=N	force file system size to N KB; default: fit the Flash size
-a N --appsize=N	force application size to N KB; default: auto detect needed size; the actual size will be 64 KB smaller then the declared size
--force2p	force 2 partition layout on 16MB Flash when OTA is used
--force3p	force 3 partition layout on 8MB Flash when OTA is used
-p commport --port=commport	overwritte configured comm port, use the specified instead
-b baud_rate --bdrate=baud_rate	overwritte configured baud rate, use the specified instead

Commands

Command	Function
all	run the build, create MicroPython firmware
menuconfig	run menuconfig to configure ESP32/MicroPython
clean	clean the build
flash	flash MicroPython firmware to ESP32
erase	erase the whole ESP32 Flash
monitor	run esp-idf terminal program
size	display static memory footprint of the firmware
size-components	display detailed memory footprint of the firmware
size-files	display detailed memory footprint of the firmware
makefs	create SPIFFS file system image which can be flashed to ESP32
flashfs	flash SPIFFS file system image to ESP32, if not created, create it first
copyfs	flash the default SPIFFS file system image to ESP32
makefatfs	create FatFS file system image which can be flashed to ESP32
flashfatfs	flash FatFS file system image to ESP32, if not created, create it first
copyfatfs	flash the default FatFS file system image to ESP32

As default the build process runs silently, without showing compiler output. You can change that by using -v or --verbose option.

To build with OTA partition layout sellect in menuconfig
→ MicroPython → Use OTA partition layout

To build with psRAM support:

In menuconfig select
→ Component config → ESP32-specific → Support for external, SPI-connected RAM

It is recommended to select
→ Component config → ESP32-specific → SPI RAM config → Make RAM allocatable using heap_caps_malloc
but other options will also work.

From May 10 2018 (ver ESP32_LoBo_v3.2.15) firmwares built with psRAM support will also run on boards without psRAM!
You must set (in menuconfig)
Component config → ESP32-specific → SPI RAM config → Ignore PSRAM when not found
for this feature to work.

---

Updating to the latest version

To update to the latest commits, go to MicroPython_ESP32_psRAM_LoBo directory and execute:

git pull

If you get the warning:

error: Your local changes to the following files would be overwritten by merge:
	....
	....
Please commit your changes or stash them before you merge.

you may execute:

git stash

and execute the git pull again.

It is recommended to execute ./BUILD.sh menuconfig after the pull as some menuconfig options may be added/changed.
After some major updates, your build environment will be cleaned. In that case you will need to run ./BUILD.sh menuconfig first.