espressif/esptool
1
0
Fork 0
mirror of https://github.com/espressif/esptool.git synced 2025-10-14 02:43:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add initial structure for new docs

Browse Source
This commit is contained in:
radim.karnis
2021-11-01 15:14:09 +01:00
parent b6546510bf
commit f65bf93e9c
15 changed files with 1517 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -12,3 +12,5 @@ local.mk
.envrc
report.xml
docs/_build/

1
MANIFEST.in
View File

@@ -5,6 +5,7 @@ include LICENSE
prune test
prune flasher_stub
prune .github
prune docs
exclude .git*
exclude MANIFEST*

17
docs/README.md Normal file
View File

@@ -0,0 +1,17 @@
# Documentation Source Folder
This folder contains source files of **esptool documentation**.
The sources do not render well in GitHub and some information is not visible at all.
Use actual documentation generated within about 20 minutes on each commit:
# Hosted Documentation
* English: https://docs.espressif.com/projects/esptool/
The above URL is for the master branch latest version. Click the drop-down in the bottom left to choose a particular version or to download a PDF.
# Building Documentation
The documentation is built using the python package `esp-docs`, which can be installed by running `pip install esp-docs`. Running `build-docs --help` will give a summary of available options. For more information see the `esp-docs` documentation at https://github.com/espressif/esp-docs/blob/master/README.md

15
docs/_static/esptool_versions.js vendored Normal file
View File

@@ -0,0 +1,15 @@
var DOCUMENTATION_VERSIONS = {
DEFAULTS: { has_targets: false,
supported_targets: [ "esp32" ]
},
VERSIONS: [
{ name: "latest", has_targets: true, supported_targets: [ "esp8266", "esp32", "esp32s2", "esp32c3", "esp32s3" ] },
],
IDF_TARGETS: [
{ text: "ESP8266", value: "esp8266" },
{ text: "ESP32", value: "esp32" },
{ text: "ESP32-S2", value: "esp32s2" },
{ text: "ESP32-S3", value: "esp32s3" },
{ text: "ESP32-C3", value: "esp32c3" },
]
};

18
docs/conf_common.py Normal file
View File

@@ -0,0 +1,18 @@
from esp_docs.conf_docs import * # noqa: F403,F401
languages = ['en']
idf_targets = ['esp8266', 'esp32', 'esp32s2', 'esp32s3', 'esp32c3']
# link roles config
github_repo = 'espressif/esptool'
# context used by sphinx_idf_theme
html_context['github_user'] = 'espressif'
html_context['github_repo'] = 'esptool'
html_static_path = ['../_static']
# Extra options required by sphinx_idf_theme
project_slug = 'esptool'
versions_url = '_static/esptool_versions.js'

6
docs/en/about.rst Normal file
View File

@@ -0,0 +1,6 @@
About
=====
Esptool was started by Fredrik Ahlberg (@themadinventor) as an unofficial community project. Later, it was maintained by Angus Gratton (@projectgus). It is now supported by Espressif Systems.
Esptool is Free Software under a GPLv2 license.

26
docs/en/conf.py Normal file
View File

@@ -0,0 +1,26 @@
# -*- coding: utf-8 -*-
#
# English Language RTD & Sphinx config file
#
# Uses ../conf_common.py for most non-language-specific settings.
# Importing conf_common adds all the non-language-specific
# parts to this conf module
import datetime
try:
from conf_common import * # noqa: F403,F401
except ImportError:
import os
import sys
sys.path.insert(0, os.path.abspath('../'))
from conf_common import * # noqa: F403,F401
# General information about the project.
project = u'esptool'
copyright = u'2016 - {}, Espressif Systems (Shanghai) Co., Ltd'.format(datetime.datetime.now().year)
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
language = 'en'

118
docs/en/contributing.rst Normal file
View File

