1{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp8266="0x0", esp32="0x1000", esp32s2="0x1000", esp32s3="0x0", esp32c3="0x0"} 2 3.. _troubleshooting: 4 5Troubleshooting 6=============== 7 8Flashing problems can be fiddly to troubleshoot. Try the suggestions here if you're having problems: 9 10Bootloader Won't Respond 11------------------------ 12 13If you see errors like "Failed to connect" then your chip is probably not entering the bootloader properly: 14 15* Check you are passing the correct serial port on the command line. 16* Check you have permissions to access the serial port, and other software (such as modem-manager on Linux) is not trying to interact with it. A common pitfall is leaving a serial terminal accessing this port open in another window and forgetting about it. 17* Check the chip is receiving 3.3V from a stable power source (see `Insufficient Power`_ for more details.) 18* Check that all pins are connected as described in :ref:`boot-mode`. Check the voltages at each pin with a multimeter, "high" pins should be close to 3.3V and "low" pins should be close to 0V. 19* If you have connected other devices to GPIO pins, try removing them and see if esptool starts working. 20* Try using a slower baud rate (``-b 9600`` is a very slow value that you can use to verify it's not a baud rate problem). 21 22Writing to Flash Fails Part Way Through 23--------------------------------------- 24 25If flashing fails with random errors part way through, retry with a lower baud rate. 26 27Power stability problems may also cause this (see `Insufficient Power`_.) 28 29Writing to Flash Succeeds but Program Doesn't Run 30------------------------------------------------- 31 32If esptool can flash your module with ``write_flash`` but your program doesn't run, check the following: 33 34Wrong Flash Mode 35^^^^^^^^^^^^^^^^ 36 37Some devices only support the ``dio`` flash mode. Writing to flash with ``qio`` mode will succeed but the chip can't read the flash back to run - so nothing happens on boot. Try passing the ``-fm dio`` option to ``write_flash``. 38 39See the :ref:`spi-flash-modes` page for a full description of the flash modes and how to determine which ones are supported on your device. 40 41Insufficient Power 42^^^^^^^^^^^^^^^^^^ 43 44The 3.3V power supply for the ESP chip has to supply large amounts of current (up to 70mA continuous, 200-300mA peak, might be slightly higher). You also need sufficient capacitance on the power circuit to meet large spikes of power demand. 45 46Insufficient Capacitance 47'''''''''''''''''''''''' 48 49If you're using a pre-made development board or module then the built-in power regulator & capacitors are usually good enough, provided the input power supply is adequate. 50 51.. note:: 52 53 This is not true for some very simple pin breakout modules - `similar to this <https://user-images.githubusercontent.com/205573/30140831-9da417a6-93ba-11e7-95c3-f422744967de.jpg>`_. These breakouts do not integrate enough capacitance to work reliably without additional components. 54 Surface mount OEM modules like ESP-WROOM02 and ESP-WROOM32 require an external bulk capacitor on the PCB to be reliable, consult the module datasheet. 55 56Power Supply Rating 57''''''''''''''''''' 58 59It is possible to have a power supply that supplies enough current for the serial bootloader stage with esptool, but not enough for normal firmware operation. You may see the 3.3V VCC voltage droop down if you measure it with a multimeter, but you can have problems even if this isn't happening. 60 61Try swapping in a 3.3V supply with a higher current rating, add capacitors to the power line, and/or shorten any 3.3V power wires. 62 63The 3.3V output from FTDI FT232R chips/adapters or Arduino boards *do not* supply sufficient current to power an ESP chip (it may seem to work sometimes, but it won't work reliably). Other USB TTL/serial adapters may also be marginal. 64 65Missing Bootloader 66^^^^^^^^^^^^^^^^^^ 67.. only:: esp8266 68 69 The `ESP8266 SDK <https://github.com/espressif/ESP8266_RTOS_SDK>`_ uses a small firmware bootloader program. The hardware bootloader in ROM loads this firmware bootloader from flash, and then it runs the program. 70 On ESP8266, firmware bootloader image (with a filename like ``boot_v1.x.bin``) has to be flashed at offset {IDF_TARGET_BOOTLOADER_OFFSET}. If the firmware bootloader is missing then the ESP8266 will not boot. 71 72 Refer to ESP8266 SDK documentation for details regarding which binaries need to be flashed at which offsets. 73 74.. only:: not esp8266 75 76 `ESP-IDF <https://github.com/espressif/esp-idf>`_ and uses a small firmware bootloader program. The hardware bootloader in ROM loads this firmware bootloader from flash, and then it runs the program. 77 On {IDF_TARGET_NAME}, the bootloader image should be flashed by ESP-IDF at offset {IDF_TARGET_BOOTLOADER_OFFSET}. 78 79 Refer to ESP-IDF documentation for details regarding which binaries need to be flashed at which offsets. 80 81SPI Pins Which Must Be Disconnected 82^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 83 84Compared to the ROM bootloader that esptool talks to, a running firmware uses more of the chip's pins to access the SPI flash. 85 86If you set "Quad I/O" mode (``-fm qio``, the esptool default) then GPIOs 7, 8, 9 & 10 are used for reading the SPI flash and must be otherwise disconnected. 87 88If you set "Dual I/O" mode (``-fm dio``) then GPIOs 7 & 8 are used for reading the SPI flash and must be otherwise disconnected. 89 90Try disconnecting anything from those pins (and/or swap to Dual I/O mode if you were previously using Quad I/O mode but want to attach things to GPIOs 9 & 10). Note that if GPIOs 9 & 10 are also connected to input pins on the SPI flash chip, they may still be unsuitable for use as general purpose I/O. 91 92In addition to these pins, GPIOs 6 & 11 are also used to access the SPI flash (in all modes). However flashing will usually fail completely if these pins are connected incorrectly. 93 94Early Stage Crash 95----------------- 96 97.. only:: esp8266 98 99 Use any of `serial terminal programs`_ to view the boot log. (ESP8266 baud rate is 74880bps). See if the program is crashing during early startup or outputting an error message. 100 101.. only:: not esp8266 102 103 Use any of `serial terminal programs`_ to view the boot log. ({IDF_TARGET_NAME} baud rate is 115200bps). See if the program is crashing during early startup or outputting an error message. 104 105Serial Terminal Programs 106------------------------ 107 108There are many serial terminal programs suitable for debugging & serial interaction. The pySerial module (which is required for ``esptool``) includes one such command line terminal program - miniterm.py. For more details `see the related pySerial documentation <https://pyserial.readthedocs.io/en/latest/tools.html#module-serial.tools.miniterm>`_ or run ``miniterm -h``. 109For exact serial port configuration values, see :ref:`serial-port-settings`. 110 111.. only:: esp8266 112 113 Note that not every serial program supports the unusual ESP8266 74880bps "boot log" baud rate. Support is especially sparse on Linux. miniterm.py supports this baud rate on all platforms. 114 115Tracing Esptool Interactions 116---------------------------- 117 118Running ``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. 119 120See :ref:`the related Advanced Topics page <tracing-communications>` for more information. 121 122Configuration File 123------------------ 124 125Although ``esptool.py`` has been tuned to work in the widest possible range of environments, an incompatible combination of hardware, OS, and drivers might cause it to fail. If you suspect this is the case, a custom configuration of internal variables might be necessary. 126 127These variables and options can be specified in a configuration file. See :ref:`the related Configuration File page <config>` for more information. 128 129Common Errors 130------------- 131 132This is a non-exhaustive list of the most common esptool errors together with explanations of possible causes and fixes. Before reading any error-specific advice, it is highly recommended to go through all of the `Troubleshooting`_ section first. 133 134No serial data received. 135^^^^^^^^^^^^^^^^^^^^^^^^ 136 137Esptool didn't receive any byte of data or a successful :ref:`slip packet <low-level-protocol>`. This error usually implies some kind of a hardware issue. This may be because the hardware is not working properly at all, the RX/TX serial lines are not connected, or because there is some problem with :ref:`resetting into the download mode <boot-mode>`. 138 139.. only:: esp8266 140 141 .. attention:: 142 143 There is a known issue regarding ESP8266 with the CH340 USB-to-serial converter (this includes NodeMCU and Wemos D1 mini devkits) on Linux. The regression affects only certain kernel versions. See `#653 <https://github.com/espressif/esptool/issues/653>`_ for details. 144 145 On ESP8266, this error might be the result of a wrong boot mode. If your devkit supports this, try resetting into the download mode manually. See :ref:`manual-bootloader` for instructions. 146 147.. only:: not esp8266 148 149 Wrong boot mode detected (0xXX)! The chip needs to be in download mode. 150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 151 152 Communication with the chip works (the ROM boot log is detected), but it is not being reset into the download mode automatically. 153 154 To resolve this, check the autoreset circuitry (if your board has it), or try resetting into the download mode manually. See :ref:`manual-bootloader` for instructions. 155 156 Download mode successfully detected, but getting no sync reply: The serial TX path seems to be down. 157 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 158 159 The chip successfully resets into the download mode and sends data to the host computer, but doesn't receive any response sent by ``esptool``. This implies a problem with the TX line running from the host to the ESP device. Double-check your board or breadboard circuit for any problems. 160 161Invalid head of packet (0xXX): Possible serial noise or corruption. 162^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 163 164This error is usually caused by one of the following reasons: 165 166.. list:: 167 168 :esp8266: * The chip is not resetting into the download mode. If the chip runs in a normal boot from flash mode, the ROM writes a log to UART when booting (see :ref:`ESP8266 boot log <boot-log-esp8266>` for more information). This data in the serial buffer result in "Invalid head of packet". You can verify this by connecting with any of `Serial Terminal Programs`_ and seeing what data is the chip sending. If this turns out to be true, check the autoreset circuitry (if your board has it), or try resetting into the download mode manually. See :ref:`manual-bootloader` for instructions. 169 * Using bad quality USB cable. 170 * Sometimes breadboards can short the SPI flash pins on the board and cause this kind of problem. Try removing your development board from the breadboard. 171 * The chip might be browning out during flashing. FTDI chips' internal 3.3V regulator is not enough to power an ESP, see `Insufficient Power`_. 172 173Other things to try: 174 175.. list:: 176 177 * Try to sync and communicate at a much lower baud rate, e.g. ``esptool.py --baud 9600 ...``. 178 * Try `tracing the interactions <Tracing Esptool Interactions>`_ running ``esptool.py --trace ...`` and see if anything is received back at all. 179 * Try skipping chip autodetection by specifying the chip type, run ``esptool.py --chip {IDF_TARGET_NAME} ...``. 180 181If none of the above mentioned fixes help and your problem persists, please `open a new issue <https://github.com/espressif/esptool/issues/new/choose>`_. 182 183A serial exception error occurred 184^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 185 186``esptool.py`` uses the `pySerial <https://pyserial.readthedocs.io/en/latest/>`_ Python module for accessing the serial port. 187If pySerial cannot operate normally, it raises an error and terminates. Some of the most common pySerial error causes are: 188 189.. list:: 190 191 * You don't have permission to access the port. 192 * The port is being already used by other software. 193 * The port doesn't exist. 194 * The device gets unexpectedly disconnected. 195 * The necessary serial port drivers are not installed or are faulty. 196 197An example of a pySerial error: 198 199.. code-block:: none 200 201 A serial exception error occurred: read failed: [Errno 6] Device not configured 202 203Errors originating from pySerial are, therefore, not a problem with ``esptool.py``, but are usually caused by a problem with hardware or drivers. 204
