diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 6f51c3a540d..0f1664a5746 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -1,21 +1,42 @@
name: Test
-on: [push, pull_request]
+on: pull_request
jobs:
test:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-22.04
steps:
- - uses: actions/checkout@v2
+ - name: Checkout
+ uses: actions/checkout@v3
- name: Setup Python
- uses: actions/setup-python@v1
+ uses: actions/setup-python@v4
with:
- python-version: 3.8
+ python-version: '3.10'
- name: Install dependencies with pip
- run: |
- pip install --no-warn-script-location --user --upgrade -r requirements.txt
+ run: pip install --no-warn-script-location --user -r requirements.txt -c constraints.txt
- - run: make html
- - run: make test
+ - name: Test doc8
+ run: make test
+
+ build:
+ needs: test
+ runs-on: ubuntu-22.04
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+
+ - name: Setup Python
+ uses: actions/setup-python@v4
+ with:
+ python-version: '3.10'
+
+ - name: Setup Graphviz
+ uses: ts-graphviz/setup-graphviz@v1
+
+ - name: Install dependencies with pip
+ run: pip install --no-warn-script-location --user -r requirements.txt -c constraints.txt
+
+ - name: Build the docs
+ run: make html
diff --git a/.gitignore b/.gitignore
index d1440c38911..0499adb29a1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
build/
+plugins/__pycache__
_build/
.idea/
.vscode/
diff --git a/.mergify.yml b/.mergify.yml
index d010a4daaf7..bf25109cd1a 100644
--- a/.mergify.yml
+++ b/.mergify.yml
@@ -8,7 +8,6 @@ pull_request_rules:
branches:
- iron
- humble
- - foxy
- name: backport at reviewers discretion
conditions:
@@ -19,7 +18,6 @@ pull_request_rules:
branches:
- iron
- humble
- - foxy
- name: backport to iron at reviewers discretion
conditions:
@@ -38,12 +36,3 @@ pull_request_rules:
backport:
branches:
- humble
-
- - name: backport to foxy at reviewers discretion
- conditions:
- - base=rolling
- - "label=backport-foxy"
- actions:
- backport:
- branches:
- - foxy
diff --git a/Makefile b/Makefile
index fed8f298a07..669b8b6e860 100644
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,11 @@
SOURCE = source
OUT = build
LINKCHECKDIR = $(OUT)/linkcheck
-BUILD = python3 -m sphinx
+PYTHON := python3
+ifeq ($(OS),Windows_NT)
+ PYTHON := python
+endif
+BUILD = $(PYTHON) -m sphinx
OPTS =-c .
help:
@@ -12,7 +16,7 @@ help:
multiversion: Makefile
sphinx-multiversion $(OPTS) "$(SOURCE)" build/html
- @echo "
" > build/html/index.html
+ @echo "" > build/html/index.html
python3 make_sitemapindex.py
%: Makefile
diff --git a/conf.py b/conf.py
index efebb3a946f..f6f0a05435e 100644
--- a/conf.py
+++ b/conf.py
@@ -25,6 +25,7 @@
from docutils.parsers.rst import Directive
sys.path.append(os.path.abspath('./sphinx-multiversion'))
+sys.path.append(os.path.abspath('plugins'))
# The suffix(es) of source filenames.
@@ -81,7 +82,7 @@
'sphinx_multiversion',
'sphinx_tabs.tabs',
'sphinx_rtd_theme',
- 'sphinx_sitemap',
+ 'sphinx_sitemap_ros',
]
# Intersphinx mapping
@@ -125,10 +126,10 @@
smv_branch_whitelist = r'^(rolling|iron|humble|galactic|foxy|eloquent|dashing|crystal)$'
-smv_released_pattern = r'^refs/(heads|remotes/[^/]+)/(humble|galactic|foxy|eloquent|dashing|crystal).*$'
+smv_released_pattern = r'^refs/(heads|remotes/[^/]+)/(iron|humble|galactic|foxy|eloquent|dashing|crystal).*$'
smv_remote_whitelist = r'^(origin)$'
-smv_latest_version = 'humble'
-smv_eol_versions = ['crystal', 'dashing', 'eloquent', 'galactic']
+smv_latest_version = 'iron'
+smv_eol_versions = ['crystal', 'dashing', 'eloquent', 'foxy', 'galactic']
distro_full_names = {
'crystal': 'Crystal Clemmys',
@@ -238,6 +239,8 @@ def generate(cls, app):
'canonical_url': os.path.relpath(
canonical_url, redirect_url
),
+ # Skip entry into sitemap.xml with reason 'redirect'.
+ 'skip_sitemap': 'redirect',
'title': os.path.basename(redirect_url),
'metatags': redirect_html_fragment.format(
base_url=app.config.html_baseurl,
diff --git a/constraints.txt b/constraints.txt
new file mode 100644
index 00000000000..dfc63ee198e
--- /dev/null
+++ b/constraints.txt
@@ -0,0 +1,30 @@
+Jinja2==3.0.3
+MarkupSafe==2.0.1
+Pygments==2.11.2
+alabaster==0.7.12
+babel==2.8.0
+certifi==2020.6.20
+chardet==4.0.0
+imagesize==1.3.0
+importlib-metadata==4.6.4
+more-itertools==8.10.0
+packaging==21.3
+pbr==5.8.0
+pip==22.0.2
+pyparsing==2.4.7
+pytz==2022.1
+requests==2.25.1
+restructuredtext-lint==1.3.2
+roman==3.3
+setuptools==59.6.0
+six==1.16.0
+snowballstemmer==2.2.0
+Sphinx==4.3.2
+sphinx-copybutton==0.4.0
+sphinx-multiversion==0.2.4
+sphinx-rtd-theme==1.0.0
+sphinx-tabs==3.2.0
+stevedore==3.5.0
+urllib3==1.26.5
+wheel==0.37.1
+zipp==1.0.0
diff --git a/docker/image/Dockerfile b/docker/image/Dockerfile
index 62462e88e65..b0dc465639f 100644
--- a/docker/image/Dockerfile
+++ b/docker/image/Dockerfile
@@ -3,7 +3,7 @@
#
# docker build -f docker/image/Dockerfile .
-FROM ubuntu:focal
+FROM ubuntu:jammy
ARG user=rosindex
ARG uid=1000
@@ -15,7 +15,13 @@ RUN apt-get update && \
git-all \
graphviz \
make \
- python3-pip && \
+ python3-doc8 \
+ python3-docutils \
+ python3-pip \
+ python3-sphinx \
+ python3-sphinx-copybutton \
+ python3-sphinx-rtd-theme \
+ python3-sphinx-tabs && \
rm -rf /var/lib/apt/lists/*
RUN useradd -u $uid -m $user
@@ -25,4 +31,4 @@ WORKDIR /tmp/doc_repository
USER $user
-CMD pip3 install --no-warn-script-location --user --upgrade -r requirements.txt && make multiversion
+CMD pip3 install --no-warn-script-location --user -r requirements.txt -c constraints.txt && make multiversion
diff --git a/plugins/sphinx_sitemap_ros.py b/plugins/sphinx_sitemap_ros.py
new file mode 100644
index 00000000000..b76e437266e
--- /dev/null
+++ b/plugins/sphinx_sitemap_ros.py
@@ -0,0 +1,238 @@
+# Copyright (c) 2013 Michael Dowling
+# Copyright (c) 2017 Jared Dillard
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+
+'''
+The implementation of this sphinx extensions is largely borrowed from the sphinx_sitemap extension
+(version: https://github.com/jdillard/sphinx-sitemap/blob/3bd87ef166bc9f3758d360ad4d23b524668b161d/sphinx_sitemap/__init__.py)
+with modifications made to add_html_link() to ignore any pages whose context contains the
+'skip_sitemap' key.
+'''
+
+
+import os
+import queue
+from multiprocessing import Manager
+from typing import Any, Dict, List, Optional
+from xml.etree import ElementTree
+
+from sphinx.application import Sphinx
+from sphinx.util.logging import getLogger
+
+__version__ = "0.0.1"
+
+logger = getLogger(__name__)
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+ """
+ Sphinx extension setup function.
+ It adds config values and connects Sphinx events to the sitemap builder.
+
+ :param app: The Sphinx Application instance
+ :return: A dict of Sphinx extension options
+ """
+ app.add_config_value("site_url", default=None, rebuild="")
+ app.add_config_value(
+ "sitemap_url_scheme", default="{lang}{version}{link}", rebuild=""
+ )
+ app.add_config_value("sitemap_locales", default=None, rebuild="")
+
+ app.add_config_value("sitemap_filename", default="sitemap.xml", rebuild="")
+
+ try:
+ app.add_config_value("html_baseurl", default=None, rebuild="")
+ except BaseException:
+ pass
+
+ app.connect("builder-inited", record_builder_type)
+ app.connect("html-page-context", add_html_link)
+ app.connect("build-finished", create_sitemap)
+
+ return {
+ "parallel_read_safe": True,
+ "parallel_write_safe": True,
+ "version": __version__,
+ }
+
+
+def get_locales(app: Sphinx) -> List[str]:
+ """
+ Get a list of locales from the extension config or automatically detect based
+ on Sphinx Application config.
+
+ :param app: The Sphinx Application instance
+ :return: A list of locales
+ """
+ # Manually configured list of locales
+ sitemap_locales: Optional[List[str]] = app.builder.config.sitemap_locales
+ if sitemap_locales:
+ # special value to add nothing -> use primary language only
+ if sitemap_locales == [None]:
+ return []
+
+ # otherwise, add each locale
+ return [locale for locale in sitemap_locales]
+
+ # Or autodetect locales
+ locales = []
+ for locale_dir in app.builder.config.locale_dirs:
+ locale_dir = os.path.join(app.confdir, locale_dir)
+ if os.path.isdir(locale_dir):
+ for locale in os.listdir(locale_dir):
+ if os.path.isdir(os.path.join(locale_dir, locale)):
+ locales.append(locale)
+ return locales
+
+
+def record_builder_type(app: Sphinx):
+ """
+ Determine if the Sphinx Builder is an instance of DirectoryHTMLBuilder and store that in the
+ application environment.
+
+ :param app: The Sphinx Application instance
+ """
+ # builder isn't initialized in the setup so we do it here
+ builder = getattr(app, "builder", None)
+ if builder is None:
+ return
+ builder.env.is_directory_builder = type(builder).__name__ == "DirectoryHTMLBuilder"
+ builder.env.app.sitemap_links = Manager().Queue()
+
+
+def hreflang_formatter(lang: str) -> str:
+ """
+ Format the supplied locale code into a string that is compatible with `hreflang`.
+ See also:
+
+ - https://en.wikipedia.org/wiki/Hreflang#Common_Mistakes
+ - https://github.com/readthedocs/readthedocs.org/pull/5638
+
+ :param lang: The locale string to format
+ :return: The formatted locale string
+ """
+ if "_" in lang:
+ return lang.replace("_", "-")
+ return lang
+
+
+def add_html_link(app: Sphinx, pagename: str, templatename, context, doctree):
+ """
+ As each page is built, collect page names for the sitemap
+
+ :param app: The Sphinx Application instance
+ :param pagename: The current page being built
+ """
+
+ # Return if the context contains `skip_sitemap`.
+ if 'skip_sitemap' in context.keys():
+ logger.debug(f"sphinx-sitemap-ros: Ignoring sitemap entry for {pagename} with reason \"{context['skip_sitemap']}\"")
+ return
+
+ env = app.builder.env
+ if app.builder.config.html_file_suffix is None:
+ file_suffix = ".html"
+ else:
+ file_suffix = app.builder.config.html_file_suffix
+
+ # Support DirectoryHTMLBuilder path structure
+ # where generated links between pages omit the index.html
+ if env.is_directory_builder: # type: ignore
+ if pagename == "index":
+ sitemap_link = ""
+ elif pagename.endswith("/index"):
+ sitemap_link = pagename[:-6] + "/"
+ else:
+ sitemap_link = pagename + "/"
+ else:
+ sitemap_link = pagename + file_suffix
+
+ env.app.sitemap_links.put(sitemap_link) # type: ignore
+
+
+def create_sitemap(app: Sphinx, exception):
+ """
+ Generates the sitemap.xml from the collected HTML page links.
+
+ :param app: The Sphinx Application instance
+ """
+ site_url = app.builder.config.site_url or app.builder.config.html_baseurl
+ if site_url:
+ site_url.rstrip("/") + "/"
+ else:
+ logger.warning(
+ "sphinx-sitemap-ros: html_baseurl is required in conf.py." "Sitemap not built.",
+ type="sitemap",
+ subtype="configuration",
+ )
+ return
+
+ if app.env.app.sitemap_links.empty(): # type: ignore
+ logger.info(
+ "sphinx-sitemap-ros: No pages generated for %s" % app.config.sitemap_filename,
+ type="sitemap",
+ subtype="information",
+ )
+ return
+
+ ElementTree.register_namespace("xhtml", "http://www.w3.org/1999/xhtml")
+
+ root = ElementTree.Element(
+ "urlset", xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+ )
+
+ locales = get_locales(app)
+
+ if app.builder.config.version:
+ version = app.builder.config.version + "/"
+ else:
+ version = ""
+
+ while True:
+ try:
+ link = app.env.app.sitemap_links.get_nowait() # type: ignore
+ except queue.Empty:
+ break
+
+ url = ElementTree.SubElement(root, "url")
+ scheme = app.config.sitemap_url_scheme
+ if app.builder.config.language:
+ lang = app.builder.config.language + "/"
+ else:
+ lang = ""
+
+ ElementTree.SubElement(url, "loc").text = site_url + scheme.format(
+ lang=lang, version=version, link=link
+ )
+
+ for lang in locales:
+ lang = lang + "/"
+ ElementTree.SubElement(
+ url,
+ "{http://www.w3.org/1999/xhtml}link",
+ rel="alternate",
+ hreflang=hreflang_formatter(lang.rstrip("/")),
+ href=site_url + scheme.format(lang=lang, version=version, link=link),
+ )
+
+ filename = app.outdir + "/" + app.config.sitemap_filename
+ ElementTree.ElementTree(root).write(
+ filename, xml_declaration=True, encoding="utf-8", method="xml"
+ )
+
+ logger.info(
+ "sphinx-sitemap-ros: %s was generated for URL %s in %s"
+ % (app.config.sitemap_filename, site_url, filename),
+ type="sitemap",
+ subtype="information",
+ )
diff --git a/requirements.txt b/requirements.txt
index 6ffb56e0aa7..69607aa7835 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,9 +1,8 @@
doc8
-docutils==0.16
-pip
-sphinx<6.0.0
-sphinx-copybutton
-sphinx-multiversion
-sphinx-rtd-theme
-sphinx-sitemap
-sphinx-tabs
+docutils
+pip==22.0.2
+sphinx==4.3.2
+sphinx-copybutton==0.4.0
+sphinx-multiversion==0.2.4
+sphinx-rtd-theme==1.0.0
+sphinx-tabs==3.2.0
diff --git a/source/Citations.rst b/source/Citations.rst
index e4d7e44c716..a433d9fc937 100644
--- a/source/Citations.rst
+++ b/source/Citations.rst
@@ -5,13 +5,12 @@ Citations
If you use ROS 2 in your work please cite the 2022 Science Robotics paper `Robot Operating System 2: Design, architecture, and uses in the wild `_.
-S. Macenski, T. Foote, B. Gerkey, C. Lalancette, W. Woodall, “Robot Operating System 2: Design, architecture, and uses in the wild,” Science Robotics vol. 7, May 2022.
+ | S. Macenski, T. Foote, B. Gerkey, C. Lalancette, W. Woodall, "Robot Operating System 2: Design, architecture, and uses in the wild," Science Robotics vol. 7, May 2022.
-.. code-block::
+.. code-block:: bibtex
- @article{
- doi:10.1126/scirobotics.abm6074,
- author = {Steven Macenski and Tully Foote and Brian Gerkey and Chris Lalancette and William Woodall },
+ @article{doi:10.1126/scirobotics.abm6074,
+ author = {Steven Macenski and Tully Foote and Brian Gerkey and Chris Lalancette and William Woodall},
title = {Robot Operating System 2: Design, architecture, and uses in the wild},
journal = {Science Robotics},
volume = {7},
@@ -21,3 +20,19 @@ S. Macenski, T. Foote, B. Gerkey, C. Lalancette, W. Woodall, “Robot Operating
doi = {10.1126/scirobotics.abm6074},
URL = {https://www.science.org/doi/abs/10.1126/scirobotics.abm6074}
}
+
+
+If you use ROS 2 Composition in your work, please cite the 2023 IEEE RA-L paper `Impact of ROS 2 Node Composition in Robotic Systems `_.
+
+ | S. Macenski, A. Soragna, M. Carroll, Z. Ge, "Impact of ROS 2 Node Composition in Robotic Systems", IEEE Robotics and Autonomous Letters (RA-L), 2023.
+
+.. code-block:: bibtex
+
+ @article{doi:10.48550/arXiv.2305.09933,
+ author = {Steven Macenski and Alberto Soragna and Michael Carroll and Zhenpeng Ge},
+ title = {Impact of ROS 2 Node Composition in Robotic Systems},
+ journal = {IEEE Robotics and Autonomous Letters (RA-L)},
+ year = {2023},
+ doi = {10.48550/arXiv.2305.09933},
+ URL = {https://arxiv.org/abs/2305.09933}
+ }
diff --git a/source/Concepts.rst b/source/Concepts.rst
index 147ddea7b6b..032cde1ab14 100644
--- a/source/Concepts.rst
+++ b/source/Concepts.rst
@@ -1,5 +1,3 @@
-.. _ConceptsHome:
-
Concepts
========
@@ -8,113 +6,9 @@ Conceptual overviews provide relatively high-level, general background informati
.. toctree::
:maxdepth: 1
- Concepts/About-Domain-ID
- Concepts/About-Different-Middleware-Vendors
- Concepts/About-Logging
- Concepts/About-Quality-of-Service-Settings
- Concepts/About-ROS-2-Client-Libraries
- Concepts/About-ROS-Interfaces
- Concepts/About-ROS-2-Parameters
- Concepts/About-Executors
- Concepts/About-Topic-Statistics
- Concepts/About-Command-Line-Tools
- Concepts/About-RQt
- Concepts/About-Composition
- Concepts/About-Catment
- Concepts/About-Cross-Compilation
- Concepts/About-Security
- Concepts/About-Tf2
-
-
-The Core Stack Developer Concepts are much more detailed conceptual articles intended for developers who plan modify or contribute to the ROS 2 core:
-
-.. toctree::
- :maxdepth: 2
-
- Concepts/About-Build-System
- Concepts/About-Internal-Interfaces
- Concepts/About-Middleware-Implementations
- Concepts/About-ROS-2-Client-Libraries
-
-Quick overview of ROS 2 Concepts
---------------------------------
-
-.. contents::
- :local:
-
-ROS 2 is a middleware based on an anonymous publish/subscribe mechanism that allows for message passing between different ROS processes.
-
-At the heart of any ROS 2 system is the ROS graph.
-The ROS graph refers to the network of nodes in a ROS system and the connections between them by which they communicate.
-
-Graph Concepts
-^^^^^^^^^^^^^^
-
-
-* Nodes: A node is an entity that uses ROS to communicate with other nodes.
-* Messages: ROS data type used when subscribing or publishing to a topic.
-* Topics: Nodes can publish messages to a topic as well as subscribe to a topic to receive messages.
-* Discovery: The automatic process through which nodes determine how to talk to each other.
-
-Nodes
-^^^^^
-
-A node is a participant in the ROS graph.
-ROS nodes use a ROS client library to communicate with other nodes.
-Nodes can publish or subscribe to Topics.
-Nodes can also provide or use Services and Actions.
-There are configurable Parameters associated with a node.
-Connections between nodes are established through a distributed discovery process.
-Nodes may be located in the same process, in different processes, or on different machines.
-These concepts will be described in more detail in the sections that follow.
-
-Client Libraries
-^^^^^^^^^^^^^^^^
-
-ROS client libraries allow nodes written in different programming languages to communicate.
-There is a core ROS client library (RCL) that implements common functionality needed for the ROS APIs of different languages.
-This makes it so that language-specific client libraries are easier to write and that they have more consistent behavior.
-
-The following client libraries are maintained by the ROS 2 team:
-
-
-* rclcpp = C++ client library
-* rclpy = Python client library
-
-Additionally, other client libraries have been developed by the ROS community.
-See the :doc:`ROS 2 Client Libraries ` article for more details.
-
-Discovery
-^^^^^^^^^
-
-Discovery of nodes happens automatically through the underlying middleware of ROS 2.
-It can be summarized as follows:
-
-#. When a node is started, it advertises its presence to other nodes on the network with the same ROS domain (set with the ROS_DOMAIN_ID environment variable).
- Nodes respond to this advertisement with information about themselves so that the appropriate connections can be made and the nodes can communicate.
-#. Nodes periodically advertise their presence so that connections can be made with new-found entities, even after the initial discovery period.
-#. Nodes advertise to other nodes when they go offline.
-
-Nodes will only establish connections with other nodes if they have compatible :doc:`Quality of Service <../Tutorials/Demos/Quality-of-Service>` settings.
-
-Take the :ref:`talker-listener demo ` for example.
-Running the C++ talker node in one terminal will publish messages on a topic,
-and the Python listener node running in another terminal will subscribe to messages on the same topic.
-
-You should see that these nodes discover each other automatically, and begin to exchange messages.
-
-Security
-^^^^^^^^
-
-ROS 2 includes the ability to secure communications among nodes within the ROS 2 computational graph.
-Similar to discovery, security happens through the underlying ROS 2 middleware (provided it has support for the corresponding security plugins).
-No additional software installation is needed to enable security; however, the middleware requires configuration files for each ROS graph participant.
-These files enable encryption and authentication, and define policies both for individual nodes and for the overall ROS graph.
-ROS 2 also adds a master "on/off" switch to control security behavior.
-
-ROS utilities can create the authoritative `trust anchor `_ for a ROS application, or an external certificate authority can be used.
-
-See the :doc:`ROS 2 Security ` article for additional details or ROS security features.
+ Concepts/Basic
+ Concepts/Intermediate
+ Concepts/Advanced
Related Content
@@ -126,4 +20,3 @@ For a brief video introduction to ROS 2, see this community contributed content:
* `Getting started with ROS Part 1: Nodes, Parameters and Topics `_
* `Getting started with ROS Part 2: Services and Actions `_
-
diff --git a/source/Concepts/About-Catment.rst b/source/Concepts/About-Catment.rst
deleted file mode 100644
index 5708ef69dc7..00000000000
--- a/source/Concepts/About-Catment.rst
+++ /dev/null
@@ -1,266 +0,0 @@
-.. redirect-from::
-
- catment
-
-On the mixing of ament and catkin (catment)
-===========================================
-
-**All that follows is experimental and speculative.**
-
-.. contents:: Table of Contents
- :depth: 2
- :local:
-
-Background
-----------
-
-There once was a thing called ``rosbuild``.
-Then came a thing called ``catkin``, which largely replaced ``rosbuild``.
-Recently introduced is a thing called ``ament``, which may one day replace ``catkin``.
-
-All three tools can be considered "meta-build systems".
-They sit atop other build systems (e.g. CMake, Python setuptools) and provide extra functionality that's intended to make those build systems easier to use, especially when managing dependencies across multiple packages and when building multiple packages in a single workspace.
-
-Each of these meta-build systems does two things:
-
-
-#.
- Adds an API to the underlying build system (e.g. CMake) that can be used to simplify common tasks (e.g. supplying all the flags exported by depended-upon packages when building an executable).
- There are usually hooks to allow injection of extra APIs by packages outside of the core meta-build system.
-
-
- * ``rosbuild``: ``mk/cmake.mk``, ``rosbuild_init()``, ``rosbuild_add_executable()``, etc.
- * ``catkin``: ``catkin_package()``, ``catkin_install_python()``, etc.
- * ``ament``: ``ament_target_dependencies()``, ``ament_export_dependencies()``, ``ament_package()``, etc.
-
-#.
- Provides a tool that can be used to iterate in dependency order over a workspace full of packages, building and perhaps installing each one.
-
-
- * ``rosbuild``: ``rosmake``
- * ``catkin``: ``catkin build``, ``catkin_make``, ``catkin_make_isolated``, etc.
- * ``ament``: ``ament build``
-
-The common thread that ties all of these systems together is the division of the code into **packages**\ , with each package containing a manifest file (``manifest.xml`` or ``package.xml``).
-This manifest is required (with some exceptions) for both parts of the meta-build system (API and build tool) to function.
-
-Postulates
-----------
-
-
-#. **While we usually consider the two aspects of a meta-build system to be coupled, they needn't be.**
- The API used inside a package and the tool that iterates over the packages can be considered largely independent, with the package manifest forming the interface between them.
- There's no reason in principle why, for example, ``rosmake`` couldn't be modified to iterate over a workspace filled with ``catkin`` packages, stepping into them in dependency order and doing the usual ``mkdir build; cd build; cmake ..; make install`` routine for each one (with appropriate flags passed to ``cmake`` and ``make``).
-#.
- **The effort required to migrate from one meta-build system to another should be minimized.**
- The mass migration from ``rosbuild`` to ``catkin`` was difficult and remains a sore point for many in the community.
- While it's reasonable to ask developers to make changes in exchange for getting access to new functionality, the changes that are required should be as small as possible without sacrificing the effectiveness of the new system.
- This is especially true when the old system is in widespread use.
-
-
- #. Corollary: **Migration to a new meta-build system should not be required without a very good reason.**
- If a developer doesn't want the functionality offered by the new system, then they shouldn't be coerced into migrating from the old system unless there's something irrevocably broken about the old system (e.g. ``rosbuild``\ 's in-source build pattern and lack of an "install" step).
-
-#.
- **Interoperability is a good thing.**
- Whenever possible (not all combinations will be practical), developers should be able to mix and match meta-build systems, including mixing their different aspects (i.e., use the building tool from one system and the API from another).
- Such mixing and matching is especially important when developers want to combine a large existing codebase using one meta-build system (e.g. ROS with ``catkin``) with new libraries and tools offered by a codebase using another meta-build system (e.g. ROS 2 with ``ament``).
- Ideally, that kind of combination can be done without requiring changes to the API used by either codebase and without telling the developer which builder tool to use.
-
-
- #. Corollary: **Workspaces needn't be homogeneous.**
- There's no reason that we shouldn't be able to freely mix, say, ``catkin`` and ``ament`` packages in one workspace, with dependencies going in both directions, so long as the builder tool in use knows how to build them both.
- The primary interface between packages (at least, CMake-controlled packages) is their CMake configuration file.
- So long as that configuration file follows the standard protocol (setting ``foo_LIBRARIES``, etc.), then it shouldn't matter who wrote the file.
- It could be auto-generated by ``catkin`` or ``ament``, or even manually crafted by a developer who wants to use plain CMake in their package, but still have that package depended-upon by ``catkin`` or ``ament`` packages.
-
-Use cases, with experimental implementations
---------------------------------------------
-
-Adding ROS packages to a ROS 2 workspace and building with ``ament build``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Let's say that you want to add some existing ROS packages to your ROS 2 workspace and don't want to migrate the ROS packages from ``catkin`` to ``ament`` (or vice versa). Here are two patches that let you do that:
-
-
-* `ament_package `__:
- Adds support for format 1 package manifests, instead of requiring format 2.
- This change isn't strictly related to ``catkin`` vs. ``ament``, because format 2 has been around for a while and ``catkin`` supports it, so developers could already update their manifests to format 2.
- But there's a ton of ROS code out there that uses format 1, so we should support it.
- This implementation could be improved, e.g. by reasoning over the various flavors of depend tags and how they differ between formats 1 and 2.
-* `ament_tools `__:
- Adds a new ``catkin`` build type to ``ament``.
- This implementation just treats ``catkin`` packages the same as plain ``cmake`` packages, which seems to work fine.
- It could be made more sophisticated.
-
-Example usage:
-
-
-#. Get the ROS 2 code as usual, using the branches mentioned above.
-#. Add to your workspace some ``catkin`` ROS packages, ensuring that all of their dependencies are satisfied (either present in the workspace or installed elsewhere with appropriate setup shell files sourced).
-#. Build as usual (e.g. ``colcon build``).
-
-Voila: your existing code isn't suddenly broken just because there's a new build tool in use.
-
-Variation: Building ROS packages with ``ament build``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Let's say that you love the new ``ament`` tool and want to use it to build your existing ROS packages that use ``catkin`` internally.
-Here's an example of how to do that, by doing a minimal installation of ``ament`` and then using it to build a workspace full of ROS ``catkin`` packages:
-
-.. code-block:: bash
-
- mkdir -p ~/ament_ws/src
- cd ~/ament_ws/src
- git clone https://github.com/osrf/osrf_pycommon.git
- git clone https://github.com/ament/ament_package.git
- cd ament_package
- git checkout catkin
- cd ..
- git clone https://github.com/ament/ament_tools.git
- cd ament_tools
- git checkout catkin
- cd ../..
- ./src/ament_tools/scripts/ament.py build
-
-Now build the ROS packages:
-
-.. code-block:: bash
-
- . $HOME/ament_ws/install/setup.bash
- cd ~/ros_catkin_ws
- ament build
-
-Voila: you used the ``ament`` build tool to build your ``catkin`` packages, without having to migrate them.
-
-Variation: Using the ``catkin`` API in a ROS 2 package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Let's say that you're building on top of ROS 2, which internally uses the ``ament`` API, and you want to add a new package using the ``catkin`` API.
-
-To make this work, you need a Python3 installation of ``catkin`` (the binary debians use Python2.7).
-Here's an example of doing that, installing to ``$HOME/catkin``:
-
-.. code-block:: bash
-
- # install catkin_pkg
- git clone https://github.com/ros-infrastructure/catkin_pkg.git
- cd catkin_pkg
- git checkout ament
- python3 setup.py install --prefix $HOME/catkin --single-version-externally-managed --record foo --install-layout deb
- # install catkin
- git clone https://github.com/ros/catkin.git
- cd catkin
- git checkout ament
- mkdir build
- cd build
- PYTHONPATH=$HOME/catkin/lib/python3/dist-packages/ cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/catkin -DPYTHON_EXECUTABLE=/usr/bin/python3
- make install
-
-To use that version of catkin, you just need to source the ``$HOME/catkin/setup.bash`` file.
-
-Let's assume that you have the usual ROS 2 workspace in ``~/ros2_ws``, and that you're on the ``catkin`` branches in ``ament_package`` and ``ament_tools``.
-Add to that workspace the ``image_tools_catkin`` package from https://github.com/gerkey/catment.
-It's a simple port of the ROS 2 ``image_tools`` package, taking it from the ``ament`` API to the ``catkin`` API.
-To build it:
-
-.. code-block:: bash
-
- cd ~/ros2_ws
- . $HOME/catkin/setup.bash
- ./src/ament/ament_tools/scripts/ament.py build
-
-Voila: when adding new packages atop ROS 2, you're free to choose which CMake API you prefer inside your package.
-
-
-* **Caveat**: Requires commenting out the use of ``CATKIN_DEPENDS`` inside ``catkin_package()``, because somewhere somebody was getting upset that things like ``rclcpp`` aren't ``catkin`` packages.
- That constraint needs to be relaxed somehow.
-* **TODO**: The same demo but with an ``ament`` package that depends on a ``catkin`` package (this is easy).
-* **TODO**: The same demo but with a package that has a vanilla ``CMakeLists.txt`` that uses neither ``ament`` nor ``catkin``, and provides a manually generated ``fooConfig.cmake`` file that exports the right stuff to make it look the same to outsiders.
-
-Building ROS 2 packages with ``catkin_make_isolated``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Let's say that you're already familiar with ROS and ``catkin`` and you're excited to try ROS 2, but you're not in the mood to learn about ``ament``.
-You'd rather stick to what you know, such as using ``catkin_make_isolated`` to build everything.
-Here is a patch that allows you to do that:
-
-
-* `catkin `__:
- Adds support for packages that declare themselves to have a build type of ``ament_*``.
- This implementation calls out to ``ament`` to build each such package.
- While ``ament_cmake`` packages can be treated as plain ``cmake`` packages (as we did when adding ``catkin`` support to ``ament``), ``ament_python`` packages require some gnarly invocations of Python.
- Instead of trying to replicate that logic in ``catkin``, it's easier to just let ``ament`` handle it.
- Also in this patch, we add the ``buildtool_export_depend`` packages to the set that are considered when building.
-* `catkin_pkg `__:
- Also in this patch, we add the ``buildtool_export_depend`` packages to the set that are considered when computing the topological order.
-
-Because we're going to call out to ``ament build``, we will also need a minimal installation of ``ament``, as done in a previous example:
-
-.. code-block:: bash
-
- mkdir -p ~/ament_ws/src
- cd ~/ament_ws/src
- git clone https://github.com/osrf/osrf_pycommon.git
- git clone https://github.com/ament/ament_package.git
- cd ament_package
- git checkout catkin
- cd ..
- git clone https://github.com/ament/ament_tools.git
- cd ament_tools
- git checkout catkin
- cd ../..
- ./src/ament_tools/scripts/ament.py build
-
-Then we need to install the modified version of catkin somewhere:
-
-.. code-block:: bash
-
- # install catkin_pkg
- git clone https://github.com/ros-infrastructure/catkin_pkg.git
- cd catkin_pkg
- git checkout ament
- python3 setup.py install --prefix $HOME/catkin --single-version-externally-managed --record foo --install-layout deb
- # install catkin
- git clone https://github.com/ros/catkin.git
- cd catkin
- git checkout ament
- mkdir build
- cd build
- PYTHONPATH=$HOME/catkin/lib/python3/dist-packages/ cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/catkin -DPYTHON_EXECUTABLE=/usr/bin/python3
- make install
-
-Now build the ROS 2 packages:
-
-.. code-block:: bash
-
- . $HOME/catkin/setup.bash
- . $HOME/ament_ws/install/setup.bash
- cd ~/ros2_ws
- touch src/eProsima/AMENT_IGNORE
- PYTHONPATH=$PYTHONPATH:/home/gerkey/ros2_ws_catkin/install_isolated/lib/python3.5/site-packages catkin_make_isolated --install
-
-Voila: you've built ROS 2 using the tools that you're familiar with.
-
-
-* **Caveat**: we're ignoring the ``eProsima`` packages in the workspace because they lack ``package.xml`` files, which means that ``catkin`` can't see them.
- ``ament`` has some heuristics for handling such packages.
- Options: backport those heuristics to ``catkin``; switch to installing non-``package.xml``-containing packages outside of the workspace; or just add a ``package.xml`` to each of those packages (e.g. in our own fork).
-
-Combining all of ROS and ROS 2 in one workspace and building it (TODO)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This step will require sorting out some things, including at least:
-
-* Package name conflicts.
- We currently have ROS 2 versions of ROS message packages, as well as some stuff in ``geometry2``.
- Either the functionality needs to be merged into one package that can support both systems, or the new versions need different names.
-* Message generation.
- ROS and ROS 2 have different message generation steps, the output of which might or might not conflict.
- Something sophisticated needs to be done to allow generation of all the right artifacts from a single message package (or, as indicated above, the new message packages need different names).
-
-Using ``bloom`` to release ``ament`` packages (TODO)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-It seems like ``bloom`` ought be able to release packages that use the ``ament`` CMake API, and that the resulting releases should be able to be built on the farm.
-We can make changes to ``bloom`` and ``ros_buildfarm`` as needed to enable this use case.
diff --git a/source/Concepts/Advanced.rst b/source/Concepts/Advanced.rst
new file mode 100644
index 00000000000..4f333d38da4
--- /dev/null
+++ b/source/Concepts/Advanced.rst
@@ -0,0 +1,11 @@
+Advanced Concepts
+=================
+
+These conceptual documents are intended for developers who plan to modify or contribute to the ROS 2 core.
+
+.. toctree::
+ :maxdepth: 1
+
+ Advanced/About-Build-System
+ Advanced/About-Internal-Interfaces
+ Advanced/About-Middleware-Implementations
diff --git a/source/Concepts/About-Build-System.rst b/source/Concepts/Advanced/About-Build-System.rst
similarity index 82%
rename from source/Concepts/About-Build-System.rst
rename to source/Concepts/Advanced/About-Build-System.rst
index 56188aac78c..fbab29aaee9 100644
--- a/source/Concepts/About-Build-System.rst
+++ b/source/Concepts/Advanced/About-Build-System.rst
@@ -1,22 +1,36 @@
-About the build system
-======================
+.. redirect-from::
-.. include:: ../../global_substitutions.txt
+ Concepts/About-Build-System
-Under everything is the build system.
-Iterating on ``catkin`` from ROS 1, we have created a set of |packages| under the moniker ``ament``.
-Some of the reasons for changing the name to ``ament`` are that we wanted it to not collide with ``catkin`` (in case we want to mix them at some point) and to prevent confusion with existing ``catkin`` documentation.
-``ament``'s primary responsibility is to make it easier to develop and maintain ROS 2 core |packages|.
-However, this responsibility extends to any user who is willing to make use of our build system conventions and tools.
-Additionally it should make |packages| conventional, such that developers should be able to pick up any ``ament`` based |package| and make some assumptions about how it works, how to introspect it, and how to build or use it.
+The build system
+================
-``ament`` consists of a few important repositories which are all in the ``ament`` `GitHub organization `_:
-
-.. contents::
- :depth: 1
+.. contents:: Table of Contents
:local:
-The ``ament_package`` Package
+.. include:: ../../../global_substitutions.txt
+
+The build system is what allows developers to build their ROS 2 code as needed.
+ROS 2 relies heavily on the division of code into packages, with each package containing a manifest file (``package.xml``).
+This manifest file contains essential metadata about the package, including its dependencies on other packages.
+This manifest is required for the meta-build tool to function.
+
+The ROS 2 build system consists of 3 major concepts.
+
+Build tool
+----------
+
+This is the software that controls the compilation and testing of a single package.
+In ROS 2 this is usually CMake for C++, and setuptools for Python, but other build tools are supported.
+
+Build helpers
+-------------
+
+These are helper functions that hook into the build tool to developer experience.
+ROS 2 packages typically rely on the ``ament`` series of packages for this.
+``ament`` consists of a few important repositories which are all in the `GitHub organization `_.
+
+The ``ament_package`` package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Located on |GitHub|_ at `ament/ament_package `_, this repository contains a single :term:`ament Python package` that provides various utilities for |ament packages|, e.g. templates for environment hooks.
@@ -59,7 +73,7 @@ Here is a list of common package types that you might run into in this software
ament Python package
A :term:`Python package` that also follows the ``ament`` packaging guidelines.
-The ``ament_cmake`` Repository
+The ``ament_cmake`` repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Located on |GitHub|_ at `ament/ament_cmake `_, this repository contains many "ament CMake" and pure CMake packages which provide the infrastructure in CMake that is required to create "ament CMake" packages.
@@ -98,7 +112,7 @@ Here a list of the |packages| in the repository along with a short description:
- ``ament_cmake_python``
- provides CMake functions for |packages| that contain Python code
- - see the :doc:`ament_cmake_python user documentation <../How-To-Guides/Ament-CMake-Python-Documentation>`
+ - see the :doc:`ament_cmake_python user documentation <../../How-To-Guides/Ament-CMake-Python-Documentation>`
- ``ament_cmake_test``
@@ -121,16 +135,17 @@ The environment setup files, often named something like ``setup.bash``, are a pl
The developers are able to do this using an "environment hook" which is basically an arbitrary bit of shell code that can set or modify environment variables, define shell functions, setup auto-completion rules, etc...
This feature is how, for example, ROS 1 set the ``ROS_DISTRO`` environment variable without ``catkin`` knowing anything about the ROS distribution.
-The ``ament_lint`` Repository
+The ``ament_lint`` repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Located on |GitHub|_ at `ament/ament_lint `_, this repository provides several |packages| which provide linting and testing services in a convenient and consistent manner.
Currently there are |packages| to support C++ style linting using ``uncrustify``, static C++ code checks using ``cppcheck``, checking for copyright in source code, Python style linting using ``pep8``, and other things.
The list of helper packages will likely grow in the future.
-Build tools
-~~~~~~~~~~~
+Meta-build tool
+---------------
+
+This is a piece of software that knows how to topologically order a group of packages, and build or test them in the correct dependency order.
+This software will call into the Build Tool to do the actual work of compiling, testing, and installing the package.
-A build tool performs the task of building a workspace of packages together at once with a single invocation.
-For ROS 2 releases up to Ardent, the build tool providing this functionality is called ``ament_tools``.
-As of ROS 2 Bouncy, ``ament_tools`` has been superseded by ``colcon``, as described in `the universal build tool article `_.
+In ROS 2, the tool named `colcon `__ is used for this.
diff --git a/source/Concepts/About-Internal-Interfaces.rst b/source/Concepts/Advanced/About-Internal-Interfaces.rst
similarity index 96%
rename from source/Concepts/About-Internal-Interfaces.rst
rename to source/Concepts/Advanced/About-Internal-Interfaces.rst
index a3833463855..a80cb2b83e8 100644
--- a/source/Concepts/About-Internal-Interfaces.rst
+++ b/source/Concepts/Advanced/About-Internal-Interfaces.rst
@@ -1,13 +1,20 @@
-About internal ROS 2 interfaces
-===============================
+.. redirect-from::
-.. include:: ../../global_substitutions.txt
+ Concepts/About-Internal-Interfaces
+
+Internal ROS 2 interfaces
+=========================
+
+.. contents:: Table of Contents
+ :local:
+
+.. include:: ../../../global_substitutions.txt
The internal ROS interfaces are public C |APIs| that are intended for use by developers who are creating |client libraries| or adding a new underlying middleware, but are not intended for use by typical ROS users.
The ROS |client libraries| provide the user facing |APIs| that most ROS users are familiar with, and may come in a variety of programming languages.
Internal API Architecture Overview
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
There are two main internal interfaces:
@@ -19,7 +26,7 @@ The underlying middleware used for ROS 2 is either a DDS or RTPS implementation,
The ``rcl`` |API| is a slightly higher level |API| which is used to implement the |client libraries| and does not touch the middleware implementation directly, but rather does so through the ROS middleware interface (``rmw`` |API|) abstraction.
-.. figure:: images/ros_client_library_api_stack.png
+.. figure:: ../images/ros_client_library_api_stack.png
:alt: ros2 software stack
As the diagram shows, these |APIs| are stacked such that the typical ROS user will use the |client library| |API|, e.g. ``rclcpp``, to implement their code (executable or library).
@@ -38,12 +45,12 @@ It also makes it easy to see what code is potentially violating the vendor porta
.. _Type Specific Interfaces:
Type Specific Interfaces
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
All along the way there are some parts of the |APIs| that are necessarily specific to the message types being exchanged, e.g. publishing a message or subscribing to a topic, and therefore require generated code for each message type.
The following diagram layouts the path from user defined ``rosidl`` files, e.g. ``.msg`` files, to the type specific code used by the user and system to perform type specific functions:
-.. figure:: images/ros_idl_api_stack_static.png
+.. figure:: ../images/ros_idl_api_stack_static.png
:alt: ros2 idl static type support stack
Figure: flow chart of "static" type support generation, from ``rosidl`` files to user facing code.
@@ -85,7 +92,7 @@ In order to accomplish this, this generic function needs some meta information a
Then to publish a message, you call a generic publish function and pass a message to be published along with a structure which contains the necessary meta data about the message type.
This is referred to as "dynamic" type support, as opposed to "static" type support which requires generated versions of a function for each type.
-.. figure:: images/ros_idl_api_stack_dynamic.png
+.. figure:: ../images/ros_idl_api_stack_dynamic.png
:alt: ros2 idl dynamic type support stack
Figure: flow chart of "dynamic" type support generation, from ``rosidl`` files to user facing code.
@@ -109,8 +116,8 @@ DDS-XTypes, or something like it, is required in the underlying middleware in or
Also, this approach to type support is normally slower than the static type support alternative.
The type specific generated code in static type support can be written to be more efficient as it does not need to iterate over the message type's meta data to perform things like serialization.
-The ``rcl`` Repository
-~~~~~~~~~~~~~~~~~~~~~~
+The ``rcl`` repository
+----------------------
The ROS Client Library interface (``rcl`` |API|) can be used by |client libraries| (e.g. ``rclc``, ``rclcpp``, ``rclpy``, etc.) in order to avoid duplicating logic and features.
By reusing the ``rcl`` |API|, client libraries can be smaller and more consistent with each other.
@@ -125,8 +132,8 @@ This implementation avoids direct contact with the middleware by instead using t
For a complete definition of the ``rcl`` |API|, see `the rcl docs `_.
-The ``rmw`` Repository
-~~~~~~~~~~~~~~~~~~~~~~
+The ``rmw`` repository
+----------------------
The ROS middleware interface (``rmw`` |API|) is the minimal set of primitive middleware capabilities needed to build ROS on top.
Providers of different middleware implementations must implement this interface in order to support the entire ROS stack on top.
@@ -138,8 +145,8 @@ The ``rmw`` |package| contains the C headers which define the interface, the imp
For a definition of the ``rmw`` |API|, see `the rmw docs `_.
-The ``rosidl`` Repository
-~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``rosidl`` repository
+-------------------------
The ``rosidl`` |API| consists of a few message related static functions and types along with a definition of what code should be generated by messages in different languages.
The generated message code specified in the |API| will be language specific, but may or may not reuse generated code for other languages.
@@ -175,12 +182,8 @@ See the :ref:`Type Specific Interfaces` section above for more details.
For more information on what exactly is in the ``rosidl`` |API| (static and generated) see this page:
-.. warning::
-
- TODO: link to definition of ``rosidl`` |APIs|
-
-The ``rcutils`` Repository
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``rcutils`` repository
+--------------------------
ROS 2 C Utilities (``rcutils``) is a C |API| composed of macros, functions, and data structures used throughout the ROS 2 codebase.
These are mainly used for error handling, commandline argument parsing, and logging which are not specific to the client or middleware layers and can be shared by both.
diff --git a/source/Concepts/About-Middleware-Implementations.rst b/source/Concepts/Advanced/About-Middleware-Implementations.rst
similarity index 82%
rename from source/Concepts/About-Middleware-Implementations.rst
rename to source/Concepts/Advanced/About-Middleware-Implementations.rst
index 84ab3740392..9ab0ac8d0fe 100644
--- a/source/Concepts/About-Middleware-Implementations.rst
+++ b/source/Concepts/Advanced/About-Middleware-Implementations.rst
@@ -1,13 +1,19 @@
+.. redirect-from::
-About ROS 2 middleware implementations
-======================================
+ Concepts/About-Middleware-Implementations
-.. include:: ../../global_substitutions.txt
+ROS 2 middleware implementations
+================================
+
+.. contents:: Table of Contents
+ :local:
+
+.. include:: ../../../global_substitutions.txt
ROS middleware implementations are sets of |packages| that implement some of the internal ROS interfaces, e.g. the ``rmw``, ``rcl``, and ``rosidl`` |APIs|.
Common Packages for DDS Middleware Packages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
All of the current ROS middleware implementations are based on full or partial DDS implementations.
For example, there is a middleware implementation that uses RTI's Connext DDS and an implementation which uses eProsima's Fast DDS.
@@ -21,13 +27,13 @@ The ``rosidl_generator_dds_idl`` |package| generates a DDS ``.idl`` file for eac
Currently DDS based ROS middleware implementations make use of this generator's output ``.idl`` files to generate pre-compiled type support that is vendor specific.
Structure of ROS Middleware Implementations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
A ROS middleware implementation is typically made up of a few |packages| in a single repository:
-- ``_cmake_module``: contains CMake Module for discovering and exposing required dependencies
-- ``rmw__``: contains the implementation of the ``rmw`` |API| in a particular language, typically C++
-- ``rosidl_typesupport__``: contains tools to generate static type support code for ``rosidl`` files, tailored to the implementation in a particular language, typically C or C++
+- ``_cmake_module``: contains CMake Module for discovering and exposing required dependencies
+- ``rmw__``: contains the implementation of the ``rmw`` |API| in a particular language, typically C++
+- ``rosidl_typesupport__``: contains tools to generate static type support code for ``rosidl`` files, tailored to the implementation in a particular language, typically C or C++
The ``_cmake_module`` |package| contains any CMake Modules and functions needed to find the supporting dependencies for the middleware implementation.
For example, ``rti_connext_dds_cmake_module`` provides wrapper logic around the CMake Module shipped with RTI Connext DDS to make sure that all packages that depend on it will select the same installation of RTI Connext DDS.
@@ -53,9 +59,3 @@ The rmw implementation for ``Fast DDS`` is on |GitHub|_ at `ros2/rmw_fastrtps_cp
The rmw implementation for ``Connext DDS`` is on |GitHub|_ at `ros2/rmw_connextdds `_.
The rmw implementation for ``GurumDDS`` is on |GitHub|_ at `ros/rmw_gurumdds `_.
-
-To learn more about what is required to create a new middleware implementation for ROS see this page:
-
-.. warning::
-
- TODO: Link to more detailed middleware implementation docs and/or tutorial.
diff --git a/source/Concepts/Basic.rst b/source/Concepts/Basic.rst
new file mode 100644
index 00000000000..b6cd5a7c3af
--- /dev/null
+++ b/source/Concepts/Basic.rst
@@ -0,0 +1,23 @@
+Basic Concepts
+==============
+
+ROS 2 is a middleware based on a strongly-typed, anonymous publish/subscribe mechanism that allows for message passing between different processes.
+
+At the heart of any ROS 2 system is the ROS graph.
+The ROS graph refers to the network of nodes in a ROS system and the connections between them by which they communicate.
+
+These are the concepts that will help you get started understanding the basics of ROS 2.
+
+.. toctree::
+ :maxdepth: 1
+
+ Basic/About-Nodes
+ Basic/About-Discovery
+ Basic/About-Interfaces
+ Basic/About-Topics
+ Basic/About-Services
+ Basic/About-Actions
+ Basic/About-Parameters
+ Basic/About-Command-Line-Tools
+ Basic/About-Launch
+ Basic/About-Client-Libraries
diff --git a/source/Concepts/Basic/About-Actions.rst b/source/Concepts/Basic/About-Actions.rst
new file mode 100644
index 00000000000..fe0311b1199
--- /dev/null
+++ b/source/Concepts/Basic/About-Actions.rst
@@ -0,0 +1,56 @@
+Actions
+=======
+
+.. contents:: Table of Contents
+ :local:
+
+In ROS 2, an action refers to a long-running remote procedure call with feedback and the ability to cancel or preempt the goal.
+For instance, the high-level state machine running a robot may call an action to tell the navigation subsystem to travel to a waypoint, which may take several seconds (or minutes) to do.
+Along the way, the navigation subsystem can provide feedback on how far along it is, and the high-level state machine has the option to cancel or preempt the travel to that waypoint.
+
+This structure is reflected in how an action message definition looks:
+
+.. code::
+
+ int32 request
+ ---
+ int32 response
+ ---
+ int32 feedback
+
+In ROS 2, actions are expected to be long running procedures, as there is overhead in setting up and monitoring the connection.
+If you need a short running remote procedure call, consider using a :doc:`service ` instead.
+
+Actions are identified by an action name, which looks much like a topic name (but is in a different namespace).
+
+An action consists of two parts: the action server and the action client.
+
+Action server
+-------------
+
+The action server is the entity that will accept the remote procedure request and perform some procedure on it.
+It is also responsible for sending out feedback as the action progresses and should react to cancellation/preemption requests.
+For instance, consider an action to calculate the Fibonacci sequence with the following interface:
+
+.. code::
+
+ int32 order
+ ---
+ int32[] sequence
+ ---
+ int32[] sequence
+
+The action server is the entity that receives this message, starts calculating the sequence up to ``order`` (providing feedback along the way), and finally returns a full result in ``sequence``.
+
+.. note::
+
+ There should only ever be one action server per action name.
+ It is undefined which action server will receive client requests in the case of multiple action servers on the same action name.
+
+Action client
+-------------
+
+An action client is an entity that will request a remote action server to perform a procedure on its behalf.
+Following the example above, the action client is the entity that creates the initial message containing the ``order``, and waits for the action server to compute the sequence and return it (with feedback along the way).
+
+Unlike the action server, there can be arbitrary numbers of action clients using the same action name.
diff --git a/source/Concepts/About-ROS-2-Client-Libraries.rst b/source/Concepts/Basic/About-Client-Libraries.rst
similarity index 90%
rename from source/Concepts/About-ROS-2-Client-Libraries.rst
rename to source/Concepts/Basic/About-Client-Libraries.rst
index 2e58984301d..890ee99047e 100644
--- a/source/Concepts/About-ROS-2-Client-Libraries.rst
+++ b/source/Concepts/Basic/About-Client-Libraries.rst
@@ -1,13 +1,12 @@
.. redirect-from::
Concepts/About-Client-Interfaces
+ Concepts/About-ROS-2-Client-Libraries
-.. include:: ../../global_substitutions.txt
+.. include:: ../../../global_substitutions.txt
-.. _ROS-2-Client-Libraries:
-
-About ROS 2 client libraries
-============================
+Client libraries
+================
.. contents:: Table of Contents
:local:
@@ -15,17 +14,16 @@ About ROS 2 client libraries
Overview
--------
-Client libraries are the APIs that allow users to implement their ROS code.
-Using client libraries, users gain access to ROS concepts such as nodes, topics, services, etc.
-Client libraries come in a variety of programming languages so that users may write ROS code in the language that is best-suited for their application.
+Client libraries are the APIs that allow users to implement their ROS 2 code.
+Using client libraries, users gain access to ROS 2 concepts such as nodes, topics, services, etc.
+Client libraries come in a variety of programming languages so that users may write ROS 2 code in the language that is best-suited for their application.
For example, you might prefer to write visualization tools in Python because it makes prototyping iterations faster, while for parts of your system that are concerned with efficiency, the nodes might be better implemented in C++.
-Nodes written using different client libraries are able to share messages with each other because all client libraries implement code generators that provide users with the capability to interact with ROS interface files in the respective language.
+Nodes written using different client libraries are able to share messages with each other because all client libraries implement code generators that provide users with the capability to interact with ROS 2 interface files in the respective language.
-In addition to the language-specific communication tools, client libraries expose to users the core functionality that makes ROS “ROS”.
+In addition to the language-specific communication tools, client libraries expose to users the core functionality that makes ROS "ROS".
For example, here is a list of functionality that can typically be accessed through a client library:
-
* Names and namespaces
* Time (real or simulated)
* Parameters
@@ -36,9 +34,9 @@ For example, here is a list of functionality that can typically be accessed thro
Supported client libraries
--------------------------
-The C++ client library (``rclcpp``) and the Python client library (``rclpy``) are both client libraries which utilize common functionality in the RCL.
+The C++ client library (``rclcpp``) and the Python client library (``rclpy``) are both client libraries which utilize common functionality in ``rcl``.
-The ``rclcpp`` Package
+The ``rclcpp`` package
~~~~~~~~~~~~~~~~~~~~~~
The ROS Client Library for C++ (``rclcpp``) is the user facing, C++ idiomatic interface which provides all of the ROS client functionality like creating nodes, publishers, and subscriptions.
@@ -51,7 +49,7 @@ The generated |API| documentation is here:
`api/rclcpp/index.html `_
-The ``rclpy`` Package
+The ``rclpy`` package
~~~~~~~~~~~~~~~~~~~~~
The ROS Client Library for Python (``rclpy``) is the Python counterpart to the C++ client library.
@@ -67,7 +65,7 @@ This is avoided if possible when communicating between publishers and subscripti
The ``rclpy`` repository is located on GitHub at `ros2/rclpy `_ and contains the |package| ``rclpy``.
The generated |API| documentation is here:
-`api/rclpy/index.html `_
+`api/rclpy/index.html `_
Community-maintained
@@ -75,7 +73,6 @@ Community-maintained
While the C++ and Python client libraries are maintained by the core ROS 2 team, members of the ROS 2 community maintain additional client libraries:
-* `Ada `__ Ada binding and tools for ROS 2 - workspace overlay.
* `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.
@@ -84,11 +81,13 @@ While the C++ and Python client libraries are maintained by the core ROS 2 team,
Older, unmaintained client libraries are:
+* `Ada `__
* `C# `__
* `Objective C and iOS `__
+* `Zig `__
-Common functionality: the RCL
+Common functionality: ``rcl``
-----------------------------
Most of the functionality found in a client library is not specific to the programming language of the client library.
@@ -102,7 +101,7 @@ In addition to making the client libraries light-weight, an advantage of having
If any changes are made to the logic/behavior of the functionality in the core RCL -- namespaces, for example -- all client libraries that use the RCL will have these changes reflected.
Furthermore, having the common core means that maintaining multiple client libraries becomes less work when it comes to bug fixes.
-`The API documentation for the RCL can be found here. `__
+The API documentation for ``rcl`` can be found `here `__.
Language-specific functionality
-------------------------------
diff --git a/source/Concepts/About-Command-Line-Tools.rst b/source/Concepts/Basic/About-Command-Line-Tools.rst
similarity index 68%
rename from source/Concepts/About-Command-Line-Tools.rst
rename to source/Concepts/Basic/About-Command-Line-Tools.rst
index 2bc2c911c88..2b0b7c71c4f 100644
--- a/source/Concepts/About-Command-Line-Tools.rst
+++ b/source/Concepts/Basic/About-Command-Line-Tools.rst
@@ -2,12 +2,12 @@
Introspection-with-command-line-tools
Tutorials/Introspection-with-command-line-tools
+ Concepts/About-Command-Line-Tools
Introspection with command line tools
=====================================
.. contents:: Table of Contents
- :depth: 1
:local:
ROS 2 includes a suite of command-line tools for introspecting a ROS 2 system.
@@ -25,24 +25,25 @@ To see all available sub-commands run:
Examples of sub-commands that are available include:
-
-* action: Introspect/interact with ROS actions
-* bag: Record/play a rosbag
-* component: Manage component containers
-* daemon: Introspect/configure the ROS 2 daemon
-* doctor: Check ROS setup for potential issues
-* interface: Show information about ROS interfaces
-* launch: Run/introspect a launch file
-* lifecycle: Introspect/manage nodes with managed lifecycles
-* node: Introspect ROS nodes
-* param: Introspect/configure parameters on a node
-* pkg: Introspect ROS packages
-* run: Run ROS nodes
-* security: Configure security settings
-* service: Introspect/call ROS services
-* test: Run a ROS launch test
-* topic: Introspect/publish ROS topics
-* trace: Tracing tools to get information on ROS nodes execution (only available on Linux)
+* ``action``: Introspect/interact with ROS actions
+* ``bag``: Record/play a rosbag
+* ``component``: Manage component containers
+* ``daemon``: Introspect/configure the ROS 2 daemon
+* ``doctor``: Check ROS setup for potential issues
+* ``interface``: Show information about ROS interfaces
+* ``launch``: Run/introspect a launch file
+* ``lifecycle``: Introspect/manage nodes with managed lifecycles
+* ``multicast``: Multicast debugging commands
+* ``node``: Introspect ROS nodes
+* ``param``: Introspect/configure parameters on a node
+* ``pkg``: Introspect ROS packages
+* ``run``: Run ROS nodes
+* ``security``: Configure security settings
+* ``service``: Introspect/call ROS services
+* ``test``: Run a ROS launch test
+* ``topic``: Introspect/publish ROS topics
+* ``trace``: Tracing tools to get information on ROS nodes execution (only available on Linux)
+* ``wtf``: An alias for ``doctor``
Example
-------
@@ -72,7 +73,7 @@ Behind the scenes
-----------------
ROS 2 uses a distributed discovery process for nodes to connect to each other.
-As this process purposefully does not use a centralized discovery mechanism (like the ROS Master in ROS 1), it can take time for ROS nodes to discover all other participants in the ROS graph.
+As this process purposefully does not use a centralized discovery mechanism, it can take time for ROS nodes to discover all other participants in the ROS graph.
Because of this, there is a long-running daemon in the background that stores information about the ROS graph to provide faster responses to queries, e.g. the list of node names.
The daemon is automatically started when the relevant command-line tools are used for the first time.
diff --git a/source/Concepts/Basic/About-Discovery.rst b/source/Concepts/Basic/About-Discovery.rst
new file mode 100644
index 00000000000..0d5a0cda2f2
--- /dev/null
+++ b/source/Concepts/Basic/About-Discovery.rst
@@ -0,0 +1,21 @@
+Discovery
+=========
+
+.. contents:: Table of Contents
+ :local:
+
+Discovery of nodes happens automatically through the underlying middleware of ROS 2.
+It can be summarized as follows:
+
+#. When a node is started, it advertises its presence to other nodes on the network with the same ROS domain (set with the ROS_DOMAIN_ID environment variable).
+ Nodes respond to this advertisement with information about themselves so that the appropriate connections can be made and the nodes can communicate.
+#. Nodes periodically advertise their presence so that connections can be made with new-found entities, even after the initial discovery period.
+#. Nodes advertise to other nodes when they go offline.
+
+Nodes will only establish connections with other nodes if they have compatible :doc:`Quality of Service <../../Tutorials/Demos/Quality-of-Service>` settings.
+
+Take the :ref:`talker-listener demo ` for example.
+Running the C++ talker node in one terminal will publish messages on a topic,
+and the Python listener node running in another terminal will subscribe to messages on the same topic.
+
+You should see that these nodes discover each other automatically, and begin to exchange messages.
diff --git a/source/Concepts/About-ROS-Interfaces.rst b/source/Concepts/Basic/About-Interfaces.rst
similarity index 66%
rename from source/Concepts/About-ROS-Interfaces.rst
rename to source/Concepts/Basic/About-Interfaces.rst
index 4ab01c62d65..d8044e231a9 100644
--- a/source/Concepts/About-ROS-Interfaces.rst
+++ b/source/Concepts/Basic/About-Interfaces.rst
@@ -1,19 +1,18 @@
-.. _InterfaceConcept:
-
.. redirect-from::
About-ROS-Interfaces
+ Concepts/About-ROS-Interfaces
-About ROS 2 interfaces
-======================
+Interfaces
+==========
.. contents:: Table of Contents
:local:
-1. Background
--------------
+Background
+----------
-ROS applications typically communicate through interfaces of one of three types: messages, services and actions.
+ROS applications typically communicate through interfaces of one of three types: :doc:`topics `, :doc:`services `, or :doc:`actions `.
ROS 2 uses a simplified description language, the interface definition language (IDL), to describe these interfaces.
This description makes it easy for ROS tools to automatically generate source code for the interface type in several target languages.
@@ -24,15 +23,18 @@ In this document we will describe the supported types:
* 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
+--------
-2. Message description specification
-------------------------------------
+Messages are a way for a ROS 2 node to send data on the network to other ROS nodes, with no response expected.
+For instance, if a ROS 2 node reads temperature data from a sensor, it can then publish that data on the ROS 2 network using a ``Temperature`` message.
+Other nodes on the ROS 2 network can subscribe to that data and receive the ``Temperature`` message.
Messages are described and defined in ``.msg`` files in the ``msg/`` directory of a ROS package.
``.msg`` files are composed of two parts: fields and constants.
-2.1 Fields
-^^^^^^^^^^
+Fields
+^^^^^^
Each field consists of a type and a name, separated by a space, i.e:
@@ -49,12 +51,11 @@ For example:
int32 my_int
string my_string
-2.1.1 Field types
-~~~~~~~~~~~~~~~~~
+Field types
+~~~~~~~~~~~
Field types can be:
-
* a built-in-type
* names of Message descriptions defined on their own, such as "geometry_msgs/PoseStamped"
@@ -128,7 +129,6 @@ Field types can be:
- builtins.str
- wstring
-
*Every built-in-type can be used to define arrays:*
.. list-table::
@@ -155,8 +155,7 @@ Field types can be:
- builtins.str*
- string
-
-All types that are more permissive than their ROS definition enforce the ROS constraints in range and length by software
+All types that are more permissive than their ROS definition enforce the ROS constraints in range and length by software.
*Example of message definition using arrays and bounded types:*
@@ -173,14 +172,14 @@ All types that are more permissive than their ROS definition enforce the ROS con
string<=10[] unbounded_array_of_strings_up_to_ten_characters_each
string<=10[<=5] up_to_five_strings_up_to_ten_characters_each
-2.1.2 Field names
-~~~~~~~~~~~~~~~~~
+Field names
+~~~~~~~~~~~
Field names must be lowercase alphanumeric characters with underscores for separating words.
They must start with an alphabetic character, and they must not end with an underscore or have two consecutive underscores.
-2.1.3 Field default value
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Field default value
+~~~~~~~~~~~~~~~~~~~
Default values can be set to any field in the message type.
Currently default values are not supported for string arrays and complex types (i.e. types not present in the built-in-types table above; that applies to all nested messages).
@@ -200,16 +199,16 @@ For example:
string full_name "John Doe"
int32[] samples [-200, -100, 0, 100, 200]
-Note:
-
+.. note::
-* string values must be defined in single ``'`` or double ``"`` quotes
-* currently string values are not escaped
+ * string values must be defined in single ``'`` or double ``"`` quotes
+ * currently string values are not escaped
-2.2 Constants
-^^^^^^^^^^^^^
+Constants
+^^^^^^^^^
-Each constant definition is like a field description with a default value, except that this value can never be changed programatically. This value assignment is indicated by use of an equal '=' sign, e.g.
+Each constant definition is like a field description with a default value, except that this value can never be changed programatically.
+This value assignment is indicated by use of an equal '=' sign, e.g.
.. code-block:: bash
@@ -228,8 +227,10 @@ For example:
Constants names have to be UPPERCASE
-3. Service description specification
-------------------------------------
+Services
+--------
+
+Services are a request/response communication, where the client (requester) is waiting for the server (responder) to make a short computation and return a result.
Services are described and defined in ``.srv`` files in the ``srv/`` directory of a ROS package.
@@ -248,33 +249,55 @@ We can of course get much more complicated (if you want to refer to a message fr
.. code-block:: bash
- #request constants
+ # request constants
int8 FOO=1
int8 BAR=2
- #request fields
+ # request fields
int8 foobar
another_pkg/AnotherMessage msg
---
- #response constants
+ # response constants
uint32 SECRET=123456
- #response fields
+ # response fields
another_pkg/YetAnotherMessage val
CustomMessageDefinedInThisPackage value
uint32 an_integer
You cannot embed another service inside of a service.
-4. New features in ROS 2 interfaces
------------------------------------
+Actions
+-------
+
+Actions are a long-running request/response communication, where the action client (requester) is waiting for the action server (the responder) to take some action and return a result.
+In contrast to services, actions can be long-running (many seconds or minutes), provide feedback while they are happening, and can be interrupted.
-The ROS 2 IDL is closely related to the `ROS 1 IDL `__.
-Most existing ROS 1 ``.msg`` and ``.srv`` files should be usable as-is with ROS 2.
-Atop ROS 1's existing feature set, the ROS 2 IDL introduces some new features, namely:
+Action definitions have the following form:
+.. code::
+
+
+ ---
+
+ ---
+
+
+Like services, the request fields are before and the response fields are after the first triple-dash (``---``), respectively.
+There is also a third set of fields after the second triple-dash, which is the fields to be sent when sending feedback.
+
+There can be arbitrary numbers of request fields (including zero), arbitrary numbers of response fields (including zero), and arbitrary numbers of feedback fields (including zero).
+
+The ````, ````, and ```` follow all of the same rules as the ```` for a message.
+The ````, ````, and ```` follow all of the same rules as the ```` for a message.
+
+For instance, the ``Fibonacci`` action definition contains the following:
+
+.. code::
+
+ int32 order
+ ---
+ int32[] sequence
+ ---
+ int32[] sequence
-* **bounded arrays**: Whereas the ROS 1 IDL allows unbounded arrays (e.g., ``int32[] foo``) and fixed-size arrays (e.g., ``int32[5] bar``), the ROS 2 IDL further allows bounded arrays (e.g., ``int32[<=5] bat``).
- There are use cases in which it's important to be able to place an upper bound on the size of an array without committing to always using that much space (e.g., in a real-time system in which you need to preallocate all memory that will be used during execution).
-* **bounded strings**: Whereas the ROS 1 IDL allows unbounded strings (e.g., ``string foo``), the ROS 2 IDL further allows bounded strings (e.g., ``string<=5 bar``).
-* **default values**: Whereas the ROS 1 IDL allows constant fields (e.g., ``int32 X=123``), the ROS 2 IDL further allows default values to be specified (e.g., ``int32 X 123``).
- The default value is used when constructing a message/service object and can be subsequently overridden by assigning to the field.
- You can also specify default values for action parts.
+This is an action definition where the action client is sending a single ``int32`` field representing the number of Fibonacci steps to take, and expecting the action server to produce an array of ``int32`` containing the complete steps.
+Along the way, the action server may also provide an intermediate array of ``int32`` contains the steps accomplished up until a certain point.
diff --git a/source/Concepts/Basic/About-Launch.rst b/source/Concepts/Basic/About-Launch.rst
new file mode 100644
index 00000000000..75a12f4d97d
--- /dev/null
+++ b/source/Concepts/Basic/About-Launch.rst
@@ -0,0 +1,18 @@
+Launch
+======
+
+.. contents:: Table of Contents
+ :local:
+
+A ROS 2 system typically consists of many nodes running across many different processes (and even different machines).
+While it is possible to run each of these nodes separately, it gets cumbersome quite quickly.
+
+The launch system in ROS 2 is meant to automate the running of many nodes with a single command.
+It helps the user describe the configuration of their system and then executes it as described.
+The configuration of the system includes what programs to run, where to run them, what arguments to pass them, and ROS-specific conventions which make it easy to reuse components throughout the system by giving them each a different configuration.
+It is also responsible for monitoring the state of the processes launched, and reporting and/or reacting to changes in the state of those processes.
+
+All of the above is specified in a launch file, which can be written in Python, XML, or YAML.
+This launch file can then be run using the ``ros2 launch`` command, and all of the nodes specified will be run.
+
+The `design document `__ details the goal of the design of ROS 2's launch system (not all functionality is currently available).
diff --git a/source/Concepts/Basic/About-Nodes.rst b/source/Concepts/Basic/About-Nodes.rst
new file mode 100644
index 00000000000..6ec5fbbfa94
--- /dev/null
+++ b/source/Concepts/Basic/About-Nodes.rst
@@ -0,0 +1,18 @@
+Nodes
+=====
+
+.. contents:: Table of Contents
+ :local:
+
+A node is a participant in the ROS 2 graph, which uses a :doc:`client library ` to communicate with other nodes.
+Nodes can communicate with other nodes within the same process, in a different process, or on a different machine.
+Nodes are typically the unit of computation in a ROS graph; each node should do one logical thing.
+
+Nodes can :doc:`publish ` to named topics to deliver data to other nodes, or :doc:`subscribe ` to named topics to get data from other nodes.
+They can also act as a :doc:`service client ` to have another node perform a computation on their behalf, or as a :doc:`service server ` to provide functionality to other nodes.
+For long-running computations, a node can act as an :doc:`action client ` to have another node perform it on their behalf, or as an :doc:`action server ` to provide functionality to other nodes.
+Nodes can provide configurable :doc:`parameters ` to change behavior during run-time.
+
+Nodes are often a complex combination of publishers, subscribers, service servers, service clients, action servers, and action clients, all at the same time.
+
+Connections between nodes are established through a distributed :doc:`discovery ` process.
diff --git a/source/Concepts/About-ROS-2-Parameters.rst b/source/Concepts/Basic/About-Parameters.rst
similarity index 62%
rename from source/Concepts/About-ROS-2-Parameters.rst
rename to source/Concepts/Basic/About-Parameters.rst
index 5ac2008c696..47c659b96bd 100644
--- a/source/Concepts/About-ROS-2-Parameters.rst
+++ b/source/Concepts/Basic/About-Parameters.rst
@@ -1,11 +1,10 @@
-.. _AboutParameters:
-
.. redirect-from::
About-ROS-2-Parameters
+ Concepts/About-ROS-2-Parameters
-About parameters in ROS 2
-=========================
+Parameters
+==========
.. contents:: Table of Contents
:local:
@@ -13,7 +12,7 @@ About parameters in ROS 2
Overview
--------
-Parameters in ROS are associated with individual nodes.
+Parameters in ROS 2 are associated with individual nodes.
Parameters are used to configure nodes at startup (and during runtime), without changing the code.
The lifetime of a parameter is tied to the lifetime of the node (though the node could implement some sort of persistence to reload values after restart).
@@ -21,10 +20,10 @@ Parameters are addressed by node name, node namespace, parameter name, and param
Providing a parameter namespace is optional.
Each parameter consists of a key, a value, and a descriptor.
-The key is a string and the value is one of the following types: bool, int64, float64, string, byte[], bool[], int64[], float64[] or string[].
+The key is a string and the value is one of the following types: ``bool``, ``int64``, ``float64``, ``string``, ``byte[]``, ``bool[]``, ``int64[]``, ``float64[]`` or ``string[]``.
By default all descriptors are empty, but can contain parameter descriptions, value ranges, type information, and additional constraints.
-For an hands-on tutorial with ROS parameters see :doc:`../Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters`.
+For an hands-on tutorial with ROS parameters see :doc:`../../Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters`.
Parameters background
---------------------
@@ -34,7 +33,7 @@ Declaring parameters
By default, a node needs to *declare* all of the parameters that it will accept during its lifetime.
This is so that the type and name of the parameters are well-defined at node startup time, which reduces the chances of misconfiguration later on.
-See :doc:`../Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-CPP` or :doc:`../Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-Python` for tutorials on declaring and using parameters from a node.
+See :doc:`../../Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-CPP` or :doc:`../../Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-Python` for tutorials on declaring and using parameters from a node.
For some types of nodes, not all of the parameters will be known ahead of time.
In these cases, the node can be instantiated with ``allow_undeclared_parameters`` set to ``true``, which will allow parameters to be get and set on the node even if they haven't been declared.
@@ -52,14 +51,16 @@ When the parameter is declared, it should be declared using a ``ParameterDescrip
Parameter callbacks
^^^^^^^^^^^^^^^^^^^
-A ROS 2 node can register two different types of callbacks to be informed when changes are happening to parameters.
-The reason that there are two types of callbacks is to have a chance to intervene before the parameter change happens, and to have a chance to react after the parameter change happens.
-A node can register for both, either, or none of the callback types.
-Both types are described below.
+A ROS 2 node can register three different types of callbacks to be informed when changes are happening to parameters.
+All three of the callbacks are optional.
+
+The first is known as a "pre set parameter" callback, and can be set by calling ``add_pre_set_parameters_callback`` from the node API.
+This callback is passed a list of the ``Parameter`` objects that are being changed, and returns nothing.
+When it is called, it can modify the ``Parameter`` list to change, add, or remove entries.
+As an example, if ``parameter2`` should change anytime that ``parameter1`` changes, that can be implemented with this callback.
-The first type is known as a "set parameter" callback, and can be set by calling ``add_on_set_parameters_callback`` from the node API.
-The callback should accept a list of ``Parameter`` objects, and return an ``rcl_interfaces/msg/SetParametersResult``.
-This callback will be called before a parameter is declared or changed on a node.
+The second is known as a "set parameter" callback, and can be set by calling ``add_on_set_parameters_callback`` from the node API.
+The callback is passed a list of immutable ``Parameter`` objects, and returns an ``rcl_interfaces/msg/SetParametersResult``.
The main purpose of this callback is to give the user the ability to inspect the upcoming change to the parameter and explicitly reject the change.
.. note::
@@ -68,29 +69,30 @@ The main purpose of this callback is to give the user the ability to inspect the
If the individual callback were to make changes to the class it is in, for instance, it may get out-of-sync with the actual parameter.
To get a callback *after* a parameter has been successfully changed, see the next type of callback below.
-The second type of callback is known as an "on parameter event" callback, and can be set by calling ``on_parameter_event`` from one of the parameter client APIs.
-The callback should accept an ``rcl_interfaces/msg/ParameterEvent`` object, and return nothing.
-This callback will be called after all parameters in the input event have been declared, changed, or deleted.
+The third type of callback is known as an "post set parameter" callback, and can be set by calling ``add_post_set_parameters_callback`` from the node API.
+The callback is passed a list of immutable ``Parameter`` objects, and returns nothing.
The main purpose of this callback is to give the user the ability to react to changes from parameters that have successfully been accepted.
+The ROS 2 demos have an `example `__ of all of these callbacks in use.
+
Interacting with parameters
---------------------------
-ROS 2 nodes can perform parameter operations through node APIs as described in :doc:`../Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-CPP` or :doc:`../Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-Python`.
+ROS 2 nodes can perform parameter operations through node APIs as described in :doc:`../../Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-CPP` or :doc:`../../Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-Python`.
External processes can perform parameter operations via parameter services that are created by default when a node is instantiated.
The services that are created by default are:
-* /node_name/describe_parameters: Uses a service type of ``rcl_interfaces/srv/DescribeParameters``.
+* ``/node_name/describe_parameters``: Uses a service type of ``rcl_interfaces/srv/DescribeParameters``.
Given a list of parameter names, returns a list of descriptors associated with the parameters.
-* /node_name/get_parameter_types: Uses a service type of ``rcl_interfaces/srv/GetParameterTypes``.
+* ``/node_name/get_parameter_types``: Uses a service type of ``rcl_interfaces/srv/GetParameterTypes``.
Given a list of parameter names, returns a list of parameter types associated with the parameters.
-* /node_name/get_parameters: Uses a service type of ``rcl_interfaces/srv/GetParameters``.
+* ``/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``.
+* ``/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.
-* /node_name/set_parameters: Uses a service type of ``rcl_interfaces/srv/SetParameters``.
+* ``/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.
-* /node_name/set_parameters_atomically: Uses a service type of ``rcl_interfaces/srv/SetParametersAtomically``.
+* ``/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.
Setting initial parameter values when running a node
@@ -103,21 +105,21 @@ Setting initial parameter values when launching nodes
-----------------------------------------------------
Initial parameter values can also be set when running the node through the ROS 2 launch facility.
-See :doc:`this document <../Tutorials/Intermediate/Launch/Using-ROS2-Launch-For-Large-Projects>` for information on how to specify parameters via launch.
+See :doc:`this document <../../Tutorials/Intermediate/Launch/Using-ROS2-Launch-For-Large-Projects>` for information on how to specify parameters via launch.
Manipulating parameter values at runtime
----------------------------------------
The ``ros2 param`` command is the general way to interact with parameters for nodes that are already running.
``ros2 param`` uses the parameter service API as described above to perform the various operations.
-See :doc:`this how-to guide <../How-To-Guides/Using-ros2-param>` for details on how to use ``ros2 param``.
+See :doc:`this how-to guide <../../How-To-Guides/Using-ros2-param>` for details on how to use ``ros2 param``.
Migrating from ROS 1
--------------------
-The :doc:`Launch file migration guide <../How-To-Guides/Launch-files-migration-guide>` explains how to migrate ``param`` and ``rosparam`` launch tags from ROS 1 to ROS 2.
+The :doc:`Launch file migration guide <../../How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files>` explains how to migrate ``param`` and ``rosparam`` launch tags from ROS 1 to ROS 2.
-The :doc:`YAML parameter file migration guide <../How-To-Guides/Parameters-YAML-files-migration-guide>` explains how to migrate parameter files from ROS 1 to ROS 2.
+The :doc:`YAML parameter file migration guide <../../How-To-Guides/Migrating-from-ROS1/Migrating-Parameters>` explains how to migrate parameter files from ROS 1 to ROS 2.
In ROS 1, the ``roscore`` acted like a global parameter blackboard where all nodes could get and set parameters.
Since there is no central ``roscore`` in ROS 2, that functionality no longer exists.
diff --git a/source/Concepts/Basic/About-Services.rst b/source/Concepts/Basic/About-Services.rst
new file mode 100644
index 00000000000..24c97825f38
--- /dev/null
+++ b/source/Concepts/Basic/About-Services.rst
@@ -0,0 +1,52 @@
+Services
+========
+
+.. contents:: Table of Contents
+ :local:
+
+In ROS 2, a service refers to a remote procedure call.
+In other words, a node can make a remote procedure call to another node which will do a computation and return a result.
+
+This structure is reflected in how a service message definition looks:
+
+.. code::
+
+ uint32 request
+ ---
+ uint32 response
+
+In ROS 2, services are expected to return quickly, as the client is generally waiting on the result.
+Services should never be used for longer running processes, in particular processes that might need to be preempted for exceptional situations.
+If you have a service that will be doing a long-running computation, consider using an :doc:`action ` instead.
+
+Services are identified by a service name, which looks much like a topic name (but is in a different namespace).
+
+A service consists of two parts: the service server and the service client.
+
+Service server
+--------------
+
+A service server is the entity that will accept a remote procedure request, and perform some computation on it.
+For instance, suppose the ROS 2 message contains the following:
+
+.. code::
+
+ uint32 a
+ uint32 b
+ ---
+ uint32 sum
+
+The service server would be the entity that receives this message, adds ``a`` and ``b`` together, and returns the ``sum``.
+
+.. note::
+
+ There should only ever be one service server per service name.
+ It is undefined which service server will receive client requests in the case of multiple service servers on the same service name.
+
+Service client
+--------------
+
+A service client is an entity that will request a remote service server to perform a computation on its behalf.
+Following from the example above, the service client is the entity that creates the initial message containing ``a`` and ``b``, and waits for the service server to compute the sum and return the result.
+
+Unlike the service server, there can be arbitrary numbers of service clients using the same service name.
diff --git a/source/Concepts/Basic/About-Topics.rst b/source/Concepts/Basic/About-Topics.rst
new file mode 100644
index 00000000000..d76b1145201
--- /dev/null
+++ b/source/Concepts/Basic/About-Topics.rst
@@ -0,0 +1,51 @@
+Topics
+======
+
+.. contents:: Table of Contents
+ :local:
+
+Topics are one of the three primary styles of interfaces provided by ROS 2.
+Topics should be used for continuous data streams, like sensor data, robot state, etc.
+
+As stated earlier, ROS 2 is a strongly-typed, anonymous publish/subscribe system.
+Let's break down that sentence and explain it a bit more.
+
+Publish/Subscribe
+-----------------
+
+A publish/subscribe system is one in which there are producers of data (publishers) and consumers of data (subscribers).
+The publishers and subscribers know how to contact each other through the concept of a "topic", which is a common name so that the entites can find each other.
+For instance, when you create a publisher, you must also give it a string that is the name of the topic; the same goes for the subscriber.
+Any publishers and subscribers that are on the same topic name can directly communicate with each other.
+There may be zero or more publishers and zero or more subscribers on any particular topic.
+When data is published to the topic by any of the publishers, all subscribers in the system will receive the data.
+This system is also known as a "bus", since it somewhat resembles a device bus from electrical engineering.
+This concept of a bus is part of what makes ROS 2 a powerful and flexible system.
+Publishers and subscribers can come and go as needed, meaning that debugging and introspection are natural extensions to the system.
+For instance, if you want to record data, you can use the ``ros2 bag record`` command.
+Under the hood, ``ros2 bag record`` creates a new subscriber to whatever topic you tell it, without interrupting the flow of data to the other parts of the system.
+
+Anonymous
+---------
+
+Another fact mentioned in the introduction is that ROS 2 is "anonymous".
+This means that when a subscriber gets a piece of data, it doesn't generally know or care which publisher originally sent it (though it can find out if it wants).
+The benefit to this architecture is that publishers and subscribers can be swapped out at will without affecting the rest of the system.
+
+Strongly-typed
+--------------
+
+Finally, the introduction also mentioned that the publish/subscribe system is "strongly-typed".
+That has two meanings in this context:
+
+1. The types of each field in a ROS message are typed, and that type is enforced at various levels.
+ For instance, if the ROS message contains:
+
+ .. code::
+
+ uint32 field1
+ string field2
+
+ Then the code will ensure that ``field`` 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.
diff --git a/source/Concepts/Intermediate.rst b/source/Concepts/Intermediate.rst
new file mode 100644
index 00000000000..0338e8f0fdf
--- /dev/null
+++ b/source/Concepts/Intermediate.rst
@@ -0,0 +1,19 @@
+Intermediate Concepts
+=====================
+
+These are the concepts that further your understanding of a basic ROS 2 system.
+
+.. toctree::
+ :maxdepth: 1
+
+ Intermediate/About-Domain-ID
+ Intermediate/About-Different-Middleware-Vendors
+ Intermediate/About-Logging
+ Intermediate/About-Quality-of-Service-Settings
+ Intermediate/About-Executors
+ Intermediate/About-Topic-Statistics
+ Intermediate/About-RQt
+ Intermediate/About-Composition
+ Intermediate/About-Cross-Compilation
+ Intermediate/About-Security
+ Intermediate/About-Tf2
diff --git a/source/Concepts/About-Composition.rst b/source/Concepts/Intermediate/About-Composition.rst
similarity index 94%
rename from source/Concepts/About-Composition.rst
rename to source/Concepts/Intermediate/About-Composition.rst
index 2a5c270954c..4a6a9399ee3 100644
--- a/source/Concepts/About-Composition.rst
+++ b/source/Concepts/Intermediate/About-Composition.rst
@@ -1,8 +1,11 @@
-About Composition
-=================
+.. redirect-from::
+
+ Concepts/About-Composition
+
+Composition
+===========
.. contents:: Table of Contents
- :depth: 1
:local:
ROS 1 - Nodes vs. Nodelets
@@ -23,16 +26,13 @@ Having different APIs, which was the biggest drawback in ROS 1, is avoided in RO
It is still possible to use the node-like style of "writing your own main" but for the common case it is not recommended.
-
By making the process layout a deploy-time decision the user can choose between:
-
* running multiple nodes in separate processes with the benefits of process/fault isolation as well as easier debugging of individual nodes and
-* running multiple nodes in a single process with the lower overhead and optionally more efficient communication (see :doc:`Intra Process Communication <../Tutorials/Demos/Intra-Process-Communication>`).
+* running multiple nodes in a single process with the lower overhead and optionally more efficient communication (see :doc:`Intra Process Communication <../../Tutorials/Demos/Intra-Process-Communication>`).
Additionally ``ros2 launch`` can be used to automate these actions through specialized launch actions.
-
Writing a Component
-------------------
@@ -58,15 +58,12 @@ Additionally, once a component is created, it must be registered with the index
In order for the component_container to be able to find desired components, it must be executed or launched from a shell that has sourced the corresponding workspace.
-.. _composition-using-components:
-
Using Components
----------------
The `composition `__ package contains a couple of different approaches on how to use components.
The three most common ones are:
-
#. Start a (`generic container process `__) and call the ROS service `load_node `__ offered by the container.
The ROS service will then load the component specified by the passed package name and library name and start executing it within the running process.
Instead of calling the ROS service programmatically you can also use a `command line tool `__ to invoke the ROS service with the passed command line arguments
@@ -77,4 +74,4 @@ The three most common ones are:
Practical application
---------------------
-Try the :doc:`Composition demos <../Tutorials/Intermediate/Composition>`.
+Try the :doc:`Composition demos <../../Tutorials/Intermediate/Composition>`.
diff --git a/source/Concepts/About-Cross-Compilation.rst b/source/Concepts/Intermediate/About-Cross-Compilation.rst
similarity index 91%
rename from source/Concepts/About-Cross-Compilation.rst
rename to source/Concepts/Intermediate/About-Cross-Compilation.rst
index e93217d764c..4a5098ae50a 100644
--- a/source/Concepts/About-Cross-Compilation.rst
+++ b/source/Concepts/Intermediate/About-Cross-Compilation.rst
@@ -1,5 +1,12 @@
-About Cross-compilation
-=======================
+.. redirect-from::
+
+ Concepts/About-Cross-Compilation
+
+Cross-compilation
+=================
+
+.. contents:: Table of Contents
+ :local:
Overview
--------
@@ -27,4 +34,4 @@ It is a Python script that compiles ROS 2 source files for supported target arch
Detailed design of the tool can be found on `ROS 2 design `__.
Instructions to use the tool are in the `cross_compile package `__.
-If you are using an older version, please follow the :doc:`cross-compilation guide <../How-To-Guides/Cross-compilation>`.
+If you are using an older version, please follow the :doc:`cross-compilation guide <../../How-To-Guides/Cross-compilation>`.
diff --git a/source/Concepts/About-Different-Middleware-Vendors.rst b/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst
similarity index 90%
rename from source/Concepts/About-Different-Middleware-Vendors.rst
rename to source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst
index 4ada90c11ab..dc8d1d897dd 100644
--- a/source/Concepts/About-Different-Middleware-Vendors.rst
+++ b/source/Concepts/Intermediate/About-Different-Middleware-Vendors.rst
@@ -1,9 +1,13 @@
.. redirect-from::
DDS-and-ROS-middleware-implementations
+ Concepts/About-Different-Middleware-Vendors
-About different ROS 2 DDS/RTPS vendors
-======================================
+Different ROS 2 middleware vendors
+==================================
+
+.. contents:: Table of Contents
+ :local:
ROS 2 is built on top of DDS/RTPS as its middleware, which provides discovery, serialization and transportation.
`This article `__ explains the motivation behind using DDS implementations, and/or the RTPS wire protocol of DDS, in detail.
@@ -47,7 +51,7 @@ Supported RMW implementations
- ``rmw_gurumdds_cpp``
- 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.
+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.
Multiple RMW implementations
----------------------------
@@ -55,7 +59,7 @@ Multiple RMW implementations
The ROS 2 binary releases for currently active distros have built-in support for several RMW implementations out of the box (Fast DDS, RTI Connext Pro, Eclipse Cyclone DDS, GurumNetworks GurumDDS).
The default is Fast DDS, which works without any additional installation steps because we distribute it with our binary packages.
-Other RMWs like Cyclone DDS, Connext or GurumDDS can be enabled by :doc:`installing additional packages <../Installation/DDS-Implementations>`, but without having to rebuild anything or replace any existing packages.
+Other RMWs like Cyclone DDS, Connext or GurumDDS can be enabled by :doc:`installing additional packages <../../Installation/DDS-Implementations>`, but without having to rebuild anything or replace any existing packages.
A ROS 2 workspace that has been built from source may build and install multiple RMW implementations simultaneously.
While the core ROS 2 code is being compiled, any RMW implementation that is found will be built if the relevant DDS/RTPS implementation has been installed properly and the relevant environment variables have been configured.
@@ -78,4 +82,4 @@ The implementation identifier is the name of the ROS package that provides the R
For example, if both ``rmw_cyclonedds_cpp`` and ``rmw_connextdds`` ROS packages are installed, ``rmw_connextdds`` would be the default.
If ``rmw_fastrtps_cpp`` is ever installed, it would be the default.
-See the :doc:`guide <../How-To-Guides/Working-with-multiple-RMW-implementations>` for how to specify which RMW implementation is to be used when running the ROS 2 examples.
+See the :doc:`guide <../../How-To-Guides/Working-with-multiple-RMW-implementations>` for how to specify which RMW implementation is to be used when running the ROS 2 examples.
diff --git a/source/Concepts/About-Domain-ID.rst b/source/Concepts/Intermediate/About-Domain-ID.rst
similarity index 98%
rename from source/Concepts/About-Domain-ID.rst
rename to source/Concepts/Intermediate/About-Domain-ID.rst
index ab804b4785d..73ca15e4e5a 100644
--- a/source/Concepts/About-Domain-ID.rst
+++ b/source/Concepts/Intermediate/About-Domain-ID.rst
@@ -1,7 +1,13 @@
+.. redirect-from::
+
+ Concepts/About-Domain-ID
The ROS_DOMAIN_ID
=================
+.. contents:: Table of Contents
+ :local:
+
Overview
--------
diff --git a/source/Concepts/About-Executors.rst b/source/Concepts/Intermediate/About-Executors.rst
similarity index 96%
rename from source/Concepts/About-Executors.rst
rename to source/Concepts/Intermediate/About-Executors.rst
index 1c777bb7003..ec15e588dec 100644
--- a/source/Concepts/About-Executors.rst
+++ b/source/Concepts/Intermediate/About-Executors.rst
@@ -1,4 +1,6 @@
-.. _Executors:
+.. redirect-from::
+
+ Concepts/About-Executors
Executors
=========
@@ -9,7 +11,7 @@ Executors
Overview
--------
-Execution management in ROS 2 is explicated by the concept of Executors.
+Execution management in ROS 2 is handled by Executors.
An Executor uses one or more threads of the underlying operating system to invoke the callbacks of subscriptions, timers, service servers, action servers, etc. on incoming messages and events.
The explicit Executor class (in `executor.hpp `_ in rclcpp, in `executors.py `_ in rclpy, or in `executor.h `_ in rclc) provides more control over execution management than the spin mechanism in ROS 1, although the basic API is very similar.
@@ -53,7 +55,7 @@ In order not to counteract the QoS settings of the middleware, an incoming messa
A *wait set* is used to inform the Executor about available messages on the middleware layer, with one binary flag per queue.
The *wait set* is also used to detect when timers expire.
-.. image:: images/executors_basic_principle.png
+.. image:: ../images/executors_basic_principle.png
The Single-Threaded Executor is also used by the container process for :doc:`components <./About-Composition>`, i.e. in all cases where nodes are created and executed without an explicit main function.
@@ -92,7 +94,7 @@ All three executors can be used with multiple nodes by calling ``add_node(..)``
rclcpp::executors::StaticSingleThreadedExecutor executor;
executor.add_node(node1);
executor.add_node(node2);
- executor.add_node(node2);
+ executor.add_node(node3);
executor.spin();
In the above example, the one thread of a Static Single-Threaded Executor is used to serve three nodes together.
@@ -138,8 +140,8 @@ There are two types of callback groups, where the type has to be specified at in
* *Reentrant:* Callbacks of this group may be executed in parallel.
Callbacks of different callback groups may always be executed in parallel.
-The Multi-Threaded Executor uses its threads as a pool to process a many callbacks as possible in parallel according to these conditions.
-For tips on how to use callback groups efficiently, see :doc:`Using Callback Groups <../How-To-Guides/Using-callback-groups>`.
+The Multi-Threaded Executor uses its threads as a pool to process as many callbacks as possible in parallel according to these conditions.
+For tips on how to use callback groups efficiently, see :doc:`Using Callback Groups <../../How-To-Guides/Using-callback-groups>`.
The Executor base class in rclcpp also has the function ``add_callback_group(..)``, which allows distributing callback groups to different Executors.
By configuring the underlying threads using the operating system scheduler, specific callbacks can be prioritized over other callbacks.
@@ -156,7 +158,7 @@ In detail, it only reports whether there are any messages for a certain topic or
The Executor uses this information to process the messages (including services and actions) in a round-robin fashion - but not in FIFO order.
The following flow diagram visualizes this scheduling semantics.
-.. image:: images/executors_scheduling_semantics.png
+.. 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. `_)
diff --git a/source/Concepts/About-Logging.rst b/source/Concepts/Intermediate/About-Logging.rst
similarity index 98%
rename from source/Concepts/About-Logging.rst
rename to source/Concepts/Intermediate/About-Logging.rst
index 234fe50394b..f0bfc75bf6b 100644
--- a/source/Concepts/About-Logging.rst
+++ b/source/Concepts/Intermediate/About-Logging.rst
@@ -1,15 +1,14 @@
.. redirect-from::
Logging
+ Concepts/About-Logging
-About logging and logger configuration
-======================================
+Logging and logger configuration
+================================
.. contents:: Table of Contents
- :depth: 2
:local:
-
Overview
--------
@@ -127,7 +126,7 @@ Logging subsystem design
The image below shows the five main pieces to the logging subsystem and how they interact.
-.. figure:: images/ros2_logging_architecture.png
+.. figure:: ../images/ros2_logging_architecture.png
:alt: ROS 2 logging architecture
:width: 550px
:align: center
@@ -185,7 +184,7 @@ Logging usage
.. group-tab:: C++
* See the `rclcpp logging demo `_ for some simple examples.
- * See the :doc:`logging demo <../Tutorials/Demos/Logging-and-logger-configuration>` for example usage.
+ * See the :doc:`logging demo <../../Tutorials/Demos/Logging-and-logger-configuration>` for example usage.
* See the `rclcpp documentation `__ for an extensive list of functionality.
.. group-tab:: Python
diff --git a/source/Concepts/About-Quality-of-Service-Settings.rst b/source/Concepts/Intermediate/About-Quality-of-Service-Settings.rst
similarity index 83%
rename from source/Concepts/About-Quality-of-Service-Settings.rst
rename to source/Concepts/Intermediate/About-Quality-of-Service-Settings.rst
index b203bd3bf66..c74842bdf1f 100644
--- a/source/Concepts/About-Quality-of-Service-Settings.rst
+++ b/source/Concepts/Intermediate/About-Quality-of-Service-Settings.rst
@@ -1,19 +1,22 @@
.. redirect-from::
About-Quality-of-Service-Settings
+ Concepts/About-Quality-of-Service-Settings
-About Quality of Service settings
-=================================
+Quality of Service settings
+===========================
+.. contents:: Table of Contents
+ :local:
Overview
--------
ROS 2 offers a rich variety of Quality of Service (QoS) policies that allow you to tune communication between nodes.
With the right set of Quality of Service policies, ROS 2 can be as reliable as TCP or as best-effort as UDP, with many, many possible states in between.
-Unlike ROS 1, which primarily only supported TCP, ROS 2 benefits from the flexibility of the underlying DDS transport in environments with lossy wireless networks where a “best effort” policy would be more suitable, or in real-time computing systems where the right Quality of Service profile is needed to meet deadlines.
+Unlike ROS 1, which primarily only supported TCP, ROS 2 benefits from the flexibility of the underlying DDS transport in environments with lossy wireless networks where a "best effort" policy would be more suitable, or in real-time computing systems where the right Quality of Service profile is needed to meet deadlines.
-A set of QoS “policies” combine to form a QoS “profile”.
+A set of QoS "policies" combine to form a QoS "profile".
Given the complexity of choosing the correct QoS policies for a given scenario, ROS 2 provides a set of predefined QoS profiles for common use cases (e.g. sensor data).
At the same time, developers are given the flexibility to control specific policies of the QoS profiles.
@@ -33,7 +36,7 @@ The base QoS profile currently includes settings for the following policies:
* Depth
- * *Queue size*: only honored if the “history” policy was set to “keep last”.
+ * *Queue size*: only honored if the "history" policy was set to "keep last".
* Reliability
@@ -42,7 +45,7 @@ The base QoS profile currently includes settings for the following policies:
* Durability
- * *Transient local*: the publisher becomes responsible for persisting samples for “late-joining” subscriptions.
+ * *Transient local*: the publisher becomes responsible for persisting samples for "late-joining" subscriptions.
* *Volatile*: no attempt is made to persist samples.
* Deadline
@@ -55,25 +58,25 @@ The base QoS profile currently includes settings for the following policies:
* Liveliness
- * *Automatic*: the system will consider all of the node’s publishers to be alive for another “lease duration” when any one of its publishers has published a message.
- * *Manual by topic*: the system will consider the publisher to be alive for another “lease duration” if it manually asserts that it is still alive (via a call to the publisher API).
+ * *Automatic*: the system will consider all of the node’s publishers to be alive for another "lease duration" when any one of its publishers has published a message.
+ * *Manual by topic*: the system will consider the publisher to be alive for another "lease duration" if it manually asserts that it is still alive (via a call to the publisher API).
* Lease Duration
* *Duration*: the maximum period of time a publisher has to indicate that it is alive before the system considers it to have lost liveliness (losing liveliness could be an indication of a failure).
-For each of the policies that is not a duration, there is also the option of “system default”, which uses the default of the underlying middleware.
-For each of the policies that is a duration, there also exists a “default” option that means the duration is unspecified, which the underlying middleware will usually interpret as an infinitely long duration.
+For each of the policies that is not a duration, there is also the option of "system default", which uses the default of the underlying middleware.
+For each of the policies that is a duration, there also exists a "default" option that means the duration is unspecified, which the underlying middleware will usually interpret as an infinitely long duration.
Comparison to ROS 1
^^^^^^^^^^^^^^^^^^^
-The “history” and “depth” policies in ROS 2 combine to provide functionality akin to the queue size in ROS 1.
+The "history" and "depth" policies in ROS 2 combine to provide functionality akin to the queue size in ROS 1.
-The “reliability” policy in ROS 2 is akin to the use of either UDPROS (only in ``roscpp``) for “best effort”, or TCPROS (ROS 1 default) for “reliable”.
+The "reliability" policy in ROS 2 is akin to the use of either UDPROS (only in ``roscpp``) for "best effort", or TCPROS (ROS 1 default) for "reliable".
Note however that even the reliable policy in ROS 2 is implemented using UDP, which allows for multicasting if appropriate.
-The “durability” policy “transient local”, combined with any depth, provides functionality similar to that of “latching” publishers.
+The "durability" policy "transient local", combined with any depth, provides functionality similar to that of "latching" publishers.
The remaining policies in ROS 2 are not akin to anything that is available in ROS 1, meaning that ROS 2 is more featureful than ROS 1 in this respect.
It is possible that in the future, even more QoS policies will be available in ROS 2.
@@ -89,8 +92,8 @@ The currently defined QoS profiles are:
* Default QoS settings for publishers and subscriptions
In order to make the transition from ROS 1 to ROS 2 easier, exercising a similar network behavior is desirable.
- By default, publishers and subscriptions in ROS 2 have “keep last” for history with a queue size of 10, “reliable” for reliability, “volatile” for durability, and “system default” for liveliness.
- Deadline, lifespan, and lease durations are also all set to “default”.
+ By default, publishers and subscriptions in ROS 2 have "keep last" for history with a queue size of 10, "reliable" for reliability, "volatile" for durability, and "system default" for liveliness.
+ Deadline, lifespan, and lease durations are also all set to "default".
* Services
@@ -126,8 +129,8 @@ QoS compatibilities
QoS profiles may be configured for publishers and subscriptions independently.
A connection between a publisher and a subscription is only made if the pair has compatible QoS profiles.
-QoS profile compatibility is determined based on a “Request vs Offered” model.
-Subscriptions *request* a QoS profile that is the “minimum quality” that it is willing to accept, and publishers *offer* a QoS profile that is the “maximum quality” that it is able to provide.
+QoS profile compatibility is determined based on a "Request vs Offered" model.
+Subscriptions *request* a QoS profile that is the "minimum quality" that it is willing to accept, and publishers *offer* a QoS profile that is the "maximum quality" that it is able to provide.
Connections are only made if every policy of the requested QoS profile is not more stringent than that of the offered QoS profile.
Multiple subscriptions can be connected to a single publisher simultaneously even if their requested QoS profiles are different.
The compatibility between a publisher and a subscription is unaffected by the presence of other publishers and subscriptions.
@@ -163,18 +166,26 @@ The following tables show the compatibility of the different policy settings and
* - Publisher
- Subscription
- Compatible
+ - Result
* - Volatile
- Volatile
- Yes
+ - New messages only
* - Volatile
- Transient local
- No
+ - No communication
* - Transient local
- Volatile
- Yes
+ - New messages only
* - Transient local
- Transient local
- Yes
+ - New and old messages
+
+To achieve a "latched" topic that is visible to late subscribers,
+both the publisher and subscriber must agree to use 'Transient Local'.
*Compatibility of deadline QoS policies:*
diff --git a/source/Concepts/About-RQt.rst b/source/Concepts/Intermediate/About-RQt.rst
similarity index 91%
rename from source/Concepts/About-RQt.rst
rename to source/Concepts/Intermediate/About-RQt.rst
index eff1d29ffab..e6811457899 100644
--- a/source/Concepts/About-RQt.rst
+++ b/source/Concepts/Intermediate/About-RQt.rst
@@ -1,22 +1,20 @@
-.. _RQt_Overview_Usage:
-
.. redirect-from::
RQt-Overview-Usage
Tutorials/RQt-Overview-Usage
+ Concepts/About-RQt
Overview and usage of RQt
=========================
.. contents:: Table of Contents
- :depth: 2
:local:
Overview
--------
RQt is a graphical user interface framework that implements various tools and interfaces in the form of plugins.
-One can run all the existing GUI tools as dockable windows within RQt!
+One can run all the existing GUI tools as dockable windows within RQt.
The tools can still run in a traditional standalone method, but RQt makes it easier to manage all the various windows in a single screen layout.
You can run any RQt tools/plugins easily by:
@@ -56,7 +54,7 @@ Installing From Debian
Building From Source
^^^^^^^^^^^^^^^^^^^^
-See :doc:`Building RQt from Source <../How-To-Guides/RQt-Source-Install>`.
+See :doc:`Building RQt from Source <../../How-To-Guides/RQt-Source-Install>`.
RQt Components Structure
------------------------
@@ -74,7 +72,7 @@ Compared to building your own GUIs from scratch:
* Standardized common procedures for GUI (start-shutdown hook, restore previous states).
* Multiple widgets can be docked in a single window.
* Easily turn your existing Qt widgets into RQt plugins.
-* Expect support at `ROS Answers `__ (ROS community website for the questions).
+* Expect support at `Robotics Stack Exchange `__ (ROS community website for the questions).
From system architecture's perspective:
diff --git a/source/Concepts/About-Security.rst b/source/Concepts/Intermediate/About-Security.rst
similarity index 84%
rename from source/Concepts/About-Security.rst
rename to source/Concepts/Intermediate/About-Security.rst
index 71f0d17b89e..a52066c4a4e 100644
--- a/source/Concepts/About-Security.rst
+++ b/source/Concepts/Intermediate/About-Security.rst
@@ -1,15 +1,24 @@
-.. _ROS-2-Security:
+.. redirect-from::
-About ROS 2 Security
-====================
+ Concepts/About-Security
+
+ROS 2 Security
+==============
.. contents:: Table of Contents
:local:
-
Overview
--------
+ROS 2 includes the ability to secure communications among nodes within the ROS 2 computational graph.
+Similar to discovery, security happens through the underlying ROS 2 middleware (provided it has support for the corresponding security plugins).
+No additional software installation is needed to enable security; however, the middleware requires configuration files for each ROS graph participant.
+These files enable encryption and authentication, and define policies both for individual nodes and for the overall ROS graph.
+ROS 2 also adds a master "on/off" switch to control security behavior.
+
+ROS utilities can create the authoritative `trust anchor `_ for a ROS application, or an external certificate authority can be used.
+
Built-in ROS 2 security features enable control over communications throughout the ROS graph.
This not only allows for encrypting data in transit between ROS domain participants, but also enables authentication of participants sending data, ensures the integrity of data being sent, and enables domain-wide access controls.
@@ -82,4 +91,4 @@ These variables generally assist ROS in managing enclaves and locating the secur
Learn More
----------
-For more information and hands-on exercises enabling ROS 2 communications security, see the :doc:`../Tutorials/Advanced/Security/Introducing-ros2-security`.
+For more information and hands-on exercises enabling ROS 2 communications security, see the :doc:`../../Tutorials/Advanced/Security/Introducing-ros2-security`.
diff --git a/source/Concepts/About-Tf2.rst b/source/Concepts/Intermediate/About-Tf2.rst
similarity index 61%
rename from source/Concepts/About-Tf2.rst
rename to source/Concepts/Intermediate/About-Tf2.rst
index 9c7a182dbca..f43fceae6b4 100644
--- a/source/Concepts/About-Tf2.rst
+++ b/source/Concepts/Intermediate/About-Tf2.rst
@@ -1,10 +1,11 @@
-.. _AboutTf2:
+.. redirect-from::
-About tf2
-=========
+ Concepts/About-Tf2
+
+Tf2
+===
.. contents:: Table of Contents
- :depth: 2
:local:
Overview
@@ -13,7 +14,7 @@ Overview
tf2 is the transform library, which lets the user keep track of multiple coordinate frames over time.
tf2 maintains the relationship between coordinate frames in a tree structure buffered in time and lets the user transform points, vectors, etc. between any two coordinate frames at any desired point in time.
-.. image:: images/ros2_tf2_frames.png
+.. image:: ../images/ros2_tf2_frames.png
Properties of tf2
-----------------
@@ -32,31 +33,31 @@ tf2 can have every component in your distributed system build its own transform
Tutorials
---------
-We created a set of :doc:`tutorials <../Tutorials/Intermediate/Tf2/Tf2-Main>` that walks you through using tf2, step by step.
-You can get started on the :doc:`introduction to tf2 <../Tutorials/Intermediate/Tf2/Introduction-To-Tf2>` tutorial.
-For a complete list of all tf2 and tf2-related tutorials check out the :doc:`tutorials <../Tutorials/Intermediate/Tf2/Tf2-Main>` page.
+We created a set of :doc:`tutorials <../../Tutorials/Intermediate/Tf2/Tf2-Main>` that walks you through using tf2, step by step.
+You can get started on the :doc:`introduction to tf2 <../../Tutorials/Intermediate/Tf2/Introduction-To-Tf2>` tutorial.
+For a complete list of all tf2 and tf2-related tutorials check out the :doc:`tutorials <../../Tutorials/Intermediate/Tf2/Tf2-Main>` page.
There are essentially two main tasks that any user would use tf2 for, listening for transforms and broadcasting transforms.
If you want to use tf2 to transform between coordinate frames, your nodes will need to listen for transforms.
What you will do is receive and buffer all coordinate frames that are broadcasted in the system, and query for specific transforms between frames.
-Check out the "Writing a listener" tutorial :doc:`(Python) <../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Listener-Py>` :doc:`(C++) <../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Listener-Cpp>` to learn more.
+Check out the "Writing a listener" tutorial :doc:`(Python) <../../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Listener-Py>` :doc:`(C++) <../../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Listener-Cpp>` to learn more.
To extend the capabilities of a robot, you will need to start broadcasting transforms.
Broadcasting transforms means to send out the relative pose of coordinate frames to the rest of the system.
A system can have many broadcasters that each provide information about a different part of the robot.
-Check out the "Writing a broadcaster" tutorial :doc:`(Python) <../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Broadcaster-Py>` :doc:`(C++) <../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Broadcaster-Cpp>` to learn more.
+Check out the "Writing a broadcaster" tutorial :doc:`(Python) <../../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Broadcaster-Py>` :doc:`(C++) <../../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Broadcaster-Cpp>` to learn more.
In addition to that, tf2 can broadcast static transforms that do not change over time.
This mainly saves storage and lookup time, but also reduces the publishing overhead.
You should note that static transforms are published once and assumed to not change, so no history is stored.
-If you want to define static transforms in your tf2 tree, take a look at the "Writing a static broadcaster" :doc:`(Python) <../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Py>` :doc:`(C++) <../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Cpp>` tutorial.
+If you want to define static transforms in your tf2 tree, take a look at the "Writing a static broadcaster" :doc:`(Python) <../../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Py>` :doc:`(C++) <../../Tutorials/Intermediate/Tf2/Writing-A-Tf2-Static-Broadcaster-Cpp>` tutorial.
-You can also learn how to add fixed and dynamic frames to your tf2 tree in the "Adding a frame" :doc:`(Python) <../Tutorials/Intermediate/Tf2/Adding-A-Frame-Py>` :doc:`(C++) <../Tutorials/Intermediate/Tf2/Adding-A-Frame-Cpp>` tutorial.
+You can also learn how to add fixed and dynamic frames to your tf2 tree in the "Adding a frame" :doc:`(Python) <../../Tutorials/Intermediate/Tf2/Adding-A-Frame-Py>` :doc:`(C++) <../../Tutorials/Intermediate/Tf2/Adding-A-Frame-Cpp>` tutorial.
Once you are finished with the basic tutorials, you can move on to learn about tf2 and time.
-The tf2 and time tutorial :doc:`(Python) <../Tutorials/Intermediate/Tf2/Learning-About-Tf2-And-Time-Py>` :doc:`(C++) <../Tutorials/Intermediate/Tf2/Learning-About-Tf2-And-Time-Cpp>` teaches the basic principles of tf2 and time.
-The advanced tutorial about tf2 and time :doc:`(Python) <../Tutorials/Intermediate/Tf2/Time-Travel-With-Tf2-Py>` :doc:`(C++) <../Tutorials/Intermediate/Tf2/Time-Travel-With-Tf2-Cpp>` teaches the principles of time traveling with tf2.
+The tf2 and time tutorial :doc:`(Python) <../../Tutorials/Intermediate/Tf2/Learning-About-Tf2-And-Time-Py>` :doc:`(C++) <../../Tutorials/Intermediate/Tf2/Learning-About-Tf2-And-Time-Cpp>` teaches the basic principles of tf2 and time.
+The advanced tutorial about tf2 and time :doc:`(Python) <../../Tutorials/Intermediate/Tf2/Time-Travel-With-Tf2-Py>` :doc:`(C++) <../../Tutorials/Intermediate/Tf2/Time-Travel-With-Tf2-Cpp>` teaches the principles of time traveling with tf2.
Paper
-----
diff --git a/source/Concepts/About-Topic-Statistics.rst b/source/Concepts/Intermediate/About-Topic-Statistics.rst
similarity index 61%
rename from source/Concepts/About-Topic-Statistics.rst
rename to source/Concepts/Intermediate/About-Topic-Statistics.rst
index 1247870b19b..369a684cc02 100644
--- a/source/Concepts/About-Topic-Statistics.rst
+++ b/source/Concepts/Intermediate/About-Topic-Statistics.rst
@@ -1,11 +1,10 @@
-.. _AboutTopicStats:
-
.. redirect-from::
About-Topic-Statistics
+ Concepts/About-Topic-Statistics
-About topic statistics
-======================
+Topic statistics
+================
.. contents:: Table of Contents
:local:
@@ -13,29 +12,20 @@ About topic statistics
Overview
--------
-ROS 2 provides integrated measurement of statistics for messages received by any
-subscription.
-Allowing a user to collect subscription statistics enables them to characterize
-the performance of their system or aid in diagnosis of any present issues.
+ROS 2 provides integrated measurement of statistics for messages received by any subscription.
+Allowing a user to collect subscription statistics enables them to characterize the performance of their system or aid in diagnosis of any present issues.
The measurements provided are the received message age and received message period.
-For each measurement the statistics provided are the average, maximum, minimum,
-standard deviation, and sample count. These statistics are calculated in a moving window.
+For each measurement the statistics provided are the average, maximum, minimum, standard deviation, and sample count.
+These statistics are calculated in a moving window.
How statistics are calculated
-----------------------------
-Each statistic set is calculated in constant time and constant memory
-by using the utilities implemented in the
-`libstatistics_collector `__
-package.
-When a new message is received by a subscription, this is a new sample for calculation in
-the current measurement window.
-The average calculated is simply a
-`moving average `__.
-The maximum, minimum, and sample count are updated upon receipt of each new sample, whereas the
-standard deviation is calculated using `Welford's online algorithm
-`__.
+Each statistic set is calculated in constant time and constant memory by using the utilities implemented in the `libstatistics_collector `__ package.
+When a new message is received by a subscription, this is a new sample for calculation in the current measurement window.
+The average calculated is simply a `moving average `__.
+The maximum, minimum, and sample count are updated upon receipt of each new sample, whereas the standard deviation is calculated using `Welford's online algorithm `__.
Types of statistics calculated
------------------------------
@@ -54,28 +44,23 @@ Behavior
--------
By default, Topic Statistics measurements are not enabled.
-After enabling this feature for a specific node via the subscription configuration options, both
-received message age and received message period measurements are enabled for that specific subscription.
+After enabling this feature for a specific node via the subscription configuration options, both received message age and received message period measurements are enabled for that specific subscription.
The data is published as a `statistics_msg/msg/MetricsMessage
-`__
-at a configurable period (default 1 second) to a configurable topic (default ``/statistics``).
+`__ at a configurable period (default 1 second) to a configurable topic (default ``/statistics``).
Note that the publishing period also serves as the sample collection window period.
Since received message period requires a message timestamp in a header field, empty data is published.
That is, all statistics values are NaN if no timestamp is found.
-Publishing NaN values instead of not publishing at all avoids the absence of a signal problem and is
-meant to explicitly show that a measurement could not be made.
+Publishing NaN values instead of not publishing at all avoids the absence of a signal problem and is meant to explicitly show that a measurement could not be made.
The first sample of each window for the received message period statistic does not yield a measurement.
-This is because calculating this statistic requires knowing the time the previous
-message arrived, so subsequent samples in the window yield measurements.
+This is because calculating this statistic requires knowing the time the previous message arrived, so subsequent samples in the window yield measurements.
Comparison to ROS 1
-------------------
-Similar to ROS 1 `Topic Statistics `__, both message age
-and message period are calculated, albeit from the subscription side.
+Similar to ROS 1 `Topic Statistics `__, both message age and message period are calculated, albeit from the subscription side.
Other ROS 1 metrics, e.g., the number of dropped messages or traffic volume, are currently not provided.
Support
@@ -84,4 +69,3 @@ Support
This feature is currently supported in ROS 2 Foxy for C++ only (rclcpp).
Future work and improvements, such as Python support, can be found
`here `__.
-
diff --git a/source/Contact.rst b/source/Contact.rst
index 3ad0af1957e..d29b06208f6 100644
--- a/source/Contact.rst
+++ b/source/Contact.rst
@@ -3,7 +3,7 @@
Contact
=======
-.. _Using ROS Answers:
+.. _Using Robotics Stack Exchange:
Support
-------
@@ -12,10 +12,10 @@ Different types of questions or discussions correspond to different avenues of c
check the descriptions below to ensure you choose the right method.
Need help troubleshooting your system?
-First, search `ROS Answers `__ to see if others have had similar issues, and if their solution works for you.
+First, search `Robotics Stack Exchange `__ to see if others have had similar issues, and if their solution works for you.
-If not, ask a new question on `ROS Answers `__.
-Make sure to add tags, at the very least the ``ros2`` tag and the distro version you are running, e.g. ``humble``.
+If not, ask a new question on `Robotics Stack Exchange `__.
+Make sure to add tags, at the very least the ``ros2`` tag and the distro version you are running, e.g. ``{DISTRO}``.
If your question is related to the documentation here, add a tag like ``docs``, or more specifically, ``tutorials``.
Contributing support
@@ -24,7 +24,7 @@ Contributing support
ROS 2 users come from a wide range of technical backgrounds, use a variety of different operating systems, and don’t necessarily have any prior experience with ROS (1 or 2).
So, it's important for users with any amount of experience to contribute support.
-If you see an issue on `ROS Answers `__ that is similar to something you’ve run into yourself, please consider providing some pointers to what helped in your situation.
+If you see an issue on `Robotics Stack Exchange `__ that is similar to something you’ve run into yourself, please consider providing some pointers to what helped in your situation.
Don’t worry if you aren't sure if your response is correct.
Simply say so, and other community members will jump in if necessary.
@@ -40,7 +40,7 @@ You can search for individual ROS 2 repositories on `ROS 2's GitHub `__.
-Next, check `ROS Answers `__ to see if someone else has asked your question or reported your issue.
+Next, check `Robotics Stack Exchange `__ to see if someone else has asked your question or reported your issue.
If it has not been reported, feel free to open an issue in the appropriate repository tracker.
If it's not clear which tracker to use for a particular issue, file it in the `ros2/ros2 repository `__ and we'll have a look at it.
@@ -106,7 +106,7 @@ This also applies to crossposting.
Try to pick the forum which you think matches best and ask there.
If you are referred to a new forum, provide a link to the old discussion.
-On https://answers.ros.org you can edit your question to provide more details.
+On `Robotics Stack Exchange `__ you can edit your question to provide more details.
The more details that you include in your question the easier it is for others to help you find your solution which makes it more likely for you to get a response.
It's considered bad form to list your personal deadlines; community members answering questions also have them.
@@ -122,7 +122,7 @@ Content, links, and images unrelated to the topic are considered spam.
For commercial posts, see also `this discussion `_.
Minimize references to content behind pay walls.
-The content posted on `ROS Discourse `__ and `ROS Answers `__ should "generally" be free and open to all users.
+The content posted on `ROS Discourse `__ and `Robotics Stack Exchange `__ should "generally" be free and open to all users.
Links to content behind pay walls such as private journal articles, text books, and paid news websites, while helpful and relevant, may not be accessible to all users.
Where possible primary sources should be free and open with paid content playing a supporting role.
diff --git a/source/How-To-Guides.rst b/source/How-To-Guides.rst
index 06a50e78932..7bf01b03cb2 100644
--- a/source/How-To-Guides.rst
+++ b/source/How-To-Guides.rst
@@ -24,10 +24,9 @@ If you are new and looking to learn the ropes, start with the :doc:`Tutorials `__ will be very helpful, an official tutorial can be found `here `__.
+Before using ``ament_cmake``, it is very helpful to know the basics of `CMake `__.
+An official tutorial can be found `here `__.
.. contents:: Table of Contents
:depth: 2
@@ -18,8 +19,8 @@ Basics
------
A basic CMake outline can be produced using ``ros2 pkg create `` on the command line.
-The basic build information is then gathered in two files: the ``package.xml`` and the ``CMakeLists.txt``.
-The ``package.xml`` must contain all dependencies and a bit of metadata to allow colcon to find the correct build order for your packages, to install the required dependencies in CI as well as provide the information for a release with ``bloom``.
+The build information is then gathered in two files: the ``package.xml`` and the ``CMakeLists.txt``, which must be in the same directory.
+The ``package.xml`` must contain all dependencies and a bit of metadata to allow colcon to find the correct build order for your packages, to install the required dependencies in CI, and to provide the information for a release with ``bloom``.
The ``CMakeLists.txt`` contains the commands to build and package executables and libraries and will be the main focus of this document.
Basic project outline
@@ -29,23 +30,22 @@ The basic outline of the ``CMakeLists.txt`` of an ament package contains:
.. code-block:: cmake
- cmake_minimum_required(VERSION 3.5)
- project(my_project)
+ cmake_minimum_required(VERSION 3.8)
+ project(my_project)
- ament_package()
+ ament_package()
The argument to ``project`` will be the package name and must be identical to the package name in the ``package.xml``.
The project setup is done by ``ament_package()`` and this call must occur exactly once per package.
-``ament_package()`` installs the ``package.xml``, registers the package with the ament index, and installs config (and possibly target) files for CMake so that it can be found by other packages using ``find_package``.
+``ament_package()`` installs the ``package.xml``, registers the package with the ament index, and installs configuration (and possibly target) files for CMake so that it can be found by other packages using ``find_package``.
Since ``ament_package()`` gathers a lot of information from the ``CMakeLists.txt`` it should be the last call in your ``CMakeLists.txt``.
-Although it is possible to follow calls to ``ament_package()`` by calls to ``install`` functions copying files and directories, it is simpler to just keep ``ament_package()`` the last call.
``ament_package`` can be given additional arguments:
- ``CONFIG_EXTRAS``: a list of CMake files (``.cmake`` or ``.cmake.in`` templates expanded by ``configure_file()``) which should be available to clients of the package.
For an example of when to use these arguments, see the discussion in `Adding resources`_.
- For more information on how to use template files, see `the official documentation `__.
+ For more information on how to use template files, see `the official documentation `__.
- ``CONFIG_EXTRAS_POST``: same as ``CONFIG_EXTRAS``, but the order in which the files are added differs.
While ``CONFIG_EXTRAS`` files are included before the files generated for the ``ament_export_*`` calls the files from ``CONFIG_EXTRAS_POST`` are included afterwards.
@@ -61,203 +61,237 @@ The only difference is again the order in which the files are added with the fol
- files added by ``CONFIG_EXTRAS_POST``
-Adding files and headers
-^^^^^^^^^^^^^^^^^^^^^^^^
+Compiler and linker options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There are two main targets to build: libraries and executables which are built by ``add_library`` and ``add_executable`` respectively.
+ROS 2 targets compilers which comply with the C++17 and C99 standard.
+Newer versions might be targeted in the future and are referenced `here `__.
+Therefore it is customary to set the corresponding CMake flags:
-With the separation of header files and implementation in C/C++, it is not always necessary to add both files as argument to ``add_library``/ ``add_executable``.
+.. code-block:: cmake
-The following best practice is proposed:
+ if(NOT CMAKE_C_STANDARD)
+ set(CMAKE_C_STANDARD 99)
+ endif()
+ if(NOT CMAKE_CXX_STANDARD)
+ set(CMAKE_CXX_STANDARD 17)
+ endif()
+
+To keep the code clean, compilers should throw warnings for questionable code and these warnings should be fixed.
-- if you are building a library, put all headers which should be usable by clients and therefore must be installed into a subdirectory of the ``include`` folder named like the package, while all other files (``.c/.cpp`` and header files which should not be exported) are inside the ``src`` folder.
+It is recommended to at least cover the following warning levels:
+
+- For Visual Studio: the default ``W1`` warnings
-- only cpp files are explicitly referenced in the call to ``add_library`` or ``add_executable``
+- For GCC and Clang: ``-Wall -Wextra -Wpedantic`` are highly recommended and ``-Wshadow`` is advisable
-- allow to find headers via
+It is currently recommended to use ``add_compile_options`` to add these options for all targets.
+This avoids cluttering the code with target-based compile options for all executables, libraries, and tests:
.. code-block:: cmake
- target_include_directories(my_target
- PUBLIC
- $
- $)
+ if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+ add_compile_options(-Wall -Wextra -Wpedantic)
+ endif()
-This adds all files in the folder ``${CMAKE_CURRENT_SOURCE_DIR}/include`` to the public interface during build time and all files in the include folder (relative to ``${CMAKE_INSTALL_DIR}``) when being installed.
+Finding dependencies
+^^^^^^^^^^^^^^^^^^^^
-In principle, using generator expressions here is not necessary if both folders are called ``include`` and top-level with respect to ``${CMAKE_CURRENT_SOURCE_DIR}`` and ``${CMAKE_INSTALL_DIR}``, but it is very common.
+Most ``ament_cmake`` projects will have dependencies on other packages.
+In CMake, this is accomplished by calling ``find_package``.
+For instance, if your package depends on ``rclcpp``, then the ``CMakeLists.txt`` file should contain:
-Adding Dependencies
-^^^^^^^^^^^^^^^^^^^
+.. code-block:: cmake
-There are two ways to link your packages against a new dependency.
+ find_package(rclcpp REQUIRED)
-The first and recommended way is to use the ament macro ``ament_target_dependencies``.
-As an example, suppose we want to link ``my_target`` against the linear algebra library Eigen3.
+.. note::
-.. code-block:: cmake
+ It should never be necessary to ``find_package`` a library that is not explicitly needed but is a dependency of another dependency that is explicitly needed.
+ If that is the case, file a bug against the corresponding package.
- find_package(Eigen3 REQUIRED)
- ament_target_dependencies(my_target Eigen3)
+Adding targets
+^^^^^^^^^^^^^^
-It includes the necessary headers and libraries and their dependencies to be correctly found by the project.
-It will also ensure that the include directories of all dependencies are ordered correctly when using overlay workspaces.
+In CMake nomenclature, ``targets`` are the artifacts that this project will create.
+Either libraries or executables can be created, and a single project can contain zero or many of each of them.
-The second way is to use ``target_link_libraries``.
+.. tabs::
-The recommended way in modern CMake is to only use targets, exporting and linking against them.
-CMake targets are namespaced, similar to C++.
-For instance, ``Eigen3`` defines the target ``Eigen3::Eigen``.
+ .. group-tab:: Libraries
-At least until ``Crystal Clemmys`` target names are not supported in the ``ament_target_dependencies`` macro.
-Sometimes it will be necessary to call the ``target_link_libaries`` CMake function.
-In the example of Eigen3, the call should then look like
+ These are created with a call to ``add_library``, which should contain both the name of the target and the source files that should be compiled to create the library.
-.. code-block:: cmake
+ With the separation of header files and implementation in C/C++, it is not usually necessary to add header files as arguments to ``add_library``.
- find_package(Eigen3 REQUIRED)
- target_link_libraries(my_target Eigen3::Eigen)
+ The following best practice is proposed:
-This will also include necessary headers, libraries and their dependencies, but in contrast to ``ament_target_dependencies`` it might not correctly order the dependencies when using overlay workspaces.
+ - Put all headers which should be usable by clients of this library (and therefore must be installed) into a subdirectory of the ``include`` folder named like the package, while all other files (``.c/.cpp`` and header files which should not be exported) are inside the ``src`` folder
-.. note::
+ - Only ``.c/.cpp`` files are explicitly referenced in the call to ``add_library``
- It should never be necessary to ``find_package`` a library that is not explicitly needed but is a dependency of another dependency that is explicitly needed.
- If that is the case, file a bug against the corresponding package.
+ - Find headers to your library ``my_library`` via
-Building a Library
-^^^^^^^^^^^^^^^^^^
+ .. code-block:: cmake
-When building a reusable library, some information needs to be exported for downstream packages to easily use it.
+ target_include_directories(my_library
+ PUBLIC
+ "$"
+ "$")
-.. code-block:: cmake
+ This adds all files in the folder ``${CMAKE_CURRENT_SOURCE_DIR}/include`` to the public interface during build time and all files in the include folder (relative to ``${CMAKE_INSTALL_DIR}``) when being installed.
- ament_export_targets(my_libraryTargets HAS_LIBRARY_TARGET)
- ament_export_dependencies(some_dependency)
+ ``ros2 pkg create`` creates a package layout that follows these rules.
- install(
- DIRECTORY include/
- DESTINATION include
- )
+ .. note::
- install(
- TARGETS my_library
- EXPORT my_libraryTargets
- LIBRARY DESTINATION lib
- ARCHIVE DESTINATION lib
- RUNTIME DESTINATION bin
- INCLUDES DESTINATION include
- )
+ Since Windows is one of the officially supported platforms, to have maximum impact, any package should also build on Windows.
+ The Windows library format enforces symbol visibility; that is, every symbol which should be used from a client has to be explicitly exported by the library (and symbols need to be implicitly imported).
+ Since GCC and Clang builds do not generally do this, it is advised to use the logic in `the GCC wiki `__.
+ To use it for a package called ``my_library``:
-Here, we assume that the folder ``include`` contains the headers which need to be exported.
-Note that it is not necessary to put all headers into a separate folder, only those that should be included by clients.
+ - Copy the logic in the link into a header file called ``visibility_control.hpp``.
-Here is what's happening in the snippet above:
+ - Replace ``DLL`` by ``MY_LIBRARY`` (for an example, see visibility control of `rviz_rendering `__).
-- The ``ament_export_targets`` macro exports the targets for CMake.
- This is necessary to allow your library's clients to use the ``target_link_libraries(client my_library::my_library)`` syntax.
- ``ament_export_targets`` can take an arbitrary list of targets named as ``EXPORT`` in an install call and an additional option ``HAS_LIBRARY_TARGET``, which adds potential libraries to environment variables.
+ - Use the macros "MY_LIBRARY_PUBLIC" for all symbols you need to export (i.e. classes or functions).
-- The ``ament_export_dependencies`` exports dependencies to downstream packages.
- This is necessary so that the user of the library does not have to call ``find_package`` for those dependencies, too.
+ - In the project ``CMakeLists.txt`` use:
-- The first ``install`` commands installs the header files which should be available to clients.
+ .. code-block:: cmake
-.. warning::
+ target_compile_definitions(my_library PRIVATE "MY_LIBRARY_BUILDING_LIBRARY")
- Calling ``ament_export_targets``, ``ament_export_dependencies``, or other ament commands from a CMake subdirectory will not work as expected.
- This is because the CMake subdirectory has no way of setting necessary variables in the parent scope where ``ament_package`` is called.
+ For more details, see :ref:`Windows Symbol Visibility in the Windows Tips and Tricks document `.
-- The last large install command installs the library.
- Archive and library files will be exported to the lib folder, runtime binaries will be installed to the bin folder and the path to installed headers is ``include``.
+ .. group-tab:: Executables
-.. note::
+ These should be created with a call to ``add_executable``, which should contain both the name of the target and the source files that should be compiled to create the executable.
+ The executable may also have to be linked with any libraries created in this package by using ``target_link_libraries``.
- Windows DLLs are treated as runtime artifacts and installed into the ``RUNTIME DESTINATION`` folder.
- It is therefore advised to not leave out the ``RUNTIME`` install even when developing libraries on Unix based systems.
+ Since executables aren't generally used by clients as a library, no header files need to be put in the ``include`` directory.
-- Regarding the ``include directory``, the install command only adds information to CMake, it does not actually install the includes folder.
- This is done by copying the headers via ``install(DIRECTORY DESTINATION )`` as described above.
+In the case that a package has both libraries and executables, make sure to combine the advice from both "Libraries" and "Executables" above.
-- The ``EXPORT`` notation of the install call requires additional attention:
- It installs the CMake files for the ``my_library`` target.
- It is named exactly like the argument in ``ament_export_targets`` and could be named like the library.
- However, this will then prohibit using the ``ament_target_dependencies`` way of including your library.
- To allow for full flexibility, it is advised to prepend the export target with something like ``Targets``.
+Linking to dependencies
+^^^^^^^^^^^^^^^^^^^^^^^
-- All install paths are relative to ``CMAKE_INSTALL_PREFIX``, which is already set correctly by colcon/ament
+There are two ways to link your targets against a dependency.
-There are two additional functions which can be used but are superfluous for target based installs:
+The first and recommended way is to use the ament macro ``ament_target_dependencies``.
+As an example, suppose we want to link ``my_library`` against the linear algebra library Eigen3.
.. code-block:: cmake
- ament_export_include_directories(include)
- ament_export_libraries(my_library)
+ find_package(Eigen3 REQUIRED)
+ ament_target_dependencies(my_library PUBLIC Eigen3)
-The first macro marks the directory of the exported include directories (this is achieved by ``INCLUDES DESTINATION`` in the target ``install`` call).
-The second macro marks the location of the installed library (this is done by the ``HAS_LIBRARY_TARGET`` argument in the call to ``ament_export_targets``).
+It includes the necessary headers and libraries and their dependencies to be correctly found by the project.
-Some of the macros can take different types of arguments for non-target exports, but since the recommended way for modern Make is to use targets, we will not cover them here.
-Documentation of these options can be found in the source code itself.
+The second way is to use ``target_link_libraries``.
-Compiler and linker options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Modern CMake prefers to use only targets, exporting and linking against them.
+CMake targets may be namespaced, similar to C++.
+Prefer to use the namespaced targets if they are available.
+For instance, ``Eigen3`` defines the target ``Eigen3::Eigen``.
-ROS 2 targets compilers which comply with the C++14 and C99 standard until at least ``Crystal Clemmys``.
-Newer versions might be targeted in the future and are referenced `here `__.
-Therefore it is customary to set the corresponding CMake flags:
+In the example of Eigen3, the call should then look like
.. code-block:: cmake
- if(NOT CMAKE_C_STANDARD)
- set(CMAKE_C_STANDARD 99)
- endif()
- if(NOT CMAKE_CXX_STANDARD)
- set(CMAKE_CXX_STANDARD 14)
- endif()
+ target_link_libraries(my_library PUBLIC Eigen3::Eigen)
-To keep the code clean, compilers should throw warnings for questionable code and these warnings should be fixed.
+This will also include necessary headers, libraries and their dependencies.
+Note that this dependency must have been previously discovered via a call to ``find_package``.
-It is recommended to at least cover the following warning levels:
+Installing
+^^^^^^^^^^
-- For Visual Studio, the default ``W1`` warnings are kept
+.. tabs::
-- For GCC and Clang: ``-Wall -Wextra -Wpedantic`` are required and ``-Wshadow -Werror`` are advisable (the latter makes warnings errors).
+ .. group-tab:: Libraries
-Although modern CMake advises to add compiler flags on a target basis, i.e. call
+ When building a reusable library, some information needs to be exported for downstream packages to easily use it.
-.. code-block:: cmake
+ First, install the headers files which should be available to clients.
+ The include directory is custom to support overlays in ``colcon``; see https://colcon.readthedocs.io/en/released/user/overriding-packages.html#install-headers-to-a-unique-include-directory for more information.
- target_compile_options(my_target PRIVATE -Wall)
+ .. code-block:: cmake
-it is at the moment recommended to use the directory level function ``add_compile_options(-Wall)`` to not clutter the code with target-based compile options for all executables and tests.
+ install(
+ DIRECTORY include/
+ DESTINATION include/${PROJECT_NAME}
+ )
-Building libraries on Windows
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ Next, install the targets and create the export target (``export_${PROJECT_NAME}``) that other code will use to find this package.
+ Note that you can use a single ``install`` call to install all of the libraries in the project.
-Since Linux, Mac and Windows are all officially supported platforms, to have maximum impact any package should also build on Windows.
-The Windows library format enforces symbol visibility:
-Every symbol which should be used from a client has to be explicitly exported by the library (and data symbols need to be implicitly imported).
+ .. code-block:: cmake
-To keep this compatible with Clang and GCC builds, it is advised to use the logic in `the GCC wiki `__.
-To use it for a package called ``my_library``:
+ install(
+ TARGETS my_library
+ EXPORT export_${PROJECT_NAME}
+ LIBRARY DESTINATION lib
+ ARCHIVE DESTINATION lib
+ RUNTIME DESTINATION bin
+ )
-- Copy the logic in the link into a header file called ``visibility_control.hpp``.
+ ament_export_targets(export_${PROJECT_NAME} HAS_LIBRARY_TARGET)
+ ament_export_dependencies(some_dependency)
-- Replace ``DLL`` by ``MY_LIBRARY`` (for an example, see visibility control of `rviz_rendering `__).
+ Here is what's happening in the snippet above:
-- Use the macros "MY_LIBRARY_PUBLIC" for all symbols you need to export (i.e. classes or functions).
+ - The ``ament_export_targets`` macro exports the targets for CMake.
+ This is necessary to allow your library's clients to use the ``target_link_libraries(client PRIVATE my_library::my_library)`` syntax.
+ If the export set includes a library, add the option ``HAS_LIBRARY_TARGET`` to ``ament_export_targets``, which adds potential libraries to environment variables.
-- In the project ``CMakeLists.txt`` use:
+ - The ``ament_export_dependencies`` exports dependencies to downstream packages.
+ This is necessary so that the user of the library does not have to call ``find_package`` for those dependencies, too.
-.. code-block:: cmake
+ .. warning::
+
+ Calling ``ament_export_targets``, ``ament_export_dependencies``, or other ament commands from a CMake subdirectory will not work as expected.
+ This is because the CMake subdirectory has no way of setting necessary variables in the parent scope where ``ament_package`` is called.
+
+ .. note::
+
+ Windows DLLs are treated as runtime artifacts and installed into the ``RUNTIME DESTINATION`` folder.
+ It is therefore advised to keep the ``RUNTIME`` install even when developing libraries on Unix based systems.
+
+ - The ``EXPORT`` notation of the install call requires additional attention:
+ It installs the CMake files for the ``my_library`` target.
+ It must be named exactly the same as the argument in ``ament_export_targets``.
+ To ensure that it can be used via ``ament_target_dependencies``, it should not be named exactly the same as the library name, but instead should have a prefix like ``export_`` (as shown above).
+
+ - All install paths are relative to ``CMAKE_INSTALL_PREFIX``, which is already set correctly by colcon/ament.
+
+ There are two additional functions which are available, but are superfluous for target based installs:
+
+ .. code-block:: cmake
+
+ ament_export_include_directories("include/${PROJECT_NAME}")
+ ament_export_libraries(my_library)
+
+ The first macro marks the directory of the exported include directories.
+ The second macro marks the location of the installed library (this is done by the ``HAS_LIBRARY_TARGET`` argument in the call to ``ament_export_targets``).
+ These should only be used if the downstream projects can't or don't want to use CMake target based dependencies.
+
+ Some of the macros can take different types of arguments for non-target exports, but since the recommended way for modern Make is to use targets, we will not cover them here.
+ Documentation of these options can be found in the source code itself.
+
+ .. group-tab:: Executables
+
+ When installing an executable, the following stanza *must be followed exactly* for the rest of the ROS tooling to find it:
+
+ .. code-block:: cmake
- target_compile_definitions(my_library PRIVATE "MY_LIBRARY_BUILDING_LIBRARY")
+ install(TARGETS my_exe
+ DESTINATION lib/${PROJECT_NAME})
-For more details, see :ref:`Windows Symbol Visibility in the Windows Tips and Tricks document `.
+In the case that a package has both libraries and executables, make sure to combine the advice from both "Libraries" and "Executables" above.
-Testing and Linting
+Linting and Testing
-------------------
In order to separate testing from building the library with colcon, wrap all calls to linters and tests in a conditional:
@@ -401,7 +435,7 @@ This extension point is useful when registering resources (see below).
.. note::
- It is possible to define custom extension points in a similar manner to ``ament_package`` and ``rosidl_generate_interfaces``, but this should hardly be necessary.
+ It is possible to define custom extension points in a similar manner to ``ament_package`` and ``rosidl_generate_interfaces``, but this should hardly be necessary.
Adding extension points
^^^^^^^^^^^^^^^^^^^^^^^
@@ -417,7 +451,7 @@ To do so:
.. code-block:: cmake
- ament_execute_extensions(my_extension_point)
+ ament_execute_extensions(my_extension_point)
Ament extensions work by defining a variable containing the name of the extension point and filling it with the macros to be executed.
Upon calling ``ament_execute_extensions``, the scripts defined in the variable are then executed one after another.
@@ -475,7 +509,7 @@ Querying the ament index
If necessary, it is possible to query the ament index for resources via CMake.
To do so, there are three functions:
-``ament_index_has_resource``: obtain a prefix path to the resource if it exists with the following parameters:
+``ament_index_has_resource``: Obtain a prefix path to the resource if it exists with the following parameters:
- ``var``: the output parameter: fill this variable with FALSE if the resource does not exist or the prefix path to the resource otherwise
diff --git a/source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst b/source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst
new file mode 100644
index 00000000000..6c14ce703a8
--- /dev/null
+++ b/source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst
@@ -0,0 +1,106 @@
+.. redirect-from::
+
+ How-To-Guides/Disabling-ZeroCopy-loaned-messages
+
+Configure Zero Copy Loaned Messages
+===================================
+
+.. contents:: Contents
+ :depth: 1
+ :local:
+
+See the `Loaned Messages `__ article for details on how loaned messages work.
+
+How to disable Loaned Messages
+------------------------------
+
+Publishers
+~~~~~~~~~~
+
+By default, *Loaned Messages* will try to borrow the memory from underlying middleware if it supports *Loaned Messages*.
+The ``ROS_DISABLE_LOANED_MESSAGES`` environment variable can be used to disable *Loaned Messages*, and fallback to normal publisher behavior, without any code changes or middleware configuration.
+You can set the environment variable with the following command:
+
+.. tabs::
+
+ .. group-tab:: Linux
+
+ .. code-block:: console
+
+ export ROS_DISABLE_LOANED_MESSAGES=1
+
+ To maintain this setting between shell sessions, you can add the command to your shell startup script:
+
+ .. code-block:: console
+
+ echo "export ROS_DISABLE_LOANED_MESSAGES=1" >> ~/.bashrc
+
+ .. group-tab:: macOS
+
+ .. code-block:: console
+
+ export ROS_DISABLE_LOANED_MESSAGES=1
+
+ To maintain this setting between shell sessions, you can add the command to your shell startup script:
+
+ .. code-block:: console
+
+ echo "export ROS_DISABLE_LOANED_MESSAGES=1" >> ~/.bash_profile
+
+ .. group-tab:: Windows
+
+ .. code-block:: console
+
+ set ROS_DISABLE_LOANED_MESSAGES=1
+
+ If you want to make this permanent between shell sessions, also run:
+
+ .. code-block:: console
+
+ setx ROS_DISABLE_LOANED_MESSAGES 1
+
+
+Subscriptions
+~~~~~~~~~~~~~
+
+Currently using *Loaned Messages* is not safe on subscription, see more details in `this issue `_.
+Because of this, by default *Loaned Messages* is ``disabled`` on subscription with `Set disable loan to on by default `_ even though underlying middleware supports that.
+To enable *Loaned Messages* on subscription, you need to set the environment variable ``ROS_DISABLE_LOANED_MESSAGES`` to ``0`` explicitly.
+
+.. tabs::
+
+ .. group-tab:: Linux
+
+ .. code-block:: console
+
+ export ROS_DISABLE_LOANED_MESSAGES=0
+
+ To maintain this setting between shell sessions, you can add the command to your shell startup script:
+
+ .. code-block:: console
+
+ echo "export ROS_DISABLE_LOANED_MESSAGES=0" >> ~/.bashrc
+
+ .. group-tab:: macOS
+
+ .. code-block:: console
+
+ export ROS_DISABLE_LOANED_MESSAGES=0
+
+ To maintain this setting between shell sessions, you can add the command to your shell startup script:
+
+ .. code-block:: console
+
+ echo "export ROS_DISABLE_LOANED_MESSAGES=0" >> ~/.bash_profile
+
+ .. group-tab:: Windows
+
+ .. code-block:: console
+
+ set ROS_DISABLE_LOANED_MESSAGES=0
+
+ If you want to make this permanent between shell sessions, also run:
+
+ .. code-block:: console
+
+ setx ROS_DISABLE_LOANED_MESSAGES 0
diff --git a/source/How-To-Guides/Cross-compilation.rst b/source/How-To-Guides/Cross-compilation.rst
index 1704fe5a9c2..ca68f7ea6f1 100644
--- a/source/How-To-Guides/Cross-compilation.rst
+++ b/source/How-To-Guides/Cross-compilation.rst
@@ -10,7 +10,7 @@ Cross-compilation
:depth: 2
:local:
-For background information on cross-compilation, see the :doc:`conceptual article <../Concepts/About-Cross-Compilation>`.
+For background information on cross-compilation, see the :doc:`conceptual article <../Concepts/Intermediate/About-Cross-Compilation>`.
This document provides you with details on how to cross-compile the ROS 2 software stack as well as provide examples for cross-compiling to systems based on the Arm cores.
diff --git a/source/How-To-Guides/DDS-tuning.rst b/source/How-To-Guides/DDS-tuning.rst
index c99f69ec88d..79014a6b238 100644
--- a/source/How-To-Guides/DDS-tuning.rst
+++ b/source/How-To-Guides/DDS-tuning.rst
@@ -129,7 +129,7 @@ Next, to set the minimum socket receive buffer size that Cyclone requests, write
https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
- 10MB
+
diff --git a/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst b/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst
deleted file mode 100644
index f76bea70b79..00000000000
--- a/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-.. _ZeroCopyLoanedMessages:
-
-Disabling Zero Copy Loaned Messages
-===================================
-
-.. contents:: Contents
- :depth: 1
- :local:
-
-See the `Loaned Messages `__ article for details on how loaned messages work.
-
-How to disable Loaned Messages
-------------------------------
-
-By default, *Loaned Messages* will try to borrow the memory from underlying middleware if it supports *Loaned Messages*.
-The ``ROS_DISABLE_LOANED_MESSAGES`` environment variable can be used to disable *Loaned Messages*, and fallback to normal publisher and subscription behavior, without any code changes or middleware configuration.
-You can set the environment variable with the following command:
-
-.. tabs::
-
- .. group-tab:: Linux
-
- .. code-block:: console
-
- export ROS_DISABLE_LOANED_MESSAGES=1
-
- To maintain this setting between shell sessions, you can add the command to your shell startup script:
-
- .. code-block:: console
-
- echo "export ROS_DISABLE_LOANED_MESSAGES=1" >> ~/.bashrc
-
- .. group-tab:: macOS
-
- .. code-block:: console
-
- export ROS_DISABLE_LOANED_MESSAGES=1
-
- To maintain this setting between shell sessions, you can add the command to your shell startup script:
-
- .. code-block:: console
-
- echo "export ROS_DISABLE_LOANED_MESSAGES=1" >> ~/.bash_profile
-
- .. group-tab:: Windows
-
- .. code-block:: console
-
- set ROS_DISABLE_LOANED_MESSAGES=1
-
- If you want to make this permanent between shell sessions, also run:
-
- .. code-block:: console
-
- setx ROS_DISABLE_LOANED_MESSAGES 1
diff --git a/source/How-To-Guides/Installation-Troubleshooting.rst b/source/How-To-Guides/Installation-Troubleshooting.rst
index 6109bd0aa89..21015d7607e 100644
--- a/source/How-To-Guides/Installation-Troubleshooting.rst
+++ b/source/How-To-Guides/Installation-Troubleshooting.rst
@@ -103,6 +103,13 @@ If you encounter exceptions when trying to source the environment after building
colcon version-check # check if newer versions available
sudo apt install python3-colcon* --only-upgrade # upgrade installed colcon packages to latest version
+Anaconda Python Conflict
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``conda`` does not work in conjunction with ROS 2.
+Make sure that your ``PATH`` environment variable does not have any conda paths in it.
+You may have to check your ``.bashrc`` for this line and comment it out.
+
.. _macOS-troubleshooting:
macOS
@@ -322,8 +329,41 @@ Fast RTPS requires ``msvcr20.dll``, which is part of the ``Visual C++ Redistribu
Although it is usually installed by default in Windows 10, we know that some Windows 10-like versions don't have it installed by default (e.g.: Windows Server 2019).
In case you don't have it installed, you can download it from `here `_.
+Failed to create process
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If running a ROS binary gives the error:
+
+.. code-block::
+
+ | failed to create process.
+
+It is likely the Python interpreter was not found.
+For each executable, the shebang (first line) of the accompanying script is used, so make sure Python is available under the expected path (default: ``C:\Python38\``).
+
Binary installation specific
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* If your example does not start because of missing DLLs, please verify that all libraries from external dependencies such as OpenCV are located inside your ``PATH`` variable.
* If you forget to call the ``local_setup.bat`` file from your terminal, the demo programs will most likely crash immediately.
+
+Running RViz with WSL2
+^^^^^^^^^^^^^^^^^^^^^^
+
+If you are using `WSL2 `__ to run ROS 2 on Windows, you may run into an issue running RViz that looks like:
+
+.. code-block:: console
+
+ $ rviz2
+ [INFO] [1695823660.091830699] [rviz2]: Stereo is NOT SUPPORTED
+ [INFO] [1695823660.091943524] [rviz2]: OpenGl version: 4.1 (GLSL 4.1)
+ D3D12: Removing Device.
+ Segmentation fault
+
+One possible solution to this is to force RViz to use software rendering:
+
+.. code-block:: console
+
+ $ export LIBGL_ALWAYS_SOFTWARE=true
+ $ rviz2
+ [INFO] [1695823660.091830699] [rviz2]: Stereo is NOT SUPPORTED
diff --git a/source/How-To-Guides/Launch-file-different-formats.rst b/source/How-To-Guides/Launch-file-different-formats.rst
index 0939d72d179..4cbb7776a19 100644
--- a/source/How-To-Guides/Launch-file-different-formats.rst
+++ b/source/How-To-Guides/Launch-file-different-formats.rst
@@ -366,7 +366,7 @@ Python, XML, or YAML: Which should I use?
.. note::
Launch files in ROS 1 were written in XML, so XML may be the most familiar to people coming from ROS 1.
- To see what's changed, you can visit :doc:`Launch-files-migration-guide`.
+ To see what's changed, you can visit :doc:`Migrating-from-ROS1/Migrating-Launch-Files`.
For most applications the choice of which ROS 2 launch format comes down to developer preference.
However, if your launch file requires flexibility that you cannot achieve with XML or YAML, you can use Python to write your launch file.
diff --git a/source/How-To-Guides/Migrating-from-ROS1.rst b/source/How-To-Guides/Migrating-from-ROS1.rst
new file mode 100644
index 00000000000..18d6756ac97
--- /dev/null
+++ b/source/How-To-Guides/Migrating-from-ROS1.rst
@@ -0,0 +1,26 @@
+Migrating from ROS 1 to ROS 2
+=============================
+
+These guides show how to convert existing ROS 1 packages to ROS 2.
+If you are new to porting between ROS 1 and ROS 2, it is recommended to read through the guides in order.
+
+.. toctree::
+ :maxdepth: 1
+
+ Migrating-from-ROS1/Migrating-Packages
+ Migrating-from-ROS1/Migrating-Interfaces
+ Migrating-from-ROS1/Migrating-CPP-Packages
+ Migrating-from-ROS1/Migrating-Python-Packages
+ Migrating-from-ROS1/Migrating-Launch-Files
+ Migrating-from-ROS1/Migrating-Parameters
+ Migrating-from-ROS1/Migrating-Scripts
+
+Automatic tools
+---------------
+
+There are also some automatic conversion tools that exist, though they are not exhaustive:
+
+* `Magical ROS 2 Conversion Tool `_
+* Launch File migrator that converts a ROS 1 XML launch file to a ROS 2 Python launch file: https://github.com/aws-robotics/ros2-launch-file-migrator
+* Amazon has made their tools for porting from ROS 1 to ROS 2 available at: https://github.com/awslabs/ros2-migration-tools/tree/master/porting\_tools
+* `rospy2 `_ Python project to automatically convert rospy calls to rclpy calls
diff --git a/source/The-ROS2-Project/Contributing/Migration-Guide.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-CPP-Packages.rst
similarity index 65%
rename from source/The-ROS2-Project/Contributing/Migration-Guide.rst
rename to source/How-To-Guides/Migrating-from-ROS1/Migrating-CPP-Packages.rst
index 77af629653d..ef3083e9e62 100644
--- a/source/The-ROS2-Project/Contributing/Migration-Guide.rst
+++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-CPP-Packages.rst
@@ -1,124 +1,30 @@
.. redirect-from::
- Migration-Guide
- Contributing/Migration-Guide
+ Migration-Guide
+ Contributing/Migration-Guide
+ The-ROS2-Project/Contributing/Migration-Guide
-Migration guide from ROS 1
-==========================
+Migrating C++ Packages
+======================
.. contents:: Table of Contents
:depth: 2
:local:
-There are two different kinds of package migrations:
-
-* Migrating the source code of an existing package from ROS 1 to ROS 2 with the intent that a significant part of the source code will stay the same or at least similar.
- An example for this could be `pluginlib `_ where the source code is maintained in different branches within the same repository and commonly patches can be ported between those branches when necessary.
-* Implementing the same or similar functionality of a ROS 1 package for ROS 2 but with the assumption that the source code will be significantly different.
- An example for this could be `roscpp `_ in ROS 1 and `rclcpp `_ in ROS 2 which are separate repositories and don't share any code.
-
-This article focuses on the former case and describes the high-level steps to migrate a ROS 1 package to ROS 2.
-It does not aim to be a step-by-step migration instruction and is not considered the *final* "solution".
-Future versions will aim to make migration smoother and less effort up to the point of maintaining a single package from the same branch for ROS 1 as well as ROS 2.
-
-Prerequisites
--------------
-
-Before being able to migrate a ROS 1 package to ROS 2 all of its dependencies must be available in ROS 2.
-
-Migration steps
----------------
-
-.. contents::
- :depth: 1
- :local:
-
-Package manifests
-^^^^^^^^^^^^^^^^^
-
-ROS 2 doesn't support format 1 of the package specification but only newer format versions (2 and higher).
-Therefore the ``package.xml`` file must be updated to at least format 2 if it uses format 1.
-Since ROS 1 supports all formats it is safe to perform that conversion in the ROS 1 package.
-
-Some packages might have different names in ROS 2 so the dependencies might need to be updated accordingly.
-
-Metapackages
-^^^^^^^^^^^^
-
-ROS 2 doesn't have a special package type for metapackages.
-Metapackages can still exist as regular packages that only contain runtime dependencies.
-When migrating metapackages from ROS 1, simply remove the ```` tag in your package manifest.
-
-Message, service, and action definitions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Message files must end in ``.msg`` and must be located in the subfolder ``msg``.
-Service files must end in ``.srv`` and must be located in the subfolder ``srv``.
-Actions files must end in ``.action`` and must be located in the subfolder ``action``.
-
-These files might need to be updated to comply with the `ROS Interface definition `__.
-Some primitive types have been removed and the types ``duration`` and ``time`` which were builtin types in ROS 1 have been replaced with normal message definitions and must be used from the `builtin_interfaces `__ package.
-Also some naming conventions are stricter than in ROS 1.
-
-In your ``package.xml``:
-
-
-* Add ``rosidl_default_generators``.
-* Add ``rosidl_default_runtime``.
-* For each dependent message package, add ``message_package``.
-
-In your ``CMakeLists.txt``:
-
-* Start by enabling C++14
-
-.. code-block:: cmake
-
- set(CMAKE_CXX_STANDARD 14)
-
-
-* Add ``find_package(rosidl_default_generators REQUIRED)``
-* For each dependent message package, add ``find_package(message_package REQUIRED)`` and replace the CMake function call to ``generate_messages`` with ``rosidl_generate_interfaces``.
-
-This will replace ``add_message_files`` and ``add_service_files`` listing of all the message and service files, which can be removed.
-
-Build system
-^^^^^^^^^^^^
-
-The build system in ROS 2 is called `ament `__
-and the build tool is :doc:`colcon <../../Tutorials/Beginner-Client-Libraries/Colcon-Tutorial>`.
-Ament is built on CMake: ``ament_cmake`` provides CMake functions to make writing ``CMakeLists.txt`` files easier.
-
Build tool
-~~~~~~~~~~
+----------
Instead of using ``catkin_make``, ``catkin_make_isolated`` or ``catkin build`` ROS 2 uses the command line tool `colcon `__ to build and install a set of packages.
+See the :doc:`beginner tutorial <../../Tutorials/Beginner-Client-Libraries/Colcon-Tutorial>` to get started with ``colcon``.
-Pure Python package
-~~~~~~~~~~~~~~~~~~~
-
-If the ROS 1 package uses CMake only to invoke the ``setup.py`` file and does not contain anything beside Python code (e.g. also no messages, services, etc.) it should be converted into a pure Python package in ROS 2:
-
-
-*
- Update or add the build type in the ``package.xml`` file:
-
- .. code-block:: xml
-
-
- ament_python
-
-
-*
- Remove the ``CMakeLists.txt`` file
-
-*
- Update the ``setup.py`` file to be a standard Python setup script
+Build system
+------------
-ROS 2 supports Python 3 only.
-While each package can choose to also support Python 2 it must invoke executables with Python 3 if it uses any API provided by other ROS 2 packages.
+The build system in ROS 2 is called `ament `__.
+Ament is built on CMake: ``ament_cmake`` provides CMake functions to make writing ``CMakeLists.txt`` files easier.
Update the *CMakeLists.txt* to use *ament_cmake*
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Apply the following changes to use ``ament_cmake`` instead of ``catkin``:
@@ -157,9 +63,6 @@ Apply the following changes to use ``ament_cmake`` instead of ``catkin``:
* Instead of passing ``INCLUDE_DIRS ...`` call ``ament_export_include_directories(...)`` before.
* Instead of passing ``LIBRARIES ...`` call ``ament_export_libraries(...)`` before.
- *
- **TODO document ament_export_targets (``ament_export_interfaces`` in Eloquent and older)?**
-
*
Replace the invocation of ``add_message_files``, ``add_service_files`` and ``generate_messages`` with `rosidl_generate_interfaces `__.
@@ -201,7 +104,7 @@ Apply the following changes to use ``ament_cmake`` instead of ``catkin``:
* ``CATKIN_PACKAGE_SHARE_DESTINATION``: ``share/${PROJECT_NAME}``
Unit tests
-~~~~~~~~~~
+^^^^^^^^^^
If you are using gtest:
@@ -237,12 +140,12 @@ Add ``ament_cmake_gtest`` to your ``package.xml``.
+ ament_cmake_gtest
Linters
-~~~~~~~
+^^^^^^^
In ROS 2 we are working to maintain clean code using linters.
-The styles for different languages are defined in our `Developer Guide `.
+The styles for different languages are defined in our :doc:`Developer Guide <../../The-ROS2-Project/Contributing/Developer-Guide>`.
-If you are starting a project from scratch it is recommended to follow the style guide and turn on the automatic linter unit tests by adding these lines just below ``if(BUILD_TESTING)`` (until alpha 5 this was ``AMENT_ENABLE_TESTING``).
+If you are starting a project from scratch it is recommended to follow the style guide and turn on the automatic linter unit tests by adding these lines just below ``if(BUILD_TESTING)``:
.. code-block:: cmake
@@ -256,20 +159,11 @@ You will also need to add the following dependencies to your ``package.xml``:
ament_lint_auto
ament_lint_common
-Continue to use ``catkin`` in CMake
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-ROS 2 uses ament as the build system but for backward compatibility ROS 2 has a package called ``catkin`` which provides almost the same API as catkin in ROS 1.
-In order to use this backward compatibility API the ``CMakeLists.txt`` must only be updated to call the function ``catkin_ament_package()`` *after* all targets.
-
-**NOTE: This has not been implemented yet and is only an idea at the moment.
-Due to the number of changes related to dependencies it has not yet been decided if this compatibility API is useful enough to justify the effort.**
-
Update source code
-^^^^^^^^^^^^^^^^^^
+------------------
Messages, services, and actions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The namespace of ROS 2 messages, services, and actions use a subnamespace (``msg``, ``srv``, or ``action``, respectively) after the package name.
Therefore an include looks like: ``#include ``.
@@ -298,7 +192,7 @@ The migration requires includes to change by:
The migration requires code to insert the ``msg`` namespace into all instances.
Use of service objects
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
Service callbacks in ROS 2 do not have boolean return values.
Instead of returning false on failures, throwing exceptions is recommended.
@@ -321,7 +215,7 @@ Instead of returning false on failures, throwing exceptions is recommended.
}
Usages of ros::Time
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
For usages of ``ros::Time``:
@@ -336,29 +230,19 @@ For usages of ``ros::Time``:
* Convert all instances using the std_msgs::Time field ``nsec`` to the builtin_interfaces::msg::Time field ``nanosec``
Usages of ros::Rate
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
There is an equivalent type ``rclcpp::Rate`` object which is basically a drop in replacement for ``ros::Rate``.
-ROS client library
-~~~~~~~~~~~~~~~~~~
-
-.. toctree::
- :titlesonly:
-
- Migration-Guide-Python
-
-
-**NOTE: Others to be written**
Boost
-~~~~~
+^^^^^
Much of the functionality previously provided by Boost has been integrated into the C++ standard library.
As such we would like to take advantage of the new core features and avoid the dependency on boost where possible.
Shared Pointers
-"""""""""""""""
+~~~~~~~~~~~~~~~
To switch shared pointers from boost to standard C++ replace instances of:
@@ -373,7 +257,7 @@ Also it is recommended practice to use ``using`` instead of ``typedef``.
For details `see here `__
Thread/Mutexes
-""""""""""""""
+~~~~~~~~~~~~~~
Another common part of boost used in ROS codebases are mutexes in ``boost::thread``.
@@ -383,7 +267,7 @@ Another common part of boost used in ROS codebases are mutexes in ``boost::threa
* Replace ``#include `` with ``#include ``
Unordered Map
-"""""""""""""
+~~~~~~~~~~~~~
Replace:
@@ -392,7 +276,7 @@ Replace:
* ``boost::unordered_map`` with ``std::unordered_map``
function
-""""""""
+~~~~~~~~
Replace:
@@ -400,29 +284,10 @@ Replace:
* ``#include `` with ``#include ``
* ``boost::function`` with ``std::function``
-Parameters
-----------
-
-In ROS 1, parameters are associated with a central server that allowed retrieving parameters at runtime through the use of the network APIs.
-In ROS 2, parameters are associated per node and are configurable at runtime with ROS services.
+Example: Converting an existing ROS 1 package to ROS 2
+------------------------------------------------------
-* See `ROS 2 Parameter design document `_ for more details about the system model.
-
-* See :doc:`ROS 2 CLI usage <../../Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters>` for a better understanding of how the CLI tools work and its differences with ROS 1 tooling.
-
-* See :doc:`../../How-To-Guides/Parameters-YAML-files-migration-guide` to see how YAML parameter files are parsed in ROS 2 and their differences with ROS implementation.
-
-Launch files
-------------
-
-While launch files in ROS 1 are always specified using `.xml `__ files, ROS 2 supports Python scripts to enable more flexibility (see `launch package `__) as well as XML and YAML files.
-See `separate tutorial <../../How-To-Guides/Launch-files-migration-guide>` on migrating launch files from ROS 1 to ROS 2.
-
-Example: Converting an existing ROS 1 package to use ROS 2
-----------------------------------------------------------
-
-Let's say that we have simple ROS 1 package called ``talker`` that uses ``roscpp``
-in one node, called ``talker``.
+Let's say that we have simple ROS 1 package called ``talker`` that uses ``roscpp`` in one node, called ``talker``.
This package is in a catkin workspace, located at ``~/ros1_talker``.
The ROS 1 code
@@ -505,12 +370,12 @@ Here is the content of those three files:
Building the ROS 1 code
~~~~~~~~~~~~~~~~~~~~~~~
-We source an environment setup file (in this case for Jade using bash), then we
+We source an environment setup file (in this case for Noetic using bash), then we
build our package using ``catkin_make install``:
.. code-block:: bash
- . /opt/ros/jade/setup.bash
+ . /opt/ros/noetic/setup.bash
cd ~/ros1_talker
catkin_make install
@@ -519,7 +384,7 @@ Running the ROS 1 node
If there's not already one running, we start a ``roscore``, first sourcing the
setup file from our ``catkin`` install tree (the system setup file at
-``/opt/ros/jade/setup.bash`` would also work here):
+``/opt/ros/noetic/setup.bash`` would also work here):
.. code-block:: bash
@@ -582,8 +447,7 @@ Changing C++ library calls
~~~~~~~~~~~~~~~~~~~~~~~~~~
Instead of passing the node's name to the library initialization call, we do
-the initialization, then pass the node name to the creation of the node object
-(we can use the ``auto`` keyword because now we're requiring a C++14 compiler):
+the initialization, then pass the node name to the creation of the node object:
.. code-block:: cpp
@@ -608,7 +472,7 @@ To further control how message delivery is handled, a quality of service
The default profile is ``rmw_qos_profile_default``.
For more details, see the
`design document `__
-and `concept overview <../../Concepts/About-Quality-of-Service-Settings>`.
+and :doc:`concept overview <../../Concepts/Intermediate/About-Quality-of-Service-Settings>`.
The creation of the outgoing message is different in the namespace:
@@ -698,14 +562,6 @@ Putting it all together, the new ``talker.cpp`` looks like this:
Changing the ``package.xml``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-ROS 2 doesn't support format 1 of the package specification but only newer format versions (2 and higher).
-We start by specifying the format version in the ``package`` tag:
-
-.. code-block:: xml
-
-
-
-
ROS 2 uses a newer version of ``catkin``, called ``ament_cmake``, which we specify in the
``buildtool_depend`` tag:
@@ -714,8 +570,7 @@ ROS 2 uses a newer version of ``catkin``, called ``ament_cmake``, which we speci
ament_cmake
-In our build dependencies, instead of ``roscpp`` we use ``rclcpp``, which provides
-the C++ API that we use.
+In our build dependencies, instead of ``roscpp`` we use ``rclcpp``, which provides the C++ API that we use.
.. code-block:: xml
@@ -723,8 +578,7 @@ the C++ API that we use.
rclcpp
We make the same addition in the run dependencies and also update from the
-``run_depend`` tag to the ``exec_depend`` tag (part of the upgrade to version 2 of
-the package format):
+``run_depend`` tag to the ``exec_depend`` tag (part of the upgrade to version 2 of the package format):
.. code-block:: xml
@@ -776,9 +630,6 @@ Putting it all together, our ``package.xml`` now looks like this:
-**TODO: show simpler version of this file just using the ```` tag, which is
-enabled by version 2 of the package format (also supported in ``catkin`` so,
-strictly speaking, orthogonal to ROS 2).**
Changing the CMake code
~~~~~~~~~~~~~~~~~~~~~~~
@@ -790,22 +641,20 @@ ROS 2 relies on a higher version of CMake:
#cmake_minimum_required(VERSION 2.8.3)
cmake_minimum_required(VERSION 3.5)
-ROS 2 relies on the C++14 standard.
-Depending on what compiler you're using, support for C++14 might not be enabled
-by default.
-Using ``gcc`` 5.3 (which is what is used on Ubuntu Xenial), we need to enable it
-explicitly, which we do by adding this line near the top of the file:
+ROS 2 relies on the C++17 standard.
+Depending on what compiler you're using, support for C++17 might not be enabled by default.
+Enable C++17 support explicitly by adding this line near the top of the file:
.. code-block:: cmake
- set(CMAKE_CXX_STANDARD 14)
+ set(CMAKE_CXX_STANDARD 17)
The preferred way to work on all platforms is this:
.. code-block:: cmake
if(NOT CMAKE_CXX_STANDARD)
- set(CMAKE_CXX_STANDARD 14)
+ set(CMAKE_CXX_STANDARD 17)
endif()
if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
add_compile_options(-Wall -Wextra -Wpedantic)
@@ -878,8 +727,7 @@ like ``Boost``, or a library being built in the same ``CMakeLists.txt``, use
target_link_libraries(target ${Boost_LIBRARIES})
For installation, ``catkin`` defines variables like ``CATKIN_PACKAGE_BIN_DESTINATION``.
-With ``ament_cmake``, we just give a path relative to the installation root, like ``bin``
-for executables:
+With ``ament_cmake``, we just give a path relative to the installation root:
.. code-block:: cmake
@@ -910,7 +758,7 @@ Putting it all together, the new ``CMakeLists.txt`` looks like this:
cmake_minimum_required(VERSION 3.5)
project(talker)
if(NOT CMAKE_CXX_STANDARD)
- set(CMAKE_CXX_STANDARD 14)
+ set(CMAKE_CXX_STANDARD 17)
endif()
if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
add_compile_options(-Wall -Wextra -Wpedantic)
@@ -937,8 +785,6 @@ Putting it all together, the new ``CMakeLists.txt`` looks like this:
ament_export_dependencies(std_msgs)
ament_package()
-**TODO: Show what this would look like with ``ament_auto``.**
-
Building the ROS 2 code
~~~~~~~~~~~~~~~~~~~~~~~
@@ -955,103 +801,10 @@ package using ``colcon build``:
Running the ROS 2 node
~~~~~~~~~~~~~~~~~~~~~~
-Because we installed the ``talker`` executable into ``bin``, after sourcing the
-setup file, from our install tree, we can invoke it by name directly
-(also, there is not yet a ROS 2 equivalent for ``rosrun``):
+Because we installed the ``talker`` executable into the correct directory, after sourcing the
+setup file, from our install tree, we can invoke it by running:
.. code-block:: bash
. ~/ros2_ws/install/setup.bash
- talker
-
-Update scripts
-^^^^^^^^^^^^^^
-
-ROS CLI arguments
-~~~~~~~~~~~~~~~~~
-
-Since `ROS Eloquent <../../Releases/Release-Eloquent-Elusor>`, ROS arguments should be scoped with ``--ros-args`` and a trailing ``--`` (the trailing double dash may be elided if no arguments follow it).
-
-Remapping names is similar to ROS 1, taking on the form ``from:=to``, except that it must be preceded by a ``--remap`` (or ``-r``) flag.
-For example:
-
-.. code-block:: bash
-
- ros2 run some_package some_ros_executable --ros-args -r foo:=bar
-
-We use a similar syntax for parameters, using the ``--param`` (or ``-p``) flag:
-
-
-.. code-block:: bash
-
- ros2 run some_package some_ros_executable --ros-args -p my_param:=value
-
-Note, this is different than using a leading underscore in ROS 1.
-
-To change a node name use ``__node`` (the ROS 1 equivalent is ``__name``):
-
-.. code-block:: bash
-
- ros2 run some_package some_ros_executable --ros-args -r __node:=new_node_name
-
-Note the use of the ``-r`` flag.
-The same remap flag is needed for changing the namespace ``__ns``:
-
-.. code-block:: bash
-
- ros2 run some_package some_ros_executable --ros-args -r __ns:=/new/namespace
-
-There is no equivalent in ROS 2 for the following ROS 1 keys:
-
-- ``__log`` (but ``--log-config-file`` can be used to provide a logger configuration file)
-- ``__ip``
-- ``__hostname``
-- ``__master``
-
-For more information, see the `design document `_.
-
-Quick reference
-"""""""""""""""
-
-+------------+-------------+----------------+
-| Feature | ROS 1 | ROS 2 |
-+============+=============+================+
-| remapping | foo:=bar | -r foo:=bar |
-+------------+-------------+----------------+
-| parameters | _foo:=bar | -p foo:=bar |
-+------------+-------------+----------------+
-| node name | __name:=foo | -r __node:=foo |
-+------------+-------------+----------------+
-| namespace | __ns:=foo | -r __ns:=foo |
-+------------+-------------+----------------+
-
-
-More examples and tools
-^^^^^^^^^^^^^^^^^^^^^^^
-
-- Launch File migrator that converts a ROS 1 XML launch file to a ROS 2 Python launch file: https://github.com/aws-robotics/ros2-launch-file-migrator
-- Amazon has exposed their tools for porting ROS 1 robots to ROS 2
- https://github.com/awslabs/ros2-migration-tools/tree/master/porting\_tools
-
-
-Licensing
----------
-
-In ROS 2 our recommended license is the `Apache 2.0 License `__.
-In ROS 1 our recommended license was the `3-Clause BSD License `__.
-
-For any new project we recommend using the Apache 2.0 License, whether ROS 1 or ROS 2.
-
-However, when migrating code from ROS 1 to ROS 2 we cannot simply change the license.
-The existing license must be preserved for any preexisting contributions.
-
-To that end if a package is being migrated we recommend keeping the existing license and continuing to contribute to that package under the existing OSI license, which we expect to be the BSD license for core elements.
-
-This will keep things clear and easy to understand.
-
-Changing the License
-^^^^^^^^^^^^^^^^^^^^
-
-It is possible to change the license, however you will need to contact all the contributors and get permission.
-For most packages this is likely to be a significant effort and not worth considering.
-If the package has a small set of contributors then this may be feasible.
+ ros2 run talker talker
diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Interfaces.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Interfaces.rst
new file mode 100644
index 00000000000..11fd99d64ea
--- /dev/null
+++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Interfaces.rst
@@ -0,0 +1,52 @@
+Migrating Interfaces
+====================
+
+.. contents:: Table of Contents
+ :depth: 2
+ :local:
+
+Messages, services, and actions are collectively called ``interfaces`` in ROS 2.
+
+Interface definitions
+---------------------
+
+Message files must end in ``.msg`` and must be located in the subfolder ``msg``.
+Service files must end in ``.srv`` and must be located in the subfolder ``srv``.
+Actions files must end in ``.action`` and must be located in the subfolder ``action``.
+
+These files might need to be updated to comply with the `ROS Interface definition `__.
+Some primitive types have been removed and the types ``duration`` and ``time`` which were builtin types in ROS 1 have been replaced with normal message definitions and must be used from the `builtin_interfaces `__ package.
+Also some naming conventions are stricter than in ROS 1.
+There is additional information in the :doc:`conceptual article <../../Concepts/Basic/About-Interfaces>`.
+
+Building interfaces
+-------------------
+
+The way in which interfaces are built in ROS 2 differs substantially from ROS 1.
+Interfaces can only be built from packages containing a ``CMakeLists.txt``.
+If you are developing a pure Python package, then the interfaces should be placed in a different package containing only the interfaces (which is best practice anyway).
+See the :doc:`custom interfaces tutorial<../../Tutorials/Beginner-Client-Libraries/Custom-ROS2-Interfaces>` for more information.
+
+Migrating interface package to ROS 2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In your ``package.xml``:
+
+* Add ``rosidl_default_generators``.
+* Add ``rosidl_default_runtime``.
+* Add ``rosidl_interface_packages``
+* For each dependent message package, add ``message_package``.
+
+In your ``CMakeLists.txt``:
+
+* Enable C++17
+
+.. code-block:: cmake
+
+ set(CMAKE_CXX_STANDARD 17)
+
+* Add ``find_package(rosidl_default_generators REQUIRED)``
+* For each dependent message package, add ``find_package(message_package REQUIRED)`` and replace the CMake function call to ``generate_messages`` with ``rosidl_generate_interfaces``.
+
+This will replace ``add_message_files`` and ``add_service_files`` listing of all the message and service files, which can be removed.
+
diff --git a/source/How-To-Guides/Launch-files-migration-guide.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files.rst
similarity index 91%
rename from source/How-To-Guides/Launch-files-migration-guide.rst
rename to source/How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files.rst
index f22e9cdf663..24212f46c93 100644
--- a/source/How-To-Guides/Launch-files-migration-guide.rst
+++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files.rst
@@ -1,27 +1,30 @@
.. redirect-from::
- Guides/Launch-files-migration-guide
- Tutorials/Launch-files-migration-guide
+ Guides/Launch-files-migration-guide
+ Tutorials/Launch-files-migration-guide
+ How-To-Guides/Launch-files-migration-guide
.. _MigratingLaunch:
-Migrating launch files from ROS 1 to ROS 2
-==========================================
+Migrating Launch Files
+======================
.. contents:: Table of Contents
:depth: 1
:local:
-This guide describes how to write XML launch files for an easy migration from ROS 1.
+While launch files in ROS 1 are always specified using `.xml `__ files, ROS 2 supports Python scripts to enable more flexibility (see `launch package `__) as well as XML and YAML files.
+
+This guide describes how to write ROS 2 XML launch files for an easy migration from ROS 1.
Background
----------
-A description of the ROS 2 launch system and its Python API can be found in :doc:`Launch System tutorial <../Tutorials/Intermediate/Launch/Launch-system>`.
+A description of the ROS 2 launch system and its Python API can be found in :doc:`Launch System tutorial <../../../Tutorials/Intermediate/Launch/Launch-system>`.
-Migrating tags from ROS 1 to ROS 2
-----------------------------------
+Migrating tags
+--------------
launch
^^^^^^
@@ -57,7 +60,8 @@ param
* Used for passing a parameter to a node.
* There's no global parameter concept in ROS 2.
For that reason, it can only be used nested in a ``node`` tag.
- Some attributes aren't supported in ROS 2: ``type``, ``textfile``, ``binfile``, ``executable``, ``command``.
+ Some attributes aren't supported in ROS 2: ``type``, ``textfile``, ``binfile``, ``executable``.
+* The ``command`` attribute is now ``value="$(command '...' )"``.
Example
~~~~~~~
@@ -180,7 +184,7 @@ include
Nest includes in ``group`` tags to scope them.
* ``ns`` attribute is not supported.
See example of ``push_ros_namespace`` tag for a workaround.
- * ``arg`` tags nested in an ``include`` tag don't support conditionals (``if`` or ``unless``).
+ * ``arg`` tags nested in an ``include`` tag don't support conditionals (``if``, ``unless``) or the ``description`` attribute.
* There is no support for nested ``env`` tags.
``set_env`` and ``unset_env`` can be used instead.
* Both ``clear_params`` and ``pass_all_args`` attributes aren't supported.
@@ -200,7 +204,7 @@ arg
* ``value`` attribute is not allowed.
Use ``let`` tag for this.
* ``doc`` is now ``description``.
- * When nested within an ``include`` tag, ``if`` and ``unless`` attributes aren't allowed.
+ * When nested within an ``include`` tag, ``if``, ``unless``, and ``description`` attributes aren't allowed.
Example
~~~~~~~
@@ -227,7 +231,7 @@ Assuming the above launch configuration is in a file named ``mylaunch.xml``, a d
ros2 launch mylaunch.xml topic_name:=custom_topic_name
-There is some additional information about passing command-line arguments in :doc:`Using Substitutions <../Tutorials/Intermediate/Launch/Using-Substitutions>`.
+There is some additional information about passing command-line arguments in :doc:`Using Substitutions <../../../Tutorials/Intermediate/Launch/Using-Substitutions>`.
env
^^^
@@ -399,7 +403,7 @@ There are, however, some changes w.r.t. ROS 1:
* There is a new ``find-exec`` substitution.
* ``arg`` has been replaced with ``var``.
It looks at configurations defined either with ``arg`` or ``let`` tag.
-* ``eval`` and ``dirname`` substitutions haven't changed.
+* ``eval`` and ``dirname`` substitutions require escape characters for string values, e.g. ``if="$(eval '\'$(var variable)\' == \'val1\'')"``.
* ``anon`` substitution is not supported.
Type inference rules
diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst
new file mode 100644
index 00000000000..960de91f517
--- /dev/null
+++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Packages.rst
@@ -0,0 +1,171 @@
+Migrating Packages
+==================
+
+.. contents:: Table of Contents
+ :depth: 2
+ :local:
+
+There are two different kinds of package migrations:
+
+* Migrating the source code of an existing package from ROS 1 to ROS 2 with the intent that a significant part of the source code will stay the same or at least similar.
+ An example for this is `pluginlib `_ where the source code is maintained in different branches within the same repository and common patches can be ported between those branches when necessary.
+* Implementing the same or similar functionality of a ROS 1 package for ROS 2 but with the assumption that the source code will be significantly different.
+ An example for this is `roscpp `_ in ROS 1 and `rclcpp `_ in ROS 2 which are separate repositories and don't share any code.
+
+Prerequisites
+-------------
+
+Before being able to migrate a ROS 1 package to ROS 2 all of its dependencies must be available in ROS 2.
+
+Package format version
+----------------------
+
+ROS 2 doesn't support format 1 of the package specification but only newer format versions (2 and higher).
+Therefore the ``package.xml`` file must be updated to at least format 2 if it uses format 1.
+Since ROS 1 supports all formats it is safe to perform that conversion in the ROS 1 package.
+
+Migrating from package format 1 to 2+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The differences between format 1 and format 2 only affect the package.xml with its dependencies.
+`REP-0140 `__ defines these differences and provides their rationale.
+
+See :doc:`the rosdep documentation <../../Tutorials/Intermediate/Rosdep>` for more information about the various tags.
+
+****
+~~~~~~~~~~~~~
+
+The tag determines which format to use, change it like this:
+
+.. code:: xml
+
+
+
+****
+~~~~~~~~~~~~~
+
+This is a new tag, intended to reduce unnecessary repetition.
+If your format 1 package contained:
+
+.. code:: xml
+
+ foo
+ foo
+
+It should be replaced with:
+
+.. code:: xml
+
+ foo
+
+In format 2, that is equivalent to:
+
+.. code:: xml
+
+ foo
+ foo
+ foo
+
+
+****
+~~~~~~~~~~~~~~~~
+
+This tag is no longer allowed.
+Wherever found, it must be replaced:
+
+.. code:: xml
+
+ foo
+
+In format 2, that is equivalent to these two new tags:
+
+.. code:: xml
+
+ foo
+ foo
+
+If the dependency is only used at run-time, only the ```` is needed.
+If it is only exported to satisfy the build dependencies of other packages, use ````.
+If both are needed, this may be a better choice:
+
+.. code:: xml
+
+ foo
+
+
+****
+~~~~~~~~~~~~~~~~~
+
+In format 2, this tag can satisfy build dependencies, not just those needed for executing your tests.
+Unlike format 1, ```` may now refer to a package also declared as some other type of dependency.
+
+Some test-only dependencies that formerly required a ````, should now be expressed using ````.
+For example:
+
+.. code:: xml
+
+ testfoo
+
+becomes:
+
+.. code:: xml
+
+ testfoo
+
+In your CMakeLists.txt make sure your test dependencies are only referenced within the conditional test block:
+
+.. code:: cmake
+
+ if (BUILD_TESTING)
+ find_package(testfoo REQUIRED)
+ endif()
+
+
+****
+~~~~~~~~~~~~~~~~
+
+This tag defines dependencies needed for building your documentation:
+
+.. code:: xml
+
+ doxygen
+ python3-sphinx
+
+This does not create binary package dependencies, unless they were also declared using some other dependency tag.
+
+Dependency names
+----------------
+
+Dependency names that come from :doc:`rosdep <../../Tutorials/Intermediate/Rosdep>` should not need to change, as those are shared across ROS 1 and ROS 2.
+
+Some packages released into ROS might have different names in ROS 2 so the dependencies might need to be updated accordingly.
+
+Metapackages
+------------
+
+ROS 2 doesn't have a special package type for metapackages.
+Metapackages can still exist as regular packages that only contain runtime dependencies.
+When migrating metapackages from ROS 1, simply remove the ```` tag in your package manifest.
+See :doc:`Using variants <../Using-Variants>` for more information on metapackages/variants.
+
+Licensing
+---------
+
+In ROS 1 our recommended license was the `3-Clause BSD License `__.
+In ROS 2 our recommended license is the `Apache 2.0 License `__.
+
+For any new project we recommend using the Apache 2.0 License, whether ROS 1 or ROS 2.
+
+However, when migrating code from ROS 1 to ROS 2 we cannot simply change the license.
+The existing license must be preserved for any preexisting contributions.
+
+To that end if a package is being migrated we recommend keeping the existing license and continuing to contribute to that package under the existing OSI license, which we expect to be the BSD license for core elements.
+
+This will keep things clear and easy to understand.
+
+Changing the License
+^^^^^^^^^^^^^^^^^^^^
+
+It is possible to change the license, however you will need to contact all the contributors and get permission.
+For most packages this is likely to be a significant effort and not worth considering.
+If the package has a small set of contributors then this may be feasible.
diff --git a/source/How-To-Guides/Parameters-YAML-files-migration-guide.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Parameters.rst
similarity index 59%
rename from source/How-To-Guides/Parameters-YAML-files-migration-guide.rst
rename to source/How-To-Guides/Migrating-from-ROS1/Migrating-Parameters.rst
index 131c5b7bdd9..ac07b2faf0e 100644
--- a/source/How-To-Guides/Parameters-YAML-files-migration-guide.rst
+++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Parameters.rst
@@ -1,17 +1,30 @@
.. redirect-from::
- Guides/Parameters-YAML-files-migration-guide
- Tutorials/Parameters-YAML-files-migration-guide
+ Guides/Parameters-YAML-files-migration-guide
+ Tutorials/Parameters-YAML-files-migration-guide
+ How-To-Guides/Parameters-YAML-files-migration-guide
-.. _yaml-ros1-ros2:
+Migrating Parameters
+====================
-Migrating YAML parameter files from ROS 1 to ROS 2
-==================================================
+.. contents:: Table of Contents
+ :depth: 2
+ :local:
+
+In ROS 1, parameters are associated with a central server that allowed retrieving parameters at runtime through the use of the network APIs.
+In ROS 2, parameters are associated per node and are configurable at runtime with ROS services.
+
+* See `ROS 2 Parameter design document `_ for more details about the system model.
+
+* See :doc:`ROS 2 CLI usage <../../Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters>` for a better understanding of how the CLI tools work and its differences with ROS 1 tooling.
+
+Migrating YAML Parameter Files
+------------------------------
This guide describes how to adapt ROS 1 parameters files for ROS 2.
YAML file example
------------------
+^^^^^^^^^^^^^^^^^
YAML is used to write parameters files in both ROS 1 and ROS 2.
The main difference in ROS 2 is that node names must be used to address parameters.
@@ -48,7 +61,7 @@ We would construct our ROS 2 parameters file as follows:
Note the use of wildcards (``/**``) to indicate that the parameter ``debug`` should be set on any node in any namespace.
Feature parity
---------------
+^^^^^^^^^^^^^^
Some features of ROS 1 parameters files do not exist in ROS 2:
diff --git a/source/The-ROS2-Project/Contributing/Migration-Guide-Python.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Python-Packages.rst
similarity index 50%
rename from source/The-ROS2-Project/Contributing/Migration-Guide-Python.rst
rename to source/How-To-Guides/Migrating-from-ROS1/Migrating-Python-Packages.rst
index 058ddaae518..c280e6b8453 100644
--- a/source/The-ROS2-Project/Contributing/Migration-Guide-Python.rst
+++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Python-Packages.rst
@@ -1,12 +1,54 @@
.. redirect-from::
- Migration-Guide-Python
+ Migration-Guide-Python
+ The-ROS2-Project/Contributing/Migration-Guide-Python
-Python migration guide from ROS 1
-=================================
+Migrating Python Packages
+=========================
+
+.. contents:: Table of Contents
+ :depth: 2
+ :local:
+
+Build tool
+----------
+
+Instead of using ``catkin_make``, ``catkin_make_isolated`` or ``catkin build`` ROS 2 uses the command line tool `colcon `__ to build and install a set of packages.
+See the :doc:`beginner tutorial <../../Tutorials/Beginner-Client-Libraries/Colcon-Tutorial>` to get started with ``colcon``.
+
+Build system
+------------
+
+For pure Python packages, ROS 2 uses the standard ``setup.py`` installation mechanism familiar to Python developers.
+
+Update the files to use *setup.py*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the ROS 1 package uses CMake only to invoke the ``setup.py`` file and does not contain anything beside Python code (e.g. no messages, services, etc.) it should be converted into a pure Python package in ROS 2:
+
+*
+ Update or add the build type in the ``package.xml`` file:
+
+ .. code-block:: xml
+
+
+ ament_python
+
+
+*
+ Remove the ``CMakeLists.txt`` file
+
+*
+ Update the ``setup.py`` file to be a standard Python setup script
+
+ROS 2 supports Python 3 only.
+While each package can choose to also support Python 2 it must invoke executables with Python 3 if it uses any API provided by other ROS 2 packages.
+
+Update source code
+------------------
Node Initialization
--------------------
+^^^^^^^^^^^^^^^^^^^
In ROS 1:
@@ -25,9 +67,8 @@ In ROS 2:
node.get_logger().info('Created node')
-
ROS Parameters
---------------
+^^^^^^^^^^^^^^
In ROS 1:
@@ -53,41 +94,46 @@ In ROS 2:
node.get_logger().warn('port: ' + port)
-
Creating a Publisher
---------------------
+^^^^^^^^^^^^^^^^^^^^
In ROS 1:
.. code-block:: python
pub = rospy.Publisher('chatter', String)
+ # or
+ pub = rospy.Publisher('chatter', String, queue_size=10)
In ROS 2:
.. code-block:: python
- pub = node.create_publisher(String, 'chatter')
-
+ pub = node.create_publisher(String, 'chatter', rclpy.qos.QoSProfile())
+ # or
+ pub = node.create_publisher(String, 'chatter', 10)
Creating a Subscriber
----------------------
+^^^^^^^^^^^^^^^^^^^^^
In ROS 1:
.. code-block:: python
sub = rospy.Subscriber('chatter', String, callback)
+ # or
+ sub = rospy.Subscriber('chatter', String, callback, queue_size=10)
In ROS 2:
.. code-block:: python
- sub = node.create_subscription(String, 'chatter', callback)
-
+ sub = node.create_subscription(String, 'chatter', callback, rclpy.qos.QoSProfile())
+ # or
+ sub = node.create_subscription(String, 'chatter', callback, 10)
Creating a Service
-------------------
+^^^^^^^^^^^^^^^^^^
In ROS 1:
@@ -101,9 +147,8 @@ In ROS 2:
srv = node.create_service(AddTwoInts, 'add_two_ints', add_two_ints_callback)
-
Creating a Service Client
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
In ROS 1:
diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Scripts.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Scripts.rst
new file mode 100644
index 00000000000..12311822757
--- /dev/null
+++ b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Scripts.rst
@@ -0,0 +1,68 @@
+Migrating Scripts
+=================
+
+ROS CLI
+-------
+
+In ROS 1 there were individual commands for performing various actions, like ``rosrun``, ``rosparam``, etc.
+
+In ROS 2, there is a single top-level commands called ``ros2``, and all of the actions are sub-commands of that, like ``ros2 run``, ``ros2 param``, etc.
+
+ROS CLI arguments
+-----------------
+
+In ROS 1, arguments to nodes were provided directly on the command-line.
+
+ROS 2 arguments should be scoped with ``--ros-args`` and a trailing ``--`` (the trailing double dash may be elided if no arguments follow it).
+
+Remapping names is similar to ROS 1, taking on the form ``from:=to``, except that it must be preceded by a ``--remap`` (or ``-r``) flag.
+For example:
+
+.. code-block:: bash
+
+ ros2 run some_package some_ros_executable --ros-args -r foo:=bar
+
+We use a similar syntax for parameters, using the ``--param`` (or ``-p``) flag:
+
+.. code-block:: bash
+
+ ros2 run some_package some_ros_executable --ros-args -p my_param:=value
+
+Note, this is different than using a leading underscore in ROS 1.
+
+To change a node name use ``__node`` (the ROS 1 equivalent is ``__name``):
+
+.. code-block:: bash
+
+ ros2 run some_package some_ros_executable --ros-args -r __node:=new_node_name
+
+Note the use of the ``-r`` flag.
+The same remap flag is needed for changing the namespace ``__ns``:
+
+.. code-block:: bash
+
+ ros2 run some_package some_ros_executable --ros-args -r __ns:=/new/namespace
+
+There is no equivalent in ROS 2 for the following ROS 1 keys:
+
+- ``__log`` (but ``--log-config-file`` can be used to provide a logger configuration file)
+- ``__ip``
+- ``__hostname``
+- ``__master``
+
+For more information, see the `design document `_.
+
+Quick reference
+~~~~~~~~~~~~~~~
+
++------------+-------------+----------------+
+| Feature | ROS 1 | ROS 2 |
++============+=============+================+
+| remapping | foo:=bar | -r foo:=bar |
++------------+-------------+----------------+
+| parameters | _foo:=bar | -p foo:=bar |
++------------+-------------+----------------+
+| node name | __name:=foo | -r __node:=foo |
++------------+-------------+----------------+
+| namespace | __ns:=foo | -r __ns:=foo |
++------------+-------------+----------------+
diff --git a/source/How-To-Guides/Node-arguments.rst b/source/How-To-Guides/Node-arguments.rst
index 90cf2b1be95..afdb4701681 100644
--- a/source/How-To-Guides/Node-arguments.rst
+++ b/source/How-To-Guides/Node-arguments.rst
@@ -49,7 +49,7 @@ The namespace, which must start with a forward slash, is set to ``/demo``, which
Passing remapping arguments to specific nodes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If multiple nodes are being run within a single process (e.g. using :doc:`Composition <../Concepts/About-Composition>`), remapping arguments can be passed to a specific node using its name as a prefix.
+If multiple nodes are being run within a single process (e.g. using :doc:`Composition <../Concepts/Intermediate/About-Composition>`), remapping arguments can be passed to a specific node using its name as a prefix.
For example, the following will pass the remapping arguments to the specified nodes:
.. code-block:: bash
diff --git a/source/How-To-Guides/Overriding-QoS-Policies-For-Recording-And-Playback.rst b/source/How-To-Guides/Overriding-QoS-Policies-For-Recording-And-Playback.rst
index 29696add627..114baf59510 100644
--- a/source/How-To-Guides/Overriding-QoS-Policies-For-Recording-And-Playback.rst
+++ b/source/How-To-Guides/Overriding-QoS-Policies-For-Recording-And-Playback.rst
@@ -19,7 +19,7 @@ Background
----------
With the introduction of DDS in ROS 2, Quality of Service (QoS) compatibility for publisher/subscriber nodes needs to be considered when recording and playing back data.
-More detail on how QoS works can be found :doc:`here <../Concepts/About-Quality-of-Service-Settings>`.
+More detail on how QoS works can be found :doc:`here <../Concepts/Intermediate/About-Quality-of-Service-Settings>`.
For the purposes of this guide, it is sufficient to know that only the reliability and durability policies affect whether publishers/subscribers are compatible and can receive data from one other.
Ros2Bag adapts its requested/offered QoS profile when recording/playing data from a topic to prevent dropped messages.
diff --git a/source/How-To-Guides/Package-maintainer-guide.rst b/source/How-To-Guides/Package-maintainer-guide.rst
index 2487f12af6d..8b5a1bb2d09 100644
--- a/source/How-To-Guides/Package-maintainer-guide.rst
+++ b/source/How-To-Guides/Package-maintainer-guide.rst
@@ -162,7 +162,7 @@ Responding to issues
Package maintainers should also look at incoming issues on the repository and triage the problems that users are having.
-For issues that look like questions, the issue should be closed and the user redirected to https://answers.ros.org.
+For issues that look like questions, the issue should be closed and the user redirected to `Robotics Stack Exchange `__ .
If an issue looks like a problem, but is not relevant to this particular repository, it should be moved to the appropriate repository with the GitHub "Transfer issue" button.
diff --git a/source/How-To-Guides/ROS-2-IDEs.rst b/source/How-To-Guides/ROS-2-IDEs.rst
new file mode 100644
index 00000000000..157a80603b6
--- /dev/null
+++ b/source/How-To-Guides/ROS-2-IDEs.rst
@@ -0,0 +1,260 @@
+IDEs and Debugging [community-contributed]
+==========================================
+
+ROS 2 is not made around a specific development environment and the main focus is on building / running from the command line.
+Nonetheless Integrated Development Environments (IDEs) can be used to develop, run and/or debug ROS 2 nodes.
+
+Below are listed some IDEs and instructions on how to use them with ROS 2.
+
+
+.. contents:: Contents
+ :depth: 2
+ :local:
+
+
+General
+-------
+
+
+.. _InstalledPythonCode:
+
+Installed Python Code
+^^^^^^^^^^^^^^^^^^^^^
+
+By default, when building workspaces with:
+
+.. code-block:: bash
+
+ colcon build
+
+The Python code will be coped over into the ``build``/``install`` directories.
+So when attaching a debugger to a ``ros2 run`` command from within an IDE, the code being run (from the ``build``/``install``) is not the same as the files opened in the IDE project.
+
+There are 2 options to deal with this:
+
+* Open the source files from ``build``/``install`` directory and place breakpoints there.
+* Build the workspace with the `--symlink-install `__ flag to colcon, which will symlink the source files to the ``build``/``install`` directory instead.
+
+
+Visual Studio Code
+------------------
+
+`VSCode `_ is a versatile and free development environment.
+
+VSCode is relatively easy to use with ROS 2.
+Simply activate your environment in a command line and start the VSCode application from the same terminal and use as normal.
+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.
+
+.. tabs::
+
+ .. group-tab:: Linux
+
+ .. code-block:: bash
+
+ source /opt/ros/{DISTRO}/setup.bash
+ cd ~/dev_ws
+ source ./install/setup.bash
+ /usr/bin/code ./src/my_node/
+
+ .. group-tab:: macOS
+
+ .. code-block:: console
+
+ . ~/ros2_install/ros2-osx/setup.bash
+ cd ~/dev_ws
+ . ./install/setup.bash
+ /Applications/Visual Studio Code.app/Contents/Resources/app/bin/code ./src/my_node/
+
+ .. group-tab:: Windows
+
+ .. code-block:: console
+
+ # For CMD:
+ call C:\dev\ros2\local_setup.bat
+ cd C:\dev_ws
+ call .\install\local_setup.bat
+ "C:\Program Files\Microsoft VS Code\Code.exe" .\src\my_node\
+
+ # For PowerShell:
+ C:\dev\ros2\local_setup.ps1
+ cd C:\dev_ws
+ .\install\local_setup.ps1
+ & "C:\Program Files\Microsoft VS Code\Code.exe" .\src\my_node\
+
+
+VSCode and any terminal created inside VSCode will correctly inherit from the parent environment and should have ROS and installed package available.
+
+.. note::
+
+ After adding packages or making major changes you might need to source your install again.
+ The simplest way to do this is to close VSCode and restart it as above.
+
+
+Python
+^^^^^^
+
+In your workspace, verify the correct interpreter is used.
+Through sourcing the basic command ``python`` should be correct, but VSCode likes to resort to an absolute path for Python.
+In the bottom right corner click on "Selected Python Interpreter" to change it.
+
+If your ROS 2 Python version is from a virtual environment, VSCode will try to source it at each run command.
+But we already started VSCode from a sourced environment, so this extra step is not necessary.
+You can disable this for the current workspace by finding "Settings" > "Extensions" > "Python" > "Activate Environment" and disabling the check.
+
+Now simply run a file or create a configuration in ``launch.json``.
+Debugging a node is easiest by creating a configuration like a ``python ...`` command, instead of ``ros2 run/launch ...``.
+An example of ``launch.json`` could be:
+
+.. code-block::
+
+ {
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "Python: File",
+ "type": "python",
+ "request": "launch",
+ "program": "my_node.py"
+ },
+ ]
+ }
+
+
+Instead you could also create a configuration for attaching to a running process, under "Attach using Process Id".
+
+
+See :doc:`Setup ROS 2 with VSCode and Docker` for full instructions on how to use VSCode, in combination with Docker.
+
+
+PyCharm
+-------
+
+`PyCharm `_ is an IDE specifically for Python.
+
+Of course it can only be meaningfully used for nodes made in Python.
+
+With PyCharm you can either attach to an existing process (probably started by you via ``ros2 run ...`` or ``ros2 launch ...``) or run the node directly from Python (equivalent to ``python [file.py]``.
+
+
+Integrate for code inspection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can setup your PyCharm project such that it is fully aware of ROS 2 code, allowing code completion and suggestion.
+
+
+Linux
+"""""
+
+Open a terminal, source ROS and start PyCharm:
+
+.. code-block:: bash
+
+ source /opt/ros/humble/setup.bash
+ cd path/to/dev_ws
+ /opt/pycharm/bin/pycharm.sh
+
+After selecting the correct interpreter, everything should work.
+
+.. note::
+
+ This is untested.
+
+
+Windows
+"""""""
+
+First sourcing ROS and then starting PyCharm from the command line seems to have no effect on Windows.
+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``.
+#. 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``).
+
+ * If you now open one of your code files, you will see warnings about missing imports.
+ Trying to run the file will confirm these issues.
+
+#. Under the "Python Interpreters" window, find and select your ROS interpreter.
+ Edit the name to something recognizable.
+ More importantly, now click the "Show Interpreter Paths" button.
+#. In the new window, you will see the paths already associated with this interpreter.
+ Click the "+" button and add two more paths (according to your ROS install):
+
+ * ``C:\dev\ros2_humble\bin``
+ * ``C:\dev\ros2_humble\Lib\site-packages``
+
+PyCharm will re-index and when finished it should correctly interpret your project, recognising the ROS 2 system packages.
+You can navigate through code, get completion and read doc blurbs as expected.
+
+
+If there are dependencies built alongside with your package, they are probably not yet recognized and result in invalid IDE warnings and runtime errors.
+
+Resolve this by:
+
+* Making sure the ``PATH`` override in the run/debug configuration includes both the ROS 2 install and your workspace, e.g.:
+
+ .. code-block:: bash
+
+ C:\dev\ros2_humble\local_setup.ps1
+ C:\dev_ws\install\local_setup.ps1
+ echo $ENV:Path
+
+* Adding the relevant folders from the ``install/`` directory to your project sources.
+
+ Go to "Settings..." and under "Project: " > "Project Structure" click "Add content root".
+ Add all the relevant ``site-packages`` folders under ``install/Lib/*``.
+
+ Finally, make sure your run/debug configuration has the option "include content roots in PYTHONPATH" enabled.
+
+.. tip::
+
+ Using the `--merge-install `__ option with your colcon build will limit the number of depending directories, making it easier to configure PyCharm.
+
+
+Attach to Process
+^^^^^^^^^^^^^^^^^
+
+Even without any configuration to PyCharm, you can always just attach to a running Python node.
+Open your project source and simply run your node as usual:
+
+.. code-block:: bash
+
+ ros2 run my_node main
+
+Then in PyCharm select "Run" > "Attach to Process...".
+It might take a second, but a small window should show listing the currently running Python instances, including your node.
+There can be multiple Python processes, so there may be some trial-and-error to find the right one.
+
+After selecting an instance, the usual debugging tools are available.
+You can pause it or create breakpoints in the code and step through it.
+
+.. note::
+
+ The code in your project might not be the files being executed, see :ref:`this`.
+
+
+Run/Debug
+^^^^^^^^^
+
+Follow the steps for integration first.
+
+Running your Python file from PyCharm will likely result in import errors.
+This is because PyCharm extends the ``PYTHONPATH`` environment variable, but it leaves ``PATH`` untouched.
+Necessary library files in ``ros/bin`` are not found.
+
+Edit the run/debug configuration for your file and under "Environment Variables:" add a new variable.
+It is currently not supported to extend the existing ``PATH``, so we need to override it.
+From a sourced ROS terminal, export the content of ``PATH`` with: ``echo $Env:PATH``.
+Copy the result.
+
+Back in PyCharm, paste it as ``PATH``, apply changes and run or debug your node.
+It should work like any Python project now, allowing easy additions of breakpoints and other debug methods.
+
+.. note::
+
+ On Windows it seems the capitalization of the ``PATH`` variable under "Environment Variables:" must be "path" (all lowercase) in order to work.
diff --git a/source/How-To-Guides/RQt-Source-Install.rst b/source/How-To-Guides/RQt-Source-Install.rst
index bc8e4620965..a91fc5ceffc 100644
--- a/source/How-To-Guides/RQt-Source-Install.rst
+++ b/source/How-To-Guides/RQt-Source-Install.rst
@@ -107,4 +107,4 @@ Windows
Using RQt
----------
-See :doc:`Overview of RQt <../Concepts/About-RQt>`.
+See :doc:`Overview of RQt <../Concepts/Intermediate/About-RQt>`.
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 9cccd5bcbe0..b327094d8fb 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
@@ -86,4 +86,4 @@ As an alternative to the command line invocation, you can create a ``docker-comp
depends_on:
- talker
-To run the containers call ``docker-compose up`` in the same directory. You can close the containers with ``Ctrl+C``.
+To run the containers call ``docker compose up`` in the same directory. You can close the containers with ``Ctrl+C``.
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 cf92adeb075..27d6a205611 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
@@ -141,7 +141,7 @@ Therefore add the following to ``.devcontainer/devcontainer.json``:
},
"containerEnv": {
"DISPLAY": "unix:0",
- "ROS_LOCALHOST_ONLY": "1",
+ "ROS_AUTOMATIC_DISCOVERY_RANGE": "LOCALHOST",
"ROS_DOMAIN_ID": "42"
},
"runArgs": [
diff --git a/source/How-To-Guides/Topics-Services-Actions.rst b/source/How-To-Guides/Topics-Services-Actions.rst
index d6a1979b675..1c1bbdfb421 100644
--- a/source/How-To-Guides/Topics-Services-Actions.rst
+++ b/source/How-To-Guides/Topics-Services-Actions.rst
@@ -8,7 +8,7 @@ Topics vs Services vs Actions
:local:
When designing a system there are three primary styles of interfaces.
-The specifications for the content is in the :doc:`Interfaces Overview <../Concepts/About-ROS-Interfaces>`.
+The specifications for the content is in the :doc:`Interfaces Overview <../Concepts/Basic/About-Interfaces>`.
This is written to provide the reader with guidelines about when to use each type of interface.
Topics
diff --git a/source/How-To-Guides/Using-Python-Packages.rst b/source/How-To-Guides/Using-Python-Packages.rst
index bfdb3d0dfca..a62d11a805d 100644
--- a/source/How-To-Guides/Using-Python-Packages.rst
+++ b/source/How-To-Guides/Using-Python-Packages.rst
@@ -96,7 +96,7 @@ Now you can build your workspace and run your python node that depends on packag
.. note::
- If you want release your package on Bloom, you should to add the packages you require to ``rosdep``, see the `rosdep key contribution guide`_.
+ If you want to release your package using Bloom, you should add the packages you require to ``rosdep``, see the `rosdep key contribution guide`_.
.. _rosdep key contribution guide: http://docs.ros.org/en/independent/api/rosdep/html/contributing_rules.html
diff --git a/source/How-To-Guides/Using-callback-groups.rst b/source/How-To-Guides/Using-callback-groups.rst
index 68d7f252363..460797c3abf 100644
--- a/source/How-To-Guides/Using-callback-groups.rst
+++ b/source/How-To-Guides/Using-callback-groups.rst
@@ -5,7 +5,7 @@ When running a node in a Multi-Threaded Executor, ROS 2 offers callback
groups as a tool for controlling the execution of different callbacks.
This page is meant as a guide on how to use callback groups efficiently.
It is assumed that the reader has a basic understanding
-about the concept of :doc:`executors <../Concepts/About-Executors>`.
+about the concept of :doc:`executors <../Concepts/Intermediate/About-Executors>`.
.. contents:: Table of Contents
:local:
@@ -28,7 +28,7 @@ In short:
executed in parallel - essentially making it as if the callbacks in the group
were executed by a SingleThreadedExecutor.
* Reentrant Callback Group allows the executor to schedule and execute
- the group's callbacks in any way the it sees fit, without restrictions.
+ the group's callbacks in any way it sees fit, without restrictions.
This means that, in addition to different callbacks being run parallel
to each other, different instances of the same callback may also be
executed concurrently.
@@ -108,27 +108,30 @@ Controlling execution
In order to control execution with callback groups, one can consider the
following guidelines.
-* Register callbacks that should never be executed in parallel to the same
- Mutually Exclusive Callback Group.
- An example case might be that the callbacks are accessing shared
- critical and non-thread-safe resources.
-* If you have a callback whose execution instances need to be able to overlap
- with each other, register it to a Reentrant Callback Group.
- An example case could be an action server that needs to be able to process
- several action calls in parallel to each other.
-* If you have different callbacks that require to be potentially executed
- in parallel to one another, register them to
-
- * a Reentrant Callback Group, or
- * different Mutually Exclusive Callback Groups (this option is good if you
- want the callbacks to not overlap themselves or also need thread
- safety with respect to some other callbacks)
- or different callback groups of any type (choose the types according
- to other criteria).
-
-Note that the option in the list is a valid way of allowing parallel
-execution for different callbacks, and can even be more desirable than simply
-registering everything into one Reentrant Callback Group.
+For the interaction of an individual callback with itself:
+
+* Register it to a Reentrant Callback Group if it should be executed in parallel to itself.
+ An example case could be an action/service server that needs to be able to
+ process several action calls in parallel to each other.
+
+* Register it to a Mutually Exclusive Callback Group if it should **never** be executed in parallel to itself.
+ An example case could be a timer callback that runs a control loop that publishes control commands.
+
+For the interaction of different callbacks with each other:
+
+* Register them to the same Mutually Exclusive Callback Group if they should **never** be executed in parallel.
+ An example case could be that the callbacks are accessing shared critical and non-thread-safe resources.
+
+If they should be executed in parallel, you have two options,
+depending on whether the individual callbacks should be able to overlap themselves or not:
+
+* Register them to different Mutually Exclusive Callback Groups (no overlap of the individual callbacks)
+
+* Register them to a Reentrant Callback Group (overlap of the individual callbacks)
+
+An example case of running different callbacks in parallel is a Node that has
+a synchronous service client and a timer calling this service.
+See the detailed example below.
Avoiding deadlocks
------------------
diff --git a/source/How-To-Guides/Using-ros2-param.rst b/source/How-To-Guides/Using-ros2-param.rst
index 327eadacd7e..9351ce614f0 100644
--- a/source/How-To-Guides/Using-ros2-param.rst
+++ b/source/How-To-Guides/Using-ros2-param.rst
@@ -5,7 +5,7 @@ Using the ``ros2 param`` command-line tool
:depth: 1
:local:
-Parameters in ROS 2 can be get, set, listed, and described through a set of services as described in :doc:`the concept document <../Concepts/About-ROS-2-Parameters>`.
+Parameters in ROS 2 can be get, set, listed, and described through a set of services as described in :doc:`the concept document <../Concepts/Basic/About-Parameters>`.
The ``ros2 param`` command-line tool is a wrapper around these service calls that makes it easy to manipulate parameters from the command-line.
``ros2 param list``
@@ -82,7 +82,7 @@ The following string typed parameter would work:
This command will remove a parameter from a particular node.
However, note that this can only remove dynamic parameters (not declared parameters).
-See :doc:`the concept document <../Concepts/About-ROS-2-Parameters>` for more information.
+See :doc:`the concept document <../Concepts/Basic/About-Parameters>` for more information.
.. code-block:: console
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 567a4aca147..78ee1a32461 100644
--- a/source/How-To-Guides/Working-with-multiple-RMW-implementations.rst
+++ b/source/How-To-Guides/Working-with-multiple-RMW-implementations.rst
@@ -16,7 +16,7 @@ This page explains the default RMW implementation and how to specify an alternat
Prerequisites
--------------
-You should have already read the :doc:`DDS and ROS middleware implementations page <../Concepts/About-Different-Middleware-Vendors>`.
+You should have already read the :doc:`DDS and ROS middleware implementations page <../Concepts/Intermediate/About-Different-Middleware-Vendors>`.
Specifying RMW implementations
------------------------------
@@ -68,10 +68,10 @@ Adding RMW implementations to your workspace
Suppose that you have built your ROS 2 workspace with only Fast DDS installed and therefore only the Fast DDS RMW implementation built.
The last time your workspace was built, any other RMW implementation packages, ``rmw_connextdds`` for example, were probably unable to find installations of the relevant DDS implementations.
If you then install an additional DDS implementation, Connext for example, you will need to re-trigger the check for a Connext installation that occurs when the Connext RMW implementation is being built.
-You can do this by specifying the ``--cmake-force-configure`` flag on your next workspace build, and you should see that the RMW implementation package then gets built for the newly installed DDS implementation.
+You can do this by specifying the ``--cmake-clean-cache`` flag on your next workspace build, and you should see that the RMW implementation package then gets built for the newly installed DDS implementation.
-It is possible to run into a problem when "rebuilding" the workspace with an additional RMW implementation using the ``--cmake-force-configure`` option where the build complains about the default RMW implementation changing.
-To resolve this, you can either set the default implementation to what is was before with the ``RMW_IMPLEMENTATION`` CMake argument or you can delete the build folder for packages that complain and continue the build with ``--start-with ``.
+It is possible to run into a problem when "rebuilding" the workspace with an additional RMW implementation using the ``--cmake-clean-cache`` option where the build complains about the default RMW implementation changing.
+To resolve this, you can either set the default implementation to what is was before with the ``RMW_IMPLEMENTATION`` CMake argument or you can delete the build folder for packages that complain and continue the build with ``--packages-start ``.
Troubleshooting
---------------
@@ -118,7 +118,7 @@ it will generate a daemon with a Fast DDS implementation:
.. code-block:: bash
- 21318 22.0 0.6 535896 55044 pts/8 Sl 16:14 0:00 /usr/bin/python3 /opt/ros/{DISTRO}/bin/_ros2_daemon --rmw-implementation rmw_fastrtps_cpp --ros-domain-id 22
+ 21318 22.0 0.6 535896 55044 pts/8 Sl 16:14 0:00 /usr/bin/python3 /opt/ros/{DISTRO}/bin/_ros2_daemon --rmw-implementation rmw_fastrtps_cpp --ros-domain-id 0
Even if you run the command line tool again with the correct RMW implementation, the daemon's RMW implementation will not change and the ROS 2 command line tools will fail.
diff --git a/source/Installation.rst b/source/Installation.rst
index edfe9894f19..1adc0d0e74a 100644
--- a/source/Installation.rst
+++ b/source/Installation.rst
@@ -50,7 +50,7 @@ We support building ROS 2 from source on the following platforms:
* :doc:`Ubuntu Linux `
* :doc:`Windows `
-* :doc:`RHEL `
+* :doc:`RHEL/Fedora `
* :doc:`macOS `
diff --git a/source/Installation/Alternatives.rst b/source/Installation/Alternatives.rst
index c0480015c8f..4a05c841222 100644
--- a/source/Installation/Alternatives.rst
+++ b/source/Installation/Alternatives.rst
@@ -12,5 +12,4 @@ A list of alternative ways to install ROS 2 – whether it's by building from s
Alternatives/RHEL-Development-Setup
Alternatives/RHEL-Install-Binary
Alternatives/macOS-Development-Setup
- Alternatives/Fedora-Development-Setup
Alternatives/Latest-Development-Setup
diff --git a/source/Installation/Alternatives/Fedora-Development-Setup.rst b/source/Installation/Alternatives/Fedora-Development-Setup.rst
deleted file mode 100644
index f35f93f5010..00000000000
--- a/source/Installation/Alternatives/Fedora-Development-Setup.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-.. redirect-from::
-
- Installation/Fedora-Development-Setup
-
-Fedora (source)
-===============
-
-How to setup the development environment?
------------------------------------------
-
-The following system dependencies are required to build ROS 2 on Fedora. They can be installed with ``dnf`` as follows:
-
-.. code-block:: bash
-
- sudo dnf install \
- cmake \
- cppcheck \
- eigen3-devel \
- gcc-c++ \
- liblsan \
- libXaw-devel \
- libyaml-devel \
- make \
- opencv-devel \
- patch \
- python3-colcon-common-extensions \
- python3-coverage \
- python3-devel \
- python3-empy \
- python3-nose \
- python3-pip \
- python3-pydocstyle \
- python3-pyparsing \
- python3-pytest \
- python3-pytest-cov \
- python3-pytest-mock \
- python3-pytest-runner \
- python3-rosdep \
- python3-setuptools \
- python3-vcstool \
- poco-devel \
- poco-foundation \
- python3-flake8 \
- python3-flake8-import-order \
- redhat-rpm-config \
- uncrustify \
- wget
-
-
-With this done, you can follow the rest of the :ref:`instructions ` to fetch and build ROS 2.
-
diff --git a/source/Installation/Alternatives/RHEL-Development-Setup.rst b/source/Installation/Alternatives/RHEL-Development-Setup.rst
index 9edf8c4234b..ebdec994c24 100644
--- a/source/Installation/Alternatives/RHEL-Development-Setup.rst
+++ b/source/Installation/Alternatives/RHEL-Development-Setup.rst
@@ -1,5 +1,7 @@
.. redirect-from::
+ Installation/Alternatives/Fedora-Development-Setup
+ Installation/Fedora-Development-Setup
Installation/RHEL-Development-Setup
RHEL (source)
@@ -29,15 +31,23 @@ Set locale
Enable required repositories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The rosdep database contains packages from the EPEL and PowerTools repositories, which are not enabled by default.
-They can be enabled by running:
+.. tabs::
-.. code-block:: bash
+ .. group-tab:: RHEL
+
+ The rosdep database contains packages from the EPEL and PowerTools repositories, which are not enabled by default.
+ They can be enabled by running:
+
+ .. code-block:: bash
+
+ sudo dnf install 'dnf-command(config-manager)' epel-release -y
+ sudo dnf config-manager --set-enabled crb
+
+ .. note:: This step may be slightly different depending on the distribution you are using. Check the EPEL documentation: https://docs.fedoraproject.org/en-US/epel/#_quickstart
- sudo dnf install 'dnf-command(config-manager)' epel-release -y
- sudo dnf config-manager --set-enabled crb
+ .. group-tab:: Fedora
-.. note:: This step may be slightly different depending on the distribution you are using. Check the EPEL documentation: https://docs.fedoraproject.org/en-US/epel/#_quickstart
+ No additional setup required.
Install development tools
@@ -75,8 +85,6 @@ Install development tools
flake8-class-newline \
flake8-deprecated
-.. _Rolling_rhel-dev-get-ros2-code:
-
Build ROS 2
-----------
@@ -123,9 +131,14 @@ More info on working with a ROS workspace can be found in :doc:`this tutorial <.
cd ~/ros2_{DISTRO}/
colcon build --symlink-install
-Note: if you are having trouble compiling all examples and this is preventing you from completing a successful build, you can use ``COLCON_IGNORE`` in the same manner as `CATKIN_IGNORE `__ to ignore the subtree or remove the folder from the workspace.
-Take for instance: you would like to avoid installing the large OpenCV library.
-Well then simply run ``touch COLCON_IGNORE`` in the ``cam2image`` demo directory to leave it out of the build process.
+.. note::
+
+ If you are having trouble compiling all examples and this is preventing you from completing a successful build, you can use the ``--packages-skip`` colcon flag to ignore the package that is causing problems.
+ For instance, if you don't want to install the large OpenCV library, you could skip building the packages that depend on it using the command:
+
+ .. code-block:: bash
+
+ colcon build --symlink-install --packages-skip image_tools intra_process_demo
Setup environment
-----------------
diff --git a/source/Installation/Alternatives/RHEL-Install-Binary.rst b/source/Installation/Alternatives/RHEL-Install-Binary.rst
index 178837c5d86..40d8ae49fb5 100644
--- a/source/Installation/Alternatives/RHEL-Install-Binary.rst
+++ b/source/Installation/Alternatives/RHEL-Install-Binary.rst
@@ -19,8 +19,6 @@ System requirements
-------------------
We currently support RHEL 9 64-bit.
-The Rolling Ridley distribution will change target platforms from time to time as new platforms are selected for development.
-Most people will want to use a stable ROS distribution.
System setup
------------
@@ -92,9 +90,7 @@ If you are going to build ROS packages or otherwise do development, you can also
Install ROS 2
-------------
-Binary releases of Rolling Ridley are not provided.
-Instead you may download nightly :ref:`prerelease binaries `.
-
+* Go to the `releases page `_
* Download the latest package for RHEL; let's assume that it ends up at ``~/Downloads/ros2-package-linux-x86_64.tar.bz2``.
* Note: there may be more than one binary download option which might cause the file name to differ.
@@ -103,9 +99,9 @@ Instead you may download nightly :ref:`prerelease binaries
.. code-block:: bash
- mkdir -p ~/ros2_{DISTRO}
- cd ~/ros2_{DISTRO}
- tar xf ~/Downloads/ros2-package-linux-x86_64.tar.bz2
+ mkdir -p ~/ros2_{DISTRO}
+ cd ~/ros2_{DISTRO}
+ tar xf ~/Downloads/ros2-package-linux-x86_64.tar.bz2
Install dependencies using rosdep
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/source/Installation/Alternatives/Ubuntu-Development-Setup.rst b/source/Installation/Alternatives/Ubuntu-Development-Setup.rst
index ccd9d4a3844..0971b4dcdd5 100644
--- a/source/Installation/Alternatives/Ubuntu-Development-Setup.rst
+++ b/source/Installation/Alternatives/Ubuntu-Development-Setup.rst
@@ -103,9 +103,14 @@ More info on working with a ROS workspace can be found in :doc:`this tutorial <.
cd ~/ros2_{DISTRO}/
colcon build --symlink-install
-Note: if you are having trouble compiling all examples and this is preventing you from completing a successful build, you can use ``COLCON_IGNORE`` in the same manner as `CATKIN_IGNORE `__ to ignore the subtree or remove the folder from the workspace.
-Take for instance: you would like to avoid installing the large OpenCV library.
-Well then simply run ``touch COLCON_IGNORE`` in the ``cam2image`` demo directory to leave it out of the build process.
+.. note::
+
+ If you are having trouble compiling all examples and this is preventing you from completing a successful build, you can use the ``--packages-skip`` colcon flag to ignore the package that is causing problems.
+ For instance, if you don't want to install the large OpenCV library, you could skip building the packages that depend on it using the command:
+
+ .. code-block:: bash
+
+ colcon build --symlink-install --packages-skip image_tools intra_process_demo
Setup environment
-----------------
@@ -150,7 +155,7 @@ Use the ROS 1 bridge (optional)
-------------------------------
The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa.
-See the dedicated `documentation `__ on how to build and use the ROS 1 bridge.
+See the dedicated :doc:`document <../../How-To-Guides/Using-ros1_bridge-Jammy-upstream>` on how to build and use the ROS 1 bridge.
Alternate compilers
-------------------
diff --git a/source/Installation/Alternatives/Ubuntu-Install-Binary.rst b/source/Installation/Alternatives/Ubuntu-Install-Binary.rst
index 52dfb95f75c..056af477197 100644
--- a/source/Installation/Alternatives/Ubuntu-Install-Binary.rst
+++ b/source/Installation/Alternatives/Ubuntu-Install-Binary.rst
@@ -23,8 +23,6 @@ System requirements
-------------------
We currently support Ubuntu Linux Jammy (22.04) 64-bit x86 and 64-bit ARM.
-The Rolling Ridley distribution will change target platforms from time to time as new platforms are selected for development.
-Most people will want to use a stable ROS distribution.
System setup
------------
@@ -55,26 +53,23 @@ If you are going to build ROS packages or otherwise do development, you can also
.. code-block:: bash
- sudo apt install ros-dev-tools
+ sudo apt update && sudo apt install ros-dev-tools
Install ROS 2
-------------
-Binary releases of Rolling Ridley are not provided.
-Instead you may download nightly :ref:`prerelease binaries `.
-
+* Go to the `releases page `_
* Download the latest package for Ubuntu; let's assume that it ends up at ``~/Downloads/ros2-package-linux-x86_64.tar.bz2``.
* Note: there may be more than one binary download option which might cause the file name to differ.
-*
- Unpack it:
+* Unpack it:
.. code-block:: bash
- mkdir -p ~/ros2_{DISTRO}
- cd ~/ros2_{DISTRO}
- tar xf ~/Downloads/ros2-package-linux-x86_64.tar.bz2
+ mkdir -p ~/ros2_{DISTRO}
+ cd ~/ros2_{DISTRO}
+ tar xf ~/Downloads/ros2-package-linux-x86_64.tar.bz2
.. _linux-install-binary-install-missing-dependencies:
@@ -89,7 +84,7 @@ Install dependencies using rosdep
sudo apt install -y python3-rosdep
sudo rosdep init
rosdep update
- rosdep install --from-paths ~/ros2_{DISTRO}/ros2-linux/share --ignore-src -y --skip-keys "cyclonedds fastcdr fastrtps rti-connext-dds-6.0.1 urdfdom_headers"
+ rosdep install --from-paths ~/ros2_{DISTRO}/ros2-linux/share --ignore-src -y --skip-keys "cyclonedds fastcdr fastrtps iceoryx_binding_c rmw_connextdds rti-connext-dds-6.0.1 urdfdom_headers"
.. include:: ../_rosdep_Linux_Mint.rst
@@ -140,7 +135,7 @@ Use the ROS 1 bridge (optional)
-------------------------------
The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa.
-See the dedicated `documentation `__ on how to build and use the ROS 1 bridge.
+See the dedicated :doc:`document <../../How-To-Guides/Using-ros1_bridge-Jammy-upstream>` on how to build and use the ROS 1 bridge.
Troubleshoot
------------
diff --git a/source/Installation/Alternatives/Windows-Development-Setup.rst b/source/Installation/Alternatives/Windows-Development-Setup.rst
index cb522d14277..6d49949fcec 100644
--- a/source/Installation/Alternatives/Windows-Development-Setup.rst
+++ b/source/Installation/Alternatives/Windows-Development-Setup.rst
@@ -43,15 +43,6 @@ Install additional Python dependencies:
pip install -U colcon-common-extensions coverage flake8 flake8-blind-except flake8-builtins flake8-class-newline flake8-comprehensions flake8-deprecated flake8-docstrings flake8-import-order flake8-quotes mock mypy==0.931 pep8 pydocstyle pytest pytest-mock vcstool
-Install miscellaneous prerequisites
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Next install xmllint:
-
-* Download the `64 bit binary archives `__ of ``libxml2`` (and its dependencies ``iconv`` and ``zlib``) from https://www.zlatkovic.com/projects/libxml/
-* Unpack all archives into e.g. ``C:\xmllint``
-* Add ``C:\xmllint\bin`` to the ``PATH``.
-
Build ROS 2
-----------
diff --git a/source/Installation/Alternatives/macOS-Development-Setup.rst b/source/Installation/Alternatives/macOS-Development-Setup.rst
index e8121b2aafe..7e09d423f83 100644
--- a/source/Installation/Alternatives/macOS-Development-Setup.rst
+++ b/source/Installation/Alternatives/macOS-Development-Setup.rst
@@ -14,8 +14,6 @@ System requirements
-------------------
We currently support macOS Mojave (10.14).
-The Rolling Ridley distribution will change target platforms from time to time as new platforms become available.
-Most people will want to use a stable ROS distribution.
System setup
------------
@@ -29,7 +27,7 @@ You need the following things installed to build ROS 2:
#.
**Xcode**
- * If you don't already have it installed, install Xcode.
+ * If you don't already have it installed, install [Xcode](https://apps.apple.com/app/xcode/id497799835).
* Note: Versions of Xcode later than 11.3.1 can no longer be installed on macOS Mojave, so you will need to install an older version manually, see: https://stackoverflow.com/a/61046761
* Also, if you don't already have it installed, install the Command Line Tools:
@@ -71,12 +69,12 @@ You need the following things installed to build ROS 2:
.. code-block:: bash
# Add the openssl dir for DDS-Security
- # if you are using ZSH, then replace '.bashrc' with '.zshrc'
- echo "export OPENSSL_ROOT_DIR=$(brew --prefix openssl)" >> ~/.bashrc
+ # if you are using BASH, then replace '.zshrc' with '.bashrc'
+ echo "export OPENSSL_ROOT_DIR=$(brew --prefix openssl)" >> ~/.zshrc
# Add the Qt directory to the PATH and CMAKE_PREFIX_PATH
- export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:/usr/local/opt/qt@5
- export PATH=$PATH:/usr/local/opt/qt@5/bin
+ export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:$(brew --prefix qt@5)
+ export PATH=$PATH:$(brew --prefix qt@5)/bin
#.
Use ``python3 -m pip`` (just ``pip`` may install Python3 or Python2) to install more stuff:
@@ -92,7 +90,7 @@ You need the following things installed to build ROS 2:
nose pep8 psutil pydocstyle pydot pygraphviz pyparsing==2.4.7 \
pytest-mock rosdep rosdistro setuptools==59.6.0 vcstool
- Please ensure that the ``$PATH`` environment variable contains the install location of the binaries (default: ``$HOME/Library/Python//bin``)
+ Please ensure that the ``$PATH`` environment variable contains the install location of the binaries (``$(brew --prefix)/bin``)
#.
*Optional*: if you want to build the ROS 1<->2 bridge, then you must also install ROS 1:
@@ -156,7 +154,7 @@ Source the ROS 2 setup file:
.. code-block:: bash
- . ~/ros2_{DISTRO}/install/setup.bash
+ . ~/ros2_{DISTRO}/install/setup.zsh
This will automatically set up the environment for any DDS vendors that support was built for.
diff --git a/source/Installation/DDS-Implementations.rst b/source/Installation/DDS-Implementations.rst
index d4b8254a8be..6e35e00ec9d 100644
--- a/source/Installation/DDS-Implementations.rst
+++ b/source/Installation/DDS-Implementations.rst
@@ -6,7 +6,7 @@ It is compatible with multiple DDS or RTPS (the DDS wire protocol) vendors.
There is currently support for eProsima's Fast DDS, RTI's Connext DDS, Eclipse Cyclone DDS, and GurumNetworks GurumDDS.
See https://ros.org/reps/rep-2000.html for supported DDS vendors by distribution.
-In Rolling, the default DDS vendor is eProsima's Fast DDS.
+The default DDS vendor is eProsima's Fast DDS.
* :doc:`Working with Eclipse Cyclone DDS ` explains how to utilize Cyclone DDS.
* :doc:`Working with eProsima Fast DDS ` explains how to utilize Fast DDS.
diff --git a/source/Installation/RHEL-Install-RPMs.rst b/source/Installation/RHEL-Install-RPMs.rst
index 76f158a9a80..384fc8bb6ec 100644
--- a/source/Installation/RHEL-Install-RPMs.rst
+++ b/source/Installation/RHEL-Install-RPMs.rst
@@ -1,14 +1,11 @@
-RHEL (RPM)
-==========
+RHEL (RPM packages)
+===================
.. contents:: Table of Contents
:depth: 2
:local:
RPM packages for ROS 2 {DISTRO_TITLE_FULL} are currently available for RHEL 9.
-The Rolling Ridley distribution will change target platforms from time to time as new platforms are selected for development.
-The target platforms are defined in `REP 2000 `__
-Most people will want to use a stable ROS distribution.
Resources
---------
diff --git a/source/Installation/Ubuntu-Install-Debians.rst b/source/Installation/Ubuntu-Install-Debians.rst
index a454942793e..c2c55dfaac9 100644
--- a/source/Installation/Ubuntu-Install-Debians.rst
+++ b/source/Installation/Ubuntu-Install-Debians.rst
@@ -2,17 +2,14 @@
Installation/Linux-Install-Debians
-Ubuntu (Debian)
-===============
+Ubuntu (Debian packages)
+========================
.. contents:: Table of Contents
:depth: 2
:local:
-Debian packages for ROS 2 {DISTRO_TITLE_FULL} are currently available for Ubuntu Jammy.
-The Rolling Ridley distribution will change target platforms from time to time as new platforms are selected for development.
-The target platforms are defined in `REP 2000 `__
-Most people will want to use a stable ROS distribution.
+Debian packages for ROS 2 {DISTRO_TITLE_FULL} are currently available for Ubuntu Jammy (22.04).
Resources
---------
@@ -45,7 +42,7 @@ If you are going to build ROS packages or otherwise do development, you can also
.. code-block:: bash
- sudo apt install ros-dev-tools
+ sudo apt update && sudo apt install ros-dev-tools
Install ROS 2
-------------
@@ -127,7 +124,7 @@ Use the ROS 1 bridge (optional)
-------------------------------
The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa.
-See the dedicated `documentation `__ on how to build and use the ROS 1 bridge.
+See the dedicated :doc:`document <../../How-To-Guides/Using-ros1_bridge-Jammy-upstream>` on how to build and use the ROS 1 bridge.
Troubleshoot
------------
diff --git a/source/Installation/Windows-Install-Binary.rst b/source/Installation/Windows-Install-Binary.rst
index 76ffb52df37..784020e0e2f 100644
--- a/source/Installation/Windows-Install-Binary.rst
+++ b/source/Installation/Windows-Install-Binary.rst
@@ -25,19 +25,17 @@ Only Windows 10 is supported.
Install ROS 2
-------------
-Binary releases of {DISTRO_TITLE_FULL} are not provided.
-Instead you may download nightly :ref:`prerelease binaries `.
-
-* Download the latest package for Windows, e.g., ``ros2-package-windows-AMD64.zip``.
+* Go to the releases page: https://github.com/ros2/ros2/releases
+* Download the latest package for Windows, e.g., ``ros2-package-windows-AMD64.zip``
.. note::
- There may be more than one binary download option which might cause the file name to differ.
+ There may be more than one binary download option which might cause the file name to differ.
.. note::
- To install debug libraries for ROS 2, see `Extra Stuff for Debug`_.
- Then continue on with downloading ``ros2-package-windows-debug-AMD64.zip``.
+ To install debug libraries for ROS 2, see `Extra Stuff for Debug`_.
+ Then continue on with downloading ``ros2-package-windows-debug-AMD64.zip``.
* Unpack the zip file somewhere (we'll assume ``C:\dev\ros2_{DISTRO}``\ ).
diff --git a/source/Installation/_Windows-Install-Prerequisites.rst b/source/Installation/_Windows-Install-Prerequisites.rst
index ca7eca6ac51..9296b248d7e 100644
--- a/source/Installation/_Windows-Install-Prerequisites.rst
+++ b/source/Installation/_Windows-Install-Prerequisites.rst
@@ -6,7 +6,7 @@ Install Chocolatey
Chocolatey is a package manager for Windows, install it by following their installation instructions:
-https://chocolatey.org/
+https://chocolatey.org/install
You'll use Chocolatey to install some other developer tools.
@@ -19,6 +19,11 @@ Open a Command Prompt and type the following to install Python via Chocolatey:
choco install -y python --version 3.8.3
+.. note::
+
+ Chocolatey will install Python in ``C:\Python38``, and the rest of the installation expects it to be there.
+ If you've installed Python somewhere else, you must copy or link it to that location.
+
Install Visual C++ Redistributables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -32,7 +37,7 @@ Install OpenSSL
^^^^^^^^^^^^^^^
Download the *Win64 OpenSSL v1.1.1n* OpenSSL installer from `this page `__.
-Scroll to the bottom of the page and download *Win64 OpenSSL v1.1.1n*.
+Scroll to the bottom of the page and download *Win64 OpenSSL v1.1.1t*.
Don't download the Win32 or Light versions, or the v3.X.Y installers.
Run the installer with default parameters, as the following commands assume you used the default installation directory.
@@ -126,6 +131,15 @@ Now install some additional python dependencies:
python -m pip install -U catkin_pkg cryptography empy importlib-metadata jsonschema lark==1.1.1 lxml matplotlib netifaces numpy opencv-python PyQt5 pillow psutil pycairo pydot pyparsing==2.4.7 pyyaml rosdistro
+Install miscellaneous prerequisites
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Next install xmllint:
+
+* Download the `64 bit binary archives `__ of ``libxml2`` (and its dependencies ``iconv`` and ``zlib``) from https://www.zlatkovic.com/projects/libxml/
+* Unpack all archives into e.g. ``C:\xmllint``
+* Add ``C:\xmllint\bin`` to the ``PATH``.
+
Install Qt5
^^^^^^^^^^^
diff --git a/source/Related-Projects/Intel-ROS2-Projects.rst b/source/Related-Projects/Intel-ROS2-Projects.rst
index c5ea1b57003..bac7ae8ad6d 100644
--- a/source/Related-Projects/Intel-ROS2-Projects.rst
+++ b/source/Related-Projects/Intel-ROS2-Projects.rst
@@ -13,7 +13,7 @@ Key Projects
We are working on below ROS 2 projects and publish source code through https://github.com/intel/ or ROS 2 GitHub repo gradually.
* `ROS2 OpenVINO `__: ROS 2 package for Intel® Visual Inference and Neural Network Optimization Toolkit to develop multiplatform computer vision solutions.
-* `ROS2 RealSense Camera `__: ROS 2 package for Intel® RealSense™ D400 serial cameras
+* `ROS2 RealSense Camera `__: ROS 2 package for Intel® RealSense™ D400 serial cameras
* `ROS2 Movidius NCS `__: ROS 2 package for object detection with Intel® Movidius™ Neural Computing Stick (NCS).
* `ROS2 Object Messages `__: ROS 2 messages for object.
* `ROS2 Object Analytics `__: ROS 2 package for object detection, tracking and 2D/3D localization.
diff --git a/source/Releases.rst b/source/Releases.rst
index dae1d92d8da..df131a49aa3 100644
--- a/source/Releases.rst
+++ b/source/Releases.rst
@@ -23,12 +23,12 @@ Rows in the table marked in green are the currently supported distributions.
.. toctree::
:hidden:
- Releases/Release-Humble-Hawksbill.rst
- Releases/Release-Foxy-Fitzroy.rst
- Releases/Release-Rolling-Ridley.rst
- Releases/Development.rst
- Releases/End-of-Life.rst
- Releases/Release-Process.rst
+ Releases/Release-Iron-Irwini
+ Releases/Release-Humble-Hawksbill
+ Releases/Release-Rolling-Ridley
+ Releases/Development
+ Releases/End-of-Life
+ Releases/Release-Process
.. raw:: html
@@ -47,12 +47,15 @@ Rows in the table marked in green are the currently supported distributions.
-->
.. |rolling| image:: Releases/rolling-small.png
:alt: Rolling logo
+.. |iron| image:: Releases/iron-small.png
+ :alt: Iron logo
+
.. |humble| image:: Releases/humble-small.png
:alt: Humble logo
@@ -86,6 +89,10 @@ Rows in the table marked in green are the currently supported distributions.
- Release date
- Logo
- EOL date
+ * - :doc:`Iron Irwini `
+ - May 23rd, 2023
+ - |iron|
+ - November 2024
* - :doc:`Humble Hawksbill `
- May 23rd, 2022
- |humble|
@@ -97,7 +104,7 @@ Rows in the table marked in green are the currently supported distributions.
* - :doc:`Foxy Fitzroy `
- June 5th, 2020
- |foxy|
- - May 2023
+ - June 20th, 2023
* - :doc:`Eloquent Elusor `
- November 22nd, 2019
- |eloquent|
@@ -145,17 +152,17 @@ There is a new ROS 2 distribution released yearly on May 23rd (`World Turtle Day
.. list-table::
:class: future-distros
:header-rows: 1
- :widths: 30 40 30
+ :widths: 35 30 20 15
* - Distro
- Release date
- - Supported until
- * - :doc:`Iron Irwini `
- - May 2023
- - November 2024
-
+ - Logo
+ - EOL date
+ * - :doc:`Jazzy Jalisco `
+ - May 2024
+ - TBD
+ - May 2029
-The expectation is to release new ROS 2 distributions once per year.
.. _rolling_distribution:
diff --git a/source/Releases/Alpha-Overview.rst b/source/Releases/Alpha-Overview.rst
index 57a45971d34..514cec769ed 100644
--- a/source/Releases/Alpha-Overview.rst
+++ b/source/Releases/Alpha-Overview.rst
@@ -19,7 +19,7 @@ ROS 2 alpha8 release (code name *Hook-and-Loop*; October 2016)
Changes to supported DDS vendors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-ROS 2 supports multiple middleware implementations (see `this page <../../Concepts/About-Different-Middleware-Vendors>` for more details).
+ROS 2 supports multiple middleware implementations (see `this page <../../Concepts/Intermediate/About-Different-Middleware-Vendors>` for more details).
Until Alpha 8, ROS 2 was supporting ROS middleware implementations for eProsima's Fast RTPS, RTI's Connext and PrismTech's OpenSplice.
To streamline our efforts, as of Alpha 8, Fast RTPS and Connext (static) will be supported, with Fast RTPS (`now Apache 2.0-licensed `__) shipped as the default.
diff --git a/source/Releases/Beta2-Overview.rst b/source/Releases/Beta2-Overview.rst
index d7fe1e8a9f9..abadccc06a0 100644
--- a/source/Releases/Beta2-Overview.rst
+++ b/source/Releases/Beta2-Overview.rst
@@ -25,7 +25,7 @@ Improvements since Beta 1 release
* Debian packages for Ubuntu Xenial
* Typesupport has been redesigned so that you only build a single executable and can choose one of the available RMW implementations by setting an environment variable (see `documentation <../../How-To-Guides/Working-with-multiple-RMW-implementations>`).
* Namespace support for nodes and topics (see `design article `__, see known issues below).
-* A set of command-line tools using the extensible ``ros2`` command (see `conceptual article <../../Concepts/About-Command-Line-Tools>`).
+* A set of command-line tools using the extensible ``ros2`` command (see `conceptual article <../../Concepts/Basic/About-Command-Line-Tools>`).
* A set of macros for logging messages in C / C++ (see API docs of `rcutils `__).
New demo application
diff --git a/source/Releases/Development.rst b/source/Releases/Development.rst
index a4bc93ef673..727fb4e0c38 100644
--- a/source/Releases/Development.rst
+++ b/source/Releases/Development.rst
@@ -6,5 +6,4 @@ Below is the ROS 2 distribution that is currently in development.
.. toctree::
:maxdepth: 1
- Release-Iron-Irwini.rst
- Iron-Irwini-Complete-Changelog.rst
+ Release-Jazzy-Jalisco
diff --git a/source/Releases/End-of-Life.rst b/source/Releases/End-of-Life.rst
index 71248ddf249..3e3bcce8ddf 100644
--- a/source/Releases/End-of-Life.rst
+++ b/source/Releases/End-of-Life.rst
@@ -6,13 +6,14 @@ Below is a list of historic ROS 2 distributions that are no longer supported.
.. toctree::
:maxdepth: 1
- Release-Galactic-Geochelone.rst
- Release-Eloquent-Elusor.rst
- Release-Dashing-Diademata.rst
- Release-Crystal-Clemmys.rst
- Release-Bouncy-Bolson.rst
- Release-Ardent-Apalone.rst
- Beta3-Overview.rst
- Beta2-Overview.rst
- Beta1-Overview.rst
- Alpha-Overview.rst
+ Release-Galactic-Geochelone
+ Release-Foxy-Fitzroy
+ Release-Eloquent-Elusor
+ Release-Dashing-Diademata
+ Release-Crystal-Clemmys
+ Release-Bouncy-Bolson
+ Release-Ardent-Apalone
+ Beta3-Overview
+ Beta2-Overview
+ Beta1-Overview
+ Alpha-Overview
diff --git a/source/Releases/Iron-Irwini-Complete-Changelog.rst b/source/Releases/Iron-Irwini-Complete-Changelog.rst
index cc2eeb4c74a..cfc49ec504f 100644
--- a/source/Releases/Iron-Irwini-Complete-Changelog.rst
+++ b/source/Releases/Iron-Irwini-Complete-Changelog.rst
@@ -1,14 +1,14 @@
-ROS 2 Iron Irwini Complete Changelog
-====================================
+Iron Irwini Changelog
+=====================
This page is a list of the complete changes in all ROS 2 core packages since the previous release.
.. contents:: Table of Contents
:local:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`action_msgs `__
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+`action_msgs `__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Update common_interfaces to C++17. (`#215 `__) (`#151 `__)
* Add service_msgs package (`#143 `__)
@@ -17,10 +17,11 @@ This page is a list of the complete changes in all ROS 2 core packages since the
* Contributors: Audrow Nash, Brian, Chris Lalancette, Jacob Perron
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`action_tutorials_cpp `__
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+`action_tutorials_cpp `__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Change all ROS2 -> ROS 2. (`#610 `__)
* Update the demos to C++17. (`#594 `__)
* Add README's for action_tutorials. (`#576 `__)
* [rolling] Update maintainers - 2022-11-07 (`#589 `__)
@@ -28,10 +29,11 @@ This page is a list of the complete changes in all ROS 2 core packages since the
* Contributors: Audrow Nash, Chris Lalancette, kagibson
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`action_tutorials_interfaces `__
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+`action_tutorials_interfaces `__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Change all ROS2 -> ROS 2. (`#610 `__)
* A couple more upgrades to C++17. (`#609 `__)
* Add README's for action_tutorials. (`#576 `__)
* [rolling] Update maintainers - 2022-11-07 (`#589 `__)
@@ -39,27 +41,27 @@ This page is a list of the complete changes in all ROS 2 core packages since the
* Contributors: Audrow Nash, Chris Lalancette, Jacob Perron, kagibson
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`action_tutorials_py `__
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+`action_tutorials_py `__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Add README's for action_tutorials. (`#576 `__)
* [rolling] Update maintainers - 2022-11-07 (`#589 `__)
* Contributors: Audrow Nash, kagibson
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`actionlib_msgs `__
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+`actionlib_msgs `__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Update common_interfaces to C++17. (`#215 `__)
* [rolling] Update maintainers - 2022-11-07 (`#210