You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
24
+
This will install ``esptool``'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.
25
25
26
-
It’s also possible to run the scripts directly from the working directory with this Development Mode installation.
26
+
It's also possible to run the scripts directly from the working directory with this Development Mode installation.
27
27
28
-
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:
28
+
To also install additional tools needed for actually developing and testing ``esptool``, run this command to install a development copy of ``esptool`` *plus* packages useful for development:
29
29
30
30
::
31
31
@@ -36,14 +36,16 @@ To also install additional tools needed for actually developing and testing ``es
36
36
Reporting Issues
37
37
----------------
38
38
39
-
Please report bugs in ``esptool.py`` if you find them. However, before reporting a bug please check through the following:
39
+
Please report bugs in ``esptool`` if you find them. However, before reporting a bug please check through the following:
40
40
41
41
* `Troubleshooting Guide <https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html>`_ - common problems and known issues.
42
42
43
43
* `Existing Open Issues <https://github.com/espressif/esptool/issues>`_ - someone might have already encountered this.
44
44
45
45
If you don’t find anything, please `open a new issue <https://github.com/espressif/esptool/issues/new/choose>`_.
46
46
47
+
.. _feature-requests:
48
+
47
49
Sending Feature Requests
48
50
------------------------
49
51
@@ -56,7 +58,7 @@ Before Contributing
56
58
57
59
Before sending us a Pull Request, please consider this list of points:
58
60
59
-
* Have you tried running ``esptool.py`` test suite locally?
61
+
* Have you tried running ``esptool`` test suite locally?
60
62
61
63
* Is the code adequately commented for people to understand how it is structured?
62
64
@@ -71,9 +73,9 @@ Before sending us a Pull Request, please consider this list of points:
71
73
Code Style & Static Analysis
72
74
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
73
75
74
-
Please follow these coding standards when writing code for ``esptool.py``:
76
+
Please follow these coding standards when writing code for ``esptool``:
75
77
76
-
Pre-commit checks
78
+
Pre-Commit Checks
77
79
"""""""""""""""""
78
80
79
81
`pre-commit <https://pre-commit.com/>`_ is a framework for managing pre-commit hooks. These hooks help to identify simple issues before committing code for review.
@@ -90,27 +92,27 @@ On the first commit ``pre-commit`` will install the hooks, subsequent checks wil
90
92
Conventional Commits
91
93
""""""""""""""""""""
92
94
93
-
``esptool.py`` complies with the `Conventional Commits standard <https://www.conventionalcommits.org/en/v1.0.0/#specification>`_. Every commit message is checked with `Conventional Precommit Linter <https://github.com/espressif/conventional-precommit-linter>`_, ensuring it adheres to the standard.
95
+
``esptool`` complies with the `Conventional Commits standard <https://www.conventionalcommits.org/en/v1.0.0/#specification>`_. Every commit message is checked with `Conventional Precommit Linter <https://github.com/espressif/conventional-precommit-linter>`_, ensuring it adheres to the standard.
94
96
95
97
96
98
Ruff
97
99
""""
98
100
99
-
``esptool.py`` is `PEP8 <https://peps.python.org/pep-0008/>`_ compliant and enforces this style guide. For compliance checking, we use `ruff <https://docs.astral.sh/ruff/>`_.
101
+
``esptool`` is `PEP8 <https://peps.python.org/pep-0008/>`_ compliant and enforces this style guide. For compliance checking, we use `ruff <https://docs.astral.sh/ruff/>`_.
100
102
``Ruff`` also auto-format files in the same style as previously used ``black``.
101
103
102
104
103
105
``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).
104
106
105
107
When you submit a Pull Request, the GitHub Actions automated build system will run automated checks using these tools.
106
108
107
-
Shinx-lint
108
-
""""""""""
109
+
Sphinx-Lint
110
+
"""""""""""
109
111
110
112
The documentation is checked for stylistic and formal issues by ``sphinx-lint``.
111
113
112
114
113
-
Codespell check
115
+
Codespell Check
114
116
"""""""""""""""
115
117
116
118
This repository utilizes an automatic `spell checker <https://github.com/codespell-project/codespell>`_ 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.
@@ -120,46 +122,46 @@ In the event of false positives, you can adjust the configuration in the `.codes
120
122
Automated Integration Tests
121
123
^^^^^^^^^^^^^^^^^^^^^^^^^^^
122
124
123
-
The test directory contains a `pytest <https://docs.pytest.org/>`_ integration suite with some integration tests for ``esptool.py``, ``espefuse.py``, and ``espsecure.py``.
125
+
The test directory contains a `pytest <https://docs.pytest.org/>`_ integration suite with some integration tests for ``esptool``, ``espefuse``, and ``espsecure``.
124
126
125
-
It is necessary to have ``esptool.py`` installed (see `Development Setup`_) in your environment in order to run these tests.
127
+
It is necessary to have ``esptool`` installed (see `Development Setup`_) in your environment in order to run these tests.
126
128
127
129
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:
128
130
129
131
* ``test_imagegen.py`` tests the ``elf2image`` command
130
-
* ``test_image_info.py`` tests the ``image_info`` command
131
-
* ``test_mergebin.py`` tests the ``merge_bin`` command
132
-
* ``test_modules.py`` tests the modules used by ``esptool.py`` for regressions
* ``test_espsecure_hsm.py`` tests support of external HSM signing in ``espsecure.py``. These tests require additional prerequisites, see ``SoftHSM2 setup`` in the `tests workflow definition <https://github.com/espressif/esptool/blob/master/.github/workflows/test_esptool.yml>`_ for more information.
132
+
* ``test_image_info.py`` tests the ``image-info`` command
133
+
* ``test_mergebin.py`` tests the ``merge-bin`` command
134
+
* ``test_modules.py`` tests the modules used by ``esptool`` for regressions
* ``test_espsecure_hsm.py`` tests support of external HSM signing in ``espsecure``. These tests require additional prerequisites, see ``SoftHSM2 setup`` in the `tests workflow definition <https://github.com/espressif/esptool/blob/master/.github/workflows/test_esptool.yml>`_ for more information.
135
137
136
138
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:
137
139
138
-
* ``test_esptool.py`` contains integration tests for ``esptool.py`` and needs to be run against real Espressif hardware with the following format:
140
+
* ``test_esptool.py`` contains integration tests for ``esptool`` and needs to be run against real Espressif hardware with the following format:
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:
148
+
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:
Some tests might fail at higher baud rates on some hardware.
153
155
154
-
* ``test_esptool_sdm.py`` contains integration tests for ``esptool.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 for ``test_esptool.py``.
156
+
* ``test_esptool_sdm.py`` contains integration tests for ``esptool`` 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 for ``test_esptool.py``.
155
157
156
158
The following tests are not run automatically by GitHub Actions, but can be run locally in a command line:
157
159
158
-
* ``test_espefuse.py`` tests ``espefuse.py`` functionality. To run it:
160
+
* ``test_espefuse.py`` tests ``espefuse`` functionality. To run it:
159
161
160
162
``pytest test_espefuse.py --chip <name of chip>``
161
163
162
-
These test use the ``--virt`` virtual mode of ``espefuse.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.
164
+
These test use the ``--virt`` virtual mode of ``espefuse`` to safely test the functionality without a connection to a chip and without the possibility of affecting the actual eFuses in a real hardware.
163
165
164
166
.. warning::
165
167
@@ -171,9 +173,7 @@ The whole test suite (without the tests needing an actual hardware or installati
171
173
Pull Request Process
172
174
--------------------
173
175
174
-
.. note::
175
-
176
-
If you are developing the stub flasher and plan to send a pull request, please use the latest toolchains available.
176
+
If you would like to contribute to the flasher stub, please see the `Flasher stub repository <https://github.com/espressif/esptool-legacy-flasher-stub>`_.
177
177
178
178
After you open the Pull Request, there will probably be some discussion in the comments field of the request itself.
Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool.py -h`.
9
+
Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool -h`.
10
10
11
11
## Contribute
12
12
13
-
If you're interested in contributing to esptool.py, please check the [contributions guide](https://docs.espressif.com/projects/esptool/en/latest/contributing.html).
13
+
If you're interested in contributing to esptool, please check the [contributions guide](https://docs.espressif.com/projects/esptool/en/latest/contributing.html).
14
14
15
15
## About
16
16
17
-
esptool.py was initially created by Fredrik Ahlberg (@[themadinventor](https://github.com/themadinventor/)), and later maintained by Angus Gratton (@[projectgus](https://github.com/projectgus/)). It is now supported by Espressif Systems. It has also received improvements from many members of the community.
17
+
esptool was initially created by Fredrik Ahlberg (@[themadinventor](https://github.com/themadinventor/)), and later maintained by Angus Gratton (@[projectgus](https://github.com/projectgus/)). It is now supported by Espressif Systems. It has also received improvements from many members of the community.
0 commit comments