From 30821a3f936e13e178afb0bd0e9ff21b5b68e970 Mon Sep 17 00:00:00 2001 From: "radim.karnis" Date: Thu, 5 May 2022 13:45:43 +0200 Subject: [PATCH] Make esptool callable as esptool.py even on Unix systems --- .github/ISSUE_TEMPLATE/bug-report-no-hw.yml | 2 +- .github/ISSUE_TEMPLATE/issue-with-hw.yml | 2 +- .github/workflows/test_esptool.yml | 6 ++-- .gitlab-ci.yml | 8 ++--- MANIFEST.in | 5 --- README.md | 2 +- .../advanced-topics/boot-mode-selection.rst | 4 +-- .../advanced-topics/firmware-image-format.rst | 4 +-- docs/en/advanced-topics/spi-flash-modes.rst | 4 +-- docs/en/espefuse/index.rst | 32 +++++++++---------- docs/en/esptool/advanced-commands.rst | 22 ++++++------- docs/en/esptool/advanced-options.rst | 2 +- docs/en/esptool/basic-commands.rst | 30 ++++++++--------- docs/en/esptool/flash-modes.rst | 2 +- docs/en/esptool/flasher-stub.rst | 2 +- docs/en/esptool/index.rst | 4 +-- docs/en/esptool/remote-serial-ports.rst | 4 +-- docs/en/index.rst | 8 +---- docs/en/troubleshooting.rst | 8 ++--- esp_rfc2217_server.py | 4 +-- espefuse.py | 10 ++++++ espefuse/__init__.py | 2 +- espsecure.py | 10 ++++++ espsecure/__init__.py | 2 +- esptool.py | 10 ++++++ esptool/__init__.py | 2 +- setup.py | 25 ++++++++++----- test/test_imagegen.py | 2 +- 28 files changed, 123 insertions(+), 95 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug-report-no-hw.yml b/.github/ISSUE_TEMPLATE/bug-report-no-hw.yml index a874d4974..48dd290a7 100644 --- a/.github/ISSUE_TEMPLATE/bug-report-no-hw.yml +++ b/.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: diff --git a/.github/ISSUE_TEMPLATE/issue-with-hw.yml b/.github/ISSUE_TEMPLATE/issue-with-hw.yml index dc5742b06..d31956525 100644 --- a/.github/ISSUE_TEMPLATE/issue-with-hw.yml +++ b/.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: diff --git a/.github/workflows/test_esptool.yml b/.github/workflows/test_esptool.yml index 1f694e093..cc36c64bf 100644 --- a/.github/workflows/test_esptool.yml +++ b/.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 diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 598fe26b7..8ca3da05b 100644 --- a/.gitlab-ci.yml +++ b/.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 diff --git a/MANIFEST.in b/MANIFEST.in index 70e3d084b..74be5e981 100644 --- a/MANIFEST.in +++ b/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 diff --git a/README.md b/README.md index c5a3e31bb..afb83bc19 100644 --- a/README.md +++ b/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 diff --git a/docs/en/advanced-topics/boot-mode-selection.rst b/docs/en/advanced-topics/boot-mode-selection.rst index ac24d3d36..d8d99a7b6 100644 --- a/docs/en/advanced-topics/boot-mode-selection.rst +++ b/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. diff --git a/docs/en/advanced-topics/firmware-image-format.rst b/docs/en/advanced-topics/firmware-image-format.rst index 67f26c5c7..b82223f69 100644 --- a/docs/en/advanced-topics/firmware-image-format.rst +++ b/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 diff --git a/docs/en/advanced-topics/spi-flash-modes.rst b/docs/en/advanced-topics/spi-flash-modes.rst index a0c9be10b..22b54766d 100644 --- a/docs/en/advanced-topics/spi-flash-modes.rst +++ b/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 ` 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 ` 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. diff --git a/docs/en/espefuse/index.rst b/docs/en/espefuse/index.rst index 8c0929951..9f2e81951 100644 --- a/docs/en/espefuse/index.rst +++ b/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 `. @@ -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 diff --git a/docs/en/esptool/advanced-commands.rst b/docs/en/esptool/advanced-commands.rst index 6eb4e22f2..c178d934c 100644 --- a/docs/en/esptool/advanced-commands.rst +++ b/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. diff --git a/docs/en/esptool/advanced-options.rst b/docs/en/esptool/advanced-options.rst index bf1727b7e..8d8b8e483 100644 --- a/docs/en/esptool/advanced-options.rst +++ b/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 ^^^^^^^^^^^^^^^^ diff --git a/docs/en/esptool/basic-commands.rst b/docs/en/esptool/basic-commands.rst index b391c5f47..abdd08bc7 100644 --- a/docs/en/esptool/basic-commands.rst +++ b/docs/en/esptool/basic-commands.rst @@ -10,13 +10,13 @@ Binary data can be written to the ESP's flash chip via the serial ``write_flash` :: - esptool --port COM4 write_flash 0x1000 my_app-0x01000.bin + esptool.py --port COM4 write_flash 0x1000 my_app-0x01000.bin Multiple flash addresses and file names can be given on the same command line: :: - esptool --port COM4 write_flash 0x00000 my_app.elf-0x00000.bin 0x40000 my_app.elf-0x40000.bin + esptool.py --port COM4 write_flash 0x00000 my_app.elf-0x00000.bin 0x40000 my_app.elf-0x40000.bin The ``--chip`` argument is optional when writing to flash, esptool will detect the type of chip when it connects to the serial port. @@ -42,7 +42,7 @@ You may also need to specify arguments for :ref:`flash mode and flash size `. +There might be cases where it is necessary to disable the stub loader (e.g. debugging). To do that, run ``esptool.py`` with the ``--no-stub`` argument. All operations will then be handled by the original ROM bootloader. See the related :ref:`advanced options page `. diff --git a/docs/en/esptool/index.rst b/docs/en/esptool/index.rst index 2a7714d84..5614bb368 100644 --- a/docs/en/esptool/index.rst +++ b/docs/en/esptool/index.rst @@ -3,9 +3,9 @@ esptool.py ========== -Use ``esptool -h`` to see a summary of all available commands and command line options. +Use ``esptool.py -h`` to see a summary of all available commands and command line options. -To see all options for a particular command, append ``-h`` to the command name. ie ``esptool write_flash -h``. +To see all options for a particular command, append ``-h`` to the command name. ie ``esptool.py write_flash -h``. .. toctree:: :maxdepth: 1 diff --git a/docs/en/esptool/remote-serial-ports.rst b/docs/en/esptool/remote-serial-ports.rst index 21ae811be..73743faaa 100644 --- a/docs/en/esptool/remote-serial-ports.rst +++ b/docs/en/esptool/remote-serial-ports.rst @@ -5,7 +5,7 @@ It is possible to connect to any networked remote serial port that supports `RFC :: - esptool --port rfc2217://192.168.1.77:4000 flash_id + esptool.py --port rfc2217://192.168.1.77:4000 flash_id Custom baud rates and DTR/RTS automatic resetting are supported over the RFC2217 protocol, the same as for a local serial port. @@ -27,7 +27,7 @@ On client: :: - esptool --port rfc2217://ADDRESS_OF_SERVER:4000?ign_set_control flash_id + esptool.py --port rfc2217://ADDRESS_OF_SERVER:4000?ign_set_control flash_id Raw Sockets diff --git a/docs/en/index.rst b/docs/en/index.rst index 85d8c5980..718003933 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -33,16 +33,10 @@ Getting started is easy: :: - $ esptool -p PORT flash_id + $ esptool.py -p PORT flash_id Replace ``PORT`` with the name of used serial port. If connection fails, see :ref:`troubleshooting`. -.. note:: - - Starting from v4.0, ``esptool.py`` is run simply as ``$ esptool -h``, on the command-line. The same applies to ``espefuse.py`` and ``espsecure.py``. - - The ``.py`` extension is only used when reffering to the tools in a written documentation. - More Information ---------------- diff --git a/docs/en/troubleshooting.rst b/docs/en/troubleshooting.rst index 791a57b52..7b08512e4 100644 --- a/docs/en/troubleshooting.rst +++ b/docs/en/troubleshooting.rst @@ -115,7 +115,7 @@ For exact serial port configuration values, see :ref:`serial-port-settings`. Tracing Esptool Interactions ---------------------------- -Running ``esptool --trace`` will dump all serial interactions to the standard output (this is *a lot* of output). This can be helpful when debugging issues with the serial connection, or when providing information for bug reports. +Running ``esptool.py --trace`` will dump all serial interactions to the standard output (this is *a lot* of output). This can be helpful when debugging issues with the serial connection, or when providing information for bug reports. See :ref:`the related Advanced Topics page ` for more information. @@ -167,8 +167,8 @@ Other things to try: .. list:: - * Try to sync and communicate at a much lower baud rate, e.g. ``esptool --baud 9600 ...``. - * Try `tracing the interactions `_ running ``esptool --trace ...`` and see if anything is received back at all. - * Try skipping chip autodetection by specifying the chip type, run ``esptool --chip {IDF_TARGET_NAME} ...``. + * Try to sync and communicate at a much lower baud rate, e.g. ``esptool.py --baud 9600 ...``. + * Try `tracing the interactions `_ running ``esptool.py --trace ...`` and see if anything is received back at all. + * Try skipping chip autodetection by specifying the chip type, run ``esptool.py --chip {IDF_TARGET_NAME} ...``. If none of the above mentioned fixes help and your problem persists, please `open a new issue `_. diff --git a/esp_rfc2217_server.py b/esp_rfc2217_server.py index d5ae8413d..891a561d0 100755 --- a/esp_rfc2217_server.py +++ b/esp_rfc2217_server.py @@ -19,7 +19,7 @@ # Esptool can connect to the ESP device through that server as it is # demonstrated in the following example: # -# esptool --port rfc2217://localhost:4000?ign_set_control flash_id +# esptool.py --port rfc2217://localhost:4000?ign_set_control flash_id # ################################################################################### # redirect data from a TCP/IP connection to a serial port and vice versa @@ -91,7 +91,7 @@ def _setRTS(self, state): def _reset_thread(self): """ - The reset logic is used from esptool because the RTS and DTR signals + The reset logic is used from esptool.py because the RTS and DTR signals cannot be retransmitted through RFC 2217 with proper timing. """ if self.logger: diff --git a/espefuse.py b/espefuse.py index c58b38eef..6dccc706a 100644 --- a/espefuse.py +++ b/espefuse.py @@ -12,6 +12,16 @@ # then this file is not used at all, # it's compatibility for the older "run from source dir" espefuse approach. +# Linux/macOS: remove current script directory to avoid importing this file +# as a module; we want to import the installed espefuse module instead +import contextlib +import os +import sys + +with contextlib.suppress(ValueError): + if os.name != "nt": + sys.path.remove(os.path.dirname(sys.executable)) + import espefuse if __name__ == "__main__": diff --git a/espefuse/__init__.py b/espefuse/__init__.py index c9ad3dc4f..76308d6ec 100755 --- a/espefuse/__init__.py +++ b/espefuse/__init__.py @@ -224,7 +224,7 @@ def main(custom_commandline=None): parser = argparse.ArgumentParser(parents=[init_parser]) subparsers = parser.add_subparsers( - dest="operation", help="Run espefuse {command} -h for additional help" + dest="operation", help="Run espefuse.py {command} -h for additional help" ) efuse_operations.add_commands(subparsers, efuses) diff --git a/espsecure.py b/espsecure.py index 4d1698f7b..f948fa013 100755 --- a/espsecure.py +++ b/espsecure.py @@ -12,6 +12,16 @@ # then this file is not used at all, # it's compatibility for the older "run from source dir" espsecure approach. +# Linux/macOS: remove current script directory to avoid importing this file +# as a module; we want to import the installed espsecure module instead +import contextlib +import os +import sys + +with contextlib.suppress(ValueError): + if os.name != "nt": + sys.path.remove(os.path.dirname(sys.executable)) + import espsecure if __name__ == "__main__": diff --git a/espsecure/__init__.py b/espsecure/__init__.py index 77b895f19..ea6fd8b80 100755 --- a/espsecure/__init__.py +++ b/espsecure/__init__.py @@ -1198,7 +1198,7 @@ def main(custom_commandline=None): ) subparsers = parser.add_subparsers( - dest="operation", help="Run espsecure {command} -h for additional help" + dest="operation", help="Run espsecure.py {command} -h for additional help" ) p = subparsers.add_parser( diff --git a/esptool.py b/esptool.py index 9f5d62ee4..896db349d 100755 --- a/esptool.py +++ b/esptool.py @@ -11,6 +11,16 @@ # If esptool is installed via setup.py or pip then this file is not used at all, # it's compatibility for the older "run from source dir" esptool approach. +# Linux/macOS: remove current script directory to avoid importing this file +# as a module; we want to import the installed esptool module instead +import contextlib +import os +import sys + +with contextlib.suppress(ValueError): + if os.name != "nt": + sys.path.remove(os.path.dirname(sys.executable)) + import esptool if __name__ == "__main__": diff --git a/esptool/__init__.py b/esptool/__init__.py index f06406cf4..50c5e2f8d 100644 --- a/esptool/__init__.py +++ b/esptool/__init__.py @@ -165,7 +165,7 @@ def main(argv=None, esp=None): ) subparsers = parser.add_subparsers( - dest="operation", help="Run esptool {command} -h for additional help" + dest="operation", help="Run esptool.py {command} -h for additional help" ) def add_spi_connection_arg(parent): diff --git a/setup.py b/setup.py index 7b77591e0..87c301b41 100644 --- a/setup.py +++ b/setup.py @@ -39,6 +39,20 @@ def find_version(*file_paths): raise RuntimeError("Unable to find version string.") +if os.name != "nt": + scripts = ["esptool.py", "espefuse.py", "espsecure.py"] + entry_points = {} +else: + scripts = [] + entry_points = { + "console_scripts": [ + "esptool.py=esptool.__init__:_main", + "espsecure.py=espsecure.__init__:_main", + "espefuse.py=espefuse.__init__:_main", + ], + } + + long_description = """ ========== esptool.py @@ -51,7 +65,7 @@ def find_version(*file_paths): Documentation ------------- Visit online `esptool documentation `_ \ -or run ``esptool -h``. +or run ``esptool.py -h``. Contributing ------------ @@ -112,11 +126,6 @@ def find_version(*file_paths): "reedsolo>=1.5.3,<=1.5.4", ], packages=find_packages(), - entry_points={ - "console_scripts": [ - "esptool=esptool.__init__:_main", - "espsecure=espsecure.__init__:_main", - "espefuse=espefuse.__init__:_main", - ], - }, + entry_points=entry_points, + scripts=scripts, ) diff --git a/test/test_imagegen.py b/test/test_imagegen.py index 23536fefb..a8115c9ac 100755 --- a/test/test_imagegen.py +++ b/test/test_imagegen.py @@ -115,7 +115,7 @@ def assertImageContainsSection(self, image, elf, section_name): def assertImageInfo(self, binpath, chip="esp8266"): """ - Run esptool image_info on a binary file, + Run esptool.py image_info on a binary file, assert no red flags about contents. """ cmd = [sys.executable, ESPTOOL_PY, "--chip", chip, "image_info", binpath]