Invoking esptool from PlatformIO Core CLI?

When I invoke esptool from the Platformio CLI with:

python C:\Users\Acer\.platformio\packages\tool-esptoolpy\esptool.py --help

all help is listed as expected. But if I invoke esptool with:

platformio pkg exec --package "platformio/tool-esptoolpy" -- esptool.py --help

or with:

platformio pkg exec -- esptool.py --help

the response is only:

Using tool-esptoolpy@1.30300.0 package

and help is not listed.

  1. Why is there such a difference in the output when using the very same option?

  2. How can the path to esptool.py be permanently added to the PlatformIO CLI %path% so I could just type:

esptool.py --help

This works for me (tested on macOS + Windows)

pio pkg exec -p "tool-esptoolpy" -- esptool.py --help

Here is the command and the response I am getting on Windows:

>pio pkg exec -p "tool-esptoolpy" -- esptool.py --help
Using tool-esptoolpy@1.30300.0 package

There are the following folders in .platformio\packages:

tool-esptool
tool-esptoolpy
tool-esptoolpy@1.30000.201119

Only this works:

>python C:\Users\Acer\.platformio\packages\tool-esptoolpy\esptool.py --help
usage: esptool [-h] [--chip {auto,esp8266,esp32,esp32s2,esp32s3beta2,esp32s3,esp32c3,esp32c6beta,esp32h2beta1,esp32h2beta2,esp32c2}] [--port PORT] [--baud BAUD]
               [--before {default_reset,usb_reset,no_reset,no_reset_no_sync}] [--after {hard_reset,soft_reset,no_reset,no_reset_stub}] [--no-stub] [--trace] [--override-vddsdio [{1.8V,1.9V,OFF}]]
               [--connect-attempts CONNECT_ATTEMPTS]
               {load_ram,dump_mem,read_mem,write_mem,write_flash,run,image_info,make_image,elf2image,read_mac,chip_id,flash_id,read_flash_status,write_flash_status,read_flash,verify_flash,erase_flash,erase_region,merge_bin,get_security_info,version}
               ...

esptool.py v3.3 - Espressif chips ROM Bootloader Utility

positional arguments:
  {load_ram,dump_mem,read_mem,write_mem,write_flash,run,image_info,make_image,elf2image,read_mac,chip_id,flash_id,read_flash_status,write_flash_status,read_flash,verify_flash,erase_flash,erase_region,merge_bin,get_security_info,version}
                        Run esptool {command} -h for additional help
    load_ram            Download an image to RAM and execute
    dump_mem            Dump arbitrary memory to disk
    read_mem            Read arbitrary memory location
    write_mem           Read-modify-write to arbitrary memory location
    write_flash         Write a binary blob to flash
    run                 Run application code in flash
    image_info          Dump headers from an application image
    make_image          Create an application image from binary files
    elf2image           Create an application image from ELF file
    read_mac            Read MAC address from OTP ROM
    chip_id             Read Chip ID from OTP ROM
    flash_id            Read SPI flash manufacturer and device ID
    read_flash_status   Read SPI flash status register
    write_flash_status  Write SPI flash status register
    read_flash          Read SPI flash content
    verify_flash        Verify a binary blob against flash
    erase_flash         Perform Chip Erase on SPI flash
    erase_region        Erase a region of the flash
    merge_bin           Merge multiple raw binary files into a single file for later flashing
    get_security_info   Get some security-related data
    version             Print esptool version

options:
  -h, --help            show this help message and exit
  --chip {auto,esp8266,esp32,esp32s2,esp32s3beta2,esp32s3,esp32c3,esp32c6beta,esp32h2beta1,esp32h2beta2,esp32c2}, -c {auto,esp8266,esp32,esp32s2,esp32s3beta2,esp32s3,esp32c3,esp32c6beta,esp32h2beta1,esp32h2beta2,esp32c2}
                        Target chip type
  --port PORT, -p PORT  Serial port device
  --baud BAUD, -b BAUD  Serial port baud rate used when flashing/reading
  --before {default_reset,usb_reset,no_reset,no_reset_no_sync}
                        What to do before connecting to the chip
  --after {hard_reset,soft_reset,no_reset,no_reset_stub}, -a {hard_reset,soft_reset,no_reset,no_reset_stub}
                        What to do after esptool.py is finished
  --no-stub             Disable launching the flasher stub, only talk to ROM bootloader. Some features will not be available.
  --trace, -t           Enable trace-level output of esptool.py interactions.
  --override-vddsdio [{1.8V,1.9V,OFF}]
                        Override ESP32 VDDSDIO internal voltage regulator (use with care)
  --connect-attempts CONNECT_ATTEMPTS
                        Number of attempts to connect, negative or 0 for infinite. Default: 7.

Output on my Windows 10 machine

>pio pkg exec -p "tool-esptoolpy" -- esptool.py --help
Using tool-esptoolpy@4.7.2 package
usage: esptool [-h]
               [--chip {auto,esp8266,esp32,esp32s2,esp32s3beta2,esp32s3,esp32c3,esp32c6beta,esp32h2beta1,esp32h2beta2,esp32c2,esp32c6,esp32c61,esp32c5,esp32c5beta3,esp32h2,esp32p4}]
               [--port PORT] [--baud BAUD] [--before {default_reset,usb_reset,no_reset,no_reset_no_sync}]
               [--after {hard_reset,soft_reset,no_reset,no_reset_stub}] [--no-stub] [--trace]
               [--override-vddsdio [{1.8V,1.9V,OFF}]] [--connect-attempts CONNECT_ATTEMPTS]
               {load_ram,dump_mem,read_mem,write_mem,write_flash,run,image_info,make_image,elf2image,read_mac,chip_id,flash_id,read_flash_status,write_flash_status,read_flash,verify_flash,erase_flash,erase_region,merge_bin,get_security_info,version}
               ...

esptool.py v4.7.2 - Espressif chips ROM Bootloader Utility

positional arguments:
  {load_ram,dump_mem,read_mem,write_mem,write_flash,run,image_info,make_image,elf2image,read_mac,chip_id,flash_id,read_flash_status,write_flash_status,read_flash,verify_flash,erase_flash,erase_region,merge_bin,get_security_info,version}

(Core 6.1.15a1)

I have the latest stable core version:

>pio upgrade
You're up-to-date!
PlatformIO 6.1.14 is currently the newest version available.

but the esptoolpy version seems much older than yours. How is that possible?

You are trying to invoke ancient esptoolpy. Try the following command:

pio pkg exec -p "tool-esptoolpy@1.40501.0" -- esptool.py --help

This was the output after the very first run:

>pio pkg exec -p "tool-esptoolpy@1.40501.0" -- esptool.py --help
Tool Manager: Installing tool-esptoolpy @ 1.40501.0
Downloading  [####################################]  100%
Unpacking  [####################################]  100%
Tool Manager: tool-esptoolpy@1.40501.0 has been installed!
Using tool-esptoolpy@1.40501.0 package

and this is the output after the new version has been installed:

>pio pkg exec -p "tool-esptoolpy@1.40501.0" -- esptool.py --help
Using tool-esptoolpy@1.40501.0 package

>platformio pkg exec -- esptool.py --help
Using tool-esptoolpy@1.40501.0 package

The help is still not showing in the output.

The folders in .platformio\packages are now:

tool-esptool
tool-esptoolpy                   <-- this is probaby the new version
tool-esptoolpy@1.30000.201119    <-- before, this was probably tool-esptoolpy
tool-esptoolpy@1.30300.0