From 9cc213289dafd20a6df3e15ce99fb0562bf1d921 Mon Sep 17 00:00:00 2001 From: Jakub Kocka Date: Wed, 11 Oct 2023 08:27:11 +0200 Subject: [PATCH] docs(get-started): Adjusteded docs flashing part to be more user friendly Closes https://github.com/espressif/esp-idf/issues/12366 --- docs/en/get-started/establish-serial-connection.rst | 4 ++-- docs/en/get-started/start-project.rst | 9 +++++---- docs/zh_CN/get-started/establish-serial-connection.rst | 4 ++-- docs/zh_CN/get-started/start-project.rst | 9 +++++---- 4 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst index 7ad7c1b0b9..4b961b885d 100644 --- a/docs/en/get-started/establish-serial-connection.rst +++ b/docs/en/get-started/establish-serial-connection.rst @@ -229,8 +229,8 @@ macOS :: .. _linux-dialout-group: -Adding User to ``dialout`` on Linux ------------------------------------ +Adding User to ``dialout`` or ``uucp`` on Linux +----------------------------------------------- The currently logged user should have read and write access the serial port over USB. On most Linux distributions, this is done by adding the user to ``dialout`` group with the following command:: diff --git a/docs/en/get-started/start-project.rst b/docs/en/get-started/start-project.rst index 2f385387c6..89610ac9b0 100644 --- a/docs/en/get-started/start-project.rst +++ b/docs/en/get-started/start-project.rst @@ -53,7 +53,7 @@ For more information on ``idf.py`` arguments, see :ref:`idf.py`. The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary. -Encountered Issues While Flashing? See this :doc:`flashing-troubleshooting` page or :doc:`establish-serial-connection` for more detailed information. +Encountered Issues While Flashing? See the "Additional Tips" below. You can also refer to :doc:`flashing-troubleshooting` page or :doc:`establish-serial-connection` for more detailed information. Normal Operation ~~~~~~~~~~~~~~~~ @@ -444,13 +444,14 @@ Now you are ready to try some other :idf:`examples`, or go straight to developin If building an example, please check the README file for the ``Supported Targets`` table. If this is present including {IDF_TARGET_NAME} target, or the table does not exist at all, the example will work on {IDF_TARGET_NAME}. + Additional Tips =============== -Permission Issues ``/dev/ttyUSB0`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Permission Denied Issue +~~~~~~~~~~~~~~~~~~~~~~~~ -With some Linux distributions, you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the dialout group `. +With some Linux distributions, you may get the error message similar to ``Could not open port : Permission denied: ''`` when flashing the {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the specific group `, such as ``dialout`` or ``uucp`` group. Python Compatibility ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/zh_CN/get-started/establish-serial-connection.rst b/docs/zh_CN/get-started/establish-serial-connection.rst index 38fcc9b890..bd6efd1049 100644 --- a/docs/zh_CN/get-started/establish-serial-connection.rst +++ b/docs/zh_CN/get-started/establish-serial-connection.rst @@ -229,8 +229,8 @@ macOS:: .. _linux-dialout-group: -在 Linux 中添加用户到 ``dialout`` ------------------------------------ +在 Linux 中添加用户到 ``dialout`` 或 ``uucp`` 组 +-------------------------------------------------- 当前登录用户应当可以通过 USB 对串口进行读写操作。在多数 Linux 版本中，都可以通过以下命令，将用户添加到 ``dialout`` 组，从而获许读写权限:: diff --git a/docs/zh_CN/get-started/start-project.rst b/docs/zh_CN/get-started/start-project.rst index b21daeb56b..b2f46b1f53 100644 --- a/docs/zh_CN/get-started/start-project.rst +++ b/docs/zh_CN/get-started/start-project.rst @@ -53,7 +53,7 @@ 勾选 ``flash`` 选项将自动编译并烧录工程，因此无需再运行 ``idf.py build``。 -若在烧录过程中遇到问题，请前往 :doc:`flashing-troubleshooting` 或 :doc:`establish-serial-connection` 获取更多详细信息。 +若在烧录过程中遇到问题，请参考下文中的“其他提示”。也可以前往 :doc:`flashing-troubleshooting` 或 :doc:`establish-serial-connection` 获取更多详细信息。 常规操作 ~~~~~~~~~~~~~~~~ @@ -444,13 +444,14 @@ 在编译示例程序前请查看 README 文件中 ``Supported Targets`` 表格。如果表格中包含 {IDF_TARGET_NAME}， 或者不存在这个表格，那么即表示 {IDF_TARGET_NAME} 支持这个示例程序。 + 其他提示 =============== -权限问题 /dev/ttyUSB0 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +权限问题 +~~~~~~~~~~~~~~~~~~~~~ -使用某些 Linux 版本向 {IDF_TARGET_NAME} 烧录固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时可以将用户添加至 :ref:`Linux Dialout 组`。 +使用某些 Linux 版本向 {IDF_TARGET_NAME} 烧录固件时，可能会出现类似 ``Could not open port : Permission denied: ''`` 错误消息。此时可以在 Linux 将用户添加至 :ref:`dialout 组或 uucp 组` 来解决此类问题。 兼容的 Python 版本 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~