ESP8266-RTOS-SDK release v3.4

# esptool.py A Python-based, open source, platform independent, utility to communicate with the ROM bootloader in Espressif ESP8266 & ESP32 chips. esptool.py was started by Fredrik Ahlberg (@[themadinventor](https://github.com/themadinventor/)) as an unofficial community project. It is now also supported by Espressif. Current primary maintainer is Angus Gratton (@[projectgus](https://github.com/projectgus/)). esptool.py is Free Software under a GPLv2 license. [](https://travis-ci.org/espressif/esptool) ## Installation / dependencies ### Easy Installation You will need [either Python 2.7 or Python 3.4 or newer](https://www.python.org/downloads/) installed on your system. The latest stable esptool.py release can be installed from [pypi](http://pypi.python.org/pypi/esptool) via pip: ``` $ pip install esptool ``` With some Python installations this may not work and you'll receive an error, try `python -m pip install esptool` or `pip2 install esptool`. After installing, you will have `esptool.py` installed into the default Python executables directory and you should be able to run it with the command `esptool.py`. ### Manual Installation Manual installation allows you to run the latest development version from this repository. esptool.py depends on [pySerial](https://github.com/pyserial/pyserial#readme) version 2.5 or newer for serial communication with the target device. If you choose to install esptool.py system-wide by running `python setup.py install`, then this will be taken care of automatically. If not using `setup.py`, then you'll have to install pySerial manually by running something like `pip install pyserial`, `easy_install pyserial` or `apt-get install python-serial`, depending on your platform. (The official pySerial installation instructions are [here](https://pyserial.readthedocs.org/en/latest/pyserial.html#installation)). esptool.py also bundles the pyaes & ecdsa Python modules as "vendored" libraries. These modules are required when using the ESP32-only `espsecure.py` and `espefuse.py` tools. If you install esptool.py via `pip` or `setup.py` as shown above, then versions of these libraries will be installed from pypi. If you run esptool.py from the repository directory directly, it will use the "vendored" versions. ## Usage Use `esptool.py -h` to see a summary of all available commands and command line options. To see all options for a particular command, append `-h` to the command name. ie `esptool.py write_flash -h`. ## Common Options ### Serial Port * The serial port is selected using the `-p` option, like `-p /dev/ttyUSB0` (Linux and macOS) or `-p COM1` (Windows). * A default serial port can be specified by setting the `ESPTOOL_PORT` environment variable. * If no `-p` option or `ESPTOOL_PORT` value is specified, `esptool.py` will enumerate all connected serial ports and try each one until it finds an Espressif device connected (new behaviour in v2.4.0). Note: Windows and macOS may require drivers to be installed for a particular USB/serial adapter, before a serial port is available. Consult the documentation for your particular device. On macOS, you can also consult [System Information](https://support.apple.com/en-us/HT203001)'s list of USB devices to identify the manufacturer or device ID when the adapter is plugged in. On Windows, you can use [Windows Update or Device Manager](https://support.microsoft.com/en-us/help/15048/windows-7-update-driver-hardware-not-working-properly) to find a driver. If using Cygwin or WSL on Windows, you have to convert the Windows-style name into an Unix-style path (`COM1` -> `/dev/ttyS0`, and so on). (This is not necessary if using esp-idf for ESP32 with the supplied Windows MSYS2 environment, this environment uses a native Windows Python which accepts COM ports as-is.) In Linux, the current user may not have access to serial ports and a "Permission Denied" error will appear. On most Linux distributions, the solution is to add the user to the `dialout` group with a command like `sudo usermod -a -G dialout <USERNAME>`. Check your Linux distribution's documentation for more information. ### Baud rate The default esptool.py baud rate is 115200bps. Different rates may be set using `-b 921600` (or another baudrate of your choice). A default baud rate can also be specified using the `ESPTOOL_BAUD` environment variable. This can speed up `write_flash` and `read_flash` operations. The baud rate is limited to 115200 when esptool.py establishes the initial connection, higher speeds are only used for data transfers. Most hardware configurations will work with `-b 230400`, some with `-b 460800`, `-b 921600` and/or `-b 1500000` or higher. If you have connectivity problems then you can also set baud rates below 115200. You can also choose 74880, which is the usual baud rate used by the ESP8266 to output [boot log](#boot-log) information. ## Commands ### Write binary data to flash: write_flash Binary data can be written to the ESP's flash chip via the serial `write_flash` command: ``` esptool.py --port COM4 write_flash 0x1000 my_app-0x01000.bin ``` Multiple flash addresses and file names can be given on the same command line: ``` esptool.py --port COM4 write_flash 0x00000 my_app.elf-0x00000.bin 0x40000 my_app.elf-0x40000.bin ``` The `--chip` argument is optional when writing to flash, esptool will detect the type of chip when it connects to the serial port. The `--port` argument is documented under [Serial Port](#serial-port). The next arguments to write_flash are one or more pairs of offset (address) and file name. When generating ESP8266 "version 1" images, the file names created by `elf2image` include the flash offsets as part of the file name. For other types of images, consult your SDK documentation to determine the files to flash at which offsets. Numeric values passed to write_flash (and other commands) can be specified either in hex (ie 0x1000), or in decimal (ie 4096). See the [Troubleshooting](#troubleshooting) section if the write_flash command is failing, or the flashed module fails to boot. #### Setting flash mode and size You may also need to specify arguments for [flash mode and flash size](#flash-modes), if you wish to override the defaults. For example: ``` esptool.py --port /dev/ttyUSB0 write_flash --flash_mode qio --flash_size 32m 0x0 bootloader.bin 0x1000 my_app.bin ``` Since esptool v2.0, these options are not often needed as the default is to keep the flash mode and size from the `.bin` image file, and to detect the flash size. See the [Flash Modes](#flash-modes) section for more details. #### Compression By default, the serial transfer data is compressed for better performance. The `-u/--no-compress` option disables this behaviour. ### Read Flash Contents: read_flash The read_flash command allows reading back the contents of flash. The arguments to the command are an address, a size, and a filename to dump the output to. For example, to read a full 2MB of attached flash: ``` ./esptool.py -p PORT -b 460800 read_flash 0 0x200000 flash_contents.bin ``` (Note that if `write_flash` updated the boot image's [flash mode and flash size](#flash-modes) during flashing then these bytes may be different when read back.) ### Erase Flash: erase_flash & erase region To erase the entire flash chip (all data replaced with 0xFF bytes): ``` esptool.py erase_flash ``` To erase a region of the flash, starting at address 0x20000 with length 0x4000 bytes (16KB): ``` esptool.py erase_region 0x20000 0x4000 ``` The address and length must both be multiples of the SPI flash erase sector size. This is 0x1000 (4096) bytes for supported flash chips. ### Read built-in MAC address: read_mac ``` esptool.py read_mac ``` ### Read SPI flash id: flash_id ``` esptool.py flash_id ``` Example output: ``` Manufacturer: e0 Device: 4016 Detected flash size: 4MB ``` Refer to [flashrom source code](h