@@ -0,0 +1,118 @@
Contributions Guide
===================
We welcome contributions to the esptool project!
How to Contribute
-----------------
Contributions to esptool - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via `Github Pull Requests <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.
Development Setup
-----------------
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:
::
pip install --user -e .[dev]
(This command uses the “extras” feature of setuptools.)
Reporting Issues
----------------
Please report bugs in esptool if you find them. However, before reporting a bug please check through the following:
* `Troubleshooting Section`_ - 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 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 <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?
* 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
esptool complies with Flake 8 and is valid Python 2 & Python 3 code
(in the same source file.)
When you submit a Pull Request, the GitHub Actions automated build
system will run automated checks for this, using the `flake8 tool`_. To
check your code locally before submitting, run ``python -m flake8`` (the
flake8 tool is installed as part of the development requirements shown
at the beginning of this document.)
Automated Integration Tests
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The test directory contains an integration suite with some integration
tests for esptool.py:
* ``test_imagegen.py`` tests the elf2image command and is run
automatically by GitHub Actions for each Pull Request. You can run
this command locally to check for regressions in the elf2image
functionality.
* ``test_esptool.py`` is a `Python unittest`_ file that contains
integration tests to be run against real Espressif hardware.
These tests need real hardware so are not run automatically by GitHub
Actions, they need to be run locally in a command line with the following format:
``./test_esptool.py <serial port> <name of chip> <baud rate> [optional test name(s)]``
For example, to run all tests on an ESP32 board connected to
/dev/ttyUSB0, at 230400bps:
``./test_esptool.py /dev/ttyUSB0 esp32 230400``
Or to run the TestFlashing suite only on an ESP8266 board connected to
/dev/ttyUSB2\` at 460800bps:
``./test_esptool.py /dev/ttyUSB2 esp8266 460800 TestFlashing``
(Note that some tests will fail at higher baud rates on some hardware.)
Pull Request Process
--------------------
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.
.. _Troubleshooting Section: https://github.com/espressif/esptool/#troubleshooting
.. _Existing Open Issues: https://github.com/espressif/esptool/issues
.. _open a new issue: https://github.com/espressif/esptool/issues/new
.. _existing issues list: https://github.com/espressif/esptool/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement
.. _flake8 tool: http://flake8.readthedocs.io/en/latest/
.. _Python unittest: https://docs.python.org/3/library/unittest.html

520
docs/en/espefuse/index.rst Normal file
View File

@@ -0,0 +1,520 @@
espefuse.py
===========
``espefuse.py`` is a tool for communicating with an Espressif chip and
reading/writing ("burning") the one-time-programmable efuses values.
.. warning::
**IMPORTANT: Because efuse is one-time-programmable, it is possible to
permanently damage or "brick" your ESP32 using this tool. Use it with
great care.**
For more details about ESP32 efuse features, see the `Technical
Reference
Manual <http://espressif.com/en/support/download/documents>`__.
``espefuse.py`` is installed alongside ``esptool.py``, so if
``esptool.py`` (v2.0 or newer) is available on the PATH then
``espefuse.py`` should be as well.
Display efuse summary
---------------------
::
espefuse.py --port /dev/ttyUSB1 summary
The options ``--port`` and ``--before`` can be supplied, and are
identical to the equivalent ``esptool.py`` options.
Output from the summary command will look like this:
::
espefuse.py v2.6-beta1
Connecting........_____.
EFUSE_NAME Description = [Meaningful Value] [Readable/Writeable] (Hex Value)
----------------------------------------------------------------------------------------
Security fuses:
FLASH_CRYPT_CNT Flash encryption mode counter = 0 R/W (0x0)
FLASH_CRYPT_CONFIG Flash encryption config (key tweak bits) = 0 R/W (0x0)
CONSOLE_DEBUG_DISABLE Disable ROM BASIC interpreter fallback = 1 R/W (0x1)
ABS_DONE_0 secure boot enabled for bootloader = 0 R/W (0x0)
ABS_DONE_1 secure boot abstract 1 locked = 0 R/W (0x0)
JTAG_DISABLE Disable JTAG = 0 R/W (0x0)
DISABLE_DL_ENCRYPT Disable flash encryption in UART bootloader = 0 R/W (0x0)
DISABLE_DL_DECRYPT Disable flash decryption in UART bootloader = 0 R/W (0x0)
DISABLE_DL_CACHE Disable flash cache in UART bootloader = 0 R/W (0x0)
BLK1 Flash encryption key
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
BLK2 Secure boot key
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
BLK3 Variable Block 3
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
Efuse fuses:
WR_DIS Efuse write disable mask = 0 R/W (0x0)
RD_DIS Efuse read disablemask = 0 R/W (0x0)
CODING_SCHEME Efuse variable block length scheme = 0 R/W (0x0)
KEY_STATUS Usage of efuse block 3 (reserved) = 0 R/W (0x0)
Config fuses:
XPD_SDIO_FORCE Ignore MTDI pin (GPIO12) for VDD_SDIO on reset = 0 R/W (0x0)
XPD_SDIO_REG If XPD_SDIO_FORCE, enable VDD_SDIO reg on reset = 0 R/W (0x0)
XPD_SDIO_TIEH If XPD_SDIO_FORCE & XPD_SDIO_REG, 1=3.3V 0=1.8V = 0 R/W (0x0)
SPI_PAD_CONFIG_CLK Override SD_CLK pad (GPIO6/SPICLK) = 0 R/W (0x0)
SPI_PAD_CONFIG_Q Override SD_DATA_0 pad (GPIO7/SPIQ) = 0 R/W (0x0)
SPI_PAD_CONFIG_D Override SD_DATA_1 pad (GPIO8/SPID) = 0 R/W (0x0)
SPI_PAD_CONFIG_HD Override SD_DATA_2 pad (GPIO9/SPIHD) = 0 R/W (0x0)
SPI_PAD_CONFIG_CS0 Override SD_CMD pad (GPIO11/SPICS0) = 0 R/W (0x0)
DISABLE_SDIO_HOST Disable SDIO host = 0 R/W (0x0)
Identity fuses:
MAC MAC Address
= 30:ae:a4:c3:86:94 (CRC 99 OK) R/W
CHIP_VER_REV1 Silicon Revision 1 = 1 R/W (0x1)
CHIP_VERSION Reserved for future chip versions = 2 R/W (0x2)
CHIP_PACKAGE Chip package identifier = 1 R/W (0x1)
Calibration fuses:
BLK3_PART_RESERVE BLOCK3 partially served for ADC calibration data = 0 R/W (0x0)
ADC_VREF Voltage reference calibration = 1093 R/W (0x11)
Flash voltage (VDD_SDIO) determined by GPIO12 on reset (High for 1.8V, Low/NC for 3.3V).
On relatively new chip, most efuses are unburned (value 0).
In espefuse.py v2.6 and newer, read-protected efuse values are displayed
as question marks (??). On earlier versions, they are displayed as
zeroes.
For details on the meaning of each efuse value, refer to the Technical
Reference Manual.
Dump raw efuse registers
------------------------
To display raw efuse register values, use the ``dump`` subcommand:
::
espefuse.py --port /dev/ttyUSB1 dump
espefuse.py v2.0-dev
Connecting....
EFUSE block 0:
00000000 c40042xx xxxxxxxx 00000000 00000033 00000000 00000000
EFUSE block 1:
00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
EFUSE block 2:
00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
EFUSE block 3:
00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
Output corresponds directly to efuse register values in the `register
space <https://github.com/espressif/esp-idf/blob/master/components/soc/esp32/include/soc/efuse_reg.h#L19>`__.
Burning an efuse
----------------
**This command can brick your ESP32**
To burn an efuse to a new value, use the ``burn_efuse`` command:
::
espefuse.py --port /dev/DONOTDOTHIS burn_efuse JTAG_DISABLE 1
The arguments to ``burn_efuse`` are the name of the efuse (as shown in
summary output) and the new value.
New values can be a numeric value in decimal or hex (with 0x prefix).
Efuse bits can only be burned from to 0 to 1, attempting to set any back
to 0 will have no effect. Most efuses have a limited bit width (many are
only 1-bit flags).
Longer efuses (MAC addresses, keys) cannot be set via this command.
By default, ``espefuse.py`` will ask you to type BURN before it
permanently sets an efuse. The ``--do-not-confirm`` option allows you to
bypass this.
Setting Flash Voltage (VDD\_SDIO)
---------------------------------
After reset, the default ESP32 behaviour is to enable and configure the
flash voltage regulator (VDD\_SDIO) based on the level of the MTDI pin
(GPIO12).
The default behaviour on reset is:
+----------------------+--------------------------------+
| MTDI (GPIO12) Pin | VDD\_SDIO Internal Regulator |
+======================+================================+
| Low or unconnected | Enabled at 3.3V |
+----------------------+--------------------------------+
| High | Enabled at 1.8V |
+----------------------+--------------------------------+
Consult ESP32 Technical Reference Manual chapter 4.8.1 "VDD\_SDIO Power
Domain" for details.
A combination of 3 efuses (``XPD_SDIO_FORCE``, ``XPD_SDIO_REG``,
``XPD_SDIO_TIEH``) can be burned in order to override this behaviour and
disable VDD\_SDIO regulator, or set it to a fixed voltage. These efuses
can be burned with individual ``burn_efuse`` commands, but the
``set_flash_voltage`` command makes it easier:
Disable VDD\_SDIO regulator
^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
espefuse.py set_flash_voltage OFF
Once set: \* VDD\_SDIO regulator always disabled. \* MTDI pin (GPIO12)
is ignored. \* Flash must be powered externally and voltage supplied to
VDD\_SDIO pin of ESP32. \* Efuse ``XPD_SDIO_FORCE`` is burned.
Fixed 1.8V VDD\_SDIO
^^^^^^^^^^^^^^^^^^^^
::
espefuse.py set_flash_voltage 1.8V
Once set: \* VDD\_SDIO regulator always enables at 1.8V. \* MTDI pin
(GPIO12) is ignored. \* External voltage should not be supplied to
VDD\_SDIO. \* Efuses ``XPD_SDIO_FORCE`` and ``XPD_SDIO_REG`` are burned.
Fixed 3.3V VDD\_SDIO
^^^^^^^^^^^^^^^^^^^^
::
espefuse.py set_flash_voltage 3.3V
Once set: \* VDD\_SDIO regulator always enables at 3.3V. \* MTDI pin
(GPIO12) is ignored. \* External voltage should not be supplied to
VDD\_SDIO. \* Efuses ``XPD_SDIO_FORCE``, ``XPD_SDIO_REG``,
``XPD_SDIO_TIEH`` are burned.
Subsequent changes
^^^^^^^^^^^^^^^^^^
Once an efuse is burned it cannot be un-burned. However, changes can be
made by burning additional efuses:
- ``set_flash_voltage OFF`` can be changed to ``1.8V`` or ``3.3V``.
- ``set_flash_voltage 1.8V`` can be changed to ``3.3V``
Burning a key
-------------
**This command can brick your ESP32**
The efuse key blocks BLK1, BLK2 and BLK3 can all hold encryption keys.
The ``burn_key`` subcommand loads a key (stored as a raw binary file)
and burns it to a key block.
"flash\_encryption" can be used as an alias for BLK1, and "secure\_boot"
can be used as an alias for BLK2.
- The ``burn_key`` command should only be used for hardware flash
encryption or secure boot keys. See `Burning non-key
data <#burning-non-key-data>`__ for a command that works for data
read by software.
Key Coding Scheme
^^^^^^^^^^^^^^^^^
When the "None" coding scheme is in use, keys are 256-bits (32 bytes)
long. When 3/4 Coding Scheme is in use (``CODING_SCHEME`` efuse has
value 1 not 0), keys are 192-bits (24 bytes) long and an additional 64
bits of error correction data are also written. espefuse.py v2.6 or
newer is required to burn keys with 3/4 Coding Scheme. The key file must
be the appropriate length for the coding scheme currently in use.
When keys are stored in ESP32 Efuse blocks, they are stored in reverse
byte order (last byte of the key is written to the first byte of efuse,
etc.)
Unprotected Keys
^^^^^^^^^^^^^^^^
By default, when an encryption key block is burned it is also read and
write protected. The ``--no-protect-key`` option will disable this
behaviour (you can separately read- or write-protect the key later.)
Note that leaving a key unprotected may compromise its use as a security
feature.
::
espefuse.py --port /dev/DONOTDOTHIS burn_key secure_boot keyfile.bin
Note that the hardware flash encryption and secure boot features require
the key to be written to the efuse block in reversed byte order,
compared to the order used by the AES algorithm on the host.
``burn_key`` automatically reverses the bytes when writing. For this
reason, an unprotected key will read back in the reverse order to the
``keyfile.bin`` on the host.
force-write-always
^^^^^^^^^^^^^^^^^^
Normally, a key will only be burned if the efuse block has not been
previously written to. The ``--force-write-always`` option can be used
to ignore this and try to burn the key anyhow. Note that this option is
still limited by the efuse hardware - hardware doesn't allow any efuse
bits to be cleared 1->0, and can't write anything to write protected
efuse blocks.
Confirmation
^^^^^^^^^^^^
The ``--do-not-confirm`` option can be used with ``burn_key``, otherwise
a manual confirmation step is required.
Limitations of the burn\_key command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``burn_key`` command is only suitable for flash encryption and
secure boot keys:
- Complete block is always written. (This means 256-bits for "None"
coding Scheme or 192-bits for 3/4 Coding Scheme).
- The data is written in reverse byte order for compatibility with
encryption hardware (see `above <#unprotected-keys>`__).
- By default, the data is read- and write-protected so it can only be
used by hardware.
Burning non-key data
--------------------
The ``burn_block_data`` command allows writing arbitrary data from a
file into an efuse block, for software use.
This command is available in espefuse.py v2.6 and newer.
Example
^^^^^^^
Write to Efuse BLK3 from binary file ``device_id.bin``, starting at
efuse byte offset 6:
::
espefuse.py -p PORT burn_block_data --offset 6 BLK3 device_id.bin
- Data is written to the Efuse block in normal byte order (treating the
Efuse block as if it was an array of bytes). It can be read back in
firmware from the efuse read registers, but these reads must be
always be complete register words (4-byte aligned).
- Part of the Efuse block can be written at a time. The ``--offset``
argument allows writing to a byte offset inside the Efuse block
itself.
- This command is not suitable for writing key data which will be used
by flash encryption or secure boot hardware. Use
`burn\_key <#burning-a-key>`__ for this.
burn\_block\_data restrictions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For "None" Coding Scheme, there are no restrictions on the range of
bytes which can be written in the Efuse block (but any bit in efuse can
only be set 0->1, never cleared 1->0).
For "3/4" Coding Scheme, the length of the data file and the offset must
both be a multiple of 6 bytes. Each 6 byte span can only be written one
time.
SPI flash pins
--------------
The following efuses configure the SPI flash pins which are used to
boot:
::
SPI_PAD_CONFIG_CLK Override SD_CLK pad (GPIO6/SPICLK) = 0 R/W (0x0)
SPI_PAD_CONFIG_Q Override SD_DATA_0 pad (GPIO7/SPIQ) = 0 R/W (0x0)
SPI_PAD_CONFIG_D Override SD_DATA_1 pad (GPIO8/SPID) = 0 R/W (0x0)
SPI_PAD_CONFIG_HD Override SD_DATA_2 pad (GPIO9/SPIHD) = 0 R/W (0x0)
SPI_PAD_CONFIG_CS0 Override SD_CMD pad (GPIO11/SPICS0) = 0 R/W (0x0)
On ESP32 chips without integrated SPI flash, these efuses are set to
zero in the factory. This causes the default GPIO pins (shown in the
summary output above) to be used for the SPI flash.
On ESP32 chips with integrated internal SPI flash, these efuses are
burned in the factory to the GPIO numbers where the flash is connected.
These values override the defaults on boot.
In order to change the SPI flash pin configuration, these efuses can be
burned to the GPIO numbers where the flash is connected. If at least one
of these efuses is burned, all of of them must be set to the correct
values.
If these efuses are burned, GPIO1 (U0TXD pin) is no longer consulted to
set the boot mode from SPI to HSPI flash on reset.
These pins can be set to any GPIO number in the range 0-29, 32 or 33.
Values 30 and 31 cannot be set. The "raw" hex value for pins 32,33 is
30,31 (this is visible in the summary output if these pins are
configured for any SPI I/Os.)
ie:
::
SPI_PAD_CONFIG_CS0 Override SD_CMD pad (GPIO11/SPICS0) = 32 R/W (0x1e)
If using the ``burn_efuse`` command to configure these pins, always
specify the actual GPIO number you wish to set.
Read- and Write- protecting efuses
----------------------------------
**This command can severely limit your ESP32 options**
Some efuses can be read- or write-protected, preventing further changes.
``burn_key`` subcommand read and write protects new keys by default, but
other efuses can be protected iwth the ``read_protect_efuse`` and
``write_protect_efuse`` commands.
The ``R/W`` output in the summary display will change to indicate
protected efuses: \* ``-/W`` indicates read protected (value will always
show all-zeroes, even though hardware may use the correct value.) \*
``R/-`` shows write protected (no further bits can be set), \* ``-/-``
means read and write protected.
Sample:
::
espefuse.py --port /dev/SOMEPORT read_protect_efuse KEY_STATUS
The ``--do-not-confirm`` option can be used with ``burn_key``, otherwise
a manual confirmation step is required.
**NOTE that efuses are often read/write protected as a group, so
protecting one will cause some related efuses to become protected.
espefuse.py will confirm the full list of efuses that will become
protected.**
The following efuses can be read protected:
* FLASH\_CRYPT\_CONFIG
* CODING\_SCHEME
* KEY\_STATUS
* BLK1
* BLK2
* BLK3
The following efuses can be write protected:
* WR\_DIS,RD\_DIS
* FLASH\_CRYPT\_CNT
* MAC
* XPD\_SDIO\_FORCE
* XPD\_SDIO\_REG
* XPD\_SDIO\_TIEH
* SPI\_PAD\_CONFIG\_CLK
* SPI\_PAD\_CONFIG\_Q
* SPI\_PAD\_CONFIG\_D
* SPI\_PAD\_CONFIG\_HD
* SPI\_PAD\_CONFIG\_CS0
* FLASH\_CRYPT\_CONFIG
* CODING\_SCHEME
* CONSOLE\_DEBUG\_DISABLE
* DISABLE\_SDIO\_HOST
* ABS\_DONE\_0
* ABS\_DONE\_1
* JTAG\_DISABLE
* DISABLE\_DL\_ENCRYPT
* DISABLE\_DL\_DECRYPT
* DISABLE\_DL\_CACHE
* KEY\_STATUS
* BLK1
* BLK2
* BLK3
Execute eFuse python script
---------------------------
::
espefuse.py execute_scripts efuse_script1.py efuse_script2.py ...
This command allows burning all needed eFuses at one time based on your
own python script and control issues during the burn process if so it
will abort the burn process. This command has a few arguments:
- ``scripts`` is a list of scripts. The special format of python
scripts can be executed inside espefuse.py.
Below you can see some examples of the script. This script file is run
from espefuse.py as ``exec(open(file.name).read())`` it means that some
functions and imported libs are available for using like ``os``. Please
use only provided functions. If you want to use other libs in the script
you can add them manually.
Inside this script, you can call all commands which are available in
CLI, see ``espefuse.py --help``. To run a efuse command you need to call
``espefuse(esp, efuses, args, 'burn_efuse DISABLE_DL_DECRYPT 1')``. This
command will not burn eFuses immediately, the burn occurs at the end of
all scripts. But if necessary, you can call ``efuses.burn_all()`` which
asks you ``Type 'BURN' (all capitals) to continue.``. To skip this
question and go without confirmation just add the ``--do-not-confirm``
flag to the ``execute_scripts`` command.
::
espefuse.py execute_scripts efuse_script1.py --do-not-confirm
Additionally, you can implement some checks based on the value of
eFuses. To get value of a eFuse use -
``efuses['FLASH_CRYPT_CNT'].get()``. Some eFuses have a dictionary to
convert from a value to a human-readable as it looks in the table is
printed by the ``summary`` command. See how it is done for
``CODING_SCHEME`` it calls ``get_meaning()`` 0: "NONE (BLK1-3 len=256
bits)", 1: "3/4 (BLK1-3 len=192 bits)", 2: "REPEAT (BLK1-3 len=128 bits)
not supported", 3: "NONE (BLK1-3 len=256 bits)".
.. code:: python
print("connected chip: %s, coding scheme %s" % (esp.get_chip_description(), efuses["CODING_SCHEME"].get_meaning()))
if os.path.exists("flash_encryption_key.bin"):
espefuse(esp, efuses, args, "burn_key flash_encryption flash_encryption_key.bin")
else:
raise esptool.FatalError("The 'flash_encryption_key.bin' file is missing in the project directory")
espefuse(esp, efuses, args, 'burn_efuse FLASH_CRYPT_CNT 0x7')
current_flash_crypt_cnt = efuses['FLASH_CRYPT_CNT'].get()
if current_flash_crypt_cnt in [0, 3]:
espefuse(esp, efuses, args, 'burn_efuse FLASH_CRYPT_CNT')
espefuse(esp, efuses, args, 'burn_efuse DISABLE_DL_ENCRYPT 1')
espefuse(esp, efuses, args, 'burn_efuse DISABLE_DL_DECRYPT 1')
espefuse(esp, efuses, args, 'burn_efuse DISABLE_DL_CACHE 1')
espefuse(esp, efuses, args, 'burn_efuse JTAG_DISABLE 1')
...
After ``efuses.burn_all()``, all needed eFuses will be burnt to chip in
order BLK\_MAX to BLK\_0. This order prevents cases when protection is
set before the value goes to a block. Please note this while developing
your scripts. Upon completion, the new eFuses will be read back, and
will be done some checks of written eFuses by espefuse.py. In
production, you might need to check that all written eFuses are set
properly, see the example below to get how to check it.
The script below burns some eFuses and checks them after reading back.
To check read and write protection using ``is_readable()`` and
``is_writeable()``.
See
`test\_efuse\_script.py <https://github.com/espressif/esptool/blob/master/test/efuse_scripts/esp32xx/test_efuse_script.py>`__

