diff --git a/source/Concepts/Basic/About-Client-Libraries.rst b/source/Concepts/Basic/About-Client-Libraries.rst index 1079ece209d..9780e0320c7 100644 --- a/source/Concepts/Basic/About-Client-Libraries.rst +++ b/source/Concepts/Basic/About-Client-Libraries.rst @@ -77,7 +77,8 @@ While the C++ and Python client libraries are maintained by the core ROS 2 team, * `C `__ ``rclc`` does not put a layer on top of rcl but complements rcl to make rcl+rclc a feature-complete client library in C. See `micro.ros.org `__ for tutorials. * `JVM and Android `__ Java and Android bindings for ROS 2. * `.NET Core, UWP and C# `__ This is a collection of projects (bindings, code generator, examples and more) for writing ROS 2 applications for .NET Core and .NET Standard. -* `Node.js `__ rclnodejs is a Node.js client for ROS 2. It provides a simple and easy JavaScript API for ROS 2 programming. +* `Node.js `__ rclnodejs is a Node.js client for ROS 2. + It provides a simple and easy JavaScript API for ROS 2 programming. * `Rust `__ This is a set of projects (the rclrs client library, code generator, examples and more) that enables developers to write ROS 2 applications in Rust. * `Flutter and Dart `__ Flutter and Dart bindings for ROS 2. diff --git a/source/Concepts/Basic/About-Interfaces.rst b/source/Concepts/Basic/About-Interfaces.rst index 228fc1789f6..ed72f28c0c9 100644 --- a/source/Concepts/Basic/About-Interfaces.rst +++ b/source/Concepts/Basic/About-Interfaces.rst @@ -18,9 +18,13 @@ This description makes it easy for ROS tools to automatically generate source co In this document we will describe the supported types: -* msg: ``.msg`` files are simple text files that describe the fields of a ROS message. They are used to generate source code for messages in different languages. -* srv: ``.srv`` files describe a service. They are composed of two parts: a request and a response. The request and response are message declarations. -* action: ``.action`` files describe actions. They are composed of three parts: a goal, a result, and feedback. +* msg: ``.msg`` files are simple text files that describe the fields of a ROS message. + They are used to generate source code for messages in different languages. +* srv: ``.srv`` files describe a service. + They are composed of two parts: a request and a response. + The request and response are message declarations. +* action: ``.action`` files describe actions. + They are composed of three parts: a goal, a result, and feedback. Each part is a message declaration itself. Messages diff --git a/source/Concepts/Basic/About-Parameters.rst b/source/Concepts/Basic/About-Parameters.rst index e0f535e1e2d..d2f5a00ce65 100644 --- a/source/Concepts/Basic/About-Parameters.rst +++ b/source/Concepts/Basic/About-Parameters.rst @@ -89,11 +89,14 @@ The services that are created by default are: * ``/node_name/get_parameters``: Uses a service type of ``rcl_interfaces/srv/GetParameters``. Given a list of parameter names, returns a list of parameter values associated with the parameters. * ``/node_name/list_parameters``: Uses a service type of ``rcl_interfaces/srv/ListParameters``. - Given an optional list of parameter prefixes, returns a list of the available parameters with that prefix. If the prefixes are empty, returns all parameters. + Given an optional list of parameter prefixes, returns a list of the available parameters with that prefix. + If the prefixes are empty, returns all parameters. * ``/node_name/set_parameters``: Uses a service type of ``rcl_interfaces/srv/SetParameters``. - Given a list of parameter names and values, attempts to set the parameters on the node. Returns a list of results from trying to set each parameter; some of them may have succeeded and some may have failed. + Given a list of parameter names and values, attempts to set the parameters on the node. + Returns a list of results from trying to set each parameter; some of them may have succeeded and some may have failed. * ``/node_name/set_parameters_atomically``: Uses a service type of ``rcl_interfaces/srv/SetParametersAtomically``. - Given a list of parameter names and values, attempts to set the parameters on the node. Returns a single result from trying to set all parameters, so if one failed, all of them failed. + Given a list of parameter names and values, attempts to set the parameters on the node. + Returns a single result from trying to set all parameters, so if one failed, all of them failed. Setting initial parameter values when running a node ---------------------------------------------------- diff --git a/source/Concepts/Basic/About-Topics.rst b/source/Concepts/Basic/About-Topics.rst index 16560d43f40..23081a69b03 100644 --- a/source/Concepts/Basic/About-Topics.rst +++ b/source/Concepts/Basic/About-Topics.rst @@ -48,4 +48,7 @@ That has two meanings in this context: Then the code will ensure that ``field1`` is always an unsigned integer and that ``field2`` is always a string. -2. The semantics of each field are well-defined. There is no automated mechanism to ensure this, but all of the core ROS types have strong semantics associated with them. For instance, the IMU message contains a 3-dimensional vector for the measured angular velocity, and each of the dimensions is specified to be in radians/second. Other interpretations should not be placed into the message. +2. The semantics of each field are well-defined. + There is no automated mechanism to ensure this, but all of the core ROS types have strong semantics associated with them. + For instance, the IMU message contains a 3-dimensional vector for the measured angular velocity, and each of the dimensions is specified to be in radians/second. + Other interpretations should not be placed into the message. diff --git a/source/Concepts/Intermediate/About-Cross-Compilation.rst b/source/Concepts/Intermediate/About-Cross-Compilation.rst index 91f1eb743c8..d70eb66e664 100644 --- a/source/Concepts/Intermediate/About-Cross-Compilation.rst +++ b/source/Concepts/Intermediate/About-Cross-Compilation.rst @@ -22,7 +22,9 @@ How does it work ? Cross-compiling simple software (e.g. no dependencies on external libraries) is relatively simple and only requiring a cross-compiler toolchain to be used instead of the native toolchain. There are a number of factors which make this process more complex: - - The software being built must support the target architecture. Architecture specific code must be properly isolated and enabled during the build according to the target architecture. Examples include assembly code. + - The software being built must support the target architecture. + Architecture specific code must be properly isolated and enabled during the build according to the target architecture. + Examples include assembly code. - All dependencies (e.g. libraries) must be present, either as pre-built or cross-compiled packages, before the target software using them is cross-compiled. - When building software stacks (as opposed to standalone software) using build tools (e.g. colcon), it is expected that the build tool provides a mechanism to allow the developer to enable cross-compilation on the underlying build system used by each piece of software in the stack. diff --git a/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst b/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst index 8c1b9ae4338..47ad1d950f5 100644 --- a/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst +++ b/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst @@ -37,19 +37,24 @@ Supported RMW implementations * - eProsima *Fast DDS* - Apache 2 - ``rmw_fastrtps_cpp`` - - Full support. Default RMW. Packaged with binary releases. + - Full support. + Default RMW. + Packaged with binary releases. * - Eclipse *Cyclone DDS* - Eclipse Public License v2.0 - ``rmw_cyclonedds_cpp`` - - Full support. Packaged with binary releases. + - Full support. + Packaged with binary releases. * - RTI *Connext DDS* - commercial, research - ``rmw_connextdds`` - - Full support. Support included in binaries, but Connext installed separately. + - Full support. + Support included in binaries, but Connext installed separately. * - GurumNetworks *GurumDDS* - commercial - ``rmw_gurumdds_cpp`` - - Community support. Support included in binaries, but GurumDDS installed separately. + - Community support. + Support included in binaries, but GurumDDS installed separately. For practical information on working with multiple RMW implementations, see the :doc:`"Working with multiple RMW implementations" <../../How-To-Guides/Working-with-multiple-RMW-implementations>` tutorial. diff --git a/source/Concepts/Intermediate/About-Executors.rst b/source/Concepts/Intermediate/About-Executors.rst index cbc4cb5d945..9be900cb881 100644 --- a/source/Concepts/Intermediate/About-Executors.rst +++ b/source/Concepts/Intermediate/About-Executors.rst @@ -163,7 +163,8 @@ The following flow diagram visualizes this scheduling semantics. .. image:: ../images/executors_scheduling_semantics.png This semantics was first described in a `paper by Casini et al. at ECRTS 2019 `_. -(Note: The paper also explains that timer events are prioritized over all other messages. `This prioritization was removed in Eloquent. `_) +(Note: The paper also explains that timer events are prioritized over all other messages. +`This prioritization was removed in Eloquent. `_) Outlook @@ -193,6 +194,12 @@ These issues have been partially addressed by the following developments: Further information ------------------- -* Michael Pöhnl et al.: `"ROS 2 Executor: How to make it efficient, real-time and deterministic?" `_. Workshop at ROS World 2021. Virtual event. 19 October 2021. -* Ralph Lange: `"Advanced Execution Management with ROS 2" `_. ROS Industrial Conference. Virtual event. 16 December 2020. +* Michael Pöhnl et al.: `"ROS 2 Executor: How to make it efficient, real-time and deterministic?" `_. + Workshop at ROS World 2021. + Virtual event. + 19 October 2021. +* Ralph Lange: `"Advanced Execution Management with ROS 2" `_. + ROS Industrial Conference. + Virtual event. + 16 December 2020. * Daniel Casini, Tobias Blass, Ingo Lütkebohle, and Björn Brandenburg: `“Response-Time Analysis of ROS 2 Processing Chains under Reservation-Based Scheduling” `_, Proc. of 31st ECRTS 2019, Stuttgart, Germany, July 2019. diff --git a/source/Contact.rst b/source/Contact.rst index 888aa74160d..8340376e3b5 100644 --- a/source/Contact.rst +++ b/source/Contact.rst @@ -57,9 +57,14 @@ When filing an issue, please make sure to: Describe exactly what you were doing or are trying to do, and exactly what, if anything, went wrong. If following a tutorial or online instructions provide a link to the specific instructions. -* Use a descriptive headline or subject line. Bad: "rviz doesn't work". Good: "Rviz crashing looking for missing .so after latest apt update" -* Include information about the exact platform, software, versions, and environment relevant to the problem. This includes how you installed the software (from binaries or from source) and which ROS middleware/DDS vendor you are using (if you know it). -* Any warnings or errors. Cut and paste them directly from the terminal window to which they were printed. Please do not re-type or include a screenshot. +* Use a descriptive headline or subject line. + Bad: "rviz doesn't work". + Good: "Rviz crashing looking for missing .so after latest apt update" +* Include information about the exact platform, software, versions, and environment relevant to the problem. + This includes how you installed the software (from binaries or from source) and which ROS middleware/DDS vendor you are using (if you know it). +* Any warnings or errors. + Cut and paste them directly from the terminal window to which they were printed. + Please do not re-type or include a screenshot. * In case of a bug consider providing a `short, self contained, correct (compilable), example `__. * When discussing any compiling/linking/installation issues, also provide the compiler version diff --git a/source/Glossary.rst b/source/Glossary.rst index 48e0ad31592..7fa6ecc9343 100644 --- a/source/Glossary.rst +++ b/source/Glossary.rst @@ -8,7 +8,11 @@ Glossary of terms used throughout this documentation: .. glossary:: API - An API, or Application Programming Interface, is an interface that is provided by an "application", which in this case is usually a shared library or other language appropriate shared resource. APIs are made up of files that define a contract between the software using the interface and the software providing the interface. These files typically manifest as header files in C and C++ and as Python files in Python. In either case it is important that APIs are grouped and described in documentation and that they are declared as either public or private. Public interfaces are subject to change rules and changes to the public interfaces prompt a new version number of the software that provides them. + An API, or Application Programming Interface, is an interface that is provided by an "application", which in this case is usually a shared library or other language appropriate shared resource. + APIs are made up of files that define a contract between the software using the interface and the software providing the interface. + These files typically manifest as header files in C and C++ and as Python files in Python. + In either case it is important that APIs are grouped and described in documentation and that they are declared as either public or private. + Public interfaces are subject to change rules and changes to the public interfaces prompt a new version number of the software that provides them. client_library A client library is an :term:`API` that provides access to the ROS graph using primitive middleware concepts like Topics, Services, and Actions. @@ -17,7 +21,8 @@ Glossary of terms used throughout this documentation: A single unit of software, including source code, build system files, documentation, tests, and other associated resources. REP - ROS Enhancement Proposal. A document that describes an enhancement, standardization, or convention for the ROS community. + ROS Enhancement Proposal. + A document that describes an enhancement, standardization, or convention for the ROS community. The associated REP approval process allows the community to iterate on a proposal until some consensus has been made, at which point it can be ratified and implemented, which then becomes documentation. All REPs are viewable from the `REP index `_. @@ -25,7 +30,8 @@ Glossary of terms used throughout this documentation: Version Control System, such as CVS, SVN, git, mercurial, etc... rclcpp - The C++ specific :term:`Client Library ` for ROS. This includes any middleware related APIs as well as the related message generation of C++ data structures based on interface definitions like Messages, Services, and Actions. + The C++ specific :term:`Client Library ` for ROS. + This includes any middleware related APIs as well as the related message generation of C++ data structures based on interface definitions like Messages, Services, and Actions. repository A collection of packages usually managed using a :term:`VCS` like git or mercurial and usually hosted on a site like GitHub or BitBucket. diff --git a/source/How-To-Guides/Ament-CMake-Documentation.rst b/source/How-To-Guides/Ament-CMake-Documentation.rst index 32242743e59..97bc8ec40b7 100644 --- a/source/How-To-Guides/Ament-CMake-Documentation.rst +++ b/source/How-To-Guides/Ament-CMake-Documentation.rst @@ -323,7 +323,8 @@ One example of how to do so can be found in the `ament_cmake_lint_cmake document Testing ^^^^^^^ -Ament contains CMake macros to simplify setting up GTests. Call: +Ament contains CMake macros to simplify setting up GTests. +Call: .. code-block:: cmake @@ -348,7 +349,9 @@ The macros have additional parameters: - ``ENV``: set environment variables (same syntax as ``APPEND_ENV``). -- ``TIMEOUT``: set a test timeout in second. The default for GTests is 60 seconds. For example: +- ``TIMEOUT``: set a test timeout in second. + The default for GTests is 60 seconds. + For example: .. code-block:: cmake @@ -550,7 +553,8 @@ For the RViz mesh resource, the corresponding choices were: - ``rviz_ogre_media_exports`` as name of the resource, -- install path relative paths to all folders containing resources. This will already enable you to write the logic for using the corresponding resource in your package. +- install path relative paths to all folders containing resources. + This will already enable you to write the logic for using the corresponding resource in your package. To allow users to easily register resources for your package, you should furthermore provide macros or functions such as the pluginlib function or ``rviz_ogre_media_exports`` function. diff --git a/source/How-To-Guides/Ament-CMake-Python-Documentation.rst b/source/How-To-Guides/Ament-CMake-Python-Documentation.rst index ccb1bcf9283..34eceaf8156 100644 --- a/source/How-To-Guides/Ament-CMake-Python-Documentation.rst +++ b/source/How-To-Guides/Ament-CMake-Python-Documentation.rst @@ -63,8 +63,8 @@ In this case, it is ``my_project``, or ``${PROJECT_NAME}``. .. warning:: Calling ``rosidl_generate_interfaces`` and ``ament_python_install_package`` in the same CMake project does not work. - See this `Github issue `_ for more info. It is best practice to instead - separate out the message generation into a separate package. + See this `Github issue `_ for more info. + It is best practice to instead separate out the message generation into a separate package. Then, another Python package that correctly depends on ``my_project`` can use it as a normal Python module: diff --git a/source/How-To-Guides/DDS-tuning.rst b/source/How-To-Guides/DDS-tuning.rst index 79014a6b238..e2c0f7c1843 100644 --- a/source/How-To-Guides/DDS-tuning.rst +++ b/source/How-To-Guides/DDS-tuning.rst @@ -163,7 +163,8 @@ However, it always at least managed to complete the delivery. **Solution:** Use the `Connext QoS profile `_ *without* adjusting ``rmem_max``. -The ROS2TEST_QOS_PROFILES.xml file was configured using RTI’s documentation on `configuring flow controllers `_. It has slow, medium and fast flow controllers (seen in the Connext QoS profile link). +The ROS2TEST_QOS_PROFILES.xml file was configured using RTI’s documentation on `configuring flow controllers `_. +It has slow, medium and fast flow controllers (seen in the Connext QoS profile link). The medium flow controller produced the best results for our case. However, the controllers will still need to be tuned for the particular machine/network/environment they are operating in. diff --git a/source/How-To-Guides/Installation-Troubleshooting.rst b/source/How-To-Guides/Installation-Troubleshooting.rst index e1faee17226..459a9322a46 100644 --- a/source/How-To-Guides/Installation-Troubleshooting.rst +++ b/source/How-To-Guides/Installation-Troubleshooting.rst @@ -66,7 +66,8 @@ If so, compare the libraries present in the directory with the one mentioned in Assuming a file with a similar name exists (same prefix like ``_rclpy.`` and same suffix like ``.so`` but a different Python version / architecture) you are using a different Python interpreter than which was used to build the C extension. Be sure to use the same Python interpreter as the one used to build the binary. -For example, such a mismatch can crop up after an update of the OS. Then, rebuilding the workspace may fix the issue. +For example, such a mismatch can crop up after an update of the OS. +Then, rebuilding the workspace may fix the issue. .. _linux-troubleshooting: @@ -289,7 +290,8 @@ Use this information to install additional dependencies or adjust your path as n CMake error setting modification time ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you run into the CMake error ``file INSTALL cannot set modification time on ...`` when installing files it is likely that an anti virus software or Windows Defender are interfering with the build. E.g. for Windows Defender you can list the workspace location to be excluded to prevent it from scanning those files. +If you run into the CMake error ``file INSTALL cannot set modification time on ...`` when installing files it is likely that an anti virus software or Windows Defender are interfering with the build. +E.g. for Windows Defender you can list the workspace location to be excluded to prevent it from scanning those files. 260 character path limit ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -323,7 +325,8 @@ patch.exe opens a new command window and asks for administrator This will also cause the build of packages which need to use patch to fail, even you allow it to use administrator rights. -- ``choco uninstall patch; colcon build --cmake-clean-cache`` - This is a bug in the `GNU Patch For Windows package `_. If this package is not installed, the build process will instead use the version of Patch distributed with git. +- ``choco uninstall patch; colcon build --cmake-clean-cache`` - This is a bug in the `GNU Patch For Windows package `_. + If this package is not installed, the build process will instead use the version of Patch distributed with git. Failed to load Fast RTPS shared library ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/How-To-Guides/Installing-on-Raspberry-Pi.rst b/source/How-To-Guides/Installing-on-Raspberry-Pi.rst index 9ee39dcbac7..a774526819a 100644 --- a/source/How-To-Guides/Installing-on-Raspberry-Pi.rst +++ b/source/How-To-Guides/Installing-on-Raspberry-Pi.rst @@ -29,7 +29,8 @@ After flashing the OS, `install Docker `__. -You may choose from ros-core, ros-base, or perception. See `here `__ for more information on these variants. +You may choose from ros-core, ros-base, or perception. +See `here `__ for more information on these variants. Fetch and run an image: diff --git a/source/How-To-Guides/ROS-2-IDEs.rst b/source/How-To-Guides/ROS-2-IDEs.rst index 157a80603b6..99fb66a4b4c 100644 --- a/source/How-To-Guides/ROS-2-IDEs.rst +++ b/source/How-To-Guides/ROS-2-IDEs.rst @@ -47,7 +47,8 @@ So: #. Create your ROS workspace as you would normally. #. In a terminal, source both ROS 2 and your install (if it was built already). -#. Start VSCode from the same command line. The terminal will be blocked until the application is closed again. +#. Start VSCode from the same command line. + The terminal will be blocked until the application is closed again. .. tabs:: @@ -172,7 +173,8 @@ Instead, some settings need to be tweaked. #. Create your ROS workspace as you would normally. #. Start PyCharm normally. -#. Open a project. This should be the root directory of the ROS node you're developing, e.g. ``C:\dev_ws\src\my_node``. +#. Open a project. + This should be the root directory of the ROS node you're developing, e.g. ``C:\dev_ws\src\my_node``. #. Click "Add new interpreter" > "Add local interpreter...". Select a system interpreter (or virtual environment if you're using one) and select the executable of your ROS Python version (typically ``C:\Python38\python.exe``). diff --git a/source/How-To-Guides/Releasing/Index-Your-Packages.rst b/source/How-To-Guides/Releasing/Index-Your-Packages.rst index 2249586273f..4a1716ff195 100644 --- a/source/How-To-Guides/Releasing/Index-Your-Packages.rst +++ b/source/How-To-Guides/Releasing/Index-Your-Packages.rst @@ -70,9 +70,15 @@ For each ROS distribution you want to release into: Here's how to fill out each item: -* YOUR-REPO-NAME: This is an arbitrary human-readable name. For repos hosted on GitHub, use the lowercase name of your repository not including the organization. For example, the repository name of ``https://github.com/ros2/rosidl`` is ``rosidl``. -* YOUR-GIT-REPO-URL: This is the https URL from which one could ``git clone`` your repository. For example, the git repo URL of ``https://github.com/ros2/rosidl`` is ``https://github.com/ros2/rosidl.git``. It is important that this URL ends in ``.git``, or it will fail to pass the linters. -* YOUR-BRANCH-NAME: This is the git branch on your repository from which you will release your package into this ROS distribution. This is commonly one of: ``main``, ``master``, or the name of the ROS distribution itself. For example, the `rosidl repository `__ uses the branch ``rolling`` to hold changes to be released into ROS Rolling. +* YOUR-REPO-NAME: This is an arbitrary human-readable name. + For repos hosted on GitHub, use the lowercase name of your repository not including the organization. + For example, the repository name of ``https://github.com/ros2/rosidl`` is ``rosidl``. +* YOUR-GIT-REPO-URL: This is the https URL from which one could ``git clone`` your repository + For example, the git repo URL of ``https://github.com/ros2/rosidl`` is ``https://github.com/ros2/rosidl.git``. + It is important that this URL ends in ``.git``, or it will fail to pass the linters. +* YOUR-BRANCH-NAME: This is the git branch on your repository from which you will release your package into this ROS distribution. + This is commonly one of: ``main``, ``master``, or the name of the ROS distribution itself. + For example, the `rosidl repository `__ uses the branch ``rolling`` to hold changes to be released into ROS Rolling. * YOUR-STATUS: This is a status from the list in `REP 141 `__. You likely want either ``maintained`` or ``developed``. Open a pull request to ros/rosdistro diff --git a/source/How-To-Guides/Run-2-nodes-in-single-or-separate-docker-containers.rst b/source/How-To-Guides/Run-2-nodes-in-single-or-separate-docker-containers.rst index b327094d8fb..717ec107ab5 100644 --- a/source/How-To-Guides/Run-2-nodes-in-single-or-separate-docker-containers.rst +++ b/source/How-To-Guides/Run-2-nodes-in-single-or-separate-docker-containers.rst @@ -58,13 +58,15 @@ Run a minimal example of 2 C++ nodes (1 topic subscriber ``listener``, 1 topic p Run two nodes in two separate docker containers ----------------------------------------------- -Open a terminal. Run the image in a container in interactive mode and launch a topic publisher (executable ``talker`` from the package ``demo_nodes_cpp``) with ``ros2 run``: +Open a terminal. +Run the image in a container in interactive mode and launch a topic publisher (executable ``talker`` from the package ``demo_nodes_cpp``) with ``ros2 run``: .. code-block:: bash docker run -it --rm osrf/ros:{DISTRO}-desktop ros2 run demo_nodes_cpp talker -Open a second terminal. Run the image in a container in interactive mode and launch a topic subscriber (executable ``listener`` from the package ``demo_nodes_cpp``) with ``ros2 run``: +Open a second terminal. +Run the image in a container in interactive mode and launch a topic subscriber (executable ``listener`` from the package ``demo_nodes_cpp``) with ``ros2 run``: .. code-block:: bash diff --git a/source/How-To-Guides/Setup-ROS-2-with-VSCode-and-Docker-Container.rst b/source/How-To-Guides/Setup-ROS-2-with-VSCode-and-Docker-Container.rst index 7d21be7f956..75b58914e97 100644 --- a/source/How-To-Guides/Setup-ROS-2-with-VSCode-and-Docker-Container.rst +++ b/source/How-To-Guides/Setup-ROS-2-with-VSCode-and-Docker-Container.rst @@ -201,7 +201,8 @@ Open and Build Development Container Use ``View->Command Palette...`` or ``Ctrl+Shift+P`` to open the command palette. Search for the command ``Dev Containers: Reopen in Container`` and execute it. -This will build your development docker container for your. It will take a while - sit back or go for a coffee. +This will build your development docker container for your. +It will take a while - sit back or go for a coffee. Test Container diff --git a/source/How-To-Guides/Topics-Services-Actions.rst b/source/How-To-Guides/Topics-Services-Actions.rst index 5a57e0d1185..dc37818d99c 100644 --- a/source/How-To-Guides/Topics-Services-Actions.rst +++ b/source/How-To-Guides/Topics-Services-Actions.rst @@ -14,13 +14,18 @@ This is written to provide the reader with guidelines about when to use each typ Topics ------ -* Should be used for continuous data streams (sensor data, robot state, ...). -* Are for continuous data flow. Data might be published and subscribed at any time independent of any senders/receivers. Many to many connection. Callbacks receive data once it is available. The publisher decides when data is sent. +* Should be used for continuous data streams (sensor data, robot state, ...) +* Are for continuous data flow. + Data might be published and subscribed at any time independent of any senders/receivers. + Many to many connection. + Callbacks receive data once it is available. + The publisher decides when data is sent. Services -------- -* Should be used for remote procedure calls that terminate quickly, e.g. for querying the state of a node or doing a quick calculation such as IK. They should never be used for longer running processes, in particular processes that might be required to preempt if exceptional situations occur and they should never change or depend on state to avoid unwanted side effects for other nodes. +* Should be used for remote procedure calls that terminate quickly, e.g. for querying the state of a node or doing a quick calculation such as IK. + They should never be used for longer running processes, in particular processes that might be required to preempt if exceptional situations occur and they should never change or depend on state to avoid unwanted side effects for other nodes. Actions ------- @@ -29,4 +34,6 @@ Actions * The most important property of actions is that they can be preempted and preemption should always be implemented cleanly by action servers. * Actions can keep state for the lifetime of a goal, i.e. if executing two action goals in parallel on the same server, for each client a separate state instance can be kept since the goal is uniquely identified by its id. * Slow perception routines which take several seconds to terminate or initiating a lower-level control mode are good use cases for actions. -* More complex non-blocking background processing. Used for longer tasks like execution of robot actions. Semantically for real-world actions. +* More complex non-blocking background processing. + Used for longer tasks like execution of robot actions. + Semantically for real-world actions. diff --git a/source/How-To-Guides/Using-Python-Packages.rst b/source/How-To-Guides/Using-Python-Packages.rst index da313b93ae7..27a750d7cba 100644 --- a/source/How-To-Guides/Using-Python-Packages.rst +++ b/source/How-To-Guides/Using-Python-Packages.rst @@ -23,7 +23,8 @@ Using Python Packages with ROS 2 Installing via ``rosdep`` ------------------------- -The fastest way to include third-party python packages is to use their corresponding rosdep keys, if available. ``rosdep`` keys can be checked via: +The fastest way to include third-party python packages is to use their corresponding rosdep keys, if available. +``rosdep`` keys can be checked via: * https://github.com/ros/rosdistro/blob/master/rosdep/base.yaml * https://github.com/ros/rosdistro/blob/master/rosdep/python.yaml diff --git a/source/How-To-Guides/Working-with-multiple-RMW-implementations.rst b/source/How-To-Guides/Working-with-multiple-RMW-implementations.rst index 78ee1a32461..a25fc367f4f 100644 --- a/source/How-To-Guides/Working-with-multiple-RMW-implementations.rst +++ b/source/How-To-Guides/Working-with-multiple-RMW-implementations.rst @@ -21,7 +21,8 @@ You should have already read the :doc:`DDS and ROS middleware implementations pa Specifying RMW implementations ------------------------------ -To have multiple RMW implementations available for use you must have installed the ROS 2 binaries and any additional dependencies for specific RMW implementations, or built ROS 2 from source with multiple RMW implementations in the workspace (the RMW implementations are included in the build by default if their compile-time dependencies are met). See :doc:`Install DDS implementations <../Installation/DDS-Implementations>`. +To have multiple RMW implementations available for use you must have installed the ROS 2 binaries and any additional dependencies for specific RMW implementations, or built ROS 2 from source with multiple RMW implementations in the workspace (the RMW implementations are included in the build by default if their compile-time dependencies are met). +See :doc:`Install DDS implementations <../Installation/DDS-Implementations>`. ---- @@ -79,7 +80,8 @@ Troubleshooting Checking the Current RMW ^^^^^^^^^^^^^^^^^^^^^^^^ -To check the RMW that is currently in use you simply check the ``RMW_IMPLEMENTATION`` environment variable. On Linux systems ``printenv`` prints the full list of environment variables. +To check the RMW that is currently in use you simply check the ``RMW_IMPLEMENTATION`` environment variable. +On Linux systems ``printenv`` prints the full list of environment variables. Other operating systems will have other procedures for viewing environment variables. If ``RMW_IMPLEMENTATION`` is not in the environment it is safe to assume you are using the default for your ROS distro, otherwise the current RMW is the value listed. The default RMW for each ROS Distro can be found in `REP-2000 `_. @@ -140,7 +142,8 @@ If you receive an error message similar to below when running RTI Connext on OSX [D0062|ENABLE]DDS_DomainParticipantPresentation_reserve_participant_index_entryports:!enable reserve participant index [D0062|ENABLE]DDS_DomainParticipant_reserve_participant_index_entryports:Unusable shared memory transport. For a more in- depth explanation of the possible problem and solution, please visit https://community.rti.com/kb/osx510. -This error is caused by an insufficient number or size of shared memory segments allowed by the operating system. As a result, the ``DomainParticipant`` is unable to allocate enough resources and calculate its participant index which causes the error. +This error is caused by an insufficient number or size of shared memory segments allowed by the operating system. +As a result, the ``DomainParticipant`` is unable to allocate enough resources and calculate its participant index which causes the error. You can increase the shared memory resources of your machine either temporarily or permanently. diff --git a/source/Package-Docs.rst b/source/Package-Docs.rst index 7f82f8adbfe..c12133aad8e 100644 --- a/source/Package-Docs.rst +++ b/source/Package-Docs.rst @@ -8,12 +8,14 @@ Here is a brief list of where to look for specific ROS package documentation. * Most ROS 2 packages have their package level documentation `included in this index page `__. -* All ROS 2 package's documentation is hosted alongside its information on the `ROS Index `_. Searching for packages on ROS Index will yield their information such as released distributions, ``README.md`` files, URLs, and other important metadata. +* All ROS 2 package's documentation is hosted alongside its information on the `ROS Index `_. + Searching for packages on ROS Index will yield their information such as released distributions, ``README.md`` files, URLs, and other important metadata. Larger Packages --------------- -Larger packages like MoveIt, Nav2, and microROS, are given their own domain or subdomain on ros.org. Here is a short list. +Larger packages like MoveIt, Nav2, and microROS, are given their own domain or subdomain on ros.org. +Here is a short list. * `MoveIt `__ * `Navigation2 `__ diff --git a/source/Related-Projects/Nvidia-ROS2-Projects.rst b/source/Related-Projects/Nvidia-ROS2-Projects.rst index 3240c848db8..a3d1a8e75a6 100644 --- a/source/Related-Projects/Nvidia-ROS2-Projects.rst +++ b/source/Related-Projects/Nvidia-ROS2-Projects.rst @@ -8,7 +8,8 @@ ROS Projects ------------ * `Isaac ROS Nvblox `__ : Hardware-accelerated 3D scene reconstruction and Nav2 local costmap provider using nvblox. * `Isaac ROS Object Detection `__ : Deep learning model support for object detection including DetectNet. -* `Isaac ROS DNN Inference `__ : This repository provides two NVIDIA GPU-accelerated ROS 2 nodes that perform deep learning inference using custom models. One node uses the TensorRT SDK, while the other uses the Triton SDK. +* `Isaac ROS DNN Inference `__ : This repository provides two NVIDIA GPU-accelerated ROS 2 nodes that perform deep learning inference using custom models. + One node uses the TensorRT SDK, while the other uses the Triton SDK. * `Isaac ROS Visual SLAM `__ : This repository provides a ROS 2 package that estimates stereo visual inertial odometry using the Isaac Elbrus GPU-accelerated library. * `Isaac ROS Argus Camera `__ : This repository provides monocular and stereo nodes that enable ROS developers to use cameras connected to Jetson platforms over a CSI interface. * `Isaac ROS image_pipeline `__ : This metapackage offers similar functionality as the standard, CPU-based image_pipeline metapackage, but does so by leveraging the Jetson platform's specialized computer vision hardware. @@ -16,7 +17,8 @@ ROS Projects * `Isaac ROS AprilTags `__ : ROS 2 node uses the NVIDIA GPU-accelerated AprilTags library to detect AprilTags in images and publish their poses, ids, and additional metadata. * `ROS and ROS 2 Docker Images `__ : Docker images for easy deployment on the NVIDIA Jetson platform, consisting of ROS 2, PyTorch, and other important machine learning libraries. * `ROS and ROS 2 DockerFiles `__: Dockerfiles for ROS 2 based on l4t which all you to build your own Docker image. -* `ROS 2 Packages for PyTorch and TensorRT `__: ROS 2 packageis for classification and object detection tasks using PyTorch and NVIDIA TensorRT. This tutorial is a good starting point AI integration with ROS 2 on NVIDIA Jetson. +* `ROS 2 Packages for PyTorch and TensorRT `__: ROS 2 packageis for classification and object detection tasks using PyTorch and NVIDIA TensorRT. + This tutorial is a good starting point AI integration with ROS 2 on NVIDIA Jetson. * `ROS / ROS 2 Packages for Accelerated Deep Learning Nodes `__: Deep learning image recognition, object detection, and semantic segmentation inference nodes and camera/video streaming nodes for ROS/ROS 2 using the `jetson-inference `__ library and `NVIDIA Hello AI World tutorial `__. * `ROS 2 Package for Human Pose Estimation `__: A ROS 2 package for human pose estimation. * `ROS 2 Package for Hand Pose Estimation and Gesture Classification `__: A ROS 2 package for real-time hand pose estimation and gesture classification using TensorRT. diff --git a/source/The-ROS2-Project/Contributing/Build-Farms.rst b/source/The-ROS2-Project/Contributing/Build-Farms.rst index 26edc804b2d..4f27b2c65b5 100644 --- a/source/The-ROS2-Project/Contributing/Build-Farms.rst +++ b/source/The-ROS2-Project/Contributing/Build-Farms.rst @@ -74,7 +74,8 @@ Execution of the jobs depends on the type of the job: * `devel jobs`_ will be triggered every time a commit is done to the respective branch polling based on a configured frequency. * `pull_request jobs`_ will be triggered by webhooks from respective pull request of the upstream [2]_ repository * `release jobs`_ will be triggered once every time a new package version is released, i.e. a new - rosdistro_ pull request was accepted for this package. The source jobs are triggered by a version + rosdistro_ pull request was accepted for this package. + The source jobs are triggered by a version change in the rosdistro distribution file, the binary jobs are triggered by their source counterpart. @@ -83,25 +84,26 @@ Frequency Asked Questions (FAQ) and Troubleshooting #. **I get Jenkins mails from failing build farm jobs. What do I do?** - Go to the job that raised the issue. You find the link on top of the Jenkins email. - Once you followed the link to the build job, click *Console Output* on the left, then click - *Full Log*. This will give you the full console output of the failing build. Try to find the - top-most error as it is usually the most important and other errors might be follow-ups. + Go to the job that raised the issue. + You find the link on top of the Jenkins email. + Once you followed the link to the build job, click *Console Output* on the left, then click *Full Log*. + This will give you the full console output of the failing build. + Try to find the top-most error as it is usually the most important and other errors might be follow-ups. - The bottom of the email might read ``'apt-src build [...]' failed. This is usually because of - an error building the package.`` This usually hints at missing dependencies, see 2. + The bottom of the email might read + ``'apt-src build [...]' failed. This is usually because of an error building the package.`` + This usually hints at missing dependencies, see 2. #. **I seem to be missing a dependency, how do I find out which one?** You basically have two options, a. is easier but may take several iterations, b. is more elaborate and gives you the full insight as well as local debugging. - a) Inspect the release job that raised the issue (see 1.) and localize the cmake dependency - issue. To do so, browse to the cmake section, e.g., navigate to the *build binarydeb* - section through the menu on the left in case of a Ubuntu/Debian build job. The *CMake Error* - will typically hint at a dependency required by the cmake configuration but missing in the - `package manifest`_. Once you have fixed the dependency in the manifest, do a new release - of your package and wait for feedback from the build farms or... + a) Inspect the release job that raised the issue (see 1.) and localize the cmake dependency issue. + To do so, browse to the cmake section, e.g., navigate to the *build binarydeb* + section through the menu on the left in case of a Ubuntu/Debian build job. + The *CMake Error* will typically hint at a dependency required by the cmake configuration but missing in the `package manifest`_. + Once you have fixed the dependency in the manifest, do a new release of your package and wait for feedback from the build farms or... b) To get the full insight and faster, local debugging, you can `run the release jobs locally`_. This allows to iterate the manifest locally until all dependencies are fixed. @@ -109,12 +111,13 @@ Frequency Asked Questions (FAQ) and Troubleshooting There are several potential reasons for this. First, release jobs build against a minimal ROS installation to check if all dependencies are - properly declared in the `package manifest`_. Devel jobs / github actions / local builds may + properly declared in the `package manifest`_. + Devel jobs / github actions / local builds may be performed in an environment that has the dependencies already installed, therefore does not - notice dependency issues. Second, they might build different versions of the source code. + notice dependency issues. + Second, they might build different versions of the source code. While devel jobs / github actions / local builds usually build the latest version from the - *upstream* [2]_ repository, `release jobs`_ build the source code of the latest release, i.e. - the source code in the respective *upstream* branches of the *release* repository [3]_. + *upstream* [2]_ repository, `release jobs`_ build the source code of the latest release, i.e. the source code in the respective *upstream* branches of the *release* repository [3]_. Further Reading diff --git a/source/The-ROS2-Project/Contributing/Code-Style-Language-Versions.rst b/source/The-ROS2-Project/Contributing/Code-Style-Language-Versions.rst index 5ee4cfafe68..99ac9f148f9 100644 --- a/source/The-ROS2-Project/Contributing/Code-Style-Language-Versions.rst +++ b/source/The-ROS2-Project/Contributing/Code-Style-Language-Versions.rst @@ -51,7 +51,8 @@ All of the following modifications only apply if we are not writing Python modul * The stuff about documentation strings doesn't apply -We can use the `pep7 `__ python module for style checking. The editor integration seems slim, we may need to look into automated checking for C in more detail. +We can use the `pep7 `__ python module for style checking. +The editor integration seems slim, we may need to look into automated checking for C in more detail. C++ --- @@ -194,7 +195,9 @@ Open Versus Cuddled Braces * Exception: when an ``if`` (or ``while``, etc.) condition is long enough to require line-wrapping, then use an open brace (i.e., don't cuddle). -* When a function call cannot fit on one line, wrap at the open parenthesis (not in between arguments) and start them on the next line with a 2-space indent. Continue with the 2-space indent on subsequent lines for more arguments. (Note that the `Google style guide `__ is internally contradictory on this point.) +* When a function call cannot fit on one line, wrap at the open parenthesis (not in between arguments) and start them on the next line with a 2-space indent. + Continue with the 2-space indent on subsequent lines for more arguments. + (Note that the `Google style guide `__ is internally contradictory on this point.) * Same goes for ``if`` (and ``while``, etc.) conditions that are too long to fit on one line. diff --git a/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst b/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst index 5c656f264dc..205069a8400 100644 --- a/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst +++ b/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst @@ -194,9 +194,11 @@ We've found that the easiest way to migrate a page from the ROS Wiki is to conve Migrating a Wiki File ^^^^^^^^^^^^^^^^^^^^^ -#. Clone the appropriate repository. If you are migrating a page to the official documentation hosted here, then you should clone https://github.com/ros2/ros2_documentation. +#. Clone the appropriate repository. + If you are migrating a page to the official documentation hosted here, then you should clone https://github.com/ros2/ros2_documentation. -#. Create a new Github branch for your migrated page. We suggest something like ``pagename-migration``. +#. Create a new Github branch for your migrated page. + We suggest something like ``pagename-migration``. #. Download the appropriate ROS Wiki page to an html file using wget or a similar tool (e.g. ``wget -O urdf.html https://wiki.ros.org/urdf``). Alternatively you can use your web browser to save the page's HTML. @@ -204,7 +206,8 @@ Migrating a Wiki File #. Next you need to remove the extraneous HTML in the file you downloaded Using your browser's developer mode, find the name of the first useful HTML element in the Wiki page. In most cases all of the HTML between the third line of the file, starting with the ```` tag, through the start of the first ``

