Skip to content
Boris Lovosevic edited this page Dec 11, 2018 · 12 revisions

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

You may want to use --depth clone option to limit the git history to only the latest commit.
The download will be much smaller and faster.

git clone --depth 1 https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo.git

You can also download the repository as a zip file (using Clone or download button on the first repository page) and unpack it to some directory.
You will not be able to use git pull to update the repository, but otherwise the building process is the same.

Build the MicroPython firmware


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.