11
docs/en/espsecure/index.rst Normal file
View File

@@ -0,0 +1,11 @@
espsecure.py
============
``espsecure.py`` is a tool for manipulating data that relates to the
ESP32' secure boot and flash encryption features.
For more details, see the ESP-IDF documentation which explains this tool
and how to use it to enable the relevant ESP32 features:
* `Secure Boot <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v2.html>`__
* `Flash Encryption <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html>`__

20
docs/en/index.rst Normal file
View File

@@ -0,0 +1,20 @@
Esptool Documentation
=========================
This is the documentation for esptool - a Python-based, open source, platform independent, utility to communicate with the ROM bootloader in Espressif `ESP8266, ESP32, ESP32-S and ESP32-C Series SoCs <https://www.espressif.com/en/products/hardware/socs>`_.
.. warning::
Documentation is currently under construction.
.. toctree::
:hidden:
Installation <installation>
Usage <usage>
Espefuse <espefuse/index>
Espsecure <espsecure/index>
Troubleshooting <troubleshooting>
Contribute <contributing>
About <about>

58
docs/en/installation.rst Normal file
View File

@@ -0,0 +1,58 @@
Installation / dependencies
===========================
Easy Installation
-----------------
You will need `either Python 2.7 or Python 3.4 or newer`_ installed on
your system.
The latest stable esptool.py release can be installed from `pypi`_ via
pip:
::
$ pip install esptool
With some Python installations this may not work and you’ll receive an
error, try ``python -m pip install esptool`` or
``pip2 install esptool``, or consult your `Python installation manual`_
for information about how to access pip.
`Setuptools`_ is also a requirement which is not available on all
systems by default. You can install it by a package manager of your
operating system, or by ``pip install setuptools``.
After installing, you will have ``esptool.py`` installed into the
default Python executables directory and you should be able to run it
with the command ``esptool.py`` or ``python -m esptool``. Please note
that probably only ``python -m esptool`` will work for Pythons installed
from Windows Store.
Development Mode Installation
-----------------------------
Development mode allows you to run the latest development version from
this repository.
.. code:: sh
$ git clone https://github.com/espressif/esptool.git
$ cd esptool
$ pip install --user -e .
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.
It’s also possible to run the scripts directly from the working
directory with this Development Mode installation.
(Note: if you actually plan to do development work with esptool itself,
see the CONTRIBUTING.md file.)
.. _either Python 2.7 or Python 3.4 or newer: https://www.python.org/downloads/
.. _pypi: http://pypi.python.org/pypi/esptool
.. _Python installation manual: https://pip.pypa.io/en/stable/installing/
.. _Setuptools: https://setuptools.readthedocs.io/en/latest/userguide/quickstart.html