`` tag can be safely removed. - In the case where there is a table of contents, the first useful tag may be an ``

`` tag. Similarly, the ROS wiki contains some footer text that starts with ``
`` and ends just above ```` that can also be removed. + In the case where there is a table of contents, the first useful tag may be an ``

`` tag. + Similarly, the ROS wiki contains some footer text that starts with ``
`` and ends just above ```` that can also be removed. #. Convert your html file by running a PanDoc conversion between HTML and restructured text. The following command converts an HTML file to the equivalent reStructured text files: ``pandoc -f html -t rst urdf.html > URDF.rst``. @@ -219,7 +222,9 @@ Migrating a Wiki File This process may require you alter the document considerably, and you may need to pull multiple wiki files. You should verify that every code sample in the document is working correctly under ROS 2. -#. Find and download any images that may be in the old document. The easiest way to do this is to right click in the browser and download all of the images. Alternatively you can find images by searching for ```` tags in the HTML file. +#. Find and download any images that may be in the old document. + The easiest way to do this is to right click in the browser and download all of the images. + Alternatively you can find images by searching for ```` tags in the HTML file. #. For each image files downloaded update the image file links to point to the correct image directory for the ROS Docs. If any of the images require updating, or could be replaced with a `Mermaid `__ chart, please make this change. @@ -247,7 +252,8 @@ After that, you can open the repository in Codespaces, it can be done just by cl :alt: Codespaces creation After that, you will be redirected to your Codespaces page, where you can see the progress of the Codespaces creation. -Once it is done, a Visual Studio Code tab will be opened in your browser. You can open the terminal by clicking on the "Terminal" tab in the top panel or by pressing :kbd:`Ctrl-J`. +Once it is done, a Visual Studio Code tab will be opened in your browser. +You can open the terminal by clicking on the "Terminal" tab in the top panel or by pressing :kbd:`Ctrl-J`. In this terminal, you can run any command you want, for example, you can run the following command to build the site for just this branch: diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index 82527cec000..8b90556e6fd 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -425,7 +425,8 @@ Package Naming Conventions Names play an important role in ROS and following naming conventions simplifies the process of learning and understanding large systems. -The ROS packages occupy a flat namespace, so naming should be done carefully and consistently. There is a standard for package naming in `REP-144 `__ +The ROS packages occupy a flat namespace, so naming should be done carefully and consistently. +There is a standard for package naming in `REP-144 `__ * Package names should follow common C variable naming conventions: lower case, start with a letter, use underscore separators, e.g. laser_viewer @@ -578,7 +579,8 @@ The usual workflow is: * In the first box "CI_BRANCH_TO_TEST" enter your feature branch name * Hit the ``build`` button - (if you are not a ROS 2 committer, you don't have access to the CI farm. In that case, ping the reviewer of your PR to run CI for you) + (if you are not a ROS 2 committer, you don't have access to the CI farm. + In that case, ping the reviewer of your PR to run CI for you) * If your use case requires running code coverage: diff --git a/source/The-ROS2-Project/Contributing/Quality-Guide.rst b/source/The-ROS2-Project/Contributing/Quality-Guide.rst index 5963076861e..ad182afa69e 100644 --- a/source/The-ROS2-Project/Contributing/Quality-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Quality-Guide.rst @@ -127,7 +127,8 @@ However, this step-by-step is a great place to start! * Enabling Analysis for Package/Target - When the C++ compiler is Clang, enable the ``-Wthread-safety`` flag. Example below for CMake-based projects + When the C++ compiler is Clang, enable the ``-Wthread-safety`` flag. + Example below for CMake-based projects .. code-block:: cmake diff --git a/source/The-ROS2-Project/Contributing/Windows-Tips-and-Tricks.rst b/source/The-ROS2-Project/Contributing/Windows-Tips-and-Tricks.rst index 01db8b8af0e..dda812a7d45 100644 --- a/source/The-ROS2-Project/Contributing/Windows-Tips-and-Tricks.rst +++ b/source/The-ROS2-Project/Contributing/Windows-Tips-and-Tricks.rst @@ -20,8 +20,10 @@ Practically speaking, 4 of those characters are always used by the drive letter, That means that only 256 characters are available for the *sum* of all parts of the path. This has two practical consequences for ROS 2: -* Some of the ROS 2 internal path names are fairly long. Because of this, we always recommend using a short path name for the root of your ROS 2 directory, like ``C:\dev``. -* When building ROS 2 from source, the default isolated build mode of colcon can generate very long path names. To avoid these very long path names, use ``--merge-install`` when building on Windows. +* Some of the ROS 2 internal path names are fairly long. + Because of this, we always recommend using a short path name for the root of your ROS 2 directory, like ``C:\dev``. +* When building ROS 2 from source, the default isolated build mode of colcon can generate very long path names. + To avoid these very long path names, use ``--merge-install`` when building on Windows. **Note**: It is possible to change Windows to have much longer maximum path lengths. See `this article `__ for more information. @@ -95,7 +97,8 @@ In another library, ``MY_LIB`` would be replaced with the library name. For a complete example of this header, see `rviz_rendering `__. -To use the macro, add ``MY_LIB_PUBLIC`` before symbols which need to be visible to external libraries. For example: +To use the macro, add ``MY_LIB_PUBLIC`` before symbols which need to be visible to external libraries. +For example: .. code-block:: c++ diff --git a/source/The-ROS2-Project/Feature-Ideas.rst b/source/The-ROS2-Project/Feature-Ideas.rst index acd1204b550..d063a42c488 100644 --- a/source/The-ROS2-Project/Feature-Ideas.rst +++ b/source/The-ROS2-Project/Feature-Ideas.rst @@ -133,7 +133,9 @@ The trailing stars indicate the rough effort: 1 star for small, 2 stars for medi * More granularity in security configuration (allow authentication only, authentication and encryption, etc.) [\*] * Integrate DDS-Security logging plugin (unified way to aggregate security events and report them to the users through a ROS interface) [\*\*] * Key storage security (right now, keys are just stored in the filesystem) [\*\*] - * More user friendly interface (make it easier to specify security config). Maybe a Qt GUI? This GUI could also assist in distributing keys somehow. [\*\*\*] + * More user friendly interface (make it easier to specify security config). + Maybe a Qt GUI? + This GUI could also assist in distributing keys somehow. [\*\*\*] * A way to say "please secure this running system" with some UI that would auto-generate keys and policies for everything that is currently running. [\*\*\*] * If there are hardware-specific features for securing keys or accelerating encryption/signing messages, that could be interesting to add to DDS/RTPS implementations that don't use it already. [\*\*\*] diff --git a/source/The-ROS2-Project/Features.rst b/source/The-ROS2-Project/Features.rst index bade5c363d3..749cf246d0b 100644 --- a/source/The-ROS2-Project/Features.rst +++ b/source/The-ROS2-Project/Features.rst @@ -73,7 +73,8 @@ For planned future development, see the :doc:`Roadmap `. - * - Preliminary support for real-time code - :doc:`Demo <../Tutorials/Demos/Real-Time-Programming>`, :doc:`demo <../Tutorials/Advanced/Allocator-Template-Tutorial>` - - Linux only. Not available for Fast RTPS. + - Linux only. + Not available for Fast RTPS. * - Preliminary support for "bare-metal" microcontrollers - `Wiki `__ - diff --git a/source/The-ROS2-Project/Marketing.rst b/source/The-ROS2-Project/Marketing.rst index 4f9037a713f..b07bee7c249 100644 --- a/source/The-ROS2-Project/Marketing.rst +++ b/source/The-ROS2-Project/Marketing.rst @@ -11,9 +11,8 @@ General Use ROS Artwork ----------------------- The ROS 2 media kit, which includes branding language, high resolution ROS logo -graphics, and release images, can be found in the `ROS art -repository. `__ Please refer to -this repository for ROS art work and our branding guidelines. +graphics, and release images, can be found in the `ROS art repository. `__ +Please refer to this repository for ROS art work and our branding guidelines. Stickers, Posters, and Canvas Prints ------------------------------------ diff --git a/source/The-ROS2-Project/Roadmap.rst b/source/The-ROS2-Project/Roadmap.rst index 4cda15fde53..f0a7b649589 100644 --- a/source/The-ROS2-Project/Roadmap.rst +++ b/source/The-ROS2-Project/Roadmap.rst @@ -56,7 +56,8 @@ Please see the :doc:`Distributions page <../Releases>` for the timeline of and i Contributing to ROS 2 --------------------- -Looking for something to work on, or just want to help out? Here are a few resources to get you going. +Looking for something to work on, or just want to help out? +Here are a few resources to get you going. 1. The :doc:`Contributing ` guide describes how to make a contribution to ROS 2. 2. Check out the list of :doc:`Feature Ideas ` for inspiration. diff --git a/source/Tutorials/Advanced/Ament-Lint-For-Clean-Code.rst b/source/Tutorials/Advanced/Ament-Lint-For-Clean-Code.rst index 14b619f960e..7f866ca5717 100644 --- a/source/Tutorials/Advanced/Ament-Lint-For-Clean-Code.rst +++ b/source/Tutorials/Advanced/Ament-Lint-For-Clean-Code.rst @@ -109,8 +109,10 @@ For example, if you wish to scan just a recently modified file you can call ``am ``ament_cppcheck`` supports the following options: -* ``--libraries [LIBRARIES ...]`` - Library configurations to load in addition to the standard libraries of C and C++. Each library is passed to cppcheck as '--library=' -* ``--include_dirs [INCLUDE_DIRS ...]`` - Include directories for C/C++ files being checked.Each directory is passed to cppcheck as '-I ' (default: None) +* ``--libraries [LIBRARIES ...]`` - Library configurations to load in addition to the standard libraries of C and C++. + Each library is passed to cppcheck as '--library=' +* ``--include_dirs [INCLUDE_DIRS ...]`` - Include directories for C/C++ files being checked. + Each directory is passed to cppcheck as '-I ' (default: None) * ``--cppcheck-version`` - Get the cppcheck version, print it, and then exit. 2.3 ``ament_cppcheck`` Example @@ -283,7 +285,8 @@ For example, if you wish to scan just one package in your workspace you can call 5.2 ``ament_uncrustify`` Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* ``-c CFG`` - The config file that Uncrustify should use if you would prefer to use your own settings. We recommend you stick to the defaults +* ``-c CFG`` - The config file that Uncrustify should use if you would prefer to use your own settings. + We recommend you stick to the defaults * ``--linelength N`` - The maximum line length. * ``--language`` - One of {C,C++,CPP}, passed to uncrustify as '-l ' to force a specific language rather then choosing one based on file extension. * ``--reformat`` - Reformat the files in place, i.e. fix the formatting errors encountered. **We recommend you use this option when running ``ament_uncrustify`` as it will save you quite a bit of time!** diff --git a/source/Tutorials/Advanced/Discovery-Server/Discovery-Server.rst b/source/Tutorials/Advanced/Discovery-Server/Discovery-Server.rst index 2ca8e669bc0..6efd96bbf6e 100644 --- a/source/Tutorials/Advanced/Discovery-Server/Discovery-Server.rst +++ b/source/Tutorials/Advanced/Discovery-Server/Discovery-Server.rst @@ -76,7 +76,8 @@ Run this tutorial The ``talker-listener`` ROS 2 demo creates a ``talker`` node that publishes a "hello world" message every second, and a ``listener`` node that listens to these messages. By :doc:`sourcing ROS 2 <../../Beginner-CLI-Tools/Configuring-ROS2-Environment>` you will get access to the CLI tool ``fastdds``. -This tool gives access to the `discovery tool `__, which can be used to launch a discovery server. This server will manage the discovery process for the nodes that connect to it. +This tool gives access to the `discovery tool `__, which can be used to launch a discovery server. +This server will manage the discovery process for the nodes that connect to it. .. important:: @@ -117,7 +118,8 @@ In a new terminal, set the environment variable ``ROS_DISCOVERY_SERVER`` to the set ROS_DISCOVERY_SERVER=127.0.0.1:11811 -Launch the listener node. Use the argument ``--remap __node:=listener_discovery_server`` to change the node's name for this tutorial. +Launch the listener node. +Use the argument ``--remap __node:=listener_discovery_server`` to change the node's name for this tutorial. .. code-block:: console @@ -330,7 +332,9 @@ In another terminal run the second server listening on localhost using another p fastdds discovery --server-id 1 --ip-address 127.0.0.1 --port 11888 -Now, run each node in a different terminal. Use ``ROS_DISCOVERY_SERVER`` environment variable to decide which server they are connected to. Be aware that the `ids must match `__. +Now, run each node in a different terminal. +Use ``ROS_DISCOVERY_SERVER`` environment variable to decide which server they are connected to. +Be aware that the `ids must match `__. .. tabs:: @@ -428,7 +432,8 @@ In this sense, ROS 2 introspection tools can be configured as **Super Client**, .. note:: - In this section we use the term *Participant* as a DDS entity. Each DDS *Participant* corresponds with a ROS 2 *Context*, a ROS 2 abstraction over DDS. + In this section we use the term *Participant* as a DDS entity. + Each DDS *Participant* corresponds with a ROS 2 *Context*, a ROS 2 abstraction over DDS. `Nodes ` are ROS 2 entities that rely on DDS communication interfaces: ``DataWriter`` and ``DataReader``. Each *Participant* can hold multiple ROS 2 Nodes. For further details about these concepts, please visit the `Node to Participant mapping design document `__ diff --git a/source/Tutorials/Advanced/Security/Deployment-Guidelines.rst b/source/Tutorials/Advanced/Security/Deployment-Guidelines.rst index 430478790db..8a2b86a4156 100644 --- a/source/Tutorials/Advanced/Security/Deployment-Guidelines.rst +++ b/source/Tutorials/Advanced/Security/Deployment-Guidelines.rst @@ -30,7 +30,8 @@ Prerequisites * A docker installation with the compose plugin. Please refer to the installation steps detailed in `Docker installation `_ and `Compose Plugin `_. * (Recommended) A basic understanding on `ROS 2 Security design `_. -* (Recommended) Previous security tutorials completion. In particular: +* (Recommended) Previous security tutorials completion. + In particular: * :doc:`Introducing-ros2-security` * :doc:`The-Keystore` diff --git a/source/Tutorials/Advanced/Security/Examine-Traffic.rst b/source/Tutorials/Advanced/Security/Examine-Traffic.rst index 2a9bc7f66ba..254c8469448 100644 --- a/source/Tutorials/Advanced/Security/Examine-Traffic.rst +++ b/source/Tutorials/Advanced/Security/Examine-Traffic.rst @@ -185,7 +185,8 @@ The typical discovery packet looks somewhat like the following:: This packet is much larger and includes information which can be used to set up encryption among ROS nodes. As we will see shortly, this actually includes some of the security configuration files that were created when we enabled security. -Interested in learning more? Take a look at the excellent paper `Network Reconnaissance and Vulnerability Excavation of Secure DDS Systems `_ to understand why this matters. +Interested in learning more? +Take a look at the excellent paper `Network Reconnaissance and Vulnerability Excavation of Secure DDS Systems `_ to understand why this matters. Display encrypted data packets diff --git a/source/Tutorials/Advanced/Simulators/Webots/Installation-MacOS.rst b/source/Tutorials/Advanced/Simulators/Webots/Installation-MacOS.rst index 7fd83be0712..cbf850f6d31 100644 --- a/source/Tutorials/Advanced/Simulators/Webots/Installation-MacOS.rst +++ b/source/Tutorials/Advanced/Simulators/Webots/Installation-MacOS.rst @@ -59,7 +59,8 @@ In the UTM software: * Leave all the remaining parameters as default. * Start the VM. Note that you can select another shared folder each time you start the VM. -* During the first launch of the VM, install Ubuntu and choose a username for your account. In this example, the username is ``ubuntu``. +* During the first launch of the VM, install Ubuntu and choose a username for your account. + In this example, the username is ``ubuntu``. * Once Ubuntu is installed, close the VM, remove the iso image from the CD/DVD field and restart the VM. 2 Configure the VM diff --git a/source/Tutorials/Advanced/Simulators/Webots/Installation-Windows.rst b/source/Tutorials/Advanced/Simulators/Webots/Installation-Windows.rst index fcc93231580..51f8120f4bd 100644 --- a/source/Tutorials/Advanced/Simulators/Webots/Installation-Windows.rst +++ b/source/Tutorials/Advanced/Simulators/Webots/Installation-Windows.rst @@ -165,7 +165,8 @@ The Tiago robot can be controlled using: ros2 run teleop_twist_keyboard teleop_twist_keyboard -With older WSL versions, RViz2 may not work directly, as no display is available. To use RViz, you can either upgrade WSL or enable X11 forwarding. +With older WSL versions, RViz2 may not work directly, as no display is available. +To use RViz, you can either upgrade WSL or enable X11 forwarding. .. tabs:: .. group-tab:: Upgrade WSL diff --git a/source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst b/source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst index d16b4980b6e..06a9efe9188 100644 --- a/source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst +++ b/source/Tutorials/Advanced/Simulators/Webots/Simulation-Supervisor.rst @@ -32,7 +32,8 @@ The ``Ros2Supervisor`` The ``Ros2Supervisor`` is made of two main parts: -* A Webots Robot node added to the simulation world. Its ``supervisor`` field is set to TRUE. +* A Webots Robot node added to the simulation world. + Its ``supervisor`` field is set to TRUE. * A ROS 2 node that connects to the Webots Robot as an extern controller (in a similar way to your own robot plugin). The ROS 2 node acts as a controller that calls Supervisor API functions to control or interact with the simulation world. diff --git a/source/Tutorials/Advanced/Topic-Statistics-Tutorial/Topic-Statistics-Tutorial.rst b/source/Tutorials/Advanced/Topic-Statistics-Tutorial/Topic-Statistics-Tutorial.rst index 9fc850fc956..7d94dbf8263 100644 --- a/source/Tutorials/Advanced/Topic-Statistics-Tutorial/Topic-Statistics-Tutorial.rst +++ b/source/Tutorials/Advanced/Topic-Statistics-Tutorial/Topic-Statistics-Tutorial.rst @@ -324,8 +324,9 @@ Summary ------- You created a subscriber node with topic statistics enabled, which published statistics data from -the :doc:`C++ <../../Beginner-Client-Libraries/Writing-A-Simple-Cpp-Service-And-Client>`'s publisher node. You were able to compile and run this node. While running, -you were able to observe the statistics data. +the :doc:`C++ <../../Beginner-Client-Libraries/Writing-A-Simple-Cpp-Service-And-Client>`'s publisher node. +You were able to compile and run this node. +While running, you were able to observe the statistics data. Related content --------------- diff --git a/source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Nodes/Understanding-ROS2-Nodes.rst b/source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Nodes/Understanding-ROS2-Nodes.rst index c3f049b3b5c..f02e40c7d8a 100644 --- a/source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Nodes/Understanding-ROS2-Nodes.rst +++ b/source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Nodes/Understanding-ROS2-Nodes.rst @@ -142,7 +142,8 @@ To examine your latest node, ``my_turtle``, run the following command: ros2 node info /my_turtle -``ros2 node info`` returns a list of subscribers, publishers, services, and actions. i.e. the ROS graph connections that interact with that node. +``ros2 node info`` returns a list of subscribers, publishers, services, and actions. +i.e. the ROS graph connections that interact with that node. The output should look like this: .. code-block:: console diff --git a/source/Tutorials/Beginner-Client-Libraries/Pluginlib.rst b/source/Tutorials/Beginner-Client-Libraries/Pluginlib.rst index ed95dd1a588..c8e1557e3ce 100644 --- a/source/Tutorials/Beginner-Client-Libraries/Pluginlib.rst +++ b/source/Tutorials/Beginner-Client-Libraries/Pluginlib.rst @@ -189,7 +189,8 @@ Create ``ros2_ws/src/polygon_plugins/plugins.xml`` with the following code: A couple things to note: 1. The ``library`` tag gives the relative path to a library that contains the plugins that we want to export. - In ROS 2, that is just the name of the library. In ROS 1, it contained the prefix ``lib`` or sometimes ``lib/lib`` (i.e. ``lib/libpolygon_plugins``), but here it is simpler. + In ROS 2, that is just the name of the library. + In ROS 1, it contained the prefix ``lib`` or sometimes ``lib/lib`` (i.e. ``lib/libpolygon_plugins``), but here it is simpler. 2. The ``class`` tag declares a plugin that we want to export from our library. Let's go through its parameters: @@ -313,4 +314,5 @@ It should print: Summary ------- -Congratulations! You've just written and used your first plugins. +Congratulations! +You've just written and used your first plugins. diff --git a/source/Tutorials/Demos/Intra-Process-Communication.rst b/source/Tutorials/Demos/Intra-Process-Communication.rst index 50a5217c4ac..acd65439876 100644 --- a/source/Tutorials/Demos/Intra-Process-Communication.rst +++ b/source/Tutorials/Demos/Intra-Process-Communication.rst @@ -324,7 +324,8 @@ The watermark and image view nodes are designed to modify the image without copy .. note:: On some systems (we've seen it happen on Linux), the address printed to the screen might not change. - This is because the same unique pointer is being reused. In this situation, the pipeline is still running. + This is because the same unique pointer is being reused. + In this situation, the pipeline is still running. Let's run the demo by executing the following executable: @@ -347,7 +348,8 @@ Pipeline with two image viewers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now let's look at an example just like the one above, except it has two image view nodes. -All the nodes are still in the same process, but now two image view windows should show up. (Note for macOS users: your image view windows might be on top of each other). +All the nodes are still in the same process, but now two image view windows should show up. +(Note for macOS users: your image view windows might be on top of each other). Let's run it with the command: .. code-block:: bash @@ -358,26 +360,39 @@ Let's run it with the command: .. image:: images/intra-process-demo-pipeline-two-windows-copy.png -Just like the last example, you can pause the rendering with the spacebar and continue by pressing the spacebar a second time. You can stop the updating to inspect the pointers written to the screen. +Just like the last example, you can pause the rendering with the spacebar and continue by pressing the spacebar a second time. +You can stop the updating to inspect the pointers written to the screen. -As you can see in the example image above, we have one image with all of the pointers the same and then another image with the same pointers as the first image for the first two entries, but the last pointer on the second image is different. To understand why this is happening consider the graph's topology: +As you can see in the example image above, we have one image with all of the pointers the same and then another image with the same pointers as the first image for the first two entries, but the last pointer on the second image is different. +To understand why this is happening consider the graph's topology: .. code-block:: bash camera_node -> watermark_node -> image_view_node -> image_view_node2 -The link between the ``camera_node`` and the ``watermark_node`` can use the same pointer without copying because there is only one intra process subscription to which the message should be delivered. But for the link between the ``watermark_node`` and the two image view nodes the relationship is one to many, so if the image view nodes were using ``unique_ptr`` callbacks then it would be impossible to deliver the ownership of the same pointer to both. It can be, however, delivered to one of them. Which one would get the original pointer is not defined, but instead is simply the last to be delivered. +The link between the ``camera_node`` and the ``watermark_node`` can use the same pointer without copying because there is only one intra process subscription to which the message should be delivered. +But for the link between the ``watermark_node`` and the two image view nodes the relationship is one to many, so if the image view nodes were using ``unique_ptr`` callbacks then it would be impossible to deliver the ownership of the same pointer to both. +It can be, however, delivered to one of them. +Which one would get the original pointer is not defined, but instead is simply the last to be delivered. -Note that the image view nodes are not subscribed with ``unique_ptr`` callbacks. Instead they are subscribed with ``const shared_ptr``\ s. This means the system deliveres the same ``shared_ptr`` to both callbacks. When the first intraprocess subscription is handled, the internally stored ``unique_ptr`` is promoted to a ``shared_ptr``. Each of the callbacks will receive shared ownership of the same message. +Note that the image view nodes are not subscribed with ``unique_ptr`` callbacks. +Instead they are subscribed with ``const shared_ptr``\ s. +This means the system deliveres the same ``shared_ptr`` to both callbacks. +When the first intraprocess subscription is handled, the internally stored ``unique_ptr`` is promoted to a ``shared_ptr``. +Each of the callbacks will receive shared ownership of the same message. Pipeline with interprocess viewer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One other important thing to get right is to avoid interruption of the intra process zero-copy behavior when interprocess subscriptions are made. To test this we can run the first image pipeline demo, ``image_pipeline_all_in_one``, and then run an instance of the stand alone ``image_view_node`` (don't forget to prefix them with ``ros2 run intra_process_demo`` in the terminal). This will look something like this: +One other important thing to get right is to avoid interruption of the intra process zero-copy behavior when interprocess subscriptions are made. +To test this we can run the first image pipeline demo, ``image_pipeline_all_in_one``, and then run an instance of the stand alone ``image_view_node`` (don't forget to prefix them with ``ros2 run intra_process_demo`` in the terminal). +This will look something like this: .. image:: images/intra-process-demo-pipeline-inter-process.png -It's hard to pause both images at the same time so the images may not line up, but the important thing to notice is that the ``image_pipeline_all_in_one`` image view shows the same address for each step. This means that the intra process zero-copy is preserved even when an external view is subscribed as well. You can also see that the interprocess image view has different process IDs for the first two lines of text and the process ID of the standalone image viewer in the third line of text. +It's hard to pause both images at the same time so the images may not line up, but the important thing to notice is that the ``image_pipeline_all_in_one`` image view shows the same address for each step. +This means that the intra process zero-copy is preserved even when an external view is subscribed as well. +You can also see that the interprocess image view has different process IDs for the first two lines of text and the process ID of the standalone image viewer in the third line of text. diff --git a/source/Tutorials/Demos/Quality-of-Service.rst b/source/Tutorials/Demos/Quality-of-Service.rst index 4620196f78f..8d2ade34a49 100644 --- a/source/Tutorials/Demos/Quality-of-Service.rst +++ b/source/Tutorials/Demos/Quality-of-Service.rst @@ -126,7 +126,8 @@ In the first window, you'll see output from the subscriber: $ sudo sysctl -w net.inet.udp.recvspace=209715 $ sudo sysctl -w net.inet.udp.maxdgram=65500 - These changes will not persist a reboot. If you want the changes to persist, add these lines to ``/etc/sysctl.conf`` (create the file if it doesn't exist already): + These changes will not persist a reboot. + If you want the changes to persist, add these lines to ``/etc/sysctl.conf`` (create the file if it doesn't exist already): .. code-block:: bash diff --git a/source/Tutorials/Demos/Real-Time-Programming.rst b/source/Tutorials/Demos/Real-Time-Programming.rst index a669272a3a7..6cc079f80ab 100644 --- a/source/Tutorials/Demos/Real-Time-Programming.rst +++ b/source/Tutorials/Demos/Real-Time-Programming.rst @@ -16,7 +16,8 @@ Background Real-time computing is a key feature of many robotics systems, particularly safety- and mission-critical applications such as autonomous vehicles, spacecrafts, and industrial manufacturing. We are designing and prototyping ROS 2 with real-time performance constraints in mind, since this is a requirement that was not considered in the early stages of ROS 1 and it is now intractable to refactor ROS 1 to be real-time friendly. -`This document `__ outlines the requirements of real-time computing and best practices for software engineers. In short: +`This document `__ outlines the requirements of real-time computing and best practices for software engineers. +In short: To make a real-time computer system, our real-time loop must update periodically to meet deadlines. We can only tolerate a small margin of error on these deadlines (our maximum allowable jitter). @@ -35,18 +36,21 @@ The real-time demo was written with Linux operating systems in mind, since many Since many of the operations done in the demo to optimize performance are OS-specific, the demo only builds and runs on Linux systems. **So, if you are an OSX or Windows user, don't try this part!** -Also this must be built from source using a static DDS API. **Currently the only supported implementation is Connext**. +Also this must be built from source using a static DDS API. +**Currently the only supported implementation is Connext**. First, follow the instructions to build ROS 2 :doc:`from source <../../Installation/Alternatives/Ubuntu-Development-Setup>` using Connext DDS as the middleware. Run the tests ^^^^^^^^^^^^^ -**Before you run make sure you have at least 8Gb of RAM free. With the memory locking, swap will not work anymore.** +**Before you run make sure you have at least 8Gb of RAM free. +With the memory locking, swap will not work anymore.** Source your ROS 2 setup.bash. -Run the demo binary, and redirect the output. You may want to use ``sudo`` in case you get permission error: +Run the demo binary, and redirect the output. +You may want to use ``sudo`` in case you get permission error: .. code-block:: bash @@ -162,7 +166,8 @@ Here, latency means the amount of time after the update was expected to occur. The requirements of a real-time system depend on the application, but let's say in this demo we have a 1kHz (1 millisecond) update loop, and we're aiming for a maximum allowable latency of 5% of our update period. -So, our average latency was really good in this run, but the maximum latency was unacceptable because it actually exceeded our update loop! What happened? +So, our average latency was really good in this run, but the maximum latency was unacceptable because it actually exceeded our update loop! +What happened? We may be suffering from a non-deterministic scheduler. If you're running a vanilla Linux system and you don't have the RT_PREEMPT kernel installed, you probably won't be able to meet the real-time goal we set for ourselves, because the Linux scheduler won't allow you to arbitrarily preempt threads at the user level. diff --git a/source/Tutorials/Demos/dummy-robot-demo.rst b/source/Tutorials/Demos/dummy-robot-demo.rst index 791e7e70045..208f2cc33c1 100644 --- a/source/Tutorials/Demos/dummy-robot-demo.rst +++ b/source/Tutorials/Demos/dummy-robot-demo.rst @@ -11,7 +11,8 @@ In this demo, we present a simple demo robot with all components from publishing Launching the demo ------------------ -We assume your ROS 2 installation dir as ``~/ros2_ws``. Please change the directories according to your platform. +We assume your ROS 2 installation dir as ``~/ros2_ws``. +Please change the directories according to your platform. To start the demo, we execute the demo bringup launch file, which we are going to explain in more details in the next section. @@ -45,14 +46,17 @@ You should see some prints inside your terminal along the lines of the following [dummy_laser-4] [INFO] [1714837459.645626640] [dummy_laser]: scan time increment: 0.000000 [robot_state_publisher-2] [INFO] [1714837459.652977937] [robot_state_publisher]: Robot initialized -If you now open RViz2 in a new terminal, you'll see your robot. 🎉 +If you now open RViz2 in a new terminal, you'll see your robot. +🎉 .. code-block:: bash $ source ~/ros2_ws/install/setup.bash $ rviz2 -This opens RViz2. Assuming you have your dummy_robot_bringup still launched, you can now add the TF display plugin and configure your global frame to ``world``. Once you did that, you should see a similar picture: +This opens RViz2. +Assuming you have your dummy_robot_bringup still launched, you can now add the TF display plugin and configure your global frame to ``world``. +Once you did that, you should see a similar picture: .. image:: images/rviz-dummy-robot.png @@ -69,10 +73,15 @@ If you have a closer look at the launch file, we start a couple of nodes at the * dummy_joint_states * robot_state_publisher -The first two packages are relatively simple. The ``dummy_map_server`` constantly publishes an empty map with a periodic update. The ``dummy_laser`` does basically the same; publishing dummy fake laser scans. +The first two packages are relatively simple. +The ``dummy_map_server`` constantly publishes an empty map with a periodic update. +The ``dummy_laser`` does basically the same; publishing dummy fake laser scans. -The ``dummy_joint_states`` node is publishing fake joint state data. As we are publishing a simple RRbot with only two joints, this node publishes joint states values for these two joints. +The ``dummy_joint_states`` node is publishing fake joint state data. +As we are publishing a simple RRbot with only two joints, this node publishes joint states values for these two joints. -The ``robot_state_publisher`` is doing the actual interesting work. It parses the given URDF file, extracts the robot model and listens to the incoming joint states. With this information, it publishes TF values for our robot which we visualize in RViz. +The ``robot_state_publisher`` is doing the actual interesting work. +It parses the given URDF file, extracts the robot model and listens to the incoming joint states. +With this information, it publishes TF values for our robot which we visualize in RViz. Hooray! diff --git a/source/Tutorials/Intermediate/RViz/Marker-Display-types/Marker-Display-types.rst b/source/Tutorials/Intermediate/RViz/Marker-Display-types/Marker-Display-types.rst index ab82bac5e29..97494d97c89 100644 --- a/source/Tutorials/Intermediate/RViz/Marker-Display-types/Marker-Display-types.rst +++ b/source/Tutorials/Intermediate/RViz/Marker-Display-types/Marker-Display-types.rst @@ -85,15 +85,18 @@ The messages in this package include comments that are helpful in understanding * ``ns``: - Namespace for these markers. This plus the id form a unique identifier. + Namespace for these markers. + This plus the id form a unique identifier. * ``id``: - Unique id assigned to this marker. It is your responsibility to keep these unique within your namespace. + Unique id assigned to this marker. + It is your responsibility to keep these unique within your namespace. * ``type``: - Type of marker (Arrow, Sphere, ...). The available types are specified in the message definition. + Type of marker (Arrow, Sphere, ...). + The available types are specified in the message definition. * ``action``: @@ -105,11 +108,16 @@ The messages in this package include comments that are helpful in understanding * ``scale``: - Scale of the marker. Applied before the position/orientation. A scale of [1, 1, 1] means the object will be 1m by 1m by 1m. + Scale of the marker. + Applied before the position/orientation. + A scale of [1, 1, 1] means the object will be 1m by 1m by 1m. * ``color``: - Color of the object, specified as r/g/b/a, with values in the range of [0, 1]. The, ``a`` or alpha value, denotes the opacity of the marker with 1 indicating opaque and 0 indicating completely transparent. The default value is 0, or completely transparent. **You must set the a value of your marker to a non-zero value or it will be transparent by default!** + Color of the object, specified as r/g/b/a, with values in the range of [0, 1]. + The, ``a`` or alpha value, denotes the opacity of the marker with 1 indicating opaque and 0 indicating completely transparent. + The default value is 0, or completely transparent. + **You must set the a value of your marker to a non-zero value or it will be transparent by default!** * ``points``: @@ -119,7 +127,8 @@ The messages in this package include comments that are helpful in understanding * ``colors``: - This field is only used for markers that use the points member. This field specifies per-vertex color r/g/b/ color (no alpha yet) for each entry in ``points``. + This field is only used for markers that use the points member. + This field specifies per-vertex color r/g/b/ color (no alpha yet) for each entry in ``points``. * ``lifetime``: @@ -154,11 +163,14 @@ The arrow type provides two different ways of specifying where the arrow should * ``Position/Orientation``: - Pivot point is around the tip of its tail. Identity orientation points it along the +X axis. ``scale.x`` is the arrow length, ``scale.y`` is the arrow width and ``scale.z`` is the arrow height. + Pivot point is around the tip of its tail. + Identity orientation points it along the +X axis. + ``scale.x`` is the arrow length, ``scale.y`` is the arrow width and ``scale.z`` is the arrow height. * ``Start/End Points``: - You can also specify a start/end point for the arrow, using the points member. If you put points into the points member, it will assume you want to do things this way. + You can also specify a start/end point for the arrow, using the points member. + If you put points into the points member, it will assume you want to do things this way. * The point at index 0 is assumed to be the start point, and the point at index 1 is assumed to be the end. * ``scale.x`` is the shaft diameter, and ``scale.y`` is the head diameter. If ``scale.z`` is not zero, it specifies the head length. @@ -207,7 +219,8 @@ Note that ``pose`` is still used (the points in the line will be transformed by .. image:: images/LineListMarker.png -Line lists use the points member of the `visualization_msgs/msg/Marker `_ message. It will draw a line between each pair of points, so 0-1, 2-3, 4-5, ... +Line lists use the points member of the `visualization_msgs/msg/Marker `_ message. +It will draw a line between each pair of points, so 0-1, 2-3, 4-5, ... Line lists also have some special handling for scale: only ``scale.x`` is used and it controls the width of the line segments. @@ -256,7 +269,8 @@ Note that ``pose`` is still used (the ``points`` in the line will be transformed .. image:: images/text_view_facing_marker.png This marker displays text in a 3D spot in the world. -The text always appears oriented correctly for the RViZ user to see the included text. Uses the ``text`` field in the marker. +The text always appears oriented correctly for the RViZ user to see the included text. +Uses the ``text`` field in the marker. Only ``scale.z`` is used. ``scale.z`` specifies the height of an uppercase "A". diff --git a/source/Tutorials/Intermediate/RViz/RViz-Custom-Display/RViz-Custom-Display.rst b/source/Tutorials/Intermediate/RViz/RViz-Custom-Display/RViz-Custom-Display.rst index 3cdf5adede7..089733158e4 100644 --- a/source/Tutorials/Intermediate/RViz/RViz-Custom-Display/RViz-Custom-Display.rst +++ b/source/Tutorials/Intermediate/RViz/RViz-Custom-Display/RViz-Custom-Display.rst @@ -3,14 +3,17 @@ Building a Custom RViz Display Background ---------- -There are many types of data that have existing visualizations in RViz. However, if there is a message type that does +There are many types of data that have existing visualizations in RViz. +However, if there is a message type that does not yet have a plugin to display it, there are two choices to see it in RViz. 1. Convert the message to another type, such as ``visualization_msgs/Marker``. 2. Write a Custom RViz Display. -With the first option, there is more network traffic and limitations to how the data can be represented. It is also quick and flexible. -The latter option is explained in this tutorial. It takes a bit of work, but can lead to much richer visualizations. +With the first option, there is more network traffic and limitations to how the data can be represented. +It is also quick and flexible. +The latter option is explained in this tutorial. +It takes a bit of work, but can lead to much richer visualizations. All of the code for this tutorial can be found in `this repository `__. In order to see the incremental progress of the plugin written in this tutorial, @@ -224,7 +227,8 @@ First, you need to add a dependency in ``CMakeLists.txt`` and ``package.xml`` on We need to add three lines to the header file: -* ``#include `` - There's `lots of options in the rviz_rendering package `_ for objects to build your visualization on. Here we're using a simple shape. +* ``#include `` - There's `lots of options in the rviz_rendering package `_ for objects to build your visualization on. + Here we're using a simple shape. * In the class, we'll add a new ``protected`` virtual method: ``void onInitialize() override;`` * We also add a pointer to our shape object: ``std::unique_ptr point_shape_;`` @@ -407,11 +411,13 @@ First, we update the plugin declaration. * We add the ``name`` field to the ``class`` tag. This changes the name that is displayed in RViz. In code, it makes sense to call it a ``PointDisplay`` but in RViz, we want to simplify. -* We put actual text into the description. Don't be lazy. +* We put actual text into the description. + Don't be lazy. * By declaring the specific message type here, when you attempt to add a Display by Topic, it will suggest this plugin for the topics of that type. We also add an icon for the plugin at ``icons/classes/Point2D.png``. -The folder is hardcoded, and the filename should match the name from the plugin declaration (or the name of the class if not specified). `[icon source] `_ +The folder is hardcoded, and the filename should match the name from the plugin declaration (or the name of the class if not specified). +`[icon source] `_ We need to install the image file in the CMake. diff --git a/source/Tutorials/Intermediate/RViz/RViz-Custom-Panel/RViz-Custom-Panel.rst b/source/Tutorials/Intermediate/RViz/RViz-Custom-Panel/RViz-Custom-Panel.rst index 1f03660ea1b..1f44bad8e61 100644 --- a/source/Tutorials/Intermediate/RViz/RViz-Custom-Panel/RViz-Custom-Panel.rst +++ b/source/Tutorials/Intermediate/RViz/RViz-Custom-Panel/RViz-Custom-Panel.rst @@ -293,7 +293,8 @@ Update ``demo_panel.cpp`` to have the following contents: Testing with ROS ^^^^^^^^^^^^^^^^ -Compile and launch RViz2 with your panel again. You should see your label and button in the panel now. +Compile and launch RViz2 with your panel again. +You should see your label and button in the panel now. .. image:: images/RViz1.png :target: images/RViz1.png diff --git a/source/Tutorials/Intermediate/RViz/RViz-User-Guide/RViz-User-Guide.rst b/source/Tutorials/Intermediate/RViz/RViz-User-Guide/RViz-User-Guide.rst index 2fdbd3ed689..cac256195a7 100644 --- a/source/Tutorials/Intermediate/RViz/RViz-User-Guide/RViz-User-Guide.rst +++ b/source/Tutorials/Intermediate/RViz/RViz-User-Guide/RViz-User-Guide.rst @@ -108,7 +108,8 @@ Built-in Display Types - Draws cells from a grid, usually obstacles from a costmap from the `navigation `__ stack. - `nav_msgs/msg/GridCells `__ * - Image - - Creates a new rendering window with an Image. Unlike the Camera display, this display does not use a CameraInfo + - Creates a new rendering window with an Image. + Unlike the Camera display, this display does not use a CameraInfo - `sensor_msgs/msg/Image `__ * - InteractiveMarker - Displays 3D objects from one or multiple Interactive Marker servers and allows mouse interaction with them @@ -144,7 +145,8 @@ Built-in Display Types - Accumulates odometry poses from over time. - `nav_msgs/msg/Odometry `__ * - Range - - Displays cones representing range measurements from sonar or IR range sensors. Version: Electric+ + - Displays cones representing range measurements from sonar or IR range sensors. + Version: Electric+ - `sensor_msgs/msg/Range `__ * - RobotModel - Shows a visual representation of a robot in the correct pose (as defined by the current TF transforms). @@ -189,8 +191,10 @@ The focal point is visualized as a small disc while you're moving the camera: Controls: * **Left mouse button**: Click and drag to rotate around the focal point. -* **Middle mouse button**: Click and drag to move the focal point in the plane formed by the camera's up and right vectors. The distance moved depends on the focal point -- if there is an object on the focal point, and you click on top of it, it will stay under your mouse. -* **Right mouse button**: Click and drag to zoom in/out of the focal point. Dragging up zooms in, down zooms out. +* **Middle mouse button**: Click and drag to move the focal point in the plane formed by the camera's up and right vectors. + The distance moved depends on the focal point -- if there is an object on the focal point, and you click on top of it, it will stay under your mouse. +* **Right mouse button**: Click and drag to zoom in/out of the focal point. + Dragging up zooms in, down zooms out. * **Scrollwheel**: Zoom in/out of the focal point FPS (first-person) Camera @@ -199,9 +203,11 @@ The FPS camera is a first-person camera, so it rotates as if you're looking with Controls: -* **Left mouse button**: Click and drag to rotate. Control-click to pick the object under the mouse and look directly at it. +* **Left mouse button**: Click and drag to rotate. + Control-click to pick the object under the mouse and look directly at it. * **Middle mouse button**: Click and drag to move along the plane formed by the camera's up and right vectors. -* **Right mouse button**: Click and drag to move along the camera's forward vector. Dragging up moves forward, down moves backward. +* **Right mouse button**: Click and drag to move along the camera's forward vector. + Dragging up moves forward, down moves backward. * **Scrollwheel**: Move forward/backward. Top-down Orthographic diff --git a/source/Tutorials/Intermediate/Rosdep.rst b/source/Tutorials/Intermediate/Rosdep.rst index c7dda3a3fc7..87414d3411d 100644 --- a/source/Tutorials/Intermediate/Rosdep.rst +++ b/source/Tutorials/Intermediate/Rosdep.rst @@ -105,7 +105,8 @@ How do I know what keys to put in my package.xml? Great question, I'm glad you asked! * If the package you want to depend in your package is ROS-based, AND has been released into the ROS ecosystem [1]_, e.g. ``nav2_bt_navigator``, you may simply use the name of the package. You can find a list of all released ROS packages in https://github.com/ros/rosdistro at ``/distribution.yaml`` (e.g. ``humble/distribution.yaml``) for your given ROS distribution. -* If you want to depend on a non-ROS package, something often called "system dependencies", you will need to find the keys for a particular library. In general, there are two files of interest: +* If you want to depend on a non-ROS package, something often called "system dependencies", you will need to find the keys for a particular library. + In general, there are two files of interest: * `rosdep/base.yaml `_ contains the ``apt`` system dependencies * `rosdep/python.yaml `_ contains the Python dependencies diff --git a/source/Tutorials/Intermediate/Testing/Python.rst b/source/Tutorials/Intermediate/Testing/Python.rst index 4350f597ece..4a729ca4304 100644 --- a/source/Tutorials/Intermediate/Testing/Python.rst +++ b/source/Tutorials/Intermediate/Testing/Python.rst @@ -48,7 +48,8 @@ Example package layout: Test Contents ------------- -You can now write tests to your heart's content. There are `plenty of resources on pytest `__, but in short, you can write functions with the ``test_`` prefix and include whatever assert statements you'd like. +You can now write tests to your heart's content. +There are `plenty of resources on pytest `__, but in short, you can write functions with the ``test_`` prefix and include whatever assert statements you'd like. .. code-block:: python diff --git a/source/Tutorials/Intermediate/Testing/Testing-Main.rst b/source/Tutorials/Intermediate/Testing/Testing-Main.rst index 2f905a7f749..4a1720cf922 100644 --- a/source/Tutorials/Intermediate/Testing/Testing-Main.rst +++ b/source/Tutorials/Intermediate/Testing/Testing-Main.rst @@ -8,14 +8,43 @@ Why automatic tests? Here are some of the many good reasons why should we have automated tests: -* You can make incremental updates to your code more quickly. ROS has hundreds of packages with many interdependencies, so it can be hard to anticipate the problems a small change might cause. If your change passes the unit tests, you can be more confident that you haven't introduced problems — or at least the problems aren't your fault. -* You can refactor your code with greater confidence. Passing the unit tests verifies that you haven't introduced any bugs while refactoring. This gives you this wonderful freedom from change fear! -* It leads to better designed code. Unit tests force you to write your code so that it can be more easily tested. This often means keeping your underlying functions and framework separate, which is one of our design goals with ROS code. -* They prevent recurring bugs (bug regressions). It's a good practice to write a unit test for every bug you fix. In fact, write the unit test before you fix the bug. This will help you to precisely, or even deterministically, reproduce the bug, and much more precisely understand what the problem is. As a result, you will also create a better patch, which you can then test with your regression test to verify that the bug is fixed. That way the bug won't accidentally get reintroduced if the code gets modified later on. It also means that it will be easier to convince the reviewer of the patch that the problem is solved, and the contribution is of high quality. -* Other people can work on your code more easily (an automatic form of documentation). It can be hard to figure out whether or not you've broken someone else's code when you make a change. The unit tests are a tool for other developers to validate their changes. Automatic tests document your coding decisions, and communicate to other developers automatically about their violation. Thus tests become documentation for your code — a documentation that does not need to be read for the most time, and when it does need to be inspected the test system will precisely indicate what to read (which tests fail). By writing automatic tests you make other contributors faster. This improves the entire ROS project. -* It is much easier to become a contributor to ROS if we have automated unit tests. It is very difficult for new external developers to contribute to your components. When they make changes to code, they are often doing it in the blind, driven by a lot of guesswork. By providing a harness of automated tests, you help them in the task. They get immediate feedback for their changes. It becomes easier to contribute to a project, and new contributors to join more easily. Also their first contributions are of higher quality, which decreases the workload on maintainers. A win-win! -* Automatic tests simplify maintainership. Especially for mature packages, which change more slowly, and mostly need to be updated to new dependencies, an automatic test suite helps to very quickly establish whether the package still works. This makes it much easier to decide whether the package is still supported or not. -* Automatic tests amplify the value of Continuous Integration. Regression tests, along with normal scenario-based requirements tests, contribute to overall body of automated tests for your component. Your component is better tested against evolution of other APIs that it depends on (CI servers will tell you better and more precisely what problems develop in your code). +* You can make incremental updates to your code more quickly. + ROS has hundreds of packages with many interdependencies, so it can be hard to anticipate the problems a small change might cause. + If your change passes the unit tests, you can be more confident that you haven't introduced problems — or at least the problems aren't your fault. +* You can refactor your code with greater confidence. + Passing the unit tests verifies that you haven't introduced any bugs while refactoring. + This gives you this wonderful freedom from change fear! +* It leads to better designed code. + Unit tests force you to write your code so that it can be more easily tested. + This often means keeping your underlying functions and framework separate, which is one of our design goals with ROS code. +* They prevent recurring bugs (bug regressions). + It's a good practice to write a unit test for every bug you fix. + In fact, write the unit test before you fix the bug. + This will help you to precisely, or even deterministically, reproduce the bug, and much more precisely understand what the problem is. + As a result, you will also create a better patch, which you can then test with your regression test to verify that the bug is fixed. + That way the bug won't accidentally get reintroduced if the code gets modified later on. + It also means that it will be easier to convince the reviewer of the patch that the problem is solved, and the contribution is of high quality. +* Other people can work on your code more easily (an automatic form of documentation). + It can be hard to figure out whether or not you've broken someone else's code when you make a change. + The unit tests are a tool for other developers to validate their changes. + Automatic tests document your coding decisions, and communicate to other developers automatically about their violation. + Thus tests become documentation for your code — a documentation that does not need to be read for the most time, and when it does need to be inspected the test system will precisely indicate what to read (which tests fail). + By writing automatic tests you make other contributors faster. + This improves the entire ROS project. +* It is much easier to become a contributor to ROS if we have automated unit tests. + It is very difficult for new external developers to contribute to your components. + When they make changes to code, they are often doing it in the blind, driven by a lot of guesswork. + By providing a harness of automated tests, you help them in the task. + They get immediate feedback for their changes. + It becomes easier to contribute to a project, and new contributors to join more easily. + Also their first contributions are of higher quality, which decreases the workload on maintainers. + A win-win! +* Automatic tests simplify maintainership. + Especially for mature packages, which change more slowly, and mostly need to be updated to new dependencies, an automatic test suite helps to very quickly establish whether the package still works. + This makes it much easier to decide whether the package is still supported or not. +* Automatic tests amplify the value of Continuous Integration. + Regression tests, along with normal scenario-based requirements tests, contribute to overall body of automated tests for your component. + Your component is better tested against evolution of other APIs that it depends on (CI servers will tell you better and more precisely what problems develop in your code). Perhaps the most important benefit of writing tests is that tests make you a good citizen. Tests influence quality in the long term. @@ -28,8 +57,13 @@ Is this all coming for free? Of course, there is never free lunch. To get the benefits of testing, some investment is necessary. -* You need to develop a test, which sometimes may be difficult or costly. Sometimes it might also be nontrivial, as the test should be automatic. Things get particularly hairy if your tests should involve special hardware (they should not: try to use simulation, mock the hardware, or narrow down the test to a smaller software problem) or require external environment, for instance human operators. -* Regression tests and other automatic tests need to be maintained. When the design of the component changes, a lot of tests become invalidated (for instance they no longer compile, or throw runtime exceptions related to the API design). These tests fail not only because the redesign re-introduced bugs but also because they need to be updated to the new design. Occasionally, with bigger redesigns, old regression tests should be dropped. +* You need to develop a test, which sometimes may be difficult or costly. + Sometimes it might also be nontrivial, as the test should be automatic. + Things get particularly hairy if your tests should involve special hardware (they should not: try to use simulation, mock the hardware, or narrow down the test to a smaller software problem) or require external environment, for instance human operators. +* Regression tests and other automatic tests need to be maintained. + When the design of the component changes, a lot of tests become invalidated (for instance they no longer compile, or throw runtime exceptions related to the API design). + These tests fail not only because the redesign re-introduced bugs but also because they need to be updated to the new design. + Occasionally, with bigger redesigns, old regression tests should be dropped. * Large bodies of tests can take a long time to run, which can increase Continuous Integration server costs. Available Tutorials: diff --git a/source/Tutorials/Intermediate/Tf2/Quaternion-Fundamentals.rst b/source/Tutorials/Intermediate/Tf2/Quaternion-Fundamentals.rst index aeba26df5ad..0deef2e89fb 100644 --- a/source/Tutorials/Intermediate/Tf2/Quaternion-Fundamentals.rst +++ b/source/Tutorials/Intermediate/Tf2/Quaternion-Fundamentals.rst @@ -168,7 +168,8 @@ You want to find the relative rotation, ``q_r``, that converts ``q_1`` to ``q_2` q_2 = q_r * q_1 You can solve for ``q_r`` similarly to solving a matrix equation. -Invert ``q_1`` and right-multiply both sides. Again, the order of multiplication is important: +Invert ``q_1`` and right-multiply both sides. +Again, the order of multiplication is important: .. code-block:: C++ diff --git a/source/Tutorials/Intermediate/Tf2/Time-Travel-With-Tf2-Cpp.rst b/source/Tutorials/Intermediate/Tf2/Time-Travel-With-Tf2-Cpp.rst index 635145b29cb..adee5bc6474 100644 --- a/source/Tutorials/Intermediate/Tf2/Time-Travel-With-Tf2-Cpp.rst +++ b/source/Tutorials/Intermediate/Tf2/Time-Travel-With-Tf2-Cpp.rst @@ -48,7 +48,8 @@ Edit the ``lookupTransform()`` call in ``turtle_tf2_listener.cpp`` file to } catch (const tf2::TransformException & ex) { Now if you run this, during the first 5 seconds, the second turtle would not know where to go because we do not yet have a 5-second history of poses of the carrot. -But what happens after these 5 seconds? Build the package then let's just give it a try: +But what happens after these 5 seconds? +Build the package then let's just give it a try: .. code-block:: console @@ -56,9 +57,11 @@ But what happens after these 5 seconds? Build the package then let's just give i .. image:: images/turtlesim_delay1.png -You should now notice that your turtle is driving around uncontrollably like in this screenshot. Let's try to understand reason behind that behavior. +You should now notice that your turtle is driving around uncontrollably like in this screenshot. +Let's try to understand reason behind that behavior. -#. In our code we asked tf2 the following question: "What was the pose of ``carrot1`` 5 seconds ago, relative to ``turtle2`` 5 seconds ago?". This means we are controlling the second turtle based on where it was 5 seconds ago as well as where the first carrot was 5 seconds ago. +#. In our code we asked tf2 the following question: "What was the pose of ``carrot1`` 5 seconds ago, relative to ``turtle2`` 5 seconds ago?". + This means we are controlling the second turtle based on where it was 5 seconds ago as well as where the first carrot was 5 seconds ago. #. However, what we really want to ask is: "What was the pose of ``carrot1`` 5 seconds ago, relative to the current position of the ``turtle2``?". diff --git a/source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Cpp.rst b/source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Cpp.rst index db71cf84dc1..742fd692e9f 100644 --- a/source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Cpp.rst +++ b/source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Cpp.rst @@ -407,7 +407,8 @@ The following command publishes a static coordinate transform to tf2 using an x/ ros2 run tf2_ros static_transform_publisher --x x --y y --z z --qx qx --qy qy --qz qz --qw qw --frame-id frame_id --child-frame-id child_frame_id -``static_transform_publisher`` is designed both as a command-line tool for manual use, as well as for use within ``launch`` files for setting static transforms. For example: +``static_transform_publisher`` is designed both as a command-line tool for manual use, as well as for use within ``launch`` files for setting static transforms. +For example: .. code-block:: console diff --git a/source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Py.rst b/source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Py.rst index 6618a2c62e2..d93da2b18a3 100644 --- a/source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Py.rst +++ b/source/Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Py.rst @@ -426,7 +426,8 @@ The following command publishes a static coordinate transform to tf2 using an x/ ros2 run tf2_ros static_transform_publisher --x x --y y --z z --qx qx --qy qy --qz qz --qw qw --frame-id frame_id --child-frame-id child_frame_id -``static_transform_publisher`` is designed both as a command-line tool for manual use, as well as for use within ``launch`` files for setting static transforms. For example: +``static_transform_publisher`` is designed both as a command-line tool for manual use, as well as for use within ``launch`` files for setting static transforms. +For example: .. code-block:: python diff --git a/source/Tutorials/Intermediate/URDF/Adding-Physical-and-Collision-Properties-to-a-URDF-Model.rst b/source/Tutorials/Intermediate/URDF/Adding-Physical-and-Collision-Properties-to-a-URDF-Model.rst index 59d54df2e34..0064c8e7944 100644 --- a/source/Tutorials/Intermediate/URDF/Adding-Physical-and-Collision-Properties-to-a-URDF-Model.rst +++ b/source/Tutorials/Intermediate/URDF/Adding-Physical-and-Collision-Properties-to-a-URDF-Model.rst @@ -61,8 +61,7 @@ However, there are two main cases where you wouldn’t: Physical Properties ------------------- -In order to get your model to simulate properly, you need to define several physical properties of your robot, i.e. -the properties that a physics engine like Gazebo would need. +In order to get your model to simulate properly, you need to define several physical properties of your robot, i.e. the properties that a physics engine like Gazebo would need. Inertia ^^^^^^^ @@ -109,7 +108,8 @@ Here is a simple one. * The inertia tensor depends on both the mass and the distribution of mass of the object. A good first approximation is to assume equal distribution of mass in the volume of the object and compute the inertia tensor based on the object's shape, as outlined above. * If unsure what to put, a matrix with ixx/iyy/izz=1e-3 or smaller is often a reasonable default for a mid-sized link (it corresponds to a box of 0.1 m side length with a mass of 0.6 kg). - The identity matrix is a particularly bad choice, since it is often much too high (it corresponds to a box of 0.1 m side length with a mass of 600 kg!). + The identity matrix is a particularly bad choice, since it is often much too high. + (it corresponds to a box of 0.1 m side length with a mass of 600 kg!) * You can also specify an origin tag to specify the center of gravity and the inertial reference frame (relative to the link's reference frame). * When using realtime controllers, inertia elements of zero (or almost zero) can cause the robot model to collapse without warning, and all links will appear with their origins coinciding with the world origin. diff --git a/source/Tutorials/Intermediate/URDF/Building-a-Movable-Robot-Model-with-URDF.rst b/source/Tutorials/Intermediate/URDF/Building-a-Movable-Robot-Model-with-URDF.rst index dd34707f77b..d44b9688b5f 100644 --- a/source/Tutorials/Intermediate/URDF/Building-a-Movable-Robot-Model-with-URDF.rst +++ b/source/Tutorials/Intermediate/URDF/Building-a-Movable-Robot-Model-with-URDF.rst @@ -109,7 +109,8 @@ Specifying the Pose ------------------- As you move the sliders around in the GUI, the model moves in Rviz. -How is this done? First the `GUI `_ parses the URDF and finds all the non-fixed joints and their limits. +How is this done? +First the `GUI `_ parses the URDF and finds all the non-fixed joints and their limits. Then, it uses the values of the sliders to publish `sensor_msgs/msg/JointState `_ messages. Those are then used by `robot_state_publisher `_ to calculate all of transforms between the different parts. The resulting transform tree is then used to display all of the shapes in Rviz. diff --git a/source/Tutorials/Intermediate/URDF/Building-a-Visual-Robot-Model-with-URDF-from-Scratch.rst b/source/Tutorials/Intermediate/URDF/Building-a-Visual-Robot-Model-with-URDF-from-Scratch.rst index d28a955fd24..73ab6718e87 100644 --- a/source/Tutorials/Intermediate/URDF/Building-a-Visual-Robot-Model-with-URDF-from-Scratch.rst +++ b/source/Tutorials/Intermediate/URDF/Building-a-Visual-Robot-Model-with-URDF-from-Scratch.rst @@ -186,7 +186,8 @@ We also rotate the leg so it is upright. * The launch file runs packages that will create TF frames for each link in your model based on your URDF. Rviz uses this information to figure out where to display each shape. -* If a TF frame does not exist for a given URDF link, then it will be placed at the origin in white (ref. `related question `_). +* If a TF frame does not exist for a given URDF link, then it will be placed at the origin in white + (ref. `related question `_). Material Girl ------------- diff --git a/source/Tutorials/Intermediate/URDF/Exporting-an-URDF-File.rst b/source/Tutorials/Intermediate/URDF/Exporting-an-URDF-File.rst index c4aad61b5a3..ae67d9cd490 100644 --- a/source/Tutorials/Intermediate/URDF/Exporting-an-URDF-File.rst +++ b/source/Tutorials/Intermediate/URDF/Exporting-an-URDF-File.rst @@ -15,7 +15,8 @@ Most roboticists work in teams, and often those teams include a mechanical engin Instead of crafting an URDF by hand it is possible to export an URDF model from many different CAD and modeling programs. These export tools are often developed by individuals that are familiar with the particular CAD program they use. Below you will find a list of available URDF exporters for a variety of CAD and 3D modeling software systems. -*The ROS core maintainers do not maintain these packages. As such we make no claims about their performance or ease of use.* +*The ROS core maintainers do not maintain these packages. +As such we make no claims about their performance or ease of use.* However, we figured it would be helpful to produce a list of available URDF exporters. **CAD Exporters** diff --git a/source/Tutorials/Intermediate/URDF/Using-URDF-with-Robot-State-Publisher.rst b/source/Tutorials/Intermediate/URDF/Using-URDF-with-Robot-State-Publisher.rst index 6a32f3626e6..94a53573c7b 100644 --- a/source/Tutorials/Intermediate/URDF/Using-URDF-with-Robot-State-Publisher.rst +++ b/source/Tutorials/Intermediate/URDF/Using-URDF-with-Robot-State-Publisher.rst @@ -282,6 +282,7 @@ Save the ``setup.py`` file with your changes. 6 Install the package ^^^^^^^^^^^^^^^^^^^^^ + .. code-block:: console cd second_ros2_ws diff --git a/source/Tutorials/Intermediate/URDF/Using-Xacro-to-Clean-Up-a-URDF-File.rst b/source/Tutorials/Intermediate/URDF/Using-Xacro-to-Clean-Up-a-URDF-File.rst index c27c6f3cad5..2f5014ada1c 100644 --- a/source/Tutorials/Intermediate/URDF/Using-Xacro-to-Clean-Up-a-URDF-File.rst +++ b/source/Tutorials/Intermediate/URDF/Using-Xacro-to-Clean-Up-a-URDF-File.rst @@ -179,7 +179,8 @@ Let’s take a look at a simple useless macro. -(This is useless, since if the origin is not specified, it has the same value as this.) This code will generate the following. +(This is useless, since if the origin is not specified, it has the same value as this.) +This code will generate the following. .. code-block:: xml diff --git a/source/Tutorials/Intermediate/Writing-an-Action-Server-Client/Cpp.rst b/source/Tutorials/Intermediate/Writing-an-Action-Server-Client/Cpp.rst index 81d690570b5..5dd898e2d48 100644 --- a/source/Tutorials/Intermediate/Writing-an-Action-Server-Client/Cpp.rst +++ b/source/Tutorials/Intermediate/Writing-an-Action-Server-Client/Cpp.rst @@ -232,7 +232,8 @@ Open up ``custom_action_cpp/CMakeLists.txt``, and add the following right after LIBRARY DESTINATION lib RUNTIME DESTINATION bin) -And now we can compile the package. Go to the top-level of the ``ros2_ws``, and run: +And now we can compile the package. +Go to the top-level of the ``ros2_ws``, and run: .. code-block:: bash @@ -360,7 +361,8 @@ Open up ``custom_action_cpp/CMakeLists.txt``, and add the following right after LIBRARY DESTINATION lib RUNTIME DESTINATION bin) -And now we can compile the package. Go to the top-level of the ``ros2_ws``, and run: +And now we can compile the package. +Go to the top-level of the ``ros2_ws``, and run: .. code-block:: bash diff --git a/source/Tutorials/Intermediate/Writing-an-Action-Server-Client/Py.rst b/source/Tutorials/Intermediate/Writing-an-Action-Server-Client/Py.rst index 322d0818557..824a5f0fb40 100644 --- a/source/Tutorials/Intermediate/Writing-an-Action-Server-Client/Py.rst +++ b/source/Tutorials/Intermediate/Writing-an-Action-Server-Client/Py.rst @@ -346,7 +346,8 @@ This is achieved by additionally passing the callback to the action client when :language: python :lines: 20 -We're all set. If we run our action client, you should see feedback being printed to the screen. +We're all set. +If we run our action client, you should see feedback being printed to the screen. Summary ------- diff --git a/source/Tutorials/Miscellaneous/Building-ROS2-Package-with-eclipse-2021-06.rst b/source/Tutorials/Miscellaneous/Building-ROS2-Package-with-eclipse-2021-06.rst index 7f5f559759a..b4bc0ad500d 100644 --- a/source/Tutorials/Miscellaneous/Building-ROS2-Package-with-eclipse-2021-06.rst +++ b/source/Tutorials/Miscellaneous/Building-ROS2-Package-with-eclipse-2021-06.rst @@ -38,7 +38,8 @@ We see that we got C++ includes. :alt: eclipse_c++_project_includes -We now import our ROS 2 project. The code is still in the old place. +We now import our ROS 2 project. +The code is still in the old place. .. image:: images/eclipse_import_project.png :target: images/eclipse_import_project.png diff --git a/source/Tutorials/Miscellaneous/Building-Realtime-rt_preempt-kernel-for-ROS-2.rst b/source/Tutorials/Miscellaneous/Building-Realtime-rt_preempt-kernel-for-ROS-2.rst index 71120de07a8..ff9ea4a0314 100644 --- a/source/Tutorials/Miscellaneous/Building-Realtime-rt_preempt-kernel-for-ROS-2.rst +++ b/source/Tutorials/Miscellaneous/Building-Realtime-rt_preempt-kernel-for-ROS-2.rst @@ -6,7 +6,9 @@ Building a real-time Linux kernel [community-contributed] ========================================================= -This tutorial begins with a clean Ubuntu 20.04.1 install on Intel x86_64. Actual kernel is 5.4.0-54-generic, but we will install the Latest Stable RT_PREEMPT Version. To build the kernel you need at least 30GB free disk space. +This tutorial begins with a clean Ubuntu 20.04.1 install on Intel x86_64. +Actual kernel is 5.4.0-54-generic, but we will install the Latest Stable RT_PREEMPT Version. +To build the kernel you need at least 30GB free disk space. Check https://wiki.linuxfoundation.org/realtime/start for the latest stable version, at the time of writing this is "Latest Stable Version 5.4-rt". If we click on the `link `_, we get the exact version. @@ -68,7 +70,8 @@ We simply want to use the config of our Ubuntu installation, so we get the Ubunt cp /boot/config-5.4.0-54-generic .config -Open Software & Updates. in the Ubuntu Software menu tick the 'Source code' box +Open Software & Updates. +in the Ubuntu Software menu tick the 'Source code' box We need some tools to build kernel, install them with @@ -83,7 +86,8 @@ To enable all Ubuntu configurations, we simply use yes '' | make oldconfig -Then we need to enable rt_preempt in the kernel. We call +Then we need to enable rt_preempt in the kernel. +We call .. code-block:: bash @@ -121,7 +125,8 @@ and set the following -> Default CPUFreq governor ( [=y]) (X) performance -Save and exit menuconfig. Now we're going to build the kernel which will take quite some time. (10-30min on a modern cpu) +Save and exit menuconfig. +Now we're going to build the kernel which will take quite some time. (10-30min on a modern cpu) .. code-block:: bash @@ -141,7 +146,8 @@ Then we install all kernel deb packages sudo dpkg -i ../*.deb -Now the real time kernel should be installed. Reboot the system and check the new kernel version +Now the real time kernel should be installed. +Reboot the system and check the new kernel version .. code-block:: bash diff --git a/source/Tutorials/Miscellaneous/Deploying-ROS-2-on-IBM-Cloud.rst b/source/Tutorials/Miscellaneous/Deploying-ROS-2-on-IBM-Cloud.rst index 47010283873..c758978f086 100644 --- a/source/Tutorials/Miscellaneous/Deploying-ROS-2-on-IBM-Cloud.rst +++ b/source/Tutorials/Miscellaneous/Deploying-ROS-2-on-IBM-Cloud.rst @@ -14,7 +14,8 @@ Deploying on IBM Cloud Kubernetes [community-contributed] About ----- -This article describes how to get ROS 2 running on IBM Cloud using Docker files. It first gives a brief overview of docker images and how they work locally and then explores IBM Cloud and how the user can deploy their containers on it. +This article describes how to get ROS 2 running on IBM Cloud using Docker files. +It first gives a brief overview of docker images and how they work locally and then explores IBM Cloud and how the user can deploy their containers on it. Afterwards, a short description of how the user can use their own custom packages for ROS 2 from github on IBM Cloud is provided. A walkthrough of how to create a cluster and utilize Kubernetes on IBM Cloud is provided and finally the Docker image is deployed on the cluster. Originally published `here `__ and `here `__. @@ -25,11 +26,10 @@ ROS 2 on IBM Cloud In this tutorial, we show how you can easily integrate and run ROS 2 on IBM Cloud with your custom packages. -ROS 2 is the new generation of ROS which gives more control over -multi-robot formations. With the advancements of cloud computing, cloud -robotics are becoming more important in today's age. In this tutorial, -we will go through a short introduction on running ROS 2 on IBM Cloud. By -the end of the tutorial, you will be able to create your own packages in +ROS 2 is the new generation of ROS which gives more control over multi-robot formations. +With the advancements of cloud computing, cloud robotics are becoming more important in today's age. +In this tutorial, we will go through a short introduction on running ROS 2 on IBM Cloud. +By the end of the tutorial, you will be able to create your own packages in ROS 2 and deploy them to the cloud using docker files. The following instructions assume you're using Linux and have been @@ -38,29 +38,26 @@ tested with Ubuntu 18.04 (Bionic Beaver). Step 1: Setting up your system ------------------------------- -Before we go into how the exact process works, lets first make sure all -the required software is properly installed. We'll point you towards the -appropriate sources to set up your system and only highlight the details -that pertain to our use-case. +Before we go into how the exact process works, lets first make sure all the required software is properly installed. +We'll point you towards the appropriate sources to set up your system and only highlight the details that pertain to our use-case. a) Docker files? ^^^^^^^^^^^^^^^^ Docker files are a form of containers that can run separate from your system, this way, you can set-up potentially hundreds of different -projects without affecting one another. You can even set-up different -versions of Linux on one machine, without the need for virtual machine. -Docker files have an advantage of saving space and only utilizing your -system resources when running. In addition, dockers are versatile and -transferable. They contain all the required pre-requisites to run +projects without affecting one another. +You can even set-up different versions of Linux on one machine, without the need for virtual machine. +Docker files have an advantage of saving space and only utilizing your system resources when running. +In addition, dockers are versatile and transferable. +They contain all the required pre-requisites to run separately, meaning that you can easily use a docker file for a specific system or service without any cubersome steps! -Excited yet? Let's start off by installing docker to your system by -following the following `link `__. -From the tutorial, you should have done some sanity checks to make sure -docker is properly set-up. Just in case, however, let's run the -following command once again that uses the hello-world docker image: +Excited yet? +Let's start off by installing docker to your system by following the following `link `__. +From the tutorial, you should have done some sanity checks to make sure docker is properly set-up. +Just in case, however, let's run the following command once again that uses the hello-world docker image: .. code-block:: bash @@ -96,16 +93,17 @@ b) ROS 2 Image ROS `announced `__ -image containers for several ROS distributions in January 2019. More -detailed instructions on the use of ROS 2 docker images can be found +image containers for several ROS distributions in January 2019. +More detailed instructions on the use of ROS 2 docker images can be found `here `__. Let's skip through that and get to real-deal right away; creating a -local ROS 2 docker. We'll create our own Dockerfile (instead of using a +local ROS 2 docker. +We'll create our own Dockerfile (instead of using a ready Image) since we'll need this method for deployment on IBM Cloud. First, we create a new directory which will hold our Dockerfile and any -other files we need later on and navigate to it. Using your favorite -$EDITOR of choice, open a new file named *Dockerfile* (make sure the +other files we need later on and navigate to it. +Using your favorite $EDITOR of choice, open a new file named *Dockerfile* (make sure the file naming is correct): .. code-block:: bash @@ -141,15 +139,14 @@ Insert the following in the *Dockerfile*, and save it (also found be for it Of course, you are free to change the ROS distribution (*foxy* is used -here) or change the directory name. The above docker file sets up -ROS-foxy and installs the demo nodes for C++ and Python. Then it -launches a file which runs a talker and a listener node. We will see it -in action in just a few, but they act very similar to the +here) or change the directory name. +The above docker file sets up ROS-foxy and installs the demo nodes for C++ and Python. +Then it launches a file which runs a talker and a listener node. +We will see it in action in just a few, but they act very similar to the publisher-subscriber example found in the `ROS wiki `__ -Now, we are ready to build the docker image to run ROS 2 in it (yes, it -is THAT easy!). +Now, we are ready to build the docker image to run ROS 2 in it (yes, it is THAT easy!). **Note**: if you have errors due to insufficient privileges or *permission denied*, try running the command with *sudo* privileges: @@ -162,7 +159,8 @@ is THAT easy!). Successfully built 0dc6ce7cb487 *0dc6ce7cb487* will most probably be different for you, so keep note of -it and copy it somewhere for reference. You can always go back and check +it and copy it somewhere for reference. +You can always go back and check the docker images you have on your system using: .. code-block:: bash @@ -191,15 +189,16 @@ Now, run the docker file using: [talker-1] [INFO] [1603852912.249556670] [talker]: Publishing: 'Hello World: 6' [listener-2] [INFO] [1603852912.250212678] [listener]: I heard: [Hello World: 6] -If it works correctly, you should see something similar to what is shown -above. As can be seen, there are two ROS nodes (a publisher and a +If it works correctly, you should see something similar to what is shown above. +As can be seen, there are two ROS nodes (a publisher and a subscriber) running and their output is provided to us through ROS INFO. Step 2: Running the image on IBM Cloud -------------------------------------- The following steps assume you have an IBM cloud account and have -ibmcloud CLI installed. If not, please check this +ibmcloud CLI installed. +If not, please check this `link `__ out to get that done first. @@ -216,20 +215,18 @@ Afterwards, login to your ibmcloud account through the terminal: $ ibmcloud login --sso -From here, let's create a container registry name-space. Make sure you -use a unique name that is also descriptive as to what it is. Here, I -used *ros2nasr*. +From here, let's create a container registry name-space. +Make sure you use a unique name that is also descriptive as to what it is. +Here, I used *ros2nasr*. .. code-block:: bash $ ibmcloud cr namespace-add ros2nasr -IBM cloud has a lot of shortcuts that would help us get our container -onto the cloud right away. The command below builds the container and -tags it with the name **ros2foxy** and the version of **1**. Make sure -you use the correct registry name you created and you are free to change -the container name as you wish. The **.** at the end indicates that the -*Dockerfile* is in the current directory (and it is important), if not, +IBM cloud has a lot of shortcuts that would help us get our container onto the cloud right away. +The command below builds the container and tags it with the name **ros2foxy** and the version of **1**. +Make sure you use the correct registry name you created and you are free to change the container name as you wish. +The **.** at the end indicates that the *Dockerfile* is in the current directory (and it is important), if not, change it to point to the directory containing the Dockerfile. .. code-block:: bash @@ -249,10 +246,9 @@ you created by running the following command OK -Next, it is important to log-in to your registry to run the docker -image. Again, if you face a *permission denied* error, perform the -command with sudo privileges. Afterwards, run your docker file as shown -below. +Next, it is important to log-in to your registry to run the docker image. +Again, if you face a *permission denied* error, perform the command with sudo privileges. +Afterwards, run your docker file as shown below. .. code-block:: bash @@ -276,14 +272,12 @@ to that you saw when you ran it locally on your machine. Step 3: Using Custom ROS 2 Packages ----------------------------------- -So now we have the full pipeline working, from creating the Dockerfile, -all the way to deploying it and seeing it work on IBM Cloud. But, what -if we want to use a custom set of packages we (or someone else) created? +So now we have the full pipeline working, from creating the Dockerfile, all the way to deploying it and seeing it work on IBM Cloud. +But, what if we want to use a custom set of packages we (or someone else) created? -Well that all has to do with how you set-up your Dockerfile. Let's use -the example provided by ROS 2 `here `__. -Create a new directory with a new Dockerfile (or overwrite the existing -one) and add the following in it (or download the file +Well that all has to do with how you set-up your Dockerfile. +Let's use the example provided by ROS 2 `here `__. +Create a new directory with a new Dockerfile (or overwrite the existing one) and add the following in it (or download the file `here `__) .. code-block:: bash @@ -408,12 +402,10 @@ and then run them. **Back to IBM Cloud** -With this Dockerfile, we can follow the same steps we did before to -deploy it on IBM Cloud. Since we already have our registry created, and -we're logged in to IBM Cloud, we directly build our new Dockerfile. -Notice how I kept the tag the same but changed the version, this way I -can update the docker image created previously. (You are free to create -a completely new one if you want) +With this Dockerfile, we can follow the same steps we did before to deploy it on IBM Cloud. +Since we already have our registry created, and we're logged in to IBM Cloud, we directly build our new Dockerfile. +Notice how I kept the tag the same but changed the version, this way I can update the docker image created previously. +(You are free to create a completely new one if you want) .. code-block:: bash @@ -434,9 +426,8 @@ image: $ docker run -v -it registry.ng.bluemix.net/ros2nasr/ros2foxy:2 -You should see, again, the same output. However, this time we did it -through custom packages from github, which allows us to utilize our -personally created packages for ROS 2 on IBM Cloud. +You should see, again, the same output. +However, this time we did it through custom packages from github, which allows us to utilize our personally created packages for ROS 2 on IBM Cloud. Extra: Deleting Docker Images ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -465,11 +456,11 @@ Step 4: Kubernetes a) Creating the Cluster ^^^^^^^^^^^^^^^^^^^^^^^ -Create a cluster using the Console. The instructions are found -`here `__. -The settings used are detailed below. These are merely suggestions and -can be changed if you need to. However, make sure you understand the -implications of your choices: +Create a cluster using the Console. +The instructions are found `here `__. +The settings used are detailed below. +These are merely suggestions and can be changed if you need to. +However, make sure you understand the implications of your choices: 1. Plan: *Standard* @@ -483,9 +474,8 @@ implications of your choices: - Geography: *North America* (you are free to change this) -- Availability: *Single zone* (you are free to change this but make - sure you understand the impact of your choices by checking the IBM - Cloud documentation.) +- Availability: *Single zone* + (you are free to change this but make sure you understand the impact of your choices by checking the IBM Cloud documentation.) - Worker Zone: *Toronto 01* (choose the location that is physically closest to you) @@ -506,13 +496,11 @@ implications of your choices: - Tags: *version:1* -After you create your cluster, you will be redirected to a page which -details how you can set up the CLI tools and access your cluster. Please -follow these instructions (or check the instructions -`here `__)and -wait for the progress bar to show that the worker nodes you created are -ready by indicating *Normal* next to the cluster name. You can also -reach this screen from the IBM Cloud Console inside the Kubernetes. +After you create your cluster, you will be redirected to a page which details how you can set up the CLI tools and access your cluster. +Please follow these instructions (or check the instructions `here `__) +and wait for the progress bar to show that the worker nodes you created are +ready by indicating *Normal* next to the cluster name. +You can also reach this screen from the IBM Cloud Console inside the Kubernetes. b) Deploying your Docker Image *Finally!* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -588,8 +576,9 @@ parameters of your cluster as well as its CPU and Memory Usage. 4. On the top right corner, click on *Exec into pod* -Now you are inside your docker image! You can source your workspace (if -needed) and run ROS 2! For example: +Now you are inside your docker image! +You can source your workspace (if needed) and run ROS 2! +For example: .. code-block:: bash @@ -599,4 +588,8 @@ needed) and run ROS 2! For example: Final Remarks --------------- -At this point, you are capable of creating your own docker image using ROS 2 packages on github. It is also possible, with little changes to utilize local ROS 2 packages as well. This could be the topic of another article. However, you are encouraged to check out the following `Dockerfile `__ which uses a local copy of the demos repository. Similarly, you can use your own local package. +At this point, you are capable of creating your own docker image using ROS 2 packages on github. +It is also possible, with little changes to utilize local ROS 2 packages as well. +This could be the topic of another article. +However, you are encouraged to check out the following `Dockerfile `__ which uses a local copy of the demos repository. +Similarly, you can use your own local package. diff --git a/source/index.rst b/source/index.rst index a686ef528cc..0d38cb776f7 100644 --- a/source/index.rst +++ b/source/index.rst @@ -29,7 +29,8 @@ From drivers and state-of-the-art algorithms to powerful developer tools, ROS ha 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. -**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 `__. +**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 `__. This site contains the documentation for ROS 2. If you are looking for ROS 1 documentation, check out the `ROS wiki `__.