Contributions Guide
We welcome contributions to the esptool.py
project!
How to Contribute
Contributions to esptool.py
- fixing bugs, adding features, adding documentation - are welcome. We accept contributions via Github Pull Requests.
Development Setup
Development mode allows you to run the latest development version from the esptool.py repository on GitHub.
$ git clone https://github.com/espressif/esptool.git
$ cd esptool
$ pip install --user -e .
This will install esptool.py
’s dependencies and create some executable script wrappers in the user’s bin
directory. The wrappers will run the scripts found in the git working directory directly, so any time the working directory contents change it will pick up the new versions.
It’s also possible to run the scripts directly from the working directory with this Development Mode installation.
To also install additional tools needed for actually developing and testing esptool.py
, run this command to install a development copy of esptool.py
plus packages useful for development:
$ pip install --user -e ".[dev]"
(This command uses the “extras” feature of setuptools.)
Reporting Issues
Please report bugs in esptool.py
if you find them. However, before reporting a bug please check through the following:
Troubleshooting Guide - common problems and known issues.
Existing Open Issues - someone might have already encountered this.
If you don’t find anything, please open a new issue.
Sending Feature Requests
Feel free to post feature requests. It’s helpful if you can explain exactly why the feature would be useful.
There are usually some outstanding feature requests in the existing issues list, feel free to add comments to them.
Before Contributing
Before sending us a Pull Request, please consider this list of points:
Have you tried running
esptool.py
test suite locally?Is the code adequately commented for people to understand how it is structured?
Is there documentation or examples that go with code contributions?
Are comments and documentation written in clear English, with no spelling or grammar errors?
If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like “fixed typo” squashed into previous commits?
If you’re unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.
Code Style & Static Analysis
Please follow these coding standards when writing code for esptool.py
:
Pre-commit checks
pre-commit is a framework for managing pre-commit hooks. These hooks help to identify simple issues before committing code for review.
To use the tool, first install pre-commit
. Then enable the pre-commit
and commit-msg
git hooks:
$ python -m pip install pre-commit
$ pre-commit install -t pre-commit -t commit-msg
On the first commit pre-commit
will install the hooks, subsequent checks will be significantly faster. If an error is found an appropriate error message will be displayed. Review the changes and re-stage for commit if you are happy with them.
Conventional Commits
esptool.py
complies with the Conventional Commits standard. Every commit message is checked with Conventional Precommit Linter, ensuring it adheres to the standard.
Ruff
esptool.py
is PEP8 compliant and enforces this style guide. For compliance checking, we use ruff.
Ruff
also auto-format files in the same style as previously used black
.
Ruff
and Conventional Precommit Linter
tools will be automatically run by pre-commit
if that is configured. To check your code manually before submitting, run python -m ruff
(this tool is installed as part of the development requirements shown at the beginning of this document).
When you submit a Pull Request, the GitHub Actions automated build system will run automated checks using these tools.
Shinx-lint
The documentation is checked for stylistic and formal issues by sphinx-lint
.
Codespell check
This repository utilizes an automatic spell checker integrated into the pre-commit process. If any spelling issues are detected, the recommended corrections will be applied automatically to the file, ready for commit. In the event of false positives, you can adjust the configuration in the .codespell.rc. To exclude files from the spell check, utilize the skip keyword followed by comma-separated paths to the files (wildcards are supported). Additionally, to exclude specific words from the spell check, employ the ignore-words-list keyword followed by comma-separated words to be skipped.
Automated Integration Tests
The test directory contains a pytest integration suite with some integration tests for esptool.py
, espefuse.py
, and espsecure.py
.
It is necessary to have esptool.py
installed (see Development Setup) in your environment in order to run these tests.
The following tests run automatically by GitHub Actions for each Pull Request. You can run them locally to check for regressions in the respective functionality:
test_imagegen.py
tests theelf2image
commandtest_image_info.py
tests theimage_info
commandtest_mergebin.py
tests themerge_bin
commandtest_modules.py
tests the modules used byesptool.py
for regressionstest_espsecure.py
testsespsecure.py
functionalitytest_espsecure_hsm.py
tests support of external HSM signing inespsecure.py
. These tests require additional prerequisites, seeSoftHSM2 setup
in the tests workflow definition for more information.
The following tests are not run automatically by GitHub Actions, because they need real connected hardware. Therefore, they need to be run locally in a command line:
test_esptool.py
contains integration tests foresptool.py
and needs to be run against real Espressif hardware with the following format:pytest test_esptool.py --port <serial port> --chip <name of chip> --baud <baud rate>
For example, to run all tests on an ESP32 board connected to /dev/ttyUSB0, at 230400bps:
pytest test_esptool.py --port /dev/ttyUSB0 --chip esp32 --baud 230400
Or to run the TestFlashing suite only (using the pytest
-k
option to select tests based on their name) on an ESP8266 board connected to /dev/ttyUSB2, at 460800bps:pytest test_esptool.py --port /dev/ttyUSB2 --chip esp8266 --baud 460800 -k TestFlashing
Note
Some tests might fail at higher baud rates on some hardware.
test_esptool_sdm.py
contains integration tests foresptool.py
with chips in secure download mode. It needs to be run against real Espressif hardware (with active SDM). The command line format is the same as fortest_esptool.py
.
The following tests are not run automatically by GitHub Actions, but can be run locally in a command line:
test_espefuse.py
testsespefuse.py
functionality. To run it:pytest test_espefuse.py --chip <name of chip>
These test use the
--virt
virtual mode ofespefuse.py
to safely test the functionality without a connection to a chip and without the possibility of affecting the actual eFuses in a real hardware.Warning
Do not attempt to run these tests on real hardware! You risk damaging or destroying the ESP chip!
The whole test suite (without the tests needing an actual hardware or installation of additional prerequisites) can be easily run with the following command in the esptool root folder: pytest -m host_test
Pull Request Process
Note
If you are developing the stub flasher and plan to send a pull request, please use the latest toolchains available.
After you open the Pull Request, there will probably be some discussion in the comments field of the request itself.
Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing.
If this process passes, it will be merged onto the public github repository, hooray!