Make esptool callable as esptool.py even on Unix systems

.github/ISSUE_TEMPLATE/bug-report-no-hw.yml

@@ -37,7 +37,7 @@ body:
     attributes:
       label: Full Esptool Command Line that Was Run
       description: Please input the full esptool command.
-      placeholder: ex. `esptool elf2image esp32-bootloader.elf`
+      placeholder: ex. `esptool.py elf2image esp32-bootloader.elf`
   - type: textarea
     id: output
     attributes:

.github/ISSUE_TEMPLATE/issue-with-hw.yml

@@ -72,7 +72,7 @@ body:
     attributes:
       label: Full Esptool Command Line that Was Run
       description: Please input the full esptool command.
-      placeholder: ex. `esptool -p COM3 write_flash 0x0 bootloader.bin`
+      placeholder: ex. `esptool.py -p COM3 write_flash 0x0 bootloader.bin`
   - type: textarea
     id: output
     attributes:

.github/workflows/test_esptool.yml

@@ -30,9 +30,9 @@ jobs:
 
     - name: Check the installed versions can run
       run: |
-        esptool --help
-        espefuse --help
-        espsecure --help
+        esptool.py --help
+        espefuse.py --help
+        espsecure.py --help
 
     - name: Build stub (Python 3.7 only)
       if: matrix.python-version == 3.7

.gitlab-ci.yml

@@ -30,7 +30,7 @@ version_check:
   only:
     - tags
   script:
-        - VERSION=$(esptool version | head -n 1)
+        - VERSION=$(esptool.py version | head -n 1)
         - |
           if [[ "$VERSION" != *"$CI_COMMIT_TAG" ]]
           then
@@ -90,9 +90,9 @@ check_installation_can_run:
     - coverage run --parallel-mode esptool.py --help
     - coverage run --parallel-mode espefuse.py --help
     - coverage run --parallel-mode espsecure.py --help
-    - esptool --help
-    - espefuse --help
-    - espsecure --help
+    - esptool.py --help
+    - espefuse.py --help
+    - espsecure.py --help
 
 # Check the stub can build and that a stub built in CI has the same contents
 # as the one embedded in esptool

MANIFEST.in

@@ -8,8 +8,3 @@ prune .github
 prune docs
 exclude .git*
 exclude MANIFEST*
-# the following scripts are only compatibility for the older "run from source dir" approach
-# these are not used at all when installing with setup.py or pip
-exclude esptool.py
-exclude espefuse.py
-exclude espsecure.py

README.md

@@ -6,7 +6,7 @@ A Python-based, open-source, platform-independent utility to communicate with th
 
 ## Documentation
 
-Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool -h`.
+Visit the [documentation](https://docs.espressif.com/projects/esptool/) or run `esptool.py -h`.
 
 ## Contribute
 

docs/en/advanced-topics/boot-mode-selection.rst

@@ -297,7 +297,7 @@ Depending on the kind of hardware you have, it may also be possible to manually
    -  ``SPIWP:0xNN`` indicates a custom ``WP`` pin value, which is stored in the bootloader header. This pin value is only used if SPI flash pins have been remapped via efuse (as shown in the ``configsip`` value).
       All custom pin values but WP are encoded in the configsip byte loaded from efuse, and WP is supplied in the bootloader header.
    -  ``clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00`` Custom GPIO drive strength values for SPI flash pins. These are read from the bootloader header in flash. Not currently supported.
-   -  ``mode: AAA, clock div: N``. SPI flash access mode. Read from the bootloader header, correspond to the ``--flash_mode`` and ``--flash_freq`` arguments supplied to ``esptool write_flash`` or ``esptool elf2image``.
+   -  ``mode: AAA, clock div: N``. SPI flash access mode. Read from the bootloader header, correspond to the ``--flash_mode`` and ``--flash_freq`` arguments supplied to ``esptool.py write_flash`` or ``esptool.py elf2image``.
    -  ``mode`` can be DIO, DOUT, QIO, or QOUT. *QIO and QOUT are not supported here*, to boot in a Quad I/O mode the ROM bootloader should load the software bootloader in a Dual I/O mode and then the ESP-IDF software bootloader enables Quad I/O based on the detected flash chip mode.
    -  ``clock div: N`` is the SPI flash clock frequency divider. This is an integer clock divider value from an 80MHz APB clock, based on the supplied ``--flash_freq`` argument (ie 80MHz=1, 40MHz=2, etc).
       The ROM bootloader actually loads the software bootloader at a lower frequency than the flash_freq value. The initial APB clock frequency is equal to the crystal frequency, so with a 40MHz crystal the SPI clock used to load the software bootloader will be half the configured value (40MHz/2=20MHz).
@@ -316,7 +316,7 @@ Depending on the kind of hardware you have, it may also be possible to manually
 
    These entries are printed as the ROM bootloader loads each segment in the software bootloader image. The load address and length of each segment is printed.
 
-   You can compare these values to the software bootloader image by running ``esptool --chip esp32 image_info /path/to/bootloader.bin`` to dump image info including a summary of each segment. Corresponding details will also be found in the bootloader ELF file headers.
+   You can compare these values to the software bootloader image by running ``esptool.py --chip esp32 image_info /path/to/bootloader.bin`` to dump image info including a summary of each segment. Corresponding details will also be found in the bootloader ELF file headers.
 
    If there is a problem with the SPI flash chip addressing mode, the values printed by the bootloader here may be corrupted.
 

docs/en/advanced-topics/firmware-image-format.rst

@@ -1,7 +1,7 @@
 Firmware Image Format
 =====================
 
-This is technical documentation for the firmware image format used by the ROM bootloader. These are the images created by ``esptool elf2image``.
+This is technical documentation for the firmware image format used by the ROM bootloader. These are the images created by ``esptool.py elf2image``.
 
 .. only:: esp8266
 
@@ -60,7 +60,7 @@ The image header is 8 bytes long:
         TODO: Update flash frequency lists to be esp32c2 or esp32h2 specific
 
 esptool.py overrides the 2nd and 3rd (start from 0) bytes according to the SPI flash info provided through command line option, regardless of corresponding bytes from the input .bin file that will be written to address 0x00000.
-So you must provide SPI flash info when running ``esptool write_flash`` command. For example: ``esptool write_flash -ff 80m -fm qio -fs 1MB 0x00000 boot.bin 0x01000 user1.bin``
+So you must provide SPI flash info when running ``esptool.py write_flash`` command. For example: ``esptool.py write_flash -ff 80m -fm qio -fs 1MB 0x00000 boot.bin 0x01000 user1.bin``
 
 .. only:: not esp8266
 

docs/en/advanced-topics/spi-flash-modes.rst

@@ -3,7 +3,7 @@
 SPI Flash Modes
 ===============
 
-The ESP chips support four different SPI flash access modes: DIO, DOUT, QIO & QOUT. These can be set via the ``--flash_mode`` option of ``esptool write_flash``.
+The ESP chips support four different SPI flash access modes: DIO, DOUT, QIO & QOUT. These can be set via the ``--flash_mode`` option of ``esptool.py write_flash``.
 
 These options control how many I/O pins are used for communication with the attached SPI flash chip, and which SPI commands are used.
 
@@ -83,7 +83,7 @@ Why don't qio & qout modes work with my Espressif chip/module?
 It is usually one of the following reasons:
 
 * The WP and HOLD pins of the SPI flash chip are not wired to the correct GPIOs of the Espressif chip. These pins must be connected correctly for quad modes to work, and not all boards/modules connect them at all.
-* The SPI flash chip does not support quad modes. Look up the flash chip datasheet to see which modes it supports. You can identify the flash chip visually, or by using the :ref:`esptool flash_id <read-spi-flash-id>` command.
+* The SPI flash chip does not support quad modes. Look up the flash chip datasheet to see which modes it supports. You can identify the flash chip visually, or by using the :ref:`esptool.py flash_id <read-spi-flash-id>` command.
 * Quad mode is not enabled correctly for this chip model. SPI flash is not a standard, so every manufacturer implements their chip differently. Most flash chips require certain commands to be sent in order to enable Quad SPI modes, and these commands vary.
   For Espressif chips, this often means that the chip first boots in a Dual SPI mode and then software detects the chip type and tries to enable Quad SPI mode.
   If the particular chip model is not supported by the software then it won't be able to enter quad mode.

docs/en/espefuse/index.rst

@@ -18,7 +18,7 @@ Display Efuse Summary
 
 ::
 
-    espefuse --port /dev/ttyUSB1 summary
+    espefuse.py --port /dev/ttyUSB1 summary
 
 The options ``--port`` and ``--before`` can be supplied, and are identical to the :ref:`equivalent esptool options <options>`.
 
@@ -90,7 +90,7 @@ To display raw efuse register values, use the ``dump`` subcommand:
 
 ::
 
-    espefuse --port /dev/ttyUSB1 dump
+    espefuse.py --port /dev/ttyUSB1 dump
     espefuse.py v2.0-dev
     Connecting....
     EFUSE block 0:
@@ -115,7 +115,7 @@ To burn an efuse to a new value, use the ``burn_efuse`` command:
 
 ::
 
-    espefuse --port /dev/ttyUSB0 burn_efuse JTAG_DISABLE 1
+    espefuse.py --port /dev/ttyUSB0 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.
 
@@ -155,7 +155,7 @@ Disable VDD_SDIO Regulator
 
 ::
 
-    espefuse set_flash_voltage OFF
+    espefuse.py set_flash_voltage OFF
 
 Once set:
 
@@ -169,7 +169,7 @@ Fixed 1.8V VDD_SDIO
 
 ::
 
-    espefuse set_flash_voltage 1.8V
+    espefuse.py set_flash_voltage 1.8V
 
 Once set:
 
@@ -183,7 +183,7 @@ Fixed 3.3V VDD_SDIO
 
 ::
 
-    espefuse set_flash_voltage 3.3V
+    espefuse.py set_flash_voltage 3.3V
 
 Once set:
 
@@ -234,7 +234,7 @@ By default, when an encryption key block is burned it is also read and write pro
 
 ::
 
-    espefuse --port /dev/ttyUSB0 burn_key secure_boot keyfile.bin
+    espefuse.py --port /dev/ttyUSB0 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.
@@ -270,7 +270,7 @@ This command is available in ``espefuse.py`` v2.6 and newer.
 
 ::
 
-    espefuse -p PORT burn_block_data --offset 6 BLK3 device_id.bin
+    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.
@@ -335,7 +335,7 @@ Example:
 
 ::
 
-    espefuse --port /dev/SOMEPORT read_protect_efuse KEY_STATUS
+    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.
 
@@ -385,7 +385,7 @@ Execute Efuse Python Script
 
 ::
 
-    espefuse execute_scripts efuse_script1.py efuse_script2.py ...
+    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:
 
@@ -396,14 +396,14 @@ 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 --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_host.py``).
 
 ::
 
-    espefuse execute_scripts efuse_script1.py --do-not-confirm
+    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.
 See how it is done for ``CODING_SCHEME`` when ``get_meaning()`` is called:
@@ -448,7 +448,7 @@ In case you are running the ``execute_scripts`` command from your production scr
 
 ::
 
-    espefuse execute_scripts efuse_script2.py --do-not-confirm --index {index} --configfiles mac_addresses.json  unique_id.json
+    espefuse.py execute_scripts efuse_script2.py --do-not-confirm --index {index} --configfiles mac_addresses.json  unique_id.json
 
 The example of a script to burn custom_mac address and unique_id getting them from configfiles.
 
@@ -496,6 +496,6 @@ The example below shows how to use the two commands ``burn_key_digest`` and ``bu
 
 ::
 
-    espefuse -c esp32c2  \
-                        burn_key_digest secure_images/ecdsa256_secure_boot_signing_key_v2.pem \
-                        burn_key BLOCK_KEY0 images/efuse/128bit_key XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
+    espefuse.py -c esp32c2  \
+                            burn_key_digest secure_images/ecdsa256_secure_boot_signing_key_v2.pem \
+                            burn_key BLOCK_KEY0 images/efuse/128bit_key XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS

docs/en/esptool/advanced-commands.rst

@@ -20,7 +20,7 @@ The ``write_flash`` command always verifies the MD5 hash of data which is writte
 
 ::
 
-    esptool verify_flash --diff yes 0x40000 my_app.elf-0x40000.bin
+    esptool.py verify_flash --diff yes 0x40000 my_app.elf-0x40000.bin
 
 
 The ``--diff yes`` option specifies that if the files are different, the details should be printed to the console.
@@ -41,7 +41,7 @@ The ``dump_mem`` command will dump a region from the chip's memory space to a fi
 
 ::
 
-    esptool dump_mem 0x40000000 65536 iram0.bin
+    esptool.py dump_mem 0x40000000 65536 iram0.bin
 
 .. _load-ram:
 
@@ -52,12 +52,12 @@ The ``load_ram`` command allows the loading of an executable binary image (creat
 
 ::
 
-    esptool --no-stub load_ram ./test/images/helloworld-esp8266.bin
+    esptool.py --no-stub load_ram ./test/images/helloworld-esp8266.bin
 
 .. note::
 
     * The binary image must only contain IRAM- and DRAM-resident segments. Any SPI flash mapped segments will not load correctly and the image will probably crash. The ``image_info`` command can be used to check the binary image contents.
-    * Because the software loader is resident in IRAM and DRAM, this limits the region where a new program may be loaded. An error will be printed if the new program overlaps with the software loader in RAM. Older esptool versions may hang. Pass ``esptool --no-stub`` to avoid this problem.
+    * Because the software loader is resident in IRAM and DRAM, this limits the region where a new program may be loaded. An error will be printed if the new program overlaps with the software loader in RAM. Older esptool versions may hang. Pass ``esptool.py --no-stub`` to avoid this problem.
     * Due to a limitation in the ROM loader, when using ``--no-stub`` any very early serial output from a program may be lost if the program resets or reconfigures the UART. To avoid this problem, a program can be compiled with ``ets_delay_us(1)`` as the very first statement after the entry point.
 
 .. _read-mem-write-mem:
@@ -69,11 +69,11 @@ The ``read_mem`` & ``write_mem`` commands allow reading and writing single words
 
 ::
 
-    esptool write_mem 0x400C0000 0xabad1dea
+    esptool.py write_mem 0x400C0000 0xabad1dea
 
 ::
 
-    esptool read_mem 0x400C0000
+    esptool.py read_mem 0x400C0000
 
 .. _read-flash-status:
 
@@ -84,7 +84,7 @@ This command is intended for use when debugging hardware flash chip-related prob
 
 ::
 
-    esptool read_flash_status --bytes 2
+    esptool.py read_flash_status --bytes 2
 
 The ``--bytes`` argument determines how many status register bytes are read.
 
@@ -105,7 +105,7 @@ This command is intended for use when debugging hardware flash chip-related prob
 
 ::
 
-    esptool write_flash_status --bytes 2 --non-volatile 0
+    esptool.py write_flash_status --bytes 2 --non-volatile 0
 
 The ``--bytes`` option is similar to the corresponding option for ``read_flash_status`` and causes a mix of ``WRSR`` (01h), ``WRSR2`` (31h), and ``WRSR3`` (11h) commands to be sent to the chip. If ``--bytes 2`` is used then ``WRSR`` is sent first with a 16-bit argument and then with an 8-bit argument, as different flash chips use this command differently.
 Otherwise, each command is accompanied by 8-bits of the new status register value.
@@ -129,11 +129,11 @@ The ``chip_id`` command allows you to read a 4 byte ID which forms part of the M
 
 ::
 
-    esptool chip_id
+    esptool.py chip_id
 
 On ESP8266, output is the same as the ``system_get_chip_id()`` SDK function. The chip ID is four bytes long, the lower three bytes are the final bytes of the MAC address. The upper byte is zero.
 
-On ESP32, there is no ``system_get_chip_id()`` function and this command is the same as ``esptool read_mac``.
+On ESP32, there is no ``system_get_chip_id()`` function and this command is the same as ``esptool.py read_mac``.
 
 .. only:: esp8266
 
@@ -146,7 +146,7 @@ On ESP32, there is no ``system_get_chip_id()`` function and this command is the
 
     ::
 
-        esptool --chip esp8266 make_image -f app.text.bin -a 0x40100000 -f app.data.bin -a 0x3ffe8000 -f app.rodata.bin -a 0x3ffe8c00 app.flash.bin
+        esptool.py --chip esp8266 make_image -f app.text.bin -a 0x40100000 -f app.data.bin -a 0x3ffe8000 -f app.rodata.bin -a 0x3ffe8c00 app.flash.bin
 
     This command does not require a serial connection.
 

docs/en/esptool/advanced-options.rst

@@ -52,7 +52,7 @@ Passing ``--no-stub`` will disable certain options, as not all options are imple
 
     The optional ``--spi-connection`` argument overrides the SPI flash connection configuration on ESP32. 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.
 
-    Supply the ``--spi-connection`` argument after the ``esptool`` command, ie ``esptool flash_id --spi-connection HSPI``.
+    Supply the ``--spi-connection`` argument after the ``esptool.py`` command, ie ``esptool.py flash_id --spi-connection HSPI``.
 
     Default Behavior
     ^^^^^^^^^^^^^^^^