The ports/espressif build setup is a rather involved process. Start with the setup described on the Build CircuitPython page. Don't forget to make fetch-port-submodules in ports/espressif or make-fetch-all-submodules at the top level.
On Linux you probably need to install ninja-build and cmake.
sudo apt install ninja-build cmake
sudo apt install ninja-build cmake
The ESP-IDF expects there to be a python command which runs python3. On Ubuntu, there is no plain python by default, so install this simple package which links python to python3.
sudo apt install python-is-python3
sudo apt install python-is-python3macOS
On macOS, you will need to install cmake and ninja:
brew install cmake brew install ninja
brew install cmake brew install ninjaRun the ESP-IDF Installation Script Once
Once you have the prerequisites installed, change to the ports/espressif directory, and run the esp-idf/install.sh script. You only need to do this once: install.sh downloads the toolchains and other files it needs, and copies a number of files into ~/.espressif. (If the ESP-IDF version used by CircuitPython changes, you will need to run install.sh again.)
install.sh also sets up a Python venv (virtual environment) in ~/.espressif/python-dev. If you are already using a venv, maybe because you're using a recent version of Linux, you'll need to deactivate that venv before running install.sh. Otherwise you'll get an error that you can't create a venv inside another venv.
cd circuitpython/ports/espressif # If you are already inside a Python venv, deactivate it. deactivate esp-idf/install.sh
cd circuitpython/ports/espressif # If you are already inside a Python venv, deactivate it. deactivate esp-idf/install.shInstall Python Packages in the ESP-IDF venv
After running export.sh, you need to repeat the pip3 install commands described here so that they take effect inside the Python environment set up by source esp-idf/export.sh. But you will need to do this only once.
# Install needed Python packages from pypi.org after running install.sh or if the needed packages change. pip3 install --upgrade -r requirements-dev.txt pip3 install --upgrade -r requirements-doc.txt
# Install needed Python packages from pypi.org after running install.sh or if the needed packages change. pip3 install --upgrade -r requirements-dev.txt pip3 install --upgrade -r requirements-doc.txtSetting Up the ESP-IDF Environment Before Building
You only need to run esp-idf/install.sh once. But later, in each fresh terminal window in which you are doing builds, you need to run esp-idf/export.sh in order to set up the correct PATH and other environment variables.
As with install.sh, if you're inside a Python venv, you need to deactivate it, so that export.sh can activate its own venv . Otherwise you will get an error that you can't create venv inside another venv.
# Do this in each new terminal. cd circuitpython/ports/espressif # If you are inside a Python venv, deactivate it. deactivate source esp-idf/export.sh
# Do this in each new terminal. cd circuitpython/ports/espressif # If you are inside a Python venv, deactivate it. deactivate source esp-idf/export.sh
export.sh will suggest that you use idf.py to do a build after you run it. But we don't use idf.py. Instead, use make. For example:
make BOARD=adafruit_magtag_2.9_grayscale
make BOARD=adafruit_magtag_2.9_grayscaleFiles Generated by a Build
make BOARD=... generates several files:
The circuitpython-firmware.bin is an intermediate file that does not include the bootloader and partition table. Ignore it: do not flash it to the chip. Flash firmware.bin instead.
Decoding a Crash BacktraceIf your Espressif build of CircuitPython crashes with a line that looks something like this, you can process this backtrace and get a symbolic backtrace.
Backtrace: 0x400e33fd:0x3ffb1090 0x40086755:0x3ffb10d0 0x40084025:0x3ffb1100 0x4008e75d:0x3ffb3b70 0x4008e7a5:0x3ffb3ba0 ...
Backtrace: 0x400e33fd:0x3ffb1090 0x40086755:0x3ffb10d0 0x40084025:0x3ffb1100 0x4008e75d:0x3ffb3b70 0x4008e7a5:0x3ffb3ba0 ...
Run this python script, substituting the BOARD name for <board> below. Then paste the Backtrace: ... line into the ? prompt. The script will look in the build-<board> directory, and use the .elf file there to decode the hex numbers in the backtrace.
$ cd ports/espressif $ python3 tools/decode_backtrace.py <board>
$ cd ports/espressif $ python3 tools/decode_backtrace.py <board>
Page last edited March 26, 2025
Text editor powered by tinymce.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4