From 9cfd4eb879fd72b1ae8b01fd3f2652f1a06c5fd8 Mon Sep 17 00:00:00 2001 From: "RepoBird.ai Agent" Date: Sun, 27 Apr 2025 09:03:05 +0000 Subject: [PATCH 1/2] docs(About-Client-Libraries.rst, About-Composition.rst, About-Different-Middleware-Vendors.rst, Developing-a-ROS-2-Package.rst, Installation-Troubleshooting.rst, Configuring-ROS2-Environment.rst, index.rst): update documentation for clarity and consistency Improve clarity in the documentation by rephrasing several sections across various files. Changes include enhancing the description of the ROS 2 workspace concept, refining the explanation of the default RMW implementation, and improving the instructions for creating a ROS 2 package. Additionally, update the installation troubleshooting section to provide clearer guidance on enabling multicast. Overall, these updates enhance the readability and consistency of the ROS 2 documentation. --- .../Concepts/Basic/About-Client-Libraries.rst | 2 +- .../Intermediate/About-Composition.rst | 15 ++++---- .../About-Different-Middleware-Vendors.rst | 2 +- .../Developing-a-ROS-2-Package.rst | 4 +-- .../Installation-Troubleshooting.rst | 35 +++++++++++-------- .../Configuring-ROS2-Environment.rst | 3 +- source/index.rst | 26 ++++++++------ 7 files changed, 49 insertions(+), 38 deletions(-) diff --git a/source/Concepts/Basic/About-Client-Libraries.rst b/source/Concepts/Basic/About-Client-Libraries.rst index 83202a3807d..9232d5809c9 100644 --- a/source/Concepts/Basic/About-Client-Libraries.rst +++ b/source/Concepts/Basic/About-Client-Libraries.rst @@ -53,7 +53,7 @@ The ``rclpy`` package The ROS Client Library for Python (``rclpy``) is the Python counterpart to the C++ client library. Like the C++ client library, ``rclpy`` also builds on top of the ``rcl`` C API for its implementation. The interface provides an idiomatic Python experience that uses native Python types and patterns like lists and context objects. -By using the ``rcl`` |API| in the implementation, it stays consistent with the other client libraries in terms of feature parity and behavior. +Using the ``rcl`` |API| helps maintain consistency with the other client libraries in terms of feature parity and behavior. In addition to providing Python idiomatic bindings around the ``rcl`` |API| and Python classes for each message, the Python client library takes care of the execution model, using ``threading.Thread`` or similar to run the functions in the ``rcl`` |API|. Like C++ it generates custom Python code for each ROS message that the user interacts with, but unlike C++ it eventually converts the native Python message object into the C version of the message. diff --git a/source/Concepts/Intermediate/About-Composition.rst b/source/Concepts/Intermediate/About-Composition.rst index 6ef546d0945..a9a288c0a5a 100644 --- a/source/Concepts/Intermediate/About-Composition.rst +++ b/source/Concepts/Intermediate/About-Composition.rst @@ -88,14 +88,13 @@ Using Components ---------------- The `composition `__ package contains a couple of different approaches on how to use components. -The three most common ones are: - -#. Start a (`generic container process `__) and call the ROS service `load_node `__ offered by the container. - The ROS service will then load the component specified by the passed package name and library name and start executing it within the running process. - Instead of calling the ROS service programmatically you can also use a `command line tool `__ to invoke the ROS service with the passed command line arguments -#. Create a `custom executable `__ containing multiple nodes which are known at compile time. - This approach requires that each component has a header file (which is not strictly needed for the first case). -#. Create a launch file and use ``ros2 launch`` to create a container process with multiple components loaded. +The composition can occur at: + +* **Compile time**: Create a `custom executable `__ containing multiple nodes which are known at compile time. This approach requires that each component has a header file (which is not strictly needed for the other cases). + +* **Launch time**: Create a launch file and use ``ros2 launch`` to start a container process and load multiple components into it. This often uses the underlying service call mechanism described below. See the :doc:`launching composable nodes <../../How-To-Guides/Launching-composable-nodes>` how-to guide for examples. + +* **Run time**: Start a (`generic container process `__) and then call the ROS service `load_node `__ offered by the container. The ROS service will then load the component specified by the passed package name and library name and start executing it within the running process. Instead of calling the ROS service programmatically you can also use the `ros2 component load `__ command line tool to invoke the ROS service with the passed command line arguments. Practical application --------------------- diff --git a/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst b/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst index 0adf23970c8..45648b2500d 100644 --- a/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst +++ b/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst @@ -81,7 +81,7 @@ Here is a list of inter-vendor communication configurations that are not support Default RMW implementation -------------------------- -If a ROS 2 workspace has multiple RMW implementations, Fast DDS is selected as the default RMW implementation if it is available. +Fast DDS is the default RMW implementation. If the Fast DDS RMW implementation is not installed, the RMW implementation with the first RMW implementation identifier in alphabetical order will be used. The implementation identifier is the name of the ROS package that provides the RMW implementation, e.g. ``rmw_cyclonedds_cpp``. For example, if both ``rmw_cyclonedds_cpp`` and ``rmw_connextdds`` ROS packages are installed, ``rmw_connextdds`` would be the default. diff --git a/source/How-To-Guides/Developing-a-ROS-2-Package.rst b/source/How-To-Guides/Developing-a-ROS-2-Package.rst index 928a8fc4511..c88606fba1e 100644 --- a/source/How-To-Guides/Developing-a-ROS-2-Package.rst +++ b/source/How-To-Guides/Developing-a-ROS-2-Package.rst @@ -32,7 +32,7 @@ All ROS 2 packages begin by running the command $ ros2 pkg create --license Apache-2.0 --dependencies [deps] -in your workspace (usually ``~/ros2_ws/src``). +in your workspace (e.g., ``~/your_project_ws/src``). To create a package for a specific client library: @@ -61,7 +61,7 @@ You will mostly use the ``add_executable()`` CMake macro along with target_link_libraries( PUBLIC [targets from your dependencies]) -to create executable nodes and link dependencies. +to create executable nodes and link dependencies. CMake, when used with `ament_target_dependencies` or similar functions, also automatically manages the necessary include directories for your targets. To install your launch files and nodes, you can use the ``install()`` macro placed towards the end of the file but before the ``ament_package()`` macro. diff --git a/source/How-To-Guides/Installation-Troubleshooting.rst b/source/How-To-Guides/Installation-Troubleshooting.rst index f7cd2307322..2e8dbdddf4c 100644 --- a/source/How-To-Guides/Installation-Troubleshooting.rst +++ b/source/How-To-Guides/Installation-Troubleshooting.rst @@ -43,20 +43,8 @@ If the first command did not return a response similar to: Received from xx.xxx.xxx.xx:43751: 'Hello World!' -then you will need to update your firewall configuration to allow multicast using `ufw `__. - -.. code-block:: console - - $ sudo ufw allow in proto udp to 224.0.0.0/4 - $ sudo ufw allow in proto udp from 224.0.0.0/4 - - -You can check if the multicast flag is enabled for your network interface using the :code:`ifconfig` tool and looking for :code:`MULTICAST` in the flags section: - -.. code-block:: bash - - eno1: flags=4163<...,MULTICAST> - ... +then multicast may not be enabled or properly configured on your system. +If the check above fails, refer to the platform-specific sections below for guidance on enabling multicast and configuring your firewall. Import failing without library present on the system ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -74,6 +62,24 @@ Then, rebuilding the workspace may fix the issue. Linux ----- +Enable multicast +^^^^^^^^^^^^^^^^ + +If the general multicast check fails, you may need to update your firewall configuration to allow multicast using `ufw `__. + +.. code-block:: console + + $ sudo ufw allow in proto udp to 224.0.0.0/4 + $ sudo ufw allow in proto udp from 224.0.0.0/4 + + +You can check if the multicast flag is enabled for your network interface using the :code:`ifconfig` tool and looking for :code:`MULTICAST` in the flags section: + +.. code-block:: bash + + eno1: flags=4163<...,MULTICAST> + ... + Internal compiler error ^^^^^^^^^^^^^^^^^^^^^^^ @@ -247,6 +253,7 @@ To resolve this error, you will need to: rosdep install error ``homebrew: Failed to detect successful installation of [qt5]`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + While following the :doc:`Creating a workspace <../Tutorials/Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace>` tutorial, you might encounter the following error stating that ``rosdep`` fails to install Qt5. .. code-block:: console diff --git a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst index eae0fb57d67..32b5f9655fb 100644 --- a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst +++ b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst @@ -22,8 +22,7 @@ Background ROS 2 relies on the notion of combining workspaces using the shell environment. "Workspace" is a ROS term for the location on your system where you're developing with ROS 2. -The core ROS 2 workspace is called the underlay. -Subsequent local workspaces are called overlays. +Workspaces are often layered on top of each other. When viewing one workspace in relation to another, the base workspace it extends is often called the 'underlay', and the subsequent workspace currently being used or developed is called the 'overlay'. These terms are relative; a workspace could be an overlay relative to the core ROS 2 installation, but an underlay relative to a newer local workspace you create. When developing with ROS 2, you will typically have several workspaces active concurrently. Combining workspaces makes developing against different versions of ROS 2, or against different sets of packages, easier. diff --git a/source/index.rst b/source/index.rst index 5abb8d6af93..b7b3416f695 100644 --- a/source/index.rst +++ b/source/index.rst @@ -12,9 +12,9 @@ ROS 2 Documentation Installation Releases + Concepts Tutorials How-To-Guides - Concepts Contact The-ROS2-Project Package-Docs @@ -27,7 +27,7 @@ ROS 2 Documentation From drivers and state-of-the-art algorithms to powerful developer tools, ROS has the open source tools you need for your next robotics project. Since ROS was started in 2007, a lot has changed in the robotics and ROS community. -The goal of the ROS 2 project is to adapt to these changes, leveraging what is great about ROS 1 and improving what isn't. +The goal of the ROS 2 project is to adapt to these changes, leveraging what is great about ROS 1 and improving what isn\'t. **Are you looking for documentation for a particular ROS package like MoveIt, image_proc, or octomap?** Please see `ROS Index `__ or check out `this index of per-package documentation `__. @@ -44,6 +44,10 @@ Getting started - Instructions to set up ROS 2 for the first time +* :doc:`Concepts ` + + - High-level explanations of core ROS 2 concepts covered in the :doc:`Tutorials ` + * :doc:`Tutorials ` - The best place to start for new users! @@ -54,10 +58,6 @@ Getting started - Quick answers to your "How do I...?" questions without working through the :doc:`Tutorials ` -* :doc:`Concepts ` - - - High-level explanations of core ROS 2 concepts covered in the :doc:`Tutorials ` - * :doc:`Contact ` - Answers to your questions or a forum to start a discussion @@ -66,11 +66,14 @@ Getting started The ROS 2 project ----------------- -If you're interested in the advancement of the ROS 2 project: +Information about the ROS 2 project: * :doc:`Contributing ` - - Best practices and methodology for contributing to ROS 2, as well as instructions for migrating existing ROS 1 content to ROS 2 + - Best practices and methodology for contributing to ROS 2 (including code, documentation, and other content), as well as instructions for migrating existing ROS 1 content to ROS 2 + +Development and Status +~~~~~~~~~~~~~~~~~~~~~~ * :doc:`Distributions ` @@ -92,6 +95,9 @@ If you're interested in the advancement of the ROS 2 project: - Presentations by the community on ROS 2 +Governance and Marketing +~~~~~~~~~~~~~~~~~~~~~~~~ + * :doc:`Project Governance ` - Information about the ROS Technical Steering Committee, Working Groups, and upcoming events @@ -121,8 +127,8 @@ If you need help, have an idea, or would like to contribute to the project, plea - Indexed list of all packages (i.e. `Python Package Index (PyPI) `_ for ROS packages) - See which ROS distributions a package supports - - Link to a package's repository, API documentation, or website - - Inspect a package's license, build type, maintainers, status, and dependencies + - Link to a package\'s repository, API documentation, or website + - Inspect a package\'s license, build type, maintainers, status, and dependencies - Get more info for a package on `Robotics Stack Exchange `__ * `ROS resource status page `__ (ROS 1, ROS 2) From 50a08ad128d1470ed0e0545a03975f851450cfc9 Mon Sep 17 00:00:00 2001 From: "RepoBird.ai Agent" Date: Sat, 3 May 2025 08:29:03 +0000 Subject: [PATCH 2/2] chore(.gitignore, source/Concepts/Intermediate/About-Composition.rst, source/How-To-Guides/Developing-a-ROS-2-Package.rst, source/How-To-Guides/Installation-Troubleshooting.rst, source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst): update documentation and improve .gitignore Add additional entries to .gitignore to ignore common build artifacts and virtual environments. Improve documentation clarity by adjusting formatting in several guides for better readability and understanding. --- .gitignore | 6 ++++ .../Intermediate/About-Composition.rst | 11 ++++-- .../Developing-a-ROS-2-Package.rst | 3 +- .../Installation-Troubleshooting.rst | 36 +++++++++---------- .../Configuring-ROS2-Environment.rst | 4 ++- 5 files changed, 36 insertions(+), 24 deletions(-) diff --git a/.gitignore b/.gitignore index 55a64e39764..975f98b6dd7 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,9 @@ _build/ .vscode/ __pycache__ ros2doc/ + +# --- AI Bot Generated Ignores (DO NOT MANUALLY EDIT BELOW THIS LINE) --- +*.exe +*.so +.venv +.venv/ diff --git a/source/Concepts/Intermediate/About-Composition.rst b/source/Concepts/Intermediate/About-Composition.rst index a9a288c0a5a..8fa19e43853 100644 --- a/source/Concepts/Intermediate/About-Composition.rst +++ b/source/Concepts/Intermediate/About-Composition.rst @@ -90,11 +90,16 @@ Using Components The `composition `__ package contains a couple of different approaches on how to use components. The composition can occur at: -* **Compile time**: Create a `custom executable `__ containing multiple nodes which are known at compile time. This approach requires that each component has a header file (which is not strictly needed for the other cases). +* **Compile time**: Create a `custom executable `__ containing multiple nodes which are known at compile time. + This approach requires that each component has a header file (which is not strictly needed for the other cases). -* **Launch time**: Create a launch file and use ``ros2 launch`` to start a container process and load multiple components into it. This often uses the underlying service call mechanism described below. See the :doc:`launching composable nodes <../../How-To-Guides/Launching-composable-nodes>` how-to guide for examples. +* **Launch time**: Create a launch file and use ``ros2 launch`` to start a container process and load multiple components into it. + This often uses the underlying service call mechanism described below. + See the :doc:`launching composable nodes <../../How-To-Guides/Launching-composable-nodes>` how-to guide for examples. -* **Run time**: Start a (`generic container process `__) and then call the ROS service `load_node `__ offered by the container. The ROS service will then load the component specified by the passed package name and library name and start executing it within the running process. Instead of calling the ROS service programmatically you can also use the `ros2 component load `__ command line tool to invoke the ROS service with the passed command line arguments. +* **Run time**: Start a (`generic container process `__) and then call the ROS service `load_node `__ offered by the container. + The ROS service will then load the component specified by the passed package name and library name and start executing it within the running process. + Instead of calling the ROS service programmatically you can also use the `ros2 component load `__ command line tool to invoke the ROS service with the passed command line arguments. Practical application --------------------- diff --git a/source/How-To-Guides/Developing-a-ROS-2-Package.rst b/source/How-To-Guides/Developing-a-ROS-2-Package.rst index c88606fba1e..8bb32da9c34 100644 --- a/source/How-To-Guides/Developing-a-ROS-2-Package.rst +++ b/source/How-To-Guides/Developing-a-ROS-2-Package.rst @@ -61,7 +61,8 @@ You will mostly use the ``add_executable()`` CMake macro along with target_link_libraries( PUBLIC [targets from your dependencies]) -to create executable nodes and link dependencies. CMake, when used with `ament_target_dependencies` or similar functions, also automatically manages the necessary include directories for your targets. +to create executable nodes and link dependencies. +CMake, when used with `ament_target_dependencies` or similar functions, also automatically manages the necessary include directories for your targets. To install your launch files and nodes, you can use the ``install()`` macro placed towards the end of the file but before the ``ament_package()`` macro. diff --git a/source/How-To-Guides/Installation-Troubleshooting.rst b/source/How-To-Guides/Installation-Troubleshooting.rst index 2e8dbdddf4c..4a1ce606e75 100644 --- a/source/How-To-Guides/Installation-Troubleshooting.rst +++ b/source/How-To-Guides/Installation-Troubleshooting.rst @@ -44,7 +44,23 @@ If the first command did not return a response similar to: Received from xx.xxx.xxx.xx:43751: 'Hello World!' then multicast may not be enabled or properly configured on your system. -If the check above fails, refer to the platform-specific sections below for guidance on enabling multicast and configuring your firewall. + +If the general multicast check fails, you may need to update your firewall configuration. +This is especially common on Linux systems where you can use `ufw `__ to allow multicast. + +.. code-block:: console + + $ sudo ufw allow in proto udp to 224.0.0.0/4 + $ sudo ufw allow in proto udp from 224.0.0.0/4 + + +You can check if the multicast flag is enabled for your network interface using the :code:`ifconfig` tool. +Look for :code:`MULTICAST` in the flags section: + +.. code-block:: bash + + eno1: flags=4163<...,MULTICAST> + ... Import failing without library present on the system ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -62,24 +78,6 @@ Then, rebuilding the workspace may fix the issue. Linux ----- -Enable multicast -^^^^^^^^^^^^^^^^ - -If the general multicast check fails, you may need to update your firewall configuration to allow multicast using `ufw `__. - -.. code-block:: console - - $ sudo ufw allow in proto udp to 224.0.0.0/4 - $ sudo ufw allow in proto udp from 224.0.0.0/4 - - -You can check if the multicast flag is enabled for your network interface using the :code:`ifconfig` tool and looking for :code:`MULTICAST` in the flags section: - -.. code-block:: bash - - eno1: flags=4163<...,MULTICAST> - ... - Internal compiler error ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst index 32b5f9655fb..e8cf051dff0 100644 --- a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst +++ b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst @@ -22,7 +22,9 @@ Background ROS 2 relies on the notion of combining workspaces using the shell environment. "Workspace" is a ROS term for the location on your system where you're developing with ROS 2. -Workspaces are often layered on top of each other. When viewing one workspace in relation to another, the base workspace it extends is often called the 'underlay', and the subsequent workspace currently being used or developed is called the 'overlay'. These terms are relative; a workspace could be an overlay relative to the core ROS 2 installation, but an underlay relative to a newer local workspace you create. +Workspaces are often layered on top of each other. +When viewing one workspace in relation to another, the base workspace it extends is often called the 'underlay', and the subsequent workspace currently being used or developed is called the 'overlay'. +These terms are relative; a workspace could be an overlay relative to the core ROS 2 installation, but an underlay relative to a newer local workspace you create. When developing with ROS 2, you will typically have several workspaces active concurrently. Combining workspaces makes developing against different versions of ROS 2, or against different sets of packages, easier.