feat: Readable error message for serial-related issues

docs/en/troubleshooting.rst

@@ -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.

esptool/__init__.py

@@ -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__":