espressif/esptool
1
0
Fork 0
mirror of https://github.com/espressif/esptool.git synced 2025-10-15 21:07:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: Readable error message for serial-related issues

Browse Source
This commit is contained in:
radim.karnis
2022-10-04 13:38:01 +02:00
parent 6fac2611d1
commit 1082852703
2 changed files with 39 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/en/troubleshooting.rst
View File

@@ -105,7 +105,7 @@ Early Stage Crash
Serial Terminal Programs
------------------------
There 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``.
There 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``.
For exact serial port configuration values, see :ref:`serial-port-settings`.
.. only:: esp8266
@@ -172,3 +172,25 @@ Other things to try:
* 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 <https://github.com/espressif/esptool/issues/new/choose>`_.
A serial exception error occurred
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``esptool.py`` uses the `pySerial <https://pyserial.readthedocs.io/en/latest/>`_ Python module for accessing the serial port.
If pySerial cannot operate normally, it raises an error and terminates. Some of the most common pySerial error causes are:
.. list::
* You don't have permission to access the port.
* The port is being already used by other software.
* The port doesn't exist.
* The device gets unexpectedly disconnected.
* The necessary serial port drivers are not installed or are faulty.
An example of a pySerial error:
.. code-block:: none
A serial exception error occurred: read failed: [Errno 6] Device not configured
Errors originating from pySerial are, therefore, not a problem with ``esptool.py``, but are usually caused by a problem with hardware or drivers.

18
esptool/__init__.py
View File

@@ -65,13 +65,15 @@ from esptool.cmds import (
write_mem,
)
from esptool.loader import DEFAULT_CONNECT_ATTEMPTS, ESPLoader, list_ports
from esptool.targets import CHIP_DEFS, CHIP_LIST, ESP32ROM, ESP8266ROM
from esptool.targets import CHIP_DEFS, CHIP_LIST, ESP32ROM
from esptool.util import (
FatalError,
NotImplementedInROMError,
flash_size_bytes,
)
import serial
def main(argv=None, esp=None):
"""
@@ -1023,8 +1025,20 @@ def _main():
try:
main()
except FatalError as e:
print("\nA fatal error occurred: %s" % e)
print(f"\nA fatal error occurred: {e}")
sys.exit(2)
except serial.serialutil.SerialException as e:
print(f"\nA serial exception error occurred: {e}")
print(
"Note: This error originates from pySerial. "
"It is likely not a problem with esptool, "
"but with the hardware connection or drivers."
)
print(
"For troubleshooting steps visit: "
"https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html"
)
sys.exit(1)
if __name__ == "__main__":