142
docs/en/troubleshooting.rst Normal file
View File

@@ -0,0 +1,142 @@
Troubleshooting
===============
Flashing problems can be fiddly to troubleshoot. Try the suggestions
here if you're having problems:
Bootloader won't respond
------------------------
If you see errors like "Failed to connect" then your chip is probably
not entering the bootloader properly:
- Check you are passing the correct serial port on the command line.
- Check you have permissions to access the serial port, and other
software (such as modem-manager on Linux) is not trying to interact
with it. A common pitfall is leaving a serial terminal accessing this
port open in another window and forgetting about it.
- Check the chip is receiving 3.3V from a stable power source (see
`Insufficient Power`_ for more details.)
- Check that all pins are connected as described in `Entering the
bootloader`_. Check the voltages at each pin with a multimeter,
"high" pins should be close to 3.3V and "low" pins should be close to
0V.
- If you have connected other devices to GPIO pins mentioned above
section, try removing them and see if esptool.py starts working.
- Try using a slower baud rate (``-b 9600`` is a very slow value that
you can use to verify it's not a baud rate problem.)
write_flash operation fails part way through
--------------------------------------------
If flashing fails with random errors part way through, retry with a
lower baud rate.
Power stability problems may also cause this (see `Insufficient
Power`_.)
write_flash succeeds but program doesn't run
--------------------------------------------
If esptool.py can flash your module with ``write_flash`` but your
program doesn't run, try the following:
Wrong Flash Mode
^^^^^^^^^^^^^^^^
Some devices only support the ``dio`` flash mode. Writing to flash with
``qio`` mode will succeed but the chip can't read the flash back to run
- so nothing happens on boot. Try passing the ``-fm dio`` option to
write_flash.
See the `SPI Flash Modes`_ wiki page for a full description of the flash
modes and how to determine which ones are supported on your device.
Insufficient Power
^^^^^^^^^^^^^^^^^^
The 3.3V power supply for the ESP8266 and ESP32 has to supply large
amounts of current (up to 70mA continuous, 200-300mA peak, slightly
higher for ESP32). You also need sufficient capacitance on the power
circuit to meet large spikes of power demand.
Insufficient Capacitance
''''''''''''''''''''''''
If you're using a pre-made development board or module then the built-in
power regulator & capacitors are usually good enough, provided the input
power supply is adequate.
*This is not true for some very simple pin breakout modules -*\ `similar
to this`_\ *. These breakouts do not integrate enough capacitance to
work reliably without additional components.*. Surface mount OEM modules
like ESP-WROOM02 and ESP-WROOM32 require an external bulk capacitor on
the PCB to be reliable, consult the module datasheet.
Power Supply Rating
'''''''''''''''''''
It is possible to have a power supply that supplies enough current for
the serial bootloader stage with esptool.py, but not enough for normal
firmware operation. You may see the 3.3V VCC voltage droop down if you
measure it with a multimeter, but you can have problems even if this
isn't happening.
Try swapping in a 3.3V supply with a higher current rating, add
capacitors to the power line, and/or shorten any 3.3V power wires.
The 3.3V output from FTDI FT232R chips/adapters or Arduino boards *do
not* supply sufficient current to power an ESP8266 or ESP32 (it may seem
to work sometimes, but it won't work reliably). Other USB TTL/serial
adapters may also be marginal.
Missing bootloader
^^^^^^^^^^^^^^^^^^
Recent ESP8266 SDKs and the ESP32 ESP-IDF both use a small firmware
bootloader program. The hardware bootloader in ROM loads this firmware
bootloader from flash, and then it runs the program. On ESP8266.
firmware bootloader image (with a filename like ``boot_v1.x.bin``) has
to be flashed at offset 0. If the firmware bootloader is missing then
the ESP8266 will not boot. On ESP32, the bootloader image should be
flashed by ESP-IDF at offset 0x1000.
Refer to SDK or ESP-IDF documentation for details regarding which
binaries need to be flashed at which offsets.
SPI Pins which must be disconnected
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Compared to the ROM bootloader that esptool.py talks to, a running
firmware uses more of the chip's pins to access the SPI flash.
If you set "Quad I/O" mode (``-fm qio``, the esptool.py default) then
GPIOs 7, 8, 9 & 10 are used for reading the SPI flash and must be
otherwise disconnected.
If you set "Dual I/O" mode (``-fm dio``) then GPIOs 7 & 8 are used for
reading the SPI flash and must be otherwise disconnected.
Try disconnecting anything from those pins (and/or swap to Dual I/O mode
if you were previously using Quad I/O mode but want to attach things to
GPIOs 9 & 10). Note that if GPIOs 9 & 10 are also connected to input
pins on the SPI flash chip, they may still be unsuitable for use as
general purpose I/O.
In addition to these pins, GPIOs 6 & 11 are also used to access the SPI
flash (in all modes). However flashing will usually fail completely if
these pins are connected incorrectly.
Early stage crash
-----------------
Use a `serial terminal program`_ to view the boot log. (ESP8266 baud
rate is 74880bps, ESP32 is 115200bps). See if the program is crashing
during early startup or outputting an error message.
.. _serial terminal program: #serial-terminal-programs
.. _Insufficient Power: #insufficient-power
.. _Entering the bootloader: #entering-the-bootloader
.. _SPI Flash Modes: https://github.com/espressif/esptool/wiki/SPI-Flash-Modes
.. _similar to this: https://user-images.githubusercontent.com/205573/30140831-9da417a6-93ba-11e7-95c3-f422744967de.jpg

561
docs/en/usage.rst Normal file
View File

@@ -0,0 +1,561 @@
Usage
=====
Use ``esptool.py -h`` to see a summary of all available commands and
command line options.
To see all options for a particular command, append ``-h`` to the
command name. ie ``esptool.py write_flash -h``.
Common Options
--------------
Serial Port
~~~~~~~~~~~
* The serial port is selected using the ``-p`` option, like
``-p /dev/ttyUSB0`` (Linux and macOS) or ``-p COM1`` (Windows).
* A default serial port can be specified by setting the
``ESPTOOL_PORT`` environment variable.
* If no ``-p`` option or ``ESPTOOL_PORT`` value is specified,
``esptool.py`` will enumerate all connected serial ports and try each
one until it finds an Espressif device connected (new behaviour in
v2.4.0).
Note: Windows and macOS may require drivers to be installed for a
particular USB/serial adapter, before a serial port is available.
Consult the documentation for your particular device. On macOS, you can
also consult `System
Information <https://support.apple.com/en-us/HT203001>`__'s list of USB
devices to identify the manufacturer or device ID when the adapter is
plugged in. On Windows, you can use `Windows Update or Device
Manager <https://support.microsoft.com/en-us/help/15048/windows-7-update-driver-hardware-not-working-properly>`__
to find a driver.
If using Cygwin or WSL on Windows, you have to convert the Windows-style
name into a Unix-style path (``COM1`` -> ``/dev/ttyS0``, and so on).
(This is not necessary if using ESP-IDF for ESP32 with the supplied
Windows MSYS2 environment, this environment uses a native Windows Python
which accepts COM ports as-is.)
In Linux, the current user may not have access to serial ports and a
"Permission Denied" error will appear. On most Linux distributions, the
solution is to add the user to the ``dialout`` group with a command like
``sudo usermod -a -G dialout <USERNAME>``. Check your Linux
distribution's documentation for more information.
Baud rate
~~~~~~~~~
The default esptool.py baud rate is 115200bps. Different rates may be
set using ``-b 921600`` (or another baud rate of your choice). A default
baud rate can also be specified using the ``ESPTOOL_BAUD`` environment
variable. This can speed up ``write_flash`` and ``read_flash``
operations.
The baud rate is limited to 115200 when esptool.py establishes the
initial connection, higher speeds are only used for data transfers.
Most hardware configurations will work with ``-b 230400``, some with
``-b 460800``, ``-b 921600`` and/or ``-b 1500000`` or higher.
If you have connectivity problems then you can also set baud rates below
115200. You can also choose 74880, which is the usual baud rate used by
the ESP8266 to output `boot
log <https://github.com/espressif/esptool/wiki/ESP8266-Boot-ROM-Log>`__
information.
Commands
--------
Write binary data to flash: write\_flash
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Binary data can be written to the ESP's flash chip via the serial
``write_flash`` command:
::
esptool.py --port COM4 write_flash 0x1000 my_app-0x01000.bin
Multiple flash addresses and file names can be given on the same command
line:
::
esptool.py --port COM4 write_flash 0x00000 my_app.elf-0x00000.bin 0x40000 my_app.elf-0x40000.bin
The ``--chip`` argument is optional when writing to flash, esptool will
detect the type of chip when it connects to the serial port.
The ``--port`` argument is documented under `Serial
Port <#serial-port>`__.
The next arguments to write\_flash are one or more pairs of offset
(address) and file name. When generating ESP8266 "version 1" images, the
file names created by ``elf2image`` include the flash offsets as part of
the file name. For other types of images, consult your SDK documentation
to determine the files to flash at which offsets.
Numeric values passed to write\_flash (and other commands) can be
specified either in hex (ie 0x1000), or in decimal (ie 4096).
See the `Troubleshooting <#troubleshooting>`__ section if the
write\_flash command is failing, or the flashed module fails to boot.
Setting flash mode and size
^^^^^^^^^^^^^^^^^^^^^^^^^^^
You may also need to specify arguments for `flash mode and flash
size <#flash-modes>`__, if you wish to override the defaults. For
example:
::
esptool.py --port /dev/ttyUSB0 write_flash --flash_mode qio --flash_size 32m 0x0 bootloader.bin 0x1000 my_app.bin
Since esptool v2.0, these options are not often needed as the default is
to keep the flash mode and size from the ``.bin`` image file. See the
`Flash Modes <#flash-modes>`__ section for more details.
Compression
^^^^^^^^^^^
By default, the serial transfer data is compressed for better
performance. The ``-u/--no-compress`` option disables this behaviour.
Erasing flash before write
^^^^^^^^^^^^^^^^^^^^^^^^^^
To successfully write data into flash, all 4096-byte memory sectors (the
smallest erasable unit) affected by the operation have to be erased
first. As a result, when the flashing offset address or the data are not
4096-byte aligned, more memory is erased than actually needed. Esptool
will display information about which flash memory sectors will be
erased.
Use the ``-e/--erase-all`` option to erase all flash sectors (not just
write areas) before programming.
Read Flash Contents: read\_flash
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The read\_flash command allows reading back the contents of flash. The
arguments to the command are an address, a size, and a filename to dump
the output to. For example, to read a full 2MB of attached flash:
::
esptool.py -p PORT -b 460800 read_flash 0 0x200000 flash_contents.bin
(Note that if ``write_flash`` updated the boot image's `flash mode and
flash size <#flash-modes>`__ during flashing then these bytes may be
different when read back.)
Erase Flash: erase\_flash & erase region
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To erase the entire flash chip (all data replaced with 0xFF bytes):
::
esptool.py erase_flash
To erase a region of the flash, starting at address 0x20000 with length
0x4000 bytes (16KB):
::
esptool.py erase_region 0x20000 0x4000
The address and length must both be multiples of the SPI flash erase
sector size. This is 0x1000 (4096) bytes for supported flash chips.
Read built-in MAC address: read\_mac
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
esptool.py read_mac
Read SPI flash id: flash\_id
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
esptool.py flash_id
Example output:
::
Manufacturer: e0
Device: 4016
Detected flash size: 4MB
Refer to `flashrom source
code <https://review.coreboot.org/plugins/gitiles/flashrom/+/refs/heads/master/flashchips.h>`__
for flash chip manufacturer name and part number.
Convert ELF to Binary: elf2image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``elf2image`` command converts an ELF file (from compiler/linker
output) into the binary executable images which can be flashed and then
booted into:
::
esptool.py --chip esp8266 elf2image my_app.elf
This command does not require a serial connection.
``elf2image`` also accepts the `Flash Modes <#flash-modes>`__ arguments
``--flash_freq`` and ``--flash_mode``, which can be used to set the
default values in the image header. This is important when generating
any image which will be booted directly by the chip. These values can
also be overwritten via the ``write_flash`` command, see the
`write\_flash command <#write-binary-data-to-flash-write_flash>`__ for
details.
By default, ``elf2image`` uses the sections in the ELF file to generate
each segment in the binary executable. To use segments (PHDRs) instead,
pass the ``--use_segments`` option.
elf2image for ESP8266
^^^^^^^^^^^^^^^^^^^^^
The default command output is two binary files:
``my_app.elf-0x00000.bin`` and ``my_app.elf-0x40000.bin``. You can alter
the firmware file name prefix using the ``--output/-o`` option.
``elf2image`` can also produce a "version 2" image file suitable for use
with a software bootloader stub such as
`rboot <https://github.com/raburton/rboot>`__ or the Espressif
bootloader program. You can't flash a "version 2" image without also
flashing a suitable bootloader.
::
esptool.py --chip esp8266 elf2image --version=2 -o my_app-ota.bin my_app.elf
elf2image for ESP32
^^^^^^^^^^^^^^^^^^^
For ESP32, elf2image produces a single output binary "image file". By
default this has the same name as the .elf file, with a .bin extension.
ie:
::
esptool.py --chip esp32 elf2image my_esp32_app.elf
In the above example, the output image file would be called
``my_esp32_app.bin``.
Output .bin image details: image\_info
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``image_info`` command outputs some information (load addresses,
sizes, etc) about a ``.bin`` file created by ``elf2image``.
::
esptool.py --chip esp32 image_info my_esp32_app.bin
Note that ``--chip esp32`` is required when reading ESP32 images.
Otherwise the default is ``--chip esp8266`` and the image will be
interpreted as an invalid ESP8266 image.
Advanced Commands
~~~~~~~~~~~~~~~~~
The following commands are less commonly used, or only of interest to
advanced users. They are documented on the wiki:
* `verify\_flash <https://github.com/espressif/esptool/wiki/Advanced-Commands#verify_flash>`__
* `dump\_mem <https://github.com/espressif/esptool/wiki/Advanced-Commands#dump_mem>`__
* `load\_ram <https://github.com/espressif/esptool/wiki/Advanced-Commands#load_ram>`__
* `read\_mem &
write\_mem <https://github.com/espressif/esptool/wiki/Advanced-Commands#read_mem--write_mem>`__
* `read\_flash\_status <https://github.com/espressif/esptool/wiki/Advanced-Commands#read_flash_status>`__
* `write\_flash\_status <https://github.com/espressif/esptool/wiki/Advanced-Commands#write_flash_status>`__
* `chip\_id <https://github.com/espressif/esptool/wiki/Advanced-Commands#chip_id>`__
* `make\_image <https://github.com/espressif/esptool/wiki/Advanced-Commands#make_image>`__
* `run <https://github.com/espressif/esptool/wiki/Advanced-Commands#run>`__
Additional ESP32 Tools
----------------------
The following tools for ESP32, bundled with esptool.py, are documented
on the wiki:
* `espefuse.py - for reading/writing ESP32 efuse
region <https://github.com/espressif/esptool/wiki/espefuse>`__
* `espsecure.py - for working with ESP32 security
features <https://github.com/espressif/esptool/wiki/espsecure>`__
Serial Connections
------------------
The ESP8266 & ESP32 ROM serial bootloader uses a 3.3V UART serial
connection. Many development boards make the serial connections for you
onboard.
However, if you are wiring the chip yourself to a USB/Serial adapter or
similar then the following connections must be made:
+---------------------+-------------------+
| ESP32/ESP8266 Pin | Serial Port Pin |
+=====================+===================+
| TX (aka GPIO1) | RX (receive) |
+---------------------+-------------------+
| RX (aka GPIO3) | TX (transmit) |
+---------------------+-------------------+
| Ground | Ground |
+---------------------+-------------------+
Note that TX (transmit) on the ESP8266 is connected to RX (receive) on
the serial port connection, and vice versa.
Do not connect the chip to 5V TTL serial adapters, and especially not to
"standard" RS-232 adapters! 3.3V serial only!
Entering the Bootloader
-----------------------
Both ESP8266 and ESP32 have to be reset in a certain way in order to
launch the serial bootloader.
On some development boards (including NodeMCU, WeMOS, HUZZAH Feather,
Core Board, ESP32-WROVER-KIT), esptool.py can automatically trigger a
reset into the serial bootloader - in which case you don't need to read
this section.
For everyone else, three things must happen to enter the serial
bootloader - a reset, required pins set correctly, and GPIO0 pulled low:
Boot Mode
~~~~~~~~~
Both ESP8266 and ESP32 choose the boot mode each time they reset. A
reset event can happen in one of several ways:
* Power applied to chip.
* The nRESET pin was low and is pulled high (on ESP8266 only).
* The CH\_PD/EN pin ("enable") pin was low and is pulled high.
On ESP8266, both the nRESET and CH\_PD pins must be pulled high for the
chip to start operating.
For more details on selecting the boot mode, see the following Wiki
pages:
* `ESP8266 Boot Mode
Selection <https://github.com/espressif/esptool/wiki/ESP8266-Boot-Mode-Selection>`__
* `ESP32 Boot Mode
Selection <https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection>`__
Flash Modes
-----------
``write_flash`` and some other commands accept command line arguments to
set bootloader flash mode, flash size and flash clock frequency. The
chip needs correct mode, frequency and size settings in order to run
correctly - although there is some flexibility. A header at the
beginning of a bootable image contains these values.
To override these values, the options ``--flash_mode``, ``--flash_size``
and/or ``--flash_freq`` must appear after ``write_flash`` on the command
line, for example:
::
esptool.py --port /dev/ttyUSB1 write_flash --flash_mode dio --flash_size 4MB 0x0 bootloader.bin
These options are only consulted when flashing a bootable image to an
ESP8266 at offset 0x0, or an ESP32 at offset 0x1000. These are addresses
used by the ROM bootloader to load from flash. When flashing at all
other offsets, these arguments are not used.
Flash Mode (--flash\_mode, -fm)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These set Quad Flash I/O or Dual Flash I/O modes. Valid values are
``keep``, ``qio``, ``qout``, ``dio``, ``dout``. The default is ``keep``,
which keeps whatever value is already in the image file. This parameter
can also be specified using the environment variable ``ESPTOOL_FM``.
Most boards use ``qio`` mode. Some ESP8266 modules, including the
ESP-12E modules on some (not all) NodeMCU boards, are dual I/O and the
firmware will only boot when flashed with ``--flash_mode dio``. Most
ESP32 modules are also dual I/O.
In ``qio`` mode, two additional GPIOs (9 and 10) are used for SPI flash
communications. If flash mode is set to ``dio`` then these pins are
available for other purposes.
For a full explanation of these modes, see the `SPI Flash Modes wiki
page <https://github.com/espressif/esptool/wiki/SPI-Flash-Modes>`__.
Flash Frequency (--flash\_freq, -ff)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Clock frequency for SPI flash interactions. Valid values are ``keep``,
``40m``, ``26m``, ``20m``, ``80m`` (MHz). The default is ``keep``, which
keeps whatever value is already in the image file. This parameter can
also be specified using the environment variable ``ESPTOOL_FF``.
The flash chip connected to most chips works with 40MHz clock speeds,
but you can try lower values if the device won't boot. The highest 80MHz
flash clock speed will give the best performance, but may cause crashing
if the flash or board design is not capable of this speed.
Flash Size (--flash\_size, -fs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Size of the SPI flash, given in megabytes. Valid values vary by chip
type:
+-----------+--------------------------------------------------------------------------------------------------------------------+
| Chip | flash\_size values |
+===========+====================================================================================================================+
| ESP32 | ``keep``, ``detect``, ``1MB``, ``2MB``, ``4MB``, ``8MB``, ``16MB`` |
+-----------+--------------------------------------------------------------------------------------------------------------------+
| ESP8266 | ``keep``, ``detect``, ``256KB``, ``512KB``, ``1MB``, ``2MB``, ``4MB``, ``2MB-c1``, ``4MB-c1``, ``8MB``, ``16MB`` |
+-----------+--------------------------------------------------------------------------------------------------------------------+
For ESP8266, some `additional sizes & layouts for OTA "firmware slots"
are available <#esp8266-and-flash-size>`__.
The default ``--flash_size`` parameter is ``keep``. This means that if
no ``--flash_size`` argument is passed when flashing a bootloader, the
value in the bootloader .bin file header is kept instead of detecting
the actual flash size and updating the header.
To enable automatic flash size detection based on SPI flash ID, add the
argument ``esptool.py [...] write_flash [...] -fs detect``. If detection
fails, a warning is printed and a default value of of ``4MB`` (4
megabytes) is used.
If flash size is not successfully detected, you can find the flash size
by using the ``flash_id`` command and then looking up the ID from the
output (see `Read SPI flash id <#read-spi-flash-id-flash_id>`__).
Alternatively, read off the silkscreen labelling of the flash chip and
search for its datasheet.
The default ``flash_size`` parameter can also be overridden using the
environment variable ``ESPTOOL_FS``.
ESP8266 and Flash Size
^^^^^^^^^^^^^^^^^^^^^^
The ESP8266 SDK stores WiFi configuration at the "end" of flash, and it
finds the end using this size. However there is no downside to
specifying a smaller flash size than you really have, as long as you
don't need to write an image larger than this size.
ESP-12, ESP-12E and ESP-12F modules (and boards that use them such as
NodeMCU, HUZZAH, etc.) usually have at least 4 megabyte / ``4MB``
(sometimes labelled 32 megabit) flash.
If using OTA, some additional sizes & layouts for OTA "firmware slots"
are available. If not using OTA updates then you can ignore these extra
sizes:
+-------------------+-----------------------+-----------------+-----------------+
| flash\_size arg | Number of OTA slots | OTA Slot Size | Non-OTA Space |
+===================+=======================+=================+=================+
| 256KB | 1 (no OTA) | 256KB | N/A |
+-------------------+-----------------------+-----------------+-----------------+
| 512KB | 1 (no OTA) | 512KB | N/A |
+-------------------+-----------------------+-----------------+-----------------+
| 1MB | 2 | 512KB | 0KB |
+-------------------+-----------------------+-----------------+-----------------+
| 2MB | 2 | 512KB | 1024KB |
+-------------------+-----------------------+-----------------+-----------------+
| 4MB | 2 | 512KB | 3072KB |
+-------------------+-----------------------+-----------------+-----------------+
| 2MB-c1 | 2 | 1024KB | 0KB |
+-------------------+-----------------------+-----------------+-----------------+
| 4MB-c1 | 2 | 1024KB | 2048KB |
+-------------------+-----------------------+-----------------+-----------------+
| 8MB [^] | 2 | 1024KB | 6144KB |
+-------------------+-----------------------+-----------------+-----------------+
| 16MB [^] | 2 | 1024KB | 14336KB |
+-------------------+-----------------------+-----------------+-----------------+
- [^] Support for 8MB & 16MB flash size is not present in all ESP8266
SDKs. If your SDK doesn't support these flash sizes, use
``--flash_size 4MB``.
ESP32 and Flash Size
^^^^^^^^^^^^^^^^^^^^
The ESP-IDF flashes a partition table to the flash at offset 0x8000. All
of the partitions in this table must fit inside the configured flash
size, otherwise the ESP32 will not work correctly.
Merging binaries
----------------
The ``merge_bin`` command will merge multiple binary files (of any kind)
into a single file that can be flashed to a device later. Any gaps
between the input files are padded with 0xFF bytes (same as unwritten
flash contents).
For example:
::
esptool.py --chip esp32 merge_bin -o merged-flash.bin --flash_mode dio --flash_size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin
Will create a file ``merged-flash.bin`` with the contents of the other 3
files. This file can be later be written to flash with
``esptool.py write_flash 0x0 merged-flash.bin``.
Note: Because gaps between the input files are padded with 0xFF bytes,
when the merged binary is written then any flash sectors between the
individual files will be erased. To avoid this, write the files
individually.
Options
~~~~~~~
- The ``merge_bin`` command supports the same ``--flash_mode``,
``--flash_size`` and ``--flash_freq`` options as the ``write_flash``
command to override the bootloader flash header (see above for
details). These options are applied to the output file contents in
the same way as when writing to flash. Make sure to pass the
``--chip`` parameter if using these options, as the supported values
and the bootloader offset both depend on the chip.
- The ``--target-offset 0xNNN`` option will create a merged binary that
should be flashed at the specified offset, instead of at offset 0x0.
- The ``--fill-flash-size SIZE`` option will pad the merged binary with
0xFF bytes to the full flash specified size, for example
``--fill-flash-size 4MB`` will create a 4MB binary file.
- It is possible to append options from a text file with ``@filename``.
As an example, this can be conveniently used with the ESP-IDF build
system, which produces a ``flash_args`` file in the build directory
of a project:
.. code:: sh
cd build # The build directory of an ESP-IDF project
esptool.py --chip esp32 merge_bin -o merged-flash.bin @flash_args
Advanced Options
----------------
See the `Advanced Options wiki
page <https://github.com/espressif/esptool/wiki/Advanced-Options>`__ for
some of the more unusual esptool.py command line options.
Remote Serial Ports
-------------------
It is possible to connect to any networked remote serial port that
supports `RFC2217 <http://www.ietf.org/rfc/rfc2217.txt>`__ (Telnet)
protocol, or a plain TCP socket. See the `Remote Serial Ports wiki
page <https://github.com/espressif/esptool/wiki/Remote-Serial-Ports>`__
for details.

2
setup.cfg
View File

@@ -24,3 +24,5 @@ per-file-ignores =
# don't require future imports or check for unused imports in __init__.py files
__init__.py: FI10, FI13, F401
test/sitecustomize.py: FI10, FI13
docs/conf_common.py: FI10, FI13, F405
docs/en/conf.py: FI10, FI13