From f65bf93e9c933f98c3d1f2ba2231c0dba0e0f018 Mon Sep 17 00:00:00 2001 From: "radim.karnis" Date: Mon, 1 Nov 2021 15:14:09 +0100 Subject: [PATCH] docs: Add initial structure for new docs --- .gitignore | 2 + MANIFEST.in | 1 + docs/README.md | 17 + docs/_static/esptool_versions.js | 15 + docs/conf_common.py | 18 + docs/en/about.rst | 6 + docs/en/conf.py | 26 ++ docs/en/contributing.rst | 118 +++++++ docs/en/espefuse/index.rst | 520 ++++++++++++++++++++++++++++ docs/en/espsecure/index.rst | 11 + docs/en/index.rst | 20 ++ docs/en/installation.rst | 58 ++++ docs/en/troubleshooting.rst | 142 ++++++++ docs/en/usage.rst | 561 +++++++++++++++++++++++++++++++ setup.cfg | 2 + 15 files changed, 1517 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/_static/esptool_versions.js create mode 100644 docs/conf_common.py create mode 100644 docs/en/about.rst create mode 100644 docs/en/conf.py create mode 100644 docs/en/contributing.rst create mode 100644 docs/en/espefuse/index.rst create mode 100644 docs/en/espsecure/index.rst create mode 100644 docs/en/index.rst create mode 100644 docs/en/installation.rst create mode 100644 docs/en/troubleshooting.rst create mode 100644 docs/en/usage.rst diff --git a/.gitignore b/.gitignore index 8771071..aeca891 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,5 @@ local.mk .envrc report.xml + +docs/_build/ diff --git a/MANIFEST.in b/MANIFEST.in index bc8c385..69a062d 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -5,6 +5,7 @@ include LICENSE prune test prune flasher_stub prune .github +prune docs exclude .git* exclude MANIFEST* diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..9b507e8 --- /dev/null +++ b/docs/README.md @@ -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 diff --git a/docs/_static/esptool_versions.js b/docs/_static/esptool_versions.js new file mode 100644 index 0000000..7615a76 --- /dev/null +++ b/docs/_static/esptool_versions.js @@ -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" }, + ] +}; diff --git a/docs/conf_common.py b/docs/conf_common.py new file mode 100644 index 0000000..ee944d1 --- /dev/null +++ b/docs/conf_common.py @@ -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' diff --git a/docs/en/about.rst b/docs/en/about.rst new file mode 100644 index 0000000..b1babfd --- /dev/null +++ b/docs/en/about.rst @@ -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. diff --git a/docs/en/conf.py b/docs/en/conf.py new file mode 100644 index 0000000..a585d12 --- /dev/null +++ b/docs/en/conf.py @@ -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' diff --git a/docs/en/contributing.rst b/docs/en/contributing.rst new file mode 100644 index 0000000..3d44b7d --- /dev/null +++ b/docs/en/contributing.rst @@ -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 `_. + +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 `_? + +* 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 [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 diff --git a/docs/en/espefuse/index.rst b/docs/en/espefuse/index.rst new file mode 100644 index 0000000..3853648 --- /dev/null +++ b/docs/en/espefuse/index.rst @@ -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 `__. + +``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 `__. + +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 `__ diff --git a/docs/en/espsecure/index.rst b/docs/en/espsecure/index.rst new file mode 100644 index 0000000..adad76d --- /dev/null +++ b/docs/en/espsecure/index.rst @@ -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 `__ +* `Flash Encryption `__ diff --git a/docs/en/index.rst b/docs/en/index.rst new file mode 100644 index 0000000..175e9e7 --- /dev/null +++ b/docs/en/index.rst @@ -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 `_. + + +.. warning:: + + Documentation is currently under construction. + +.. toctree:: + :hidden: + + Installation + Usage + Espefuse + Espsecure + Troubleshooting + Contribute + About diff --git a/docs/en/installation.rst b/docs/en/installation.rst new file mode 100644 index 0000000..d00941b --- /dev/null +++ b/docs/en/installation.rst @@ -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 \ No newline at end of file diff --git a/docs/en/troubleshooting.rst b/docs/en/troubleshooting.rst new file mode 100644 index 0000000..e24cd2e --- /dev/null +++ b/docs/en/troubleshooting.rst @@ -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 \ No newline at end of file diff --git a/docs/en/usage.rst b/docs/en/usage.rst new file mode 100644 index 0000000..4204433 --- /dev/null +++ b/docs/en/usage.rst @@ -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 `__'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 `__ +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 ``. 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 `__ +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 `__ +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 `__ 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 `__ +* `dump\_mem `__ +* `load\_ram `__ +* `read\_mem & + write\_mem `__ +* `read\_flash\_status `__ +* `write\_flash\_status `__ +* `chip\_id `__ +* `make\_image `__ +* `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 `__ +* `espsecure.py - for working with ESP32 security + features `__ + +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 `__ +* `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 `__. + +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 `__ 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 `__ (Telnet) +protocol, or a plain TCP socket. See the `Remote Serial Ports wiki +page `__ +for details. diff --git a/setup.cfg b/setup.cfg index 27df43c..d60426d 100644 --- a/setup.cfg +++ b/setup.cfg @@ -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