diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index de0ca91ed8..e4ca05f75d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -73,7 +73,7 @@ Code Style & Static Analysis Please follow these coding standards when writing code for ``esptool.py``: -Pre-commit checks +Pre-Commit Checks """"""""""""""""" `pre-commit `_ is a framework for managing pre-commit hooks. These hooks help to identify simple issues before committing code for review. @@ -104,13 +104,13 @@ Ruff When you submit a Pull Request, the GitHub Actions automated build system will run automated checks using these tools. -Shinx-lint -"""""""""" +Sphinx-Lint +""""""""""" The documentation is checked for stylistic and formal issues by ``sphinx-lint``. -Codespell check +Codespell Check """"""""""""""" This repository utilizes an automatic `spell checker `_ integrated into the pre-commit process. If any spelling issues are detected, the recommended corrections will be applied automatically to the file, ready for commit. @@ -143,7 +143,7 @@ The following tests are not run automatically by GitHub Actions, because they ne ``pytest test_esptool.py --port /dev/ttyUSB0 --chip esp32 --baud 230400`` - Or to run the TestFlashing suite only (using the pytest ``-k`` option to select tests based on their name) on an ESP8266 board connected to /dev/ttyUSB2, at 460800bps: + Or to run the ``TestFlashing`` suite only (using the pytest ``-k`` option to select tests based on their name) on an ESP8266 board connected to /dev/ttyUSB2, at 460800bps: ``pytest test_esptool.py --port /dev/ttyUSB2 --chip esp8266 --baud 460800 -k TestFlashing`` @@ -171,9 +171,7 @@ The whole test suite (without the tests needing an actual hardware or installati Pull Request Process -------------------- -.. note:: - - If you are developing the stub flasher and plan to send a pull request, please use the latest toolchains available. +If you would like to contribute to the flasher stub, please see the `Flasher stub repository `_. After you open the Pull Request, there will probably be some discussion in the comments field of the request itself. diff --git a/docs/en/advanced-topics/diag/firmware_image_ext_header_format.diag b/docs/en/advanced-topics/diag/firmware_image_ext_header_format.diag new file mode 100644 index 0000000000..1c3d8c95b4 --- /dev/null +++ b/docs/en/advanced-topics/diag/firmware_image_ext_header_format.diag @@ -0,0 +1,15 @@ +packetdiag command_packet_format{ + colwidth = 16 + node_width = 50 + node_height = 50 + default_fontsize = 16 + + 0: "WP"; + 1-3: "Drive settings"; + 4-5: "Chip ID"; + 6: "Rev." [color = grey]; + 7-8: "Min rev."; + 9-10: "Max rev."; + 11-14: "Reserved" [color = grey]; + 15: "Hash"; +} diff --git a/docs/en/advanced-topics/diag/firmware_image_format.diag b/docs/en/advanced-topics/diag/firmware_image_format.diag new file mode 100644 index 0000000000..7566c37e5f --- /dev/null +++ b/docs/en/advanced-topics/diag/firmware_image_format.diag @@ -0,0 +1,12 @@ +packetdiag command_packet_format{ + colwidth = 16 + node_width = 50 + node_height = 50 + default_fontsize = 16 + + 0-7: "Image header"; + 8-23: "Image extended header"; + 24-31: "Segmets" [color = lightgrey]; + 32-47: "..." [color = lightgrey]; + 48-63: "Footer"; +} diff --git a/docs/en/advanced-topics/diag/firmware_image_format_esp8266.diag b/docs/en/advanced-topics/diag/firmware_image_format_esp8266.diag new file mode 100644 index 0000000000..8b94afbd0c --- /dev/null +++ b/docs/en/advanced-topics/diag/firmware_image_format_esp8266.diag @@ -0,0 +1,11 @@ +packetdiag command_packet_format{ + colwidth = 16 + node_width = 50 + node_height = 50 + default_fontsize = 16 + + 0-7: "Image header"; + 8-23: "Segmets" [color = lightgrey]; + 24-31: "..." [color = lightgrey]; + 32-47: "Footer"; +} diff --git a/docs/en/advanced-topics/diag/firmware_image_header_format.diag b/docs/en/advanced-topics/diag/firmware_image_header_format.diag new file mode 100644 index 0000000000..bc230811f5 --- /dev/null +++ b/docs/en/advanced-topics/diag/firmware_image_header_format.diag @@ -0,0 +1,12 @@ +packetdiag command_packet_format{ + colwidth = 8 + node_width = 100 + node_height = 50 + default_fontsize = 16 + + 0: "0xE9"; + 1: "Number of\nsegments"; + 2: "Flash Mode"; + 3: "Flash\nsize/freq"; + 4-7: "Entry point"; +} diff --git a/docs/en/advanced-topics/firmware-image-format.rst b/docs/en/advanced-topics/firmware-image-format.rst index 04312c17cb..7f7aec54c2 100644 --- a/docs/en/advanced-topics/firmware-image-format.rst +++ b/docs/en/advanced-topics/firmware-image-format.rst @@ -18,15 +18,27 @@ This is technical documentation for the firmware image format used by the ROM bo .. only:: esp8266 + .. packetdiag:: diag/firmware_image_format_esp8266.diag + :caption: Firmware image format + :align: center + The firmware file consists of a header, a variable number of data segments and a footer. Multi-byte fields are little-endian. .. only:: not esp8266 + .. packetdiag:: diag/firmware_image_format.diag + :caption: Firmware image format + :align: center + The firmware file consists of a header, an extended header, a variable number of data segments and a footer. Multi-byte fields are little-endian. File Header ----------- +.. packetdiag:: diag/firmware_image_header_format.diag + :caption: Firmware image header + :align: center + The image header is 8 bytes long: .. only:: esp8266 @@ -128,7 +140,10 @@ The image header is 8 bytes long: +--------+------------------------------------------------------------------------------------------------+ -``esptool.py`` overrides the 2nd and 3rd (counted from 0) bytes according to the SPI flash info provided through the command line option. These bytes are only overridden if this is a bootloader image (an image written to a correct bootloader offset of {IDF_TARGET_BOOTLOADER_OFFSET}), in this case, the appended SHA256 digest is also updated to reflect the header changes. Generating images without SHA256 digest can be achieved by running ``esptool.py elf2image`` with the ``--dont-append-digest`` argument. +``esptool.py`` overrides the 2nd and 3rd (counted from 0) bytes according to the SPI flash info provided through the command line options (see :ref:`flash-modes`). +These bytes are only overridden if this is a bootloader image (an image written to a correct bootloader offset of {IDF_TARGET_BOOTLOADER_OFFSET}). +In this case, the appended SHA256 digest, which is a cryptographic hash used to verify the integrity of the image, is also updated to reflect the header changes. +Generating images without SHA256 digest can be achieved by running ``esptool.py elf2image`` with the ``--dont-append-digest`` argument. .. only:: esp8266 @@ -139,12 +154,14 @@ The image header is 8 bytes long: Extended File Header -------------------- - The 16-byte long extended header comes right after the image header, individual segments come right after it: + .. packetdiag:: diag/firmware_image_ext_header_format.diag + :caption: Extended File Header + :align: center +--------+---------------------------------------------------------------------------------------------------------+ | Byte | Description | +========+=========================================================================================================+ - | 0 | WP pin when SPI pins set via efuse (read by ROM bootloader) | + | 0 | WP pin when SPI pins set via eFuse (read by ROM bootloader) | +--------+---------------------------------------------------------------------------------------------------------+ | 1-3 | Drive settings for the SPI flash pins (read by ROM bootloader) | +--------+---------------------------------------------------------------------------------------------------------+ diff --git a/docs/en/advanced-topics/serial-protocol.rst b/docs/en/advanced-topics/serial-protocol.rst index 48c85eec93..4c69cc3d60 100644 --- a/docs/en/advanced-topics/serial-protocol.rst +++ b/docs/en/advanced-topics/serial-protocol.rst @@ -7,11 +7,7 @@ This is technical documentation for the serial protocol used by the UART bootloa The UART bootloader runs on chip reset if certain strapping pins are set. See :ref:`entering-the-bootloader` for details of this process. -.. only:: not esp8266 - - The {IDF_TARGET_NAME} ROM loader serial protocol is similar to ESP8266, although {IDF_TARGET_NAME} adds some additional commands and some slightly different behaviour. - -By default, esptool uploads a stub "software loader" to the IRAM of the chip. The stub loader then replaces the ROM loader for all future interactions. This standardizes much of the behaviour. Pass ``--no-stub`` to esptool in order to disable the stub loader. See :ref:`stub` for more information. +By default, esptool uploads a stub "software loader" to the IRAM of the chip. The stub loader then replaces the ROM loader for all future interactions. This standardizes much of the behavior. Pass ``--no-stub`` to esptool in order to disable the stub loader. See :ref:`stub` for more information. .. note:: @@ -78,7 +74,7 @@ Each received command will result in a response SLIP packet sent from the ESP ch | 8..n | Data | Variable length data payload. Length indicated by "Size" field. | +--------+-------------+--------------------------------------------------------------------------------------------------------------+ -Status bytes +Status Bytes """""""""""" The final bytes of the Data payload indicate command status: @@ -153,7 +149,7 @@ After sending a command, the host should continue to read response packets until Commands ^^^^^^^^ -Supported by stub loader and ROM loader +Supported by Stub Loader and ROM Loader """"""""""""""""""""""""""""""""""""""" .. only:: esp8266 @@ -259,10 +255,10 @@ Supported by stub loader and ROM loader | ``0x14`` | GET_SECURITY_INFO | Read chip security info | | {IDF_TARGET_SECURITY_INFO} | +------------+----------------------+----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ -Supported by stub loader only +Supported by Stub Loader Only """"""""""""""""""""""""""""" -ROM loaders will not recognise these commands. +ROM loaders will not recognize these commands. +------------+-------------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+ | Byte | Name | Description | Input | Output | @@ -349,7 +345,7 @@ All three of these sequences follow a similar pattern: * An _END command (FLASH_END, etc) is sent to exit the bootloader and optionally reset the chip (or jump to an address in RAM, in the case of MEM_END). Not necessary to send after flashing if you wish to continue sending other or different commands. It's not necessary to send flash erase commands before sending commands to write to flash, etc. The ROM loaders erase the to-be-written region in response to the FLASH_BEGIN command. -The stub loader does just-in-time erasing as it writes data, to maximise overall flashing performance (each block of data is read into RAM via serial while the previous block is simultaneously being written to flash, and 4KB and 64KB erases are done as needed before writing to flash). +The stub loader does just-in-time erasing as it writes data, to maximize overall flashing performance (each block of data is read into RAM via serial while the previous block is simultaneously being written to flash, and 4KB and 64KB erases are done as needed before writing to flash). The block size chosen should be small enough to fit into RAM of the device. Esptool uses 16KB which gives good performance when used with the stub loader. @@ -382,7 +378,7 @@ The SPI_FLASH_MD5 command passes the start address in flash and the size of data SPI Configuration Commands ^^^^^^^^^^^^^^^^^^^^^^^^^^ -SPI Attach command +SPI Attach Command """""""""""""""""" The SPI _ATTACH command enables the SPI flash interface. It takes a 32-bit data payload which is used to determine which SPI peripheral and pins should be used to connect to SPI flash. @@ -413,7 +409,7 @@ The SPI _ATTACH command enables the SPI flash interface. It takes a 32-bit data | (other values) | Pin numbers as 6-bit values, packed into a 30-bit value. Order (from MSB): HD pin, Q pin, D pin, CS pin, CLK pin. | +------------------+----------------------------------------------------------------------------------------------------------------------------------+ - The "Default SPI flash interface" uses pins configured via the ``SPI_PAD_CONFIG_xxx`` efuses (if unset, these efuses are all zero and the default SPI flash pins given in the datasheet are used.) + The "Default SPI flash interface" uses pins configured via the ``SPI_PAD_CONFIG_xxx`` eFuses (if unset, these eFuses are all zero and the default SPI flash pins given in the datasheet are used.) When writing the values of each pin as 6-bit numbers packed into the data word, each 6-bit value uses the following representation: @@ -421,7 +417,7 @@ The SPI _ATTACH command enables the SPI flash interface. It takes a 32-bit data * Pin numbers 0 through 30 are represented as themselves. * Pin numbers 32 & 33 are represented as values 30 & 31. - * It is not possible to represent pins 30 & 31 or pins higher than 33. This is the same 6-bit representation used by the ``SPI_PAD_CONFIG_xxx`` efuses. + * It is not possible to represent pins 30 & 31 or pins higher than 33. This is the same 6-bit representation used by the ``SPI_PAD_CONFIG_xxx`` eFuses. On {IDF_TARGET_NAME} ROM loader only, there is an additional 4 bytes in the data payload of this command. These bytes should all be set to zero. @@ -436,7 +432,7 @@ The SPI_SET_PARAMS command sets some parameters of the attached SPI flash chip ( All the values which are passed except total size are hardcoded, and most are not used when writing to flash. See `flash_set_parameters function `__ in esptool for the values which it sends. -32-bit Read/Write +32-Bit Read/Write ^^^^^^^^^^^^^^^^^ The 32-bit read/write commands (READ_REG, WRITE_REG) allow word-oriented reading and writing of memory and register data. diff --git a/docs/en/advanced-topics/spi-flash-modes.rst b/docs/en/advanced-topics/spi-flash-modes.rst index 22b54766de..e19bafaf30 100644 --- a/docs/en/advanced-topics/spi-flash-modes.rst +++ b/docs/en/advanced-topics/spi-flash-modes.rst @@ -74,6 +74,20 @@ In ``qout`` mode, the host uses the "Quad Output Fast Read" (6BH) command to rea In ``qio`` mode, the host uses the "Quad I/O Fast Read" (EBH) command to read data. This command is the same as "Dual I/O Fast Read", only both address & data are transferred on 4 pins instead of 2 with 4 bits per clock cycle. This makes both the address & data transfer exactly twice as fast as "Dual I/O Fast Read". +.. only:: esp32s3 + + Octal SPI + ^^^^^^^^^ + + Some ESP chips additionally support Octal SPI mode. This mode uses 8 pins for communication with the SPI flash chip, and allows for even faster data transfers than Quad SPI. This mode added four additional pins (SPIIO4~7) compared to Quad SPI for data transfers. + + The 1st and 2nd bootloaders don't support ``opi`` mode. Because of that esptool doesn't use ``opi`` and ``dout`` is used instead. The bootloader retrieves the information from eFuse and effectively replaces the mode. + + .. note:: + + Use the ``esptool.py flash_id`` command to check if your ESP is using Quad or Octal SPI mode. It prints information based on the eFuse settings. + + Frequently Asked Questions -------------------------- diff --git a/docs/en/espefuse/burn-bit-cmd.rst b/docs/en/espefuse/burn-bit-cmd.rst index 11b180bf41..6a3787d37e 100644 --- a/docs/en/espefuse/burn-bit-cmd.rst +++ b/docs/en/espefuse/burn-bit-cmd.rst @@ -3,12 +3,12 @@ Burn Bit ======== -The ``espefuse.py burn_bit`` command burns bits in efuse blocks by bit number. This is useful when the fields are not represented in the eFuse table. +The ``espefuse.py burn_bit`` command burns bits in eFuse blocks by bit number. This is useful when the fields are not represented in the eFuse table. Positional arguments: -- ``block`` - Efuse block. -- ``bit number`` - Bit number in the efuse block [0..BLK_LEN-1] (list of numbers, like 10 15 18 17 5 etc.). +- ``block`` - eFuse block. +- ``bit number`` - Bit number in the eFuse block [0..BLK_LEN-1] (list of numbers, like 10 15 18 17 5 etc.). Optional arguments: @@ -39,7 +39,7 @@ Burning bits to BLOCK2: Reading updated efuses... Successful -Burning In Multiple Blocks +Burning in Multiple Blocks ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none diff --git a/docs/en/espefuse/burn-block-data-cmd.rst b/docs/en/espefuse/burn-block-data-cmd.rst index 0b09519600..7bbf78b8ce 100644 --- a/docs/en/espefuse/burn-block-data-cmd.rst +++ b/docs/en/espefuse/burn-block-data-cmd.rst @@ -10,7 +10,7 @@ This command is available in ``espefuse.py`` v2.6 and newer. Positional arguments: * ``Name of key block`` -* ``Datafile``. File containing data to burn into the efuse block. The file size can be smaller than the eFuse block size. +* ``Datafile``. File containing data to burn into the eFuse block. The file size can be smaller than the eFuse block size. It can be list of blocks and datafiles (like BLOCK1 datafile1.bin BLOCK2 datafile2.bin etc.). diff --git a/docs/en/espefuse/burn-efuse-cmd.rst b/docs/en/espefuse/burn-efuse-cmd.rst index 4d6446d9c7..31a915c0c7 100644 --- a/docs/en/espefuse/burn-efuse-cmd.rst +++ b/docs/en/espefuse/burn-efuse-cmd.rst @@ -1,6 +1,6 @@ .. _burn-efuse-cmd: -Burn Efuse +Burn eFuse ========== The ``espefuse.py burn_efuse`` command burns eFuses. The arguments to ``burn_efuse`` are eFuse names (as shown in summary output) and new values. @@ -90,7 +90,7 @@ On {IDF_TARGET_NAME} chips without integrated SPI flash, these eFuses are left z On {IDF_TARGET_NAME} 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. +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 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. diff --git a/docs/en/espefuse/burn-key-cmd.rst b/docs/en/espefuse/burn-key-cmd.rst index c6a7714c26..483f5d6dbf 100644 --- a/docs/en/espefuse/burn-key-cmd.rst +++ b/docs/en/espefuse/burn-key-cmd.rst @@ -155,7 +155,7 @@ By default, when an encryption key block is burned it is also read and write pro Force Writing a Key ^^^^^^^^^^^^^^^^^^^ -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. +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 does not allow any eFuse bits to be cleared 1->0, and can not write anything to write protected eFuse blocks. diff --git a/docs/en/espefuse/execute-scripts-cmd.rst b/docs/en/espefuse/execute-scripts-cmd.rst index 81319a354a..0ec35504ab 100644 --- a/docs/en/espefuse/execute-scripts-cmd.rst +++ b/docs/en/espefuse/execute-scripts-cmd.rst @@ -18,7 +18,7 @@ Optional arguments: > 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: +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``. * ``--index`` integer index (it means the number of chip in the batch in the range 1 - the max number of chips in the batch). It allows to retrieve unique data per chip from configfiles and then burn them (ex. CUSTOM_MAC, UNIQUE_ID). @@ -27,7 +27,7 @@ This command allows burning all needed efuses at one time based on your own pyth 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. +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. If necessary, you can call ``efuses.burn_all()`` which prompts ``Type 'BURN' (all capitals) to continue.``. To skip this check and go without confirmation just add the ``--do-not-confirm`` flag to the ``execute_scripts`` command. This command supports nesting. This means that one script can be called from another script (see the test case ``test_execute_scripts_nesting`` in ``esptool/test/test_espefuse.py``). @@ -36,7 +36,7 @@ This command supports nesting. This means that one script can be called from ano > 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 an 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. +Additionally, you can implement some checks based on the value of eFuses. To get value of an 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 ESP32) for ``CODING_SCHEME`` when ``get_meaning()`` is called: * 0: ``NONE (BLK1-3 len=256 bits)`` @@ -67,10 +67,10 @@ See how it is done (for ESP32) for ``CODING_SCHEME`` when ``get_meaning()`` is c 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. +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. -The script `execute_efuse_script.py `__ burns some efuses and checks them after reading back. To check read and write protection, ``is_readable()`` and ``is_writeable()`` are called. +The script `execute_efuse_script.py `__ burns some eFuses and checks them after reading back. To check read and write protection, ``is_readable()`` and ``is_writeable()`` are called. Burn Unique Data Per Chip ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/espefuse/index.rst b/docs/en/espefuse/index.rst index 5a39c40ae8..679c0bcced 100644 --- a/docs/en/espefuse/index.rst +++ b/docs/en/espefuse/index.rst @@ -50,7 +50,7 @@ Optional General Arguments Of Commands - ``-h``, ``--help`` - Show help message and exit. Use ``-h`` to see a summary of all available commands and command line options. To see all options for a particular chip and command, add ``-c {IDF_TARGET_NAME}`` and ``-h`` to the command name, i.e. ``espefuse.py -c {IDF_TARGET_NAME} burn_key -h``. - ``--chip``, ``-c`` - Target chip type. If this argument is omitted, the tool automatically detects the chip type when connected. But if the command has a help option, the chip is not connected, and the default chip is ``esp32``, please specify the specific type of chip to get the correct help. Example of usage: ``-c esp32``, ``-c esp32c3``, ``-c esp32s2`` and others. - ``--baud``, ``-b`` - Serial port baud rate, the same as for esptool. -- ``--port``, ``-p`` - Serial port device, ``-p /dev/ttyUSB0`` (Linux and macOS) or ``-p COM1`` (Windows). +- ``--port``, ``-p`` - Serial port device, for example: ``-p /dev/ttyUSB0`` (Linux and macOS) or ``-p COM1`` (Windows). - ``--before`` - What to do before connecting to the chip: ``default_reset``, ``no_reset``, ``esp32r1``, ``no_reset_no_sync``. - ``--debug``, ``-d`` - Show debugging information. - ``--virt`` - For host tests. The tool will work in the virtual mode (without connecting to a chip). @@ -58,7 +58,7 @@ Optional General Arguments Of Commands - ``--do-not-confirm`` - Do not pause for confirmation before permanently writing eFuses. Use with caution. If this option is not used, a manual confirmation step is required, you need to enter the word ``BURN`` to continue burning. - ``--extend-efuse-table`` - CSV file from `ESP-IDF `_ (esp_efuse_custom_table.csv). -Virtual mode +Virtual Mode ^^^^^^^^^^^^ This mode is enabled with the ``--virt`` flag (need to specify chip with ``--chip``). This helps to test commands without physical access to the chip. Burned data is not saved between commands. Using ``--path-efuse-file``, you can save the written data to a file. Delete the file to clear eFuses. @@ -94,7 +94,7 @@ This tool automatically adds encoding data to the burning data if it requires. E All coding schemes (except ``None``) require additional encoding data to be provided at write time. Due to the encoding data, such blocks cannot be overwritten again without breaking the block's coding scheme. Use the :ref:`perform-multiple-operations` feature or list multiple eFuses/keys. -Burning Efuse +Burning eFuse ------------- Burning occurs in order from BLOCK(max) to BLOCK0. This prevents read/write protection from being set before the data is set. After burning, the tool reads the written data back and compares the original data, and additionally checks the status of the coding scheme, if there are any errors, it re-burns the data again to correct it. @@ -114,7 +114,7 @@ The example below shows how to use the two commands ``burn_key_digest`` and ``bu burn_key_digest secure_images/ecdsa256_secure_boot_signing_key_v2.pem \ burn_key BLOCK_KEY0 images/efuse/128bit_key.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS -Extend Efuse Table +Extend eFuse Table ------------------ This tool supports the use of `CSV files `_ from the `ESP-IDF `_ (e.g., ``esp_efuse_custom_table.csv``) to add custom eFuse fields. You can use this argument with any supported commands to access these custom eFuses. diff --git a/docs/en/espefuse/set-flash-voltage-cmd.rst b/docs/en/espefuse/set-flash-voltage-cmd.rst index 6340858cae..3437414e59 100644 --- a/docs/en/espefuse/set-flash-voltage-cmd.rst +++ b/docs/en/espefuse/set-flash-voltage-cmd.rst @@ -24,9 +24,9 @@ Positional arguments: Setting Flash Voltage ({IDF_TARGET_VDD_SPI}) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -After reset, the default {IDF_TARGET_NAME} behaviour is to enable and configure the flash voltage regulator ({IDF_TARGET_VDD_SPI}) based on the level of the MTDI pin ({IDF_TARGET_VDD_GPIO}). +After reset, the default {IDF_TARGET_NAME} behavior is to enable and configure the flash voltage regulator ({IDF_TARGET_VDD_SPI}) based on the level of the MTDI pin ({IDF_TARGET_VDD_GPIO}). -The default behaviour on reset is: +The default behavior on reset is: +--------------------+--------------------+ | MTDI | Internal Regulator | @@ -44,7 +44,7 @@ The default behaviour on reset is: Consult {IDF_TARGET_NAME} Technical Reference Manual for details. -A combination of 3 efuses (``{IDF_TARGET_VDD_FORCE}``, ``{IDF_TARGET_VDD_REG}``, ``{IDF_TARGET_VDD_TIEH}``) can be burned in order to override this behaviour and disable {IDF_TARGET_VDD_SPI} 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: +A combination of 3 eFuses (``{IDF_TARGET_VDD_FORCE}``, ``{IDF_TARGET_VDD_REG}``, ``{IDF_TARGET_VDD_TIEH}``) can be burned in order to override this behavior and disable {IDF_TARGET_VDD_SPI} 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 {IDF_TARGET_VDD_SPI} Regulator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -58,7 +58,7 @@ Once set: * {IDF_TARGET_VDD_SPI} regulator always disabled. * MTDI pin ({IDF_TARGET_VDD_GPIO}) is ignored. * Flash must be powered externally and voltage supplied to {IDF_TARGET_VDD_SPI} pin of {IDF_TARGET_NAME}. -* Efuse ``{IDF_TARGET_VDD_FORCE}`` is burned. +* eFuse ``{IDF_TARGET_VDD_FORCE}`` is burned. Fixed 1.8V {IDF_TARGET_VDD_SPI} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -91,7 +91,7 @@ Once set: Subsequent Changes ^^^^^^^^^^^^^^^^^^ -Once an efuse is burned it cannot be un-burned. However, changes can be made by burning additional efuses: +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`` diff --git a/docs/en/espefuse/summary-cmd.rst b/docs/en/espefuse/summary-cmd.rst index 195083ebdd..e460d66d6e 100644 --- a/docs/en/espefuse/summary-cmd.rst +++ b/docs/en/espefuse/summary-cmd.rst @@ -11,7 +11,7 @@ Optional arguments: - ``summary`` - text format (default option). - ``json`` - json format. Usage ``--format json``. - ``value_only`` - only the value of the eFuse specified as an argument will be displayed. For more information, refer to the :ref:`Filtering eFuses ` section. -- ``--file`` - File to save the efuse summary. Usage ``--file efuses.json``. +- ``--file`` - File to save the eFuse summary. Usage ``--file efuses.json``. - List of eFuses to filter. For more information, refer to the :ref:`Filtering eFuses ` section. Text Format Summary diff --git a/docs/en/espsecure/index.rst b/docs/en/espsecure/index.rst index c03b3478e1..de6f286de2 100644 --- a/docs/en/espsecure/index.rst +++ b/docs/en/espsecure/index.rst @@ -12,7 +12,7 @@ For more details, see the ESP-IDF documentation which explains this tool and how .. _hsm_signing: -Remote Signing using an external HSM +Remote Signing Using an External HSM ------------------------------------ An external Hardware Security Module (HSM) can be used for remote signing of images in secure boot v2 scheme. @@ -44,7 +44,7 @@ If the public key is not stored in the external HSM, you can specify the ``--key python espsecure.py verify_signature --version 2 --keyfile -HSM config file +HSM Config File ~~~~~~~~~~~~~~~ An HSM config file is required with the fields (``pkcs11_lib``, ``credentials``, ``slot``, ``label``, ``label_pubkey``) diff --git a/docs/en/esptool/advanced-commands.rst b/docs/en/esptool/advanced-commands.rst index 533145823e..849f3c7177 100644 --- a/docs/en/esptool/advanced-commands.rst +++ b/docs/en/esptool/advanced-commands.rst @@ -11,8 +11,8 @@ The following less common commands are for more advanced users. .. _verify-flash: -Verify Flash Data: verify_flash -------------------------------- +Verify Flash Data: ``verify_flash`` +----------------------------------- The ``verify_flash`` command allows you to verify that data in flash matches a local file. @@ -34,8 +34,8 @@ The ``--diff yes`` option specifies that if the files are different, the details .. _dump-mem: -Dump a Memory Region to File: dump_mem --------------------------------------- +Dump a Memory Region to File: ``dump_mem`` +------------------------------------------ The ``dump_mem`` command will dump a region from the chip's memory space to a file. For example, to dump the ROM (64 kB) from an ESP8266: @@ -45,8 +45,8 @@ The ``dump_mem`` command will dump a region from the chip's memory space to a fi .. _load-ram: -Load a Binary to RAM: load_ram ------------------------------- +Load a Binary to RAM: ``load_ram`` +---------------------------------- The ``load_ram`` command allows the loading of an executable binary image (created with the ``elf2image`` or ``make_image`` commands) directly into RAM, and then immediately executes the program contained within it. Command also supports ``.hex`` file created by ``merge_bin`` command from supported ``.bin`` files. @@ -62,8 +62,8 @@ The ``load_ram`` command allows the loading of an executable binary image (creat .. _read-mem-write-mem: -Read or Write RAM: read_mem / write_mem ---------------------------------------- +Read or Write RAM: ``read_mem`` & ``write_mem`` +----------------------------------------------- The ``read_mem`` & ``write_mem`` commands allow reading and writing single words (4 bytes) of RAM. This can be used to "peek" and "poke" at registers. @@ -77,8 +77,8 @@ The ``read_mem`` & ``write_mem`` commands allow reading and writing single words .. _read-flash-status: -Read Flash Chip Registers: read_flash_status --------------------------------------------- +Read Flash Chip Registers: ``read_flash_status`` +------------------------------------------------ This command is intended for use when debugging hardware flash chip-related problems. It allows sending a ``RDSR``, ``RDSR2`` and/or ``RDSR3`` commands to the flash chip to read the status register contents. This can be used to check write protection status, for example: @@ -98,8 +98,8 @@ The ``--bytes`` argument determines how many status register bytes are read. .. _write-flash-status: -Write Flash Chip Registers: write_flash_status ------------------------------------------------ +Write Flash Chip Registers: ``write_flash_status`` +-------------------------------------------------- This command is intended for use when debugging hardware flash chip-related problems. It allows sending ``WRSR``, ``WRSR2`` and/or ``WRSR3`` commands to the flash chip to write the status register contents. This can be used to clear write protection bits, for example: @@ -122,8 +122,8 @@ A second option ``--non-volatile`` can be used in order to send a ``WREN`` (06h) .. _read-flash-sfdp: -Read Serial Flash Discoverable Parameters (SFDP): read_flash_sfdp ------------------------------------------------------------------ +Read Serial Flash Discoverable Parameters (SFDP): ``read_flash_sfdp`` +--------------------------------------------------------------------- The Serial Flash Discoverable Parameters (SFDP) store essential vendor-specific configuration data of the flash memory chip. These parameters help identify and interact with different flash devices. Usage: @@ -137,8 +137,8 @@ This will read 4 bytes from SFDP address 16. .. _chip-id: - Read the Chip ID: chip_id - ------------------------- + Read the Chip ID: ``chip_id`` + ----------------------------- The ``chip_id`` command allows you to read a 4 byte ID which forms part of the MAC address. It is usually better to use ``read_mac`` to identify a chip. @@ -150,8 +150,8 @@ This will read 4 bytes from SFDP address 16. .. _make-image: - Assemble a Firmware Image: make_image - ------------------------------------- + Assemble a Firmware Image: ``make_image`` + ----------------------------------------- ``make_image`` allows you to manually assemble a firmware image from binary segments (such as those extracted from objcopy). For example: @@ -167,7 +167,7 @@ This will read 4 bytes from SFDP address 16. .. _run: - Boot Application Code: run - -------------------------- + Boot Application Code: ``run`` + ------------------------------ The ``run`` command immediately exits the bootloader and attempts to boot the normal application code. diff --git a/docs/en/esptool/advanced-options.rst b/docs/en/esptool/advanced-options.rst index 2e53b9f016..0deba2d719 100644 --- a/docs/en/esptool/advanced-options.rst +++ b/docs/en/esptool/advanced-options.rst @@ -3,17 +3,17 @@ Advanced Options ================ -The following advanced configuration options can be used for all esptool commands (they are placed before the command name on the command line). +The following advanced global configuration options can be used for all esptool commands. They are placed before the command name on the command line. For example, the option ``--before no_reset`` has to be placed before ``flash_id``. The command should look like this: ``esptool.py --before no_reset flash_id``. -For basic/fundamental configuration options, see the :ref:`options` page. +For basic/fundamental global configuration options, see the :ref:`options` page. Reset Modes ----------- By default, esptool tries to hard reset the chip into bootloader mode before it starts and hard resets the chip to run the normal program once it is complete. The ``--before`` and ``--after`` options allow this behavior to be changed: -Reset Before Operation -^^^^^^^^^^^^^^^^^^^^^^ +Reset Before Operation: ``--before`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``--before`` argument allows you to specify whether the chip needs resetting into bootloader mode before esptool talks to it. @@ -24,8 +24,8 @@ The ``--before`` argument allows you to specify whether the chip needs resetting * ``--before no_reset_no_sync`` will skip DTR/RTS control signal assignments and skip also the serial synchronization command. This is useful if your chip is already running the :ref:`stub bootloader ` and you want to avoid resetting the chip and uploading the stub again. :esp32c3 or esp32s3 or esp32c6 or esp32h2 or esp32p4 or esp32c5 or esp32c61: * ``--before usb_reset`` will use custom reset sequence for USB-JTAG-Serial (used for example for ESP chips connected through the USB-JTAG-Serial peripheral). Usually, this option doesn't have to be used directly. Esptool should be able to detect connection through USB-JTAG-Serial. -Reset After Operation -^^^^^^^^^^^^^^^^^^^^^ +Reset After Operation: ``--after`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``--after`` argument allows you to specify whether the chip should be reset after the esptool operation completes: @@ -60,8 +60,8 @@ There are 3 possible values for this option: .. _disable_stub: -Disabling the Stub Loader -------------------------- +Disabling the Stub Loader: ``--no-stub`` +---------------------------------------- The ``--no-stub`` option disables uploading of a software "stub loader" that manages flash operations, and only talks directly to the loader in ROM. @@ -69,8 +69,8 @@ Passing ``--no-stub`` will disable certain options, as not all options are imple .. only:: not esp8266 - Overriding SPI Flash Connections - -------------------------------- + Overriding SPI Flash Connections: ``--spi-connection`` + ------------------------------------------------------ The optional ``--spi-connection`` argument overrides the SPI flash connection configuration on {IDF_TARGET_NAME}. This means that the SPI flash can be connected to other pins, or esptool can be used to communicate with a different SPI flash chip to the default. @@ -85,7 +85,7 @@ Passing ``--no-stub`` will disable certain options, as not all options are imple If the ``--spi-connection`` argument is not provided, the SPI flash is configured to use :ref:`pin numbers set in eFuse `. These are the same SPI flash pins that are used during a normal boot. - The only exception to this is if the ``--no-stub`` option is also provided. In this case, efuse values are ignored and ``--spi-connection`` will default to ``--spi-connection SPI`` unless set to a different value. + The only exception to this is if the ``--no-stub`` option is also provided. In this case, eFuse values are ignored and ``--spi-connection`` will default to ``--spi-connection SPI`` unless set to a different value. .. only:: esp32 @@ -100,7 +100,7 @@ Passing ``--no-stub`` will disable certain options, as not all options are imple * HD = GPIO 9 * CS = GPIO 11 - During normal booting, this configuration is selected if all SPI pin efuses are unset and GPIO1 (U0TXD) is not pulled low (default). + During normal booting, this configuration is selected if all SPI pin eFuses are unset and GPIO1 (U0TXD) is not pulled low (default). This is the normal pin configuration for ESP32 chips that do not contain embedded flash. @@ -115,16 +115,16 @@ Passing ``--no-stub`` will disable certain options, as not all options are imple * HD = GPIO 4 * CS = GPIO 15 - During normal booting, this configuration is selected if all SPI pin efuses are unset and GPIO1 (U0TXD) is pulled low on reset. + During normal booting, this configuration is selected if all SPI pin eFuses are unset and GPIO1 (U0TXD) is pulled low on reset. Custom SPI Pin Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``--spi-connection ,,,,`` allows a custom list of pins to be configured for the SPI flash connection. This can be used to emulate the flash configuration equivalent to a particular set of SPI pin efuses being burned. The values supplied are GPIO numbers. + ``--spi-connection ,,,,`` allows a custom list of pins to be configured for the SPI flash connection. This can be used to emulate the flash configuration equivalent to a particular set of SPI pin eFuses being burned. The values supplied are GPIO numbers. .. only:: esp32 - For example, ``--spi-connection 6,17,8,11,16`` sets an identical configuration to the factory efuse configuration for ESP32s with embedded flash. + For example, ``--spi-connection 6,17,8,11,16`` sets an identical configuration to the factory eFuse configuration for ESP32s with embedded flash. When setting a custom pin configuration, the SPI peripheral (not HSPI) will be used unless the ``CLK`` pin value is set to 14 (HSPI CLK), in which case the HSPI peripheral will be used. @@ -140,15 +140,15 @@ Anywhere on the esptool command line, you can specify a file name as ``@filename An example of this is available in the :ref:`merge_bin ` command description. -.. note:: PowerShell users +.. note:: - Because of `splatting `__ in PowerShell (method of passing a collection of parameter values to a command as a unit) there is a need to add quotes around @filename.txt ("@filename.txt") to be correctly resolved. + PowerShell users need to add quotes around @filename.txt ("@filename.txt") for it to be correctly resolved. This is because of `splatting `__, a method of passing a collection of parameter values to a command as a unit. -Filtering serial ports ----------------------- +Filtering Serial Ports: ``--port-filter`` +----------------------------------------- .. _filtering_serial_ports: -``--port-filter =`` allows limiting ports that will be tried. This can be useful when esptool is run on a system +``--port-filter =`` allows limiting ports that will be considered during chip autodetection. This can be useful when esptool is run on a system with many serial ports. There are a few different types that can be combined. A port must match all specified FilterTypes, and must match at least one FilterValue for each specified FilterType to be considered. Example filter configurations: diff --git a/docs/en/esptool/basic-commands.rst b/docs/en/esptool/basic-commands.rst index e016dc4381..4c6419c72e 100644 --- a/docs/en/esptool/basic-commands.rst +++ b/docs/en/esptool/basic-commands.rst @@ -5,8 +5,8 @@ Basic Commands .. _write-flash: -Write Binary Data to Flash: write_flash ----------------------------------------- +Write Binary Data to Flash: ``write_flash`` +------------------------------------------- Binary data can be written to the ESP's flash chip via the serial ``write_flash`` command: @@ -77,14 +77,14 @@ Use the ``-e/--erase-all`` option to erase all flash sectors (not just the write .. only:: esp32 - Overwriting the encrypted firmware (bootloader, application, etc.) without the ``--encrypt`` option is disabled, if `Flash Encryption `_ is enabled and Encrypted Download being disabled (efuse bit ``EFUSE_DISABLE_DL_ENCRYPT`` is set). + Overwriting the encrypted firmware (bootloader, application, etc.) without the ``--encrypt`` option is disabled, if `Flash Encryption `_ is enabled and Encrypted Download being disabled (eFuse bit ``EFUSE_DISABLE_DL_ENCRYPT`` is set). .. only:: not esp32 Overwriting the encrypted firmware (bootloader, application, etc.) without the ``--encrypt`` option is disabled, if: * `Flash Encryption `_ and Secure Download Mode are enabled or - * `Flash Encryption `_ is enabled but Encrypted Download is disabled (efuse bit ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` is set). + * `Flash Encryption `_ is enabled but Encrypted Download is disabled (eFuse bit ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` is set). This is a safety measure to prevent accidentally overwriting the encrypted firmware with a plaintext binary, which **can ultimately lead to bricking the device**. @@ -98,8 +98,8 @@ Use the ``-e/--erase-all`` option to erase all flash sectors (not just the write This behavior can be overridden with the ``--force`` option. -Read Flash Contents: read_flash --------------------------------- +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: @@ -126,8 +126,8 @@ It is also possible to autodetect flash size by using ``ALL`` as size. The above .. _erase_flash: -Erase Flash: erase_flash & erase_region ---------------------------------------- +Erase Flash: ``erase_flash`` & ``erase_region`` +----------------------------------------------- To erase the entire flash chip (all data replaced with 0xFF bytes): @@ -154,8 +154,8 @@ The address and length must both be multiples of the SPI flash erase sector size This behavior can be overridden with the ``--force`` option. **Use this only at your own risk and only if you know what you are doing!** -Read Built-in MAC Address: read_mac ------------------------------------- +Read Built-in MAC Address: ``read_mac`` +--------------------------------------- :: @@ -163,8 +163,8 @@ Read Built-in MAC Address: read_mac .. _read-spi-flash-id: -Read SPI Flash ID: flash_id ---------------------------- +Read SPI Flash ID: ``flash_id`` +------------------------------- :: @@ -182,8 +182,8 @@ Refer to `flashrom source code `__ is detected in the image, specific fields describing the application are also displayed. - - If the given binary file is a bootloader and a valid `ESP-IDF bootloader header `__ is detected in the image, specific fields describing the bootloader are also displayed. + If the given binary file is an application with a valid `ESP-IDF application header `__ + or a bootloader with a valid `ESP-IDF bootloader header `__ + detected in the image, specific fields describing the application or bootloader are also displayed. .. _merge-bin: -Merge Binaries for Flashing: merge_bin --------------------------------------- +Merge Binaries for Flashing: ``merge_bin`` +------------------------------------------ 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 based on the selected output format. For example: diff --git a/docs/en/esptool/basic-options.rst b/docs/en/esptool/basic-options.rst index 5d9bb4c468..e06caf7ff6 100644 --- a/docs/en/esptool/basic-options.rst +++ b/docs/en/esptool/basic-options.rst @@ -5,10 +5,13 @@ Basic Options These are the basic/fundamental esptool options needed to define the communication with an ESP target. For advanced configuration options, see the :ref:`advanced-options` page. +Esptool has global and command-specific options. Global options have to be specified after ``esptool.py``. They are used to configure the serial port, baud rate, and chip type. +Command-specific options are specified after the command and are used to configure the command itself. For more information about commands and their options, see :ref:`commands` or see help in the command line. + .. _chip-type: -Chip Type ---------- +Chip Type: ``--chip``, ``-c`` +----------------------------- * The target chip type can be selected using the ``--chip``/ ``-c`` option, e.g. ``esptool.py --chip {IDF_TARGET_PATH_NAME} ``. * A default chip type can be specified by setting the ``ESPTOOL_CHIP`` environment variable. @@ -17,8 +20,8 @@ Chip Type .. _serial-port: -Serial Port ------------ +Serial Port: ``--port``, ``-p`` +------------------------------- * 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. @@ -38,8 +41,8 @@ On most Linux distributions, the solution is to add the user to the ``dialout`` You can call ``su - $USER`` to enable read and write permissions for the serial port without having to log out and back in again. Check your Linux distribution's documentation for more information. -Baud Rate ---------- +Baud Rate: ``--baud``, ``-b`` +----------------------------- The default esptool 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. diff --git a/docs/en/esptool/configuration-file.rst b/docs/en/esptool/configuration-file.rst index ed264cd4c0..194f60c4c2 100644 --- a/docs/en/esptool/configuration-file.rst +++ b/docs/en/esptool/configuration-file.rst @@ -23,13 +23,13 @@ directory ``esptool.py`` is being run in is inspected. If a configuration file is not found here, the current user's OS configuration directory is inspected next: - Linux: ``/home//.config/esptool/`` - - MacOS ``/Users//.config/esptool/`` + - macOS ``/Users//.config/esptool/`` - Windows: ``c:\Users\\AppData\Local\esptool\`` If a configuration file is still not found, the last inspected location is the home directory: - Linux: ``/home//`` - - MacOS ``/Users//`` + - macOS ``/Users//`` - Windows: ``c:\Users\\`` On Windows, the home directory can be set with the ``HOME`` or ``USERPROFILE`` environment variables. @@ -40,7 +40,7 @@ environment variable, e.g. ``ESPTOOL_CFGFILE = ~/custom_config.cfg``. This overrides the search priorities described above. ``esptool.py`` will read settings from other usual configuration files if no other -configuration file is used. It will automatically read from ``setup.cfg`` or +configuration file is used. It will automatically read from ``setup.cfg`` or ``tox.ini`` if they exist. As a result, the order of priority of inspected configuration files is: @@ -87,7 +87,7 @@ Complete list of configurable options: +------------------------------+-----------------------------------------------------------+----------+ | chip_erase_timeout | Timeout for a full chip erase | 120 s | +------------------------------+-----------------------------------------------------------+----------+ -| max_timeout | The longest any command can run | 240 s | +| max_timeout | The longest any operation can run (e.g. writing a block) | 240 s | +------------------------------+-----------------------------------------------------------+----------+ | sync_timeout | Timeout for syncing with the bootloader | 0.1 s | +------------------------------+-----------------------------------------------------------+----------+ @@ -114,6 +114,13 @@ Complete list of configurable options: | custom_hard_reset_sequence | Custom reset sequence for hard resetting the chip | | +------------------------------+-----------------------------------------------------------+----------+ + +.. note:: + + ``connect_attempts`` is the number of attempts to connect to the chip after the port is detected. This is useful when the chip does not enter bootloader mode immediately. For example, when :ref:`automatic bootloader mode ` does not work and :ref:`manual bootloader mode ` has to be used. + + On the other hand, ``open_port_attempts`` is the number of attempts to look for a port to open. When starting the command, the port does not have to be available. This can be useful when the chip is in deep sleep and is connected using USB-Serial/JTAG. In such cases, the port can disappear. + Custom Reset Sequences ---------------------- @@ -146,13 +153,25 @@ For example: ``D0|R1|W0.1|D1|R0|W0.05|D0`` represents the following classic rese .. code-block:: python - _setDTR(False) # IO0=HIGH + _setDTR(False) # BOOT=HIGH _setRTS(True) # EN=LOW, chip in reset time.sleep(0.1) - _setDTR(True) # IO0=LOW + _setDTR(True) # BOOT=LOW _setRTS(False) # EN=HIGH, chip out of reset time.sleep(0.05) - _setDTR(False) # IO0=HIGH, done + _setDTR(False) # BOOT=HIGH, done + +The sequence can be visualized as follows: + +.. figure:: diag/reset_sequence.svg + :align: center + :alt: Signal representation of sequence + + Signal representation of the reset sequence + +.. note:: + + Please note that this sequence is representation of signals on Espressif devkit and may differ on other boards. Similarly, ``R1|W0.1|R0`` represents the classic hard reset sequence: diff --git a/docs/en/esptool/diag/reset_sequence.svg b/docs/en/esptool/diag/reset_sequence.svg new file mode 100644 index 0000000000..32eca6bc3d --- /dev/null +++ b/docs/en/esptool/diag/reset_sequence.svg @@ -0,0 +1,1380 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DTR + + + + + + + + + + + + + + + + + + + + + RTS + + + + + + + + + + + + + + + + + + + + + EN + + + + + + + + + + + + + + + + + + + + + BOOT + + + + + + + + + + + + + + + + + + + + + + + + 0.1s + + + + + 0.05s + + + + + + + + + + + + + + + diff --git a/docs/en/esptool/flash-modes.rst b/docs/en/esptool/flash-modes.rst index 04b94fa915..c43d8a223a 100644 --- a/docs/en/esptool/flash-modes.rst +++ b/docs/en/esptool/flash-modes.rst @@ -23,8 +23,8 @@ To override these values, the options ``--flash_mode``, ``--flash_size`` and/or These options are only consulted when flashing a bootable image to an {IDF_TARGET_NAME} at offset {IDF_TARGET_BOOTLOADER_OFFSET}. 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) -------------------------------- +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``. @@ -40,15 +40,15 @@ In ``qio`` mode, two additional GPIOs are used for SPI flash communications. If For a full explanation of these modes, see the :ref:`SPI Flash Modes page `. -Flash Frequency (--flash_freq, -ff) ------------------------------------- +Flash Frequency: ``--flash_freq``, ``-ff`` +------------------------------------------ Clock frequency for SPI flash interactions. Valid values are ``keep``, {IDF_TARGET_FLASH_FREQ} (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 {IDF_TARGET_FLASH_FREQ_0}MHz clock speeds, but you can try lower values if the device won't boot. The highest {IDF_TARGET_FLASH_FREQ_F}MHz 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) -------------------------------- +Flash Size: ``--flash_size``, ``-fs`` +------------------------------------- Size of the SPI flash, given in megabytes. diff --git a/docs/en/esptool/flasher-stub.rst b/docs/en/esptool/flasher-stub.rst index c2f179be7c..e2efb990f4 100644 --- a/docs/en/esptool/flasher-stub.rst +++ b/docs/en/esptool/flasher-stub.rst @@ -16,7 +16,7 @@ Benefits The flasher stub behaves the same as the original bootloader, but uses more heavily optimized UART routines. -The main benefit is improved performance of flashing and some other operations (like reading flash). Additionally, there are a few commands which are only available when using the stub loader (such as :ref:`erase_flash and erase_region `). It also allows to work around any bugs in ROM bootloaders. +The main benefit is improved performance of flashing and some other operations (like reading flash). Additionally, it also allows to work around any bugs in ROM bootloaders. Disabling the Stub Loader ------------------------- diff --git a/docs/en/esptool/flashing-firmware.rst b/docs/en/esptool/flashing-firmware.rst index 4280b06ec5..c32631d2d5 100644 --- a/docs/en/esptool/flashing-firmware.rst +++ b/docs/en/esptool/flashing-firmware.rst @@ -46,9 +46,14 @@ ESP-IDF ESP-IDF outputs the full esptool command used for flashing after the build is finished, for example:: - Project build complete. To flash, run this command: - python esptool.py -p (PORT) -b 460800 --before default_reset --after hard_reset --chip {IDF_TARGET_PATH_NAME} write_flash --flash_mode dio --flash_size detect --flash_freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin - or run 'idf.py -p (PORT) flash' + Project build complete. To flash, run: + idf.py flash + or + idf.py -p PORT flash + or + python -m esptool --chip {IDF_TARGET_PATH_NAME} -b 460800 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size 2MB --flash_freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin + or from the "esp-idf/examples/get-started/hello_world/build" directory + python -m esptool --chip {IDF_TARGET_PATH_NAME} -b 460800 --before default_reset --after hard_reset write_flash "@flash_args" Arduino ^^^^^^^ @@ -62,18 +67,18 @@ To do a verbose upload and see the exact esptool invocation, run ``pio run -v -t :: - “.../.platformio/penv/bin/python2.7” “.../.platformio/packages/tool-esptoolpy/esptool.py” --chip {IDF_TARGET_PATH_NAME} --port “/dev/cu.usbserial001” --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect {IDF_TARGET_BOOTLOADER_OFFSET} .../.platformio/packages/framework-arduinoespressif32/tools/sdk/bin/bootloader_dio_40m.bin 0x8000 .../project_folder/.pio/build/esp32doit-devkit-v1/partitions.bin 0xe000 .../.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin 0x10000 .pio/build/esp32doit-devkit-v1/firmware.bin + ".../.platformio/penv/bin/python" ".../.platformio/packages/tool-esptoolpy/esptool.py" --chip {IDF_TARGET_PATH_NAME} --port "/dev/cu.usbserial001" --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect {IDF_TARGET_BOOTLOADER_OFFSET} .../.platformio/packages/framework-arduinoespressif32/tools/sdk/bin/bootloader_dio_40m.bin 0x8000 .../project_folder/.pio/build/esp32doit-devkit-v1/partitions.bin 0xe000 .../.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin 0x10000 .pio/build/esp32doit-devkit-v1/firmware.bin Flashing -------- -If you split the output, you’ll find the ``write_flash`` command with a list of paths to binary files and their respective flashing offsets. If necessary, change the paths to the actual file locations. +If you split the output, you'll find the ``write_flash`` command with a list of paths to binary files and their respective flashing offsets. If necessary, change the paths to the actual file locations. Change ``PORT`` to the name of :ref:`actually used serial port ` and run the command. A successful flash looks like this:: - $ python esptool.py -p /dev/tty.usbserial-0001 -b 460800 --before default_reset --after hard_reset --chip {IDF_TARGET_PATH_NAME} write_flash --flash_mode dio --flash_size detect --flash_freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin - esptool.py v3.2-dev + $ python -m esptool -p /dev/tty.usbserial-0001 -b 460800 --before default_reset --after hard_reset --chip {IDF_TARGET_PATH_NAME} write_flash --flash_mode dio --flash_size detect --flash_freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin + esptool.py v4.8.1 Serial port /dev/tty.usbserial-0001 Connecting......... Chip is ESP32-D0WD (revision 1) @@ -91,6 +96,7 @@ Change ``PORT`` to the name of :ref:`actually used serial port ` an Flash will be erased from 0x00008000 to 0x00008fff... Flash will be erased from 0x00010000 to 0x00039fff... Flash params set to 0x0240 + SHA digest in image updated Compressed 25536 bytes to 15935... Wrote 25536 bytes (15935 compressed) at 0x00001000 in 0.7 seconds (effective 275.5 kbit/s)... Hash of data verified. diff --git a/docs/en/esptool/index.rst b/docs/en/esptool/index.rst index 495896fb99..421305b929 100644 --- a/docs/en/esptool/index.rst +++ b/docs/en/esptool/index.rst @@ -14,13 +14,12 @@ To see all options for a particular command, append ``-h`` to the command name. Basic Commands Advanced Options Advanced Commands - Flasher Stub - Flash Modes Entering the Bootloader Serial Connection - Configuration File - Remote Serial Ports Flashing Firmware + Flasher Stub + Flash Modes + Configuration File Scripting .. only:: not esp8266 @@ -29,3 +28,4 @@ To see all options for a particular command, append ``-h`` to the command name. * :ref:`espefuse` * :ref:`espsecure` + * :ref:`esp_rfc2217_server.py ` diff --git a/docs/en/index.rst b/docs/en/index.rst index 60a965a9ae..5aef221417 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -1,13 +1,14 @@ Esptool.py Documentation ======================== -This is the documentation for ``esptool.py`` - a Python-based, open source, platform independent utility to communicate with the ROM bootloader in `Espressif SoCs `_. +This is the documentation for ``esptool.py`` - a Python-based, open source, platform independent serial communication tool. Esptool communicates with the ROM bootloader (or flasher stub) in `Espressif SoCs `_. +The flasher stub is a small program included with esptool that replaces the original ROM bootloader in the chip to fix some of its limitations and bugs. See :ref:`stub` for more details. ``esptool.py``, ``espefuse.py`` and ``espsecure.py`` are a complete toolset for working with Espressif chips. They can do a number of things, for example: * Read, write, erase, and verify binary data stored in flash. * Read chip features and other related data such as MAC address or flash chip ID. -* Read and write the one-time-programmable efuses. +* Read and write the one-time-programmable eFuses. * Prepare binary executable images ready for flashing. * Analyze, assemble, and merge binary images. @@ -29,6 +30,11 @@ Getting started is easy: 2) Connect an Espressif chip to your computer. +.. note:: + + Please note that serial communication has to work and chip has to be in the :ref:`download mode `. + This is usually done :ref:`automatically ` or can be done :ref:`manually `. Esptool cannot function until this is resolved. For more information, see :ref:`troubleshooting`. + 3) Run ``esptool.py`` commands. For example, to read information about your chip's SPI flash, run: :: @@ -37,6 +43,19 @@ Getting started is easy: Replace ``PORT`` with the name of used serial port. If connection fails, see :ref:`troubleshooting`. +After successfully executing the command, esptool will hard reset the chip, causing it to run the user code. This behavior can be adjusted, see :ref:`advanced-options`. + +Alternatives +------------ + +``esptool.py`` is not the only tool for working with Espressif chips. Some notable options include: + +- `esptool.js `__ is a JavaScript port of esptool.py that can be used in a web browser or in a Node.js environment. +- `espflash `__ is a Rust port of esptool.py. It relies on the support in `esp-hal `__, which may delay support for new chips. +- `OpenOCD `__ is a general-purpose tool for debugging and flashing chips. + +Among these, esptool.py is the most feature-rich, and support for the newest chips and features usually appears here first. + More Information ---------------- @@ -47,6 +66,7 @@ More Information Esptool :not esp8266:Espefuse :not esp8266:Espsecure + Remote Serial Ports Advanced Topics Troubleshooting Contribute diff --git a/docs/en/installation.rst b/docs/en/installation.rst index 9e201d9d37..aff59b8c39 100644 --- a/docs/en/installation.rst +++ b/docs/en/installation.rst @@ -39,7 +39,7 @@ Creating a virtual environment (venv) is a good practice. This is particularly h - Activate the virtual environment: - On Windows: ``esptoolenv\Scripts\activate`` - - On Linux or MacOS: ``source esptoolenv/bin/activate`` + - On Linux or macOS: ``source esptoolenv/bin/activate`` - Install the latest ``esptool.py`` version within the active virtual environment: ``pip install esptool`` - You can now use it within this virtual environment without affecting your system-wide installations: ``esptool.py `` @@ -58,30 +58,33 @@ If you are using ``esptool.py`` as a standalone tool (as a global installation o $ pip install --upgrade esptool -As a Component -^^^^^^^^^^^^^^ +As a Part of SDK/Framework +^^^^^^^^^^^^^^^^^^^^^^^^^^ -If ``esptool.py`` is installed as a component of a development framework (e.g. `ESP-IDF `_, `Arduino `_, or `PlatformIO `_), it is advised to follow the update guide of used framework for instructions and not to update the tool directly. +If ``esptool.py`` is installed as a part of a development SDK/framework (e.g. `ESP-IDF `_, `Arduino `_, or `PlatformIO `_), it is advised to follow the update guide of used framework for instructions and not to update the tool directly. If updating directly is unavoidable, make sure you update to a compatible version by staying on the same MAJOR version number (explained in the :ref:`versions` article). For instance, if your currently installed ``esptool.py`` is ``v3.3.1``, only update to ``v3.*.*``. You risk introducing incompatible changes by updating to ``v4.*.*`` or higher. :: - $ pip install esptool==3.3.2 + $ pip install "esptool<4" -Shell completions +Shell Completions ----------------- To activate autocompletion, you can manually add commands provided below to your shell's config file or run them in your current terminal session for one-time activation. You will likely have to restart or re-login for the autocompletion to start working. -bash: +Bash +^^^^ + :: eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)" -zsh: +Zsh +^^^ To activate completions in zsh, first make sure `compinit` is marked for autoload and run autoload: @@ -97,7 +100,8 @@ Afterwards you can enable completions for esptool.py, espsecure.py and espefuse. eval "$(register-python-argcomplete esptool.py espsecure.py espefuse.py)" -fish: +Fish +^^^^ Not required to be in the config file, only run once diff --git a/docs/en/esptool/remote-serial-ports.rst b/docs/en/remote-serial-ports.rst similarity index 88% rename from docs/en/esptool/remote-serial-ports.rst rename to docs/en/remote-serial-ports.rst index 5863516f03..e35d598fec 100644 --- a/docs/en/esptool/remote-serial-ports.rst +++ b/docs/en/remote-serial-ports.rst @@ -1,6 +1,8 @@ Remote Serial Ports =================== +If you would like to connect to an Espressif SoC that is not directly connected to your system, you can use a remote serial port. This is useful when the chip is on a different machine, or for example when using WSL on Windows. + It is possible to connect to any networked remote serial port that supports `RFC2217 `__ (Telnet) protocol. To do this, specify the serial port to esptool as ``rfc2217://:``. For example, to read information about your chip's SPI flash, run: :: @@ -9,6 +11,8 @@ It is possible to connect to any networked remote serial port that supports `RFC Custom baud rates and DTR/RTS automatic resetting are supported over the RFC2217 protocol, the same as for a local serial port. +.. _rfc2217_server: + Pyserial Example Servers ------------------------ @@ -37,7 +41,7 @@ For servers or hardware network/serial adapters which don't support the full RFC These raw sockets don't support setting the baud rate or automatic resetting into the bootloader. If using this mode, don't pass the ``--baud`` option to esptool. You need to set the baud rate manually on the server, and manually reset the chip into the bootloader mode (or use some other signalling/control method to tell the server to do so). -Here's a very basic example using the common Linux/OSX command line "netcat" and "stty" commands: +Here's a very basic example using the common Linux/macOS command line "netcat" and "stty" commands: On server: diff --git a/docs/en/versions.rst b/docs/en/versions.rst index 648701e066..c5d8a1f2f1 100644 --- a/docs/en/versions.rst +++ b/docs/en/versions.rst @@ -13,7 +13,7 @@ There are no support periods defined and bugfixes are not planned, therefore it The following information is directed mainly towards package maintainers. Regular users should always use the most recent version of ``esptool.py`` to benefit from the latest features and bugfixes. -Use the latest esptool (recommended) +Use the Latest Esptool (Recommended) ------------------------------------ If your use case doesn't impose any constraints on ``esptool.py``, the latest release should be always used. @@ -21,7 +21,7 @@ To see the latest available version and its release notes, visit the `release pa To get the latest possible version, simply define your dependency as ``esptool`` (without any release operator and a version identifier). -Use the latest bugfix release of a minor esptool release +Use the Latest Bugfix Release of a Minor Esptool Release -------------------------------------------------------- Some use cases might require a specific ``esptool.py`` version without getting new features, but with automatic bugfixes. @@ -30,19 +30,19 @@ This can be achieved by defining your dependency as ``esptool~=4.0.1`` (explicit This notation selects the latest version of ``esptool.py``, greater than or equal to ``v4.0.1``, but still in the ``v4.0.*`` version (this compatible release clause is approximately equivalent to the pair of comparison clauses ``>= 4.0.1``, ``== 4.0.*``). So, for example, ``v4.1.0`` won't be downloaded. More information about compatible release clauses `can be found here `_. -Use the latest esptool without any future breaking change +Use the Latest Esptool Without Any Future Breaking Change --------------------------------------------------------- If you also want to get new features (instead of just bugfixes), define your version requirement as ``esptool~=4.0`` (explicitly stating only the ``MAJOR`` and ``MINOR`` numbers). This way the latest minor versions (``>= 4.0``, ``== 4.*``) are automatically installed. Backward-compatibility is still ensured, because ``esptool.py`` respects the semantic versioning specification (which states that breaking changes should occur only in ``MAJOR`` versions). -Use the previous major esptool release (only if you cannot upgrade) +Use the Previous Major Esptool Release (Only if You Cannot Upgrade) ------------------------------------------------------------------- If your use case is not compatible with the latest ``MAJOR`` release of ``esptool.py``, a previous compatible version has to be specified. This can be achieved by defining your dependency as ``esptool~=3.0`` (explicitly stating your desired ``MAJOR`` number and at least also the ``MINOR`` number, ``PATCH`` can also be specified). -Use a specific esptool release +Use a Specific Esptool Release ------------------------------ If a very specific release is required, define your dependency as ``esptool==4.1.2``. This specific version will be used and no new features or bugfixes will be automatically installed. diff --git a/esptool/loader.py b/esptool/loader.py index 90246e401a..ee92de6492 100644 --- a/esptool/loader.py +++ b/esptool/loader.py @@ -1066,7 +1066,7 @@ def get_uart_no(self): def uses_usb_jtag_serial(self): """ - Check if the chip uses USB JTAG/SERIAL mode. + Check if the chip uses USB-Serial/JTAG mode. """ return False