From 1110ab72905c5bea82f3df96af3588aad04ce037 Mon Sep 17 00:00:00 2001 From: Kacper Bojakowski Date: Mon, 27 Apr 2026 19:14:48 +0200 Subject: [PATCH 1/5] Draft Setting up environment --- .../Configuring-ROS2-Environment.rst | 143 ++++++++++++------ 1 file changed, 96 insertions(+), 47 deletions(-) diff --git a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst index eae0fb57d67..e1177c6d1f9 100644 --- a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst +++ b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst @@ -4,53 +4,58 @@ .. _ConfigROS2: -Configuring environment -======================= +Setting up your environment - how-to +==================================== -**Goal:** This tutorial will show you how to prepare your ROS 2 environment. +After you install ROS, you need to configure your shell before commands and packages are available. +In this guide, you will learn how to access ROS commands and packages by sourcing setup files and configuring environment variables. -**Tutorial level:** Beginner - -**Time:** 5 minutes +**Area: ROS-installation | Content-type: how-to | Experience: beginner, intermediate** .. contents:: Contents :depth: 2 :local: -Background ----------- +Summary +------- + +You need to configure the ROS development environment before use. +If you ever face any problems locating or using packages with ROS, the first thing you should do is check your environment variables and ensure they are set to the version and distro you intended. -ROS 2 relies on the notion of combining workspaces using the shell environment. -"Workspace" is a ROS term for the location on your system where you're developing with ROS 2. -The core ROS 2 workspace is called the underlay. +ROS relies on the notion of combining workspaces using the shell environment. +"Workspace" is the location on your system where you are developing with ROS. +The core ROS workspace is called the underlay. Subsequent local workspaces are called overlays. -When developing with ROS 2, you will typically have several workspaces active concurrently. +When developing with ROS, you will typically have several workspaces active at the same time. + +Combining workspaces makes it easier to develop against different versions of ROS 2 or different sets of packages. +It also allows the installation of several ROS 2 distributions (or "distros", such as Dashing or Eloquent) on the same computer and switching between them. + +You can do this in one of the two ways: -Combining workspaces makes developing against different versions of ROS 2, or against different sets of packages, easier. -It also allows the installation of several ROS 2 distributions (or "distros", e.g. Dashing and Eloquent) on the same computer and switching between them. +* Source the setup files in every new shell you open. +* Add the source command to your startup script. -This is accomplished by sourcing setup files every time you open a new shell, or by adding the source command to your shell startup script once. -Without sourcing the setup files, you won't be able to access ROS 2 commands, or find or use ROS 2 packages. -In other words, you won't be able to use ROS 2. +Without sourcing the setup files, you won't be able to access ROS commands or find or use ROS packages. Prerequisites ------------- -Before starting these tutorials, install ROS 2 by following the instructions on the ROS 2 :doc:`../../Installation` page. +Install ROS by following the instructions on the ROS :doc:`../../Installation` page. -The commands used in this tutorial assume you followed the binary packages installation guide for your operating system (deb packages for Linux). -You can still follow along if you built from source, but the path to your setup files will likely be different. -You also won't be able to use the ``sudo apt install ros--`` command (used frequently in the beginner level tutorials) if you install from source. +The commands in this guide assume you installed binary packages for your operating system (deb packages on Linux). +If you built ROS from source, you can still follow this guide, but the path to your setup files is probably different. +If you install from source, you cannot use ``sudo apt install ros--``, which appears often in the beginner tutorials. -If you are using Linux or macOS, but are not already familiar with the shell, `this tutorial `__ will help. +If you use Linux or macOS, but are not already familiar with the shell, follow `this tutorial `__. -Tasks +Steps ----- 1 Source the setup files ^^^^^^^^^^^^^^^^^^^^^^^^ -You will need to run this command on every new shell you open to have access to the ROS 2 commands, like so: +To access the ROS commands, you need to run the following command on every new shell you open: .. tabs:: @@ -77,13 +82,13 @@ You will need to run this command on every new shell you open to have access to $ call C:\dev\ros2\local_setup.bat .. note:: - The exact command depends on where you installed ROS 2. - If you're having problems, ensure the file path leads to your installation. + The exact command depends on where you installed ROS. + If you have problems, make sure that the file path leads to your installation. 2 Add sourcing to your shell startup script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you don't want to have to source the setup file every time you open a new shell (skipping task 1), then you can add the command to your shell startup script: +If you don't want to source the setup file every time you open a new shell, you can add the following command to your shell startup script: .. tabs:: @@ -105,9 +110,9 @@ If you don't want to have to source the setup file every time you open a new she .. group-tab:: Windows - Only for PowerShell users, create a folder in 'My Documents' called 'WindowsPowerShell'. - Within 'WindowsPowerShell', create file 'Microsoft.PowerShell_profile.ps1'. - Inside the file, paste: + If you use PowerShell, create a folder in **My Documents** named **WindowsPowerShell**. + Inside **WindowsPowerShell**, create the file **Microsoft.PowerShell_profile.ps1**. + Paste the following line into that file: .. code-block:: console @@ -120,13 +125,13 @@ If you don't want to have to source the setup file every time you open a new she $ Unblock-File C:\dev\ros2_{DISTRO}\local_setup.ps1 - To undo this, remove the new 'Microsoft.PowerShell_profile.ps1' file. + To undo this step, delete **Microsoft.PowerShell_profile.ps1**. 3 Check environment variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Sourcing ROS 2 setup files will set several environment variables necessary for operating ROS 2. -If you ever have problems finding or using your ROS 2 packages, make sure that your environment is properly set up using the following command: +Sourcing ROS setup files sets the environment variables that ROS needs. +If you cannot find or use packages, confirm your environment with the following command: .. tabs:: @@ -148,7 +153,7 @@ If you ever have problems finding or using your ROS 2 packages, make sure that y $ set | findstr -i ROS -Check that variables like ``ROS_DISTRO`` and ``ROS_VERSION`` are set. +Confirm that variables such as ``ROS_DISTRO`` and ``ROS_VERSION`` are set. :: @@ -156,15 +161,15 @@ Check that variables like ``ROS_DISTRO`` and ``ROS_VERSION`` are set. ROS_PYTHON_VERSION=3 ROS_DISTRO={DISTRO} -If the environment variables are not set correctly, return to the ROS 2 package installation section of the installation guide you followed. +If the environment variables are not set correctly, return to the ROS package installation section of the installation guide you followed. If you need more specific help (because environment setup files can come from different places), you can `get answers `__ from the community. 3.1 The ``ROS_DOMAIN_ID`` variable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the `domain ID <../../Concepts/Intermediate/About-Domain-ID>` article for details on ROS domain IDs. +For details on domain IDs, read :doc:`About Domain ID <../../Concepts/Intermediate/About-Domain-ID>`. -Once you have determined a unique integer for your group of ROS 2 nodes, you can set the environment variable with the following command: +After you determine a unique integer for your group of ROS nodes, set the variable with the following command: .. tabs:: @@ -207,20 +212,64 @@ Once you have determined a unique integer for your group of ROS 2 nodes, you can 3.2 The ``ROS_AUTOMATIC_DISCOVERY_RANGE`` variable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, ROS 2 communication is not limited to localhost. -``ROS_AUTOMATIC_DISCOVERY_RANGE`` environment variable allows you to limit ROS 2 discovery range. +By default, ROS communication is not limited to localhost. +``ROS_AUTOMATIC_DISCOVERY_RANGE`` environment variable allows you to limit ROS discovery range. Using ``ROS_AUTOMATIC_DISCOVERY_RANGE`` is helpful in certain settings, such as classrooms, where multiple robots may publish to the same topic causing strange behaviors. See :ref:`Improved Dynamic Discovery ` for more details. -Summary -------- +4 Verify your environment configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use this step to confirm that your shell has the ROS paths and variables from the earlier steps in this guide, including any optional variables you set. + +Choose a terminal session that matches how you configured ROS: + +* If you only source manually, run the commands below after you run your ``source``, ``.``, or ``call`` command in that terminal. +* If you use a startup script, open a new terminal window first, then run the commands below. + +Run: + +.. code-block:: console + + $ ros2 --help + +If usage text appears, your shell picked up the ROS command paths from the setup files in this guide. + +If you set optional ``ROS_DOMAIN_ID`` or ``ROS_AUTOMATIC_DISCOVERY_RANGE`` values earlier in this guide, run the same ROS-related environment check again in this shell (for example ``printenv`` / ``set`` as when you reviewed ROS variables) and confirm you see the values you expect. + +Related content +---------------- + +More articles: + +* :doc:`Installing on Ubuntu (deb packages) <../../Installation/Ubuntu-Install-Debs>` +* :doc:`Installing on Windows <../../Installation/Windows-Install-Binary>` +* :doc:`Installing on RHEL (RPM packages) <../../Installation/RHEL-Install-RPMs>` +* :doc:`Creating a workspace <../Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace>` + +FAQs +---- + +Do I need to source the setup files in every new terminal? + Yes. + ROS commands and packages are only available in shells where you have sourced the setup files. + To avoid doing this manually each time, add the source command to your shell startup script. -The ROS 2 development environment needs to be correctly configured before use. -This can be done in two ways: either sourcing the setup files in every new shell you open, or adding the source command to your startup script. +How do I check that my ROS environment is configured correctly? + List ROS-related environment variables (for example with ``printenv | grep -i ROS`` on Linux or macOS, or ``set | findstr -i ROS`` on Windows). + Confirm that ``ROS_DISTRO`` and ``ROS_VERSION`` are set, then run ``ros2 --help``. + If usage text appears, your shell picked up the ROS command paths from the setup files. -If you ever face any problems locating or using packages with ROS 2, the first thing you should do is check your environment variables and ensure they are set to the version and distro you intended. +Why is the ``ros2`` command not found after I installed ROS? + Installing ROS does not configure your shell automatically. + You must source the setup file for your installation (for example ``/opt/ros/{DISTRO}/setup.bash`` on Linux when using deb packages) in each new shell, or add that command to your startup script. -Next steps ----------- +What is ``ROS_DOMAIN_ID`` and when should I set it? + ``ROS_DOMAIN_ID`` selects which logical DDS domain your nodes use for discovery. + Nodes only discover each other when they share the same domain ID. + Set a unique value when you need to isolate groups of nodes, such as in classrooms where multiple robots would otherwise see the same topics. -Now that you have a working ROS 2 installation and you know how to source its setup files, you can start learning the ins and outs of ROS 2 with the :doc:`turtlesim tool <./Introducing-Turtlesim/Introducing-Turtlesim>`. +Can I install multiple ROS distributions on the same computer? + Yes. + Install each distribution separately, then source the setup file for the one you want to use in that shell session. + Combining workspaces through sourcing also lets you layer local overlays on top of the core underlay. \ No newline at end of file From 05a414ee75e18744f182430651ee9695375e5019 Mon Sep 17 00:00:00 2001 From: Kacper Bojakowski Date: Mon, 15 Jun 2026 00:44:24 +0200 Subject: [PATCH 2/5] Implement peer review feedback --- .../Configuring-ROS2-Environment.rst | 44 ++++++++----------- 1 file changed, 19 insertions(+), 25 deletions(-) diff --git a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst index e1177c6d1f9..6da4916fe19 100644 --- a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst +++ b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst @@ -7,8 +7,8 @@ Setting up your environment - how-to ==================================== -After you install ROS, you need to configure your shell before commands and packages are available. -In this guide, you will learn how to access ROS commands and packages by sourcing setup files and configuring environment variables. +After you install ROS, you need to configure your shell to access the relevant commands and packages. +This article describes how to access ROS commands and packages by sourcing setup files and configuring environment variables. **Area: ROS-installation | Content-type: how-to | Experience: beginner, intermediate** @@ -19,33 +19,23 @@ In this guide, you will learn how to access ROS commands and packages by sourcin Summary ------- -You need to configure the ROS development environment before use. -If you ever face any problems locating or using packages with ROS, the first thing you should do is check your environment variables and ensure they are set to the version and distro you intended. - -ROS relies on the notion of combining workspaces using the shell environment. -"Workspace" is the location on your system where you are developing with ROS. -The core ROS workspace is called the underlay. -Subsequent local workspaces are called overlays. -When developing with ROS, you will typically have several workspaces active at the same time. - -Combining workspaces makes it easier to develop against different versions of ROS 2 or different sets of packages. -It also allows the installation of several ROS 2 distributions (or "distros", such as Dashing or Eloquent) on the same computer and switching between them. +You always need to source the setup files to configure your shell environment. You can do this in one of the two ways: * Source the setup files in every new shell you open. * Add the source command to your startup script. -Without sourcing the setup files, you won't be able to access ROS commands or find or use ROS packages. +Without sourcing the setup files, you won't be able to access ROS commands or find and use ROS packages. Prerequisites ------------- Install ROS by following the instructions on the ROS :doc:`../../Installation` page. -The commands in this guide assume you installed binary packages for your operating system (deb packages on Linux). +This guide assumes you have installed binary packages for your operating system (deb packages on Linux). If you built ROS from source, you can still follow this guide, but the path to your setup files is probably different. -If you install from source, you cannot use ``sudo apt install ros--``, which appears often in the beginner tutorials. +If you install from source, you cannot use ``sudo apt install ros--``, which is often used in the beginner tutorials. If you use Linux or macOS, but are not already familiar with the shell, follow `this tutorial `__. @@ -55,7 +45,8 @@ Steps 1 Source the setup files ^^^^^^^^^^^^^^^^^^^^^^^^ -To access the ROS commands, you need to run the following command on every new shell you open: +Use the source command to import the environment variables which enable your shell to access the ROS commands. +You need to run this on every new shell you open: .. tabs:: @@ -85,8 +76,8 @@ To access the ROS commands, you need to run the following command on every new s The exact command depends on where you installed ROS. If you have problems, make sure that the file path leads to your installation. -2 Add sourcing to your shell startup script -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Add sourcing to your shell startup script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you don't want to source the setup file every time you open a new shell, you can add the following command to your shell startup script: @@ -98,7 +89,7 @@ If you don't want to source the setup file every time you open a new shell, you $ echo "source /opt/ros/{DISTRO}/setup.bash" >> ~/.bashrc - To undo this, locate your system's shell startup script and remove the appended source command. + To undo this, locate your system's shell startup script and remove the source command. .. group-tab:: macOS @@ -131,7 +122,9 @@ If you don't want to source the setup file every time you open a new shell, you ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sourcing ROS setup files sets the environment variables that ROS needs. -If you cannot find or use packages, confirm your environment with the following command: + +.. note:: + If you can't find or use packages, check your environment variables and ensure they are set to the version and distro you intended to use. .. tabs:: @@ -214,13 +207,14 @@ After you determine a unique integer for your group of ROS nodes, set the variab By default, ROS communication is not limited to localhost. ``ROS_AUTOMATIC_DISCOVERY_RANGE`` environment variable allows you to limit ROS discovery range. -Using ``ROS_AUTOMATIC_DISCOVERY_RANGE`` is helpful in certain settings, such as classrooms, where multiple robots may publish to the same topic causing strange behaviors. -See :ref:`Improved Dynamic Discovery ` for more details. +Using ``ROS_AUTOMATIC_DISCOVERY_RANGE`` is helpful in certain settings, such as classrooms, where multiple robots may publish to the same topic, which can cause strange behaviors. + +For more details, see :ref:`Improved Dynamic Discovery `. 4 Verify your environment configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Use this step to confirm that your shell has the ROS paths and variables from the earlier steps in this guide, including any optional variables you set. +Confirm that your shell has the ROS paths and variables from the earlier steps in this guide, including any optional variables you set. Choose a terminal session that matches how you configured ROS: @@ -272,4 +266,4 @@ What is ``ROS_DOMAIN_ID`` and when should I set it? Can I install multiple ROS distributions on the same computer? Yes. Install each distribution separately, then source the setup file for the one you want to use in that shell session. - Combining workspaces through sourcing also lets you layer local overlays on top of the core underlay. \ No newline at end of file + Combining workspaces through sourcing also lets you layer local overlays on top of the core underlay. From a3633be67974e38d276660ef6d10c06a7d45dfe4 Mon Sep 17 00:00:00 2001 From: Kacper Bojakowski Date: Mon, 6 Jul 2026 10:53:15 +0200 Subject: [PATCH 3/5] Update Configuring-ROS2-Environment.rst --- .../Configuring-ROS2-Environment.rst | 46 ++++++++++--------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst index 6da4916fe19..9ff39f6d73f 100644 --- a/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst +++ b/source/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.rst @@ -19,12 +19,12 @@ This article describes how to access ROS commands and packages by sourcing setup Summary ------- -You always need to source the setup files to configure your shell environment. +You always need to ``source`` the setup files to configure your shell environment. You can do this in one of the two ways: * Source the setup files in every new shell you open. -* Add the source command to your startup script. +* Add the ``source`` command to your startup script. Without sourcing the setup files, you won't be able to access ROS commands or find and use ROS packages. @@ -35,7 +35,10 @@ Install ROS by following the instructions on the ROS :doc:`../../Installation` p This guide assumes you have installed binary packages for your operating system (deb packages on Linux). If you built ROS from source, you can still follow this guide, but the path to your setup files is probably different. -If you install from source, you cannot use ``sudo apt install ros--``, which is often used in the beginner tutorials. + +.. note:: + + If you installed from source, you cannot use ``sudo apt install ros--``. If you use Linux or macOS, but are not already familiar with the shell, follow `this tutorial `__. @@ -45,7 +48,7 @@ Steps 1 Source the setup files ^^^^^^^^^^^^^^^^^^^^^^^^ -Use the source command to import the environment variables which enable your shell to access the ROS commands. +Use the ``source`` command to import the environment variables which enable your shell to access the ROS commands. You need to run this on every new shell you open: .. tabs:: @@ -57,8 +60,7 @@ You need to run this on every new shell you open: $ source /opt/ros/{DISTRO}/setup.bash - Replace ``.bash`` with your shell if you're not using bash. - Possible values are: ``setup.bash``, ``setup.sh``, ``setup.zsh``. + If you're not using bash, replace ``.bash`` with one of the possible values: ``setup.bash``, ``setup.sh``, or ``setup.zsh``. .. group-tab:: macOS @@ -89,7 +91,7 @@ If you don't want to source the setup file every time you open a new shell, you $ echo "source /opt/ros/{DISTRO}/setup.bash" >> ~/.bashrc - To undo this, locate your system's shell startup script and remove the source command. + To undo this, locate your system's shell startup script and remove the ``source`` command. .. group-tab:: macOS @@ -97,7 +99,7 @@ If you don't want to source the setup file every time you open a new shell, you $ echo "source ~/ros2_install/ros2-osx/setup.bash" >> ~/.bash_profile - To undo this, locate your system's shell startup script and remove the appended source command. + To undo this, locate your system's shell startup script and remove the appended ``source`` command. .. group-tab:: Windows @@ -155,14 +157,18 @@ Confirm that variables such as ``ROS_DISTRO`` and ``ROS_VERSION`` are set. ROS_DISTRO={DISTRO} If the environment variables are not set correctly, return to the ROS package installation section of the installation guide you followed. -If you need more specific help (because environment setup files can come from different places), you can `get answers `__ from the community. +If you need more specific help (because environment setup files can come from different places), :doc:`get answers from the community <../../The-ROS2-Project/Contributing>`. -3.1 The ``ROS_DOMAIN_ID`` variable -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +3.1 (Optional) Set the ``ROS_DOMAIN_ID`` variable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For details on domain IDs, read :doc:`About Domain ID <../../Concepts/Intermediate/About-Domain-ID>`. +``ROS_DOMAIN_ID`` places your nodes in a DDS domain. +Nodes only communicate with other nodes in the same domain, so a unique value prevents your nodes from seeing or being seen by other ROS nodes on the same network. -After you determine a unique integer for your group of ROS nodes, set the variable with the following command: +For the value of ``ROS_DOMAIN_ID``, choose any integer between 0 and 101 that no other ROS user on your network is using. +If you are working alone or on an isolated network, any value in that range is fine. + +To set the ``ROS_DOMAIN_ID`` variable, run: .. tabs:: @@ -202,12 +208,12 @@ After you determine a unique integer for your group of ROS nodes, set the variab $ setx ROS_DOMAIN_ID -3.2 The ``ROS_AUTOMATIC_DISCOVERY_RANGE`` variable -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +3.2 (Optional) The ``ROS_AUTOMATIC_DISCOVERY_RANGE`` variable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, ROS communication is not limited to localhost. -``ROS_AUTOMATIC_DISCOVERY_RANGE`` environment variable allows you to limit ROS discovery range. -Using ``ROS_AUTOMATIC_DISCOVERY_RANGE`` is helpful in certain settings, such as classrooms, where multiple robots may publish to the same topic, which can cause strange behaviors. +The ``ROS_AUTOMATIC_DISCOVERY_RANGE`` environment variable allows you to limit ROS discovery range. +Using ``ROS_AUTOMATIC_DISCOVERY_RANGE`` is helpful in settings such as classrooms, where multiple robots may publish to the same topic, which can cause strange behaviors. For more details, see :ref:`Improved Dynamic Discovery `. @@ -219,9 +225,7 @@ Confirm that your shell has the ROS paths and variables from the earlier steps i Choose a terminal session that matches how you configured ROS: * If you only source manually, run the commands below after you run your ``source``, ``.``, or ``call`` command in that terminal. -* If you use a startup script, open a new terminal window first, then run the commands below. - -Run: +* If you use a startup script, open a new terminal window, then run the commands below: .. code-block:: console @@ -247,7 +251,7 @@ FAQs Do I need to source the setup files in every new terminal? Yes. ROS commands and packages are only available in shells where you have sourced the setup files. - To avoid doing this manually each time, add the source command to your shell startup script. + To avoid doing this manually each time, add the ``source`` command to your shell startup script. How do I check that my ROS environment is configured correctly? List ROS-related environment variables (for example with ``printenv | grep -i ROS`` on Linux or macOS, or ``set | findstr -i ROS`` on Windows). From 24089d04e8bfccbf0fba5b9589363d40675b3951 Mon Sep 17 00:00:00 2001 From: Kacper Bojakowski Date: Mon, 20 Jul 2026 05:12:44 +0200 Subject: [PATCH 4/5] Implement peer review feedback --- .../Configuring-ROS2-Environment.rst | 36 +++++++++++++++---- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/source/Get-Started/Configuring-ROS2-Environment.rst b/source/Get-Started/Configuring-ROS2-Environment.rst index bbefca222fa..42b1df2c674 100644 --- a/source/Get-Started/Configuring-ROS2-Environment.rst +++ b/source/Get-Started/Configuring-ROS2-Environment.rst @@ -79,8 +79,8 @@ You need to run this on every new shell you open: The exact command depends on where you installed ROS. If you have problems, make sure that the file path leads to your installation. -Add sourcing to your shell startup script -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +2 (Optional) Add sourcing to your shell startup script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you don't want to source the setup file every time you open a new shell, you can add the following command to your shell startup script: @@ -222,12 +222,14 @@ For more details, see :ref:`Improved Dynamic Discovery Date: Mon, 20 Jul 2026 05:32:19 +0200 Subject: [PATCH 5/5] Add further context and clarifications --- .../Configuring-ROS2-Environment.rst | 61 ++++++++++++++++--- 1 file changed, 52 insertions(+), 9 deletions(-) diff --git a/source/Get-Started/Configuring-ROS2-Environment.rst b/source/Get-Started/Configuring-ROS2-Environment.rst index 42b1df2c674..47a06b6a36a 100644 --- a/source/Get-Started/Configuring-ROS2-Environment.rst +++ b/source/Get-Started/Configuring-ROS2-Environment.rst @@ -124,10 +124,10 @@ If you don't want to source the setup file every time you open a new shell, you 3 Check environment variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Sourcing ROS setup files sets the environment variables that ROS needs. +After you source the setup files, check that your shell picked up the ROS environment variables. +This confirms which distribution is active and whether the ``source`` command succeeded. -.. note:: - If you can't find or use packages, check your environment variables and ensure they are set to the version and distro you intended to use. +To list ROS-related environment variables, run: .. tabs:: @@ -157,6 +157,9 @@ Confirm that variables such as ``ROS_DISTRO`` and ``ROS_VERSION`` are set. ROS_PYTHON_VERSION=3 ROS_DISTRO={DISTRO} +.. note:: + If you later can't find or use packages, check these variables again and make sure that they match the version and distribution you intended to use. + If the environment variables are not set correctly, return to the ROS package installation section of the installation guide you followed. If you need more specific help (because environment setup files can come from different places), :doc:`get answers from the community <../The-ROS2-Project/Contributing>`. @@ -210,14 +213,54 @@ To set the ``ROS_DOMAIN_ID`` variable, run: $ setx ROS_DOMAIN_ID -3.2 (Optional) The ``ROS_AUTOMATIC_DISCOVERY_RANGE`` variable -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +3.2 (Optional) Set the ``ROS_AUTOMATIC_DISCOVERY_RANGE`` variable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, ROS nodes try to discover other nodes across the local network, not only on your machine. +The ``ROS_AUTOMATIC_DISCOVERY_RANGE`` environment variable lets you limit how far that discovery reaches. +This is helpful in settings such as classrooms, where multiple robots may publish to the same topic and interfere with one another. + +To limit discovery to the local machine, set the variable to ``LOCALHOST``: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: console + + $ export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST + + To maintain this setting between shell sessions, you can add the command to your shell startup script: + + .. code-block:: console + + $ echo "export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST" >> ~/.bashrc + + .. group-tab:: macOS + + .. code-block:: console + + $ export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST + + To maintain this setting between shell sessions, you can add the command to your shell startup script: + + .. code-block:: console + + $ echo "export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST" >> ~/.bash_profile + + .. group-tab:: Windows + + .. code-block:: console + + $ set ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST + + If you want to make this permanent between shell sessions, also run: + + .. code-block:: console -By default, ROS communication is not limited to localhost. -The ``ROS_AUTOMATIC_DISCOVERY_RANGE`` environment variable allows you to limit ROS discovery range. -Using ``ROS_AUTOMATIC_DISCOVERY_RANGE`` is helpful in settings such as classrooms, where multiple robots may publish to the same topic, which can cause strange behaviors. + $ setx ROS_AUTOMATIC_DISCOVERY_RANGE LOCALHOST -For more details, see :ref:`Improved Dynamic Discovery `. +For other values and more advanced discovery options, see :ref:`Improved Dynamic Discovery `. 4 Verify your environment configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^