esp-flasher-stub

This project is experimental and not yet ready for production use.

The project's goal is to replace the legacy flasher stub of esptool in the near future.

Build Dependencies

Submodules

The project depends on esp-stub-lib in the form of git submodule. Don't forget to get/update the submodule as well before building:

git submodule update --init --recursive

Toolchains

You will need the following toolchains set up and available in your PATH:

1. xtensa-lx106-elf-*
2. xtensa-*-elf-*
3. riscv32-esp-elf-*

There is a convenience script for AMD64 Linux machines to download and install them into the toolchains directory:

mkdir -p toolchains
cd toolchains
../tools/setup_toolchains.sh

Then run the following export script in every terminal where the project is used:

. ./tools/export_toolchains.sh

Esptool

Esptool is needed for ELF file analysis.

Virtual Environment Requirement: It is strongly recommended to use a virtual environment for installing esptool to avoid conflicts with system packages and ensure reproducible builds. The virtual environment isolates the Python dependencies and prevents version conflicts that could affect the build process.

Run the following commands in order to install it:

python -m venv venv
source venv/bin/activate
pip install esptool

Important: Run the following command in every terminal where the project is used to activate the virtual environment:

source venv/bin/activate

How to Build

Build for one selected chip target

mkdir -p build
cmake . -B build -G Ninja -DTARGET_CHIP=esp32s2   # Replace with your desired chip, e.g. esp32, esp8266
ninja -C build

Build for all supported chip targets

./tools/build_all_chips.sh

How To Use With Esptool

1. Install esptool in development mode.

2. Obtain the flasher stub binaries as JSON files either from the releases page or from the artifacts of your pull request.

3. Replace the esptool's JSON files in the esptool/targets/stub_flasher directory with the obtained JSON files.

   Example copy command (adjust the path to your esptool directory):

   cp build-*/*.json ~/esptool/esptool/targets/stub_flasher/1/

Contributing

Please install the pre-commit hooks to ensure that your commits are properly formatted:

pip install pre-commit
pre-commit install -t pre-commit -t commit-msg

How To Release (For Maintainers Only)

python -m venv venv
source venv/bin/activate
pip install commitizen czespressif
git fetch
git checkout -b update/release_v1.1.0
git reset --hard origin/master
cz bump
git push -u
git push --tags

Create a pull request and edit the automatically created draft release notes.

License

This document and the attached source code are released as Free Software under either the Apache License Version 2 or MIT License at your option.