Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Action Clients
==============

.. include:: the_topic_is_under_heavy_construction.rst
.. include:: ../the_topic_is_under_heavy_construction.rst

.. versionadded:: Jazzy

Expand Down Expand Up @@ -70,9 +70,9 @@ Action Client
#. Create the Node with an :code:`ActionClient`.
#. Update the :file:`setup.py` so that :program:`ros2 run` finds the node (if needed).

:download:`move_straight_in_2d_action_client_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py>`
:download:`move_straight_in_2d_action_client_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py>`

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
:language: python
:lines: 24-
:linenos:
Expand All @@ -87,7 +87,7 @@ In the action client, we will have to manage two instances of :code:`Future`. On
It is important to keep them as attributes
of the instance to guarantee they will not get out of scope before the result is obtained. This is done as follows.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
:language: python
:lines: 37-45
:emphasize-lines: 4,7,8
Expand All @@ -102,7 +102,7 @@ Whenever a feedback is sent, the method we assign as callback will be called.
After we send the goal request and assign a callback for the feedback, we assign another callback. This second callback
is for the result of the goal request operation.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
:language: python
:lines: 47-57
:emphasize-lines: 1,5,10,11
Expand All @@ -113,21 +113,21 @@ to ask for a result.

We ask for a result asynchronously. We then assign a third callback for when a response is sent.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
:language: python
:lines: 59-68
:emphasize-lines: 1,4,9,10

The result callback will receive a future and process the result of the action somehow. In this toy example, we simply
print the results to the screen.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
:language: python
:lines: 70-72

Lastly, we see that the callback for the feedback is, again, very similar to that for a subscriber.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
:language: python
:lines: 74-76

Expand All @@ -137,7 +137,7 @@ the action is triggered only once.
When doing so, please remember to call the action after the node is instantiated and before :code:`rclpy.spin()`. Otherwise,
the object will not yet exist, or you will be locked in the spinner before sending the goal.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py
:language: python
:lines: 87-95

Expand All @@ -146,7 +146,7 @@ Build and source

Before we proceed, let us build and source once.

.. include:: the_canonical_build_command.rst
.. include:: ../the_canonical_build_command.rst

Testing the Action Client
-------------------------
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Action Servers
==============

.. include:: the_topic_is_under_heavy_construction.rst
.. include:: ../the_topic_is_under_heavy_construction.rst

.. versionadded:: Jazzy

Expand Down Expand Up @@ -72,9 +72,9 @@ In this section, we will do the following.

Let us create the action server as follows.

:download:`move_straight_in_2d_action_server_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py>`
:download:`move_straight_in_2d_action_server_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py>`

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
:language: python
:lines: 24-
:linenos:
Expand All @@ -84,7 +84,7 @@ As always, our class must inherit from :code:`rclpy.node.Node`, so that it can b
An action server is an instance of :code:`rclpy.action.ActionServer`.
As input to the initializer of :code:`ActionServer`, we need an action, a string that names this action server, and a suitable callback.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
:language: python
:lines: 37-50
:emphasize-lines: 1, 10
Expand All @@ -107,7 +107,7 @@ not set a goal as succeeded, it will automatically be aborted at the end of the
Lastly, the method must return an instance of :code:`MyAction.Result`. In our case, we have the field :code:`final_position`
in the action file description, therefore we populate it as needed.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
:language: python
:lines: 85-116
:emphasize-lines: 1, 7, 12, 18, 24, 30, 32
Expand All @@ -116,15 +116,15 @@ The other methods are to support the important aspects of the action server. The
the Euclidean distance between :code:`current_position` and :code:`desired_position`. Remember :ref:`The distance equation <eq:actions_distance>`.
This is represented by the following piece of code.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
:language: python
:lines: 54-65
:emphasize-lines: 1, 12

The action server will update the :code:`current_position` based on a simple constant speed motion of the point.
Remember :ref:`The controller equation <eq:actions_controller>`. This is represented by the following piece of code.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py
:language: python
:lines: 67-82

Expand All @@ -137,7 +137,7 @@ Adjusting the :file:`setup.py`

This file will include the directives for the server and client. The one for the server is highlighted below.

.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/setup.py
.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/setup.py
:language: python
:emphasize-lines: 23

Expand All @@ -146,7 +146,7 @@ Build and source

Before we proceed, let us build and source once.

.. include:: the_canonical_build_command.rst
.. include:: ../the_canonical_build_command.rst

Testing the Action Server
-------------------------
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Call for Actions: Action Servers and Clients
============================================

.. include:: the_topic_is_under_heavy_construction.rst
.. include:: ../the_topic_is_under_heavy_construction.rst

.. versionadded:: Jazzy

Expand Down
33 changes: 32 additions & 1 deletion docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,42 @@
'sphinx_design', # https://sphinx-design.readthedocs.io/en/latest/get_started.html
'sphinxext.remoteliteralinclude', # https://github.com/wpilibsuite/sphinxext-remoteliteralinclude
'sphinxcontrib.mermaid', #https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/
'sphinxcontrib.bibtex' #https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html
'sphinxcontrib.bibtex', #https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html
'sphinx_reredirects' #https://gitlab.com/jborean93/sphinx-reredirects
]

bibtex_bibfiles = ['refs.bib']

# Old page locations from the topic-directory reorganisation (the pages were
# git mv'ed into per-topic folders, e.g. installation -> setup/installation).
# sphinx_reredirects emits meta-refresh pages for these during the html build.
redirects = {
'installation': 'setup/installation',
'terminator': 'setup/terminator',
'workspace_setup': 'setup/workspace_setup',
'create_packages': 'packages/create_packages',
'create_python_package': 'packages/create_python_package',
'create_python_node_with_template': 'packages/create_python_node_with_template',
'source_after_build': 'packages/source_after_build',
'running_node': 'packages/running_node',
'create_python_node_from_scratch': 'python_node/create_python_node_from_scratch',
'python_node_explained': 'python_node/python_node_explained',
'create_python_library': 'python_library/create_python_library',
'using_python_library': 'python_library/using_python_library',
'interfaces': 'interfaces/interfaces',
'create_interface_package': 'interfaces/create_interface_package',
'publishers_and_subscribers': 'messages/publishers_and_subscribers',
'inspecting_topics': 'messages/inspecting_topics',
'parameters_and_launch': 'parameters_and_launch/parameters_and_launch',
'launch_configurable_nodes': 'parameters_and_launch/launch_configurable_nodes',
'inspecting_parameters': 'parameters_and_launch/inspecting_parameters',
'service_servers_and_clients': 'services/service_servers_and_clients',
'inspecting_services': 'services/inspecting_services',
'actions': 'actions/actions',
'action_servers': 'actions/action_servers',
'action_clients': 'actions/action_clients',
}

intersphinx_mapping = {
'python': ('https://docs.python.org/3.12/', None),
'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
Expand Down
68 changes: 34 additions & 34 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ These tutorials have been the backbone of `EEEN62021 Software for Robotics <http

🤟 **Using this tutorial**

This is a tutorial that supposes that the user will follow it linearly. Some readers can skip the :doc:`Preamble <preamble/ubuntu>` if they are somewhat already comfortable in Python and Ubuntu. Otherwise, all steps can be considered as dependent on the prior ones, starting from :doc:`ROS2 Setup <installation>`.
This is a tutorial that supposes that the user will follow it linearly. Some readers can skip the :doc:`Preamble <preamble/ubuntu>` if they are somewhat already comfortable in Python and Ubuntu. Otherwise, all steps can be considered as dependent on the prior ones, starting from :doc:`ROS2 Setup <setup/installation>`.

It is expected that the user will be working directly on an Ubuntu machine. :program:`Docker` images are available but no compatibility with host systems other than Ubuntu has been attempted.

Expand All @@ -57,31 +57,31 @@ If you enjoyed this tutorial, please
#. :doc:`Preamble: Python Best Practices <preamble/python/python_best_practices>`
A quick memory refresher for the Python stuff useful in ROS2.

#. :doc:`ROS2 Setup <installation>` (⭐start here⭐)
#. :doc:`ROS2 Setup <setup/installation>` (⭐start here⭐)
Installing ROS2 and setting up its environment for use.

#. :doc:`ROS2 Python Package/Build <create_packages>`
#. :doc:`ROS2 Python Package/Build <packages/create_packages>`
Creating our first ROS2 package with :program:`ament_python` and building it with :program:`colcon`.

#. :doc:`ROS2 Python Node <running_node>`
#. :doc:`ROS2 Python Node <packages/running_node>`
Creating ``rclpy`` Nodes and figuring out what all that means.

#. :doc:`ROS2 Python Library <create_python_library>`
#. :doc:`ROS2 Python Library <python_library/create_python_library>`
Create Python libraries and importing/using them in another :program:`ament_python` package.

#. :doc:`ROS2 Interfaces <interfaces>`
#. :doc:`ROS2 Interfaces <interfaces/interfaces>`
ROS2 interfaces, i.e., messages ``.msg``, services ``.srv``, and actions ``.action``. Creating custom interface packages with :program:`ament_cmake`.

#. :doc:`ROS2 Messages in Python <publishers_and_subscribers>`
#. :doc:`ROS2 Messages in Python <messages/publishers_and_subscribers>`
Writing and using ROS2 messages, publishers, and subscribers.

#. :doc:`ROS2 Parameter/Launch <parameters_and_launch>`
#. :doc:`ROS2 Parameter/Launch <parameters_and_launch/parameters_and_launch>`
Making configurable ROS2 Nodes using parameters and launch files.

#. :doc:`ROS2 Services in Python <service_servers_and_clients>`
#. :doc:`ROS2 Services in Python <services/service_servers_and_clients>`
Writing ROS2 services, service servers, and service clients.

#. :doc:`ROS2 Actions in Python <actions>`
#. :doc:`ROS2 Actions in Python <actions/actions>`
Writing ROS2 actions, action servers, and action clients.

#. :doc:`Frame Transformations <transformations/index>`
Expand Down Expand Up @@ -112,78 +112,78 @@ If you enjoyed this tutorial, please
:maxdepth: 2
:hidden:

installation
terminator
workspace_setup
setup/installation
setup/terminator
setup/workspace_setup

.. toctree::
:caption: ROS2 Python Package/Build
:maxdepth: 2
:hidden:

create_packages
create_python_package
create_python_node_with_template
source_after_build
running_node
packages/create_packages
packages/create_python_package
packages/create_python_node_with_template
packages/source_after_build
packages/running_node

.. toctree::
:caption: ROS2 Python Node
:maxdepth: 2
:hidden:

create_python_node_from_scratch
python_node_explained
python_node/create_python_node_from_scratch
python_node/python_node_explained

.. toctree::
:caption: ROS2 Python Library
:maxdepth: 2
:hidden:

create_python_library
using_python_library
python_library/create_python_library
python_library/using_python_library

.. toctree::
:caption: ROS2 Interfaces: Messages, Services, and Actions
:maxdepth: 2
:hidden:

interfaces
create_interface_package
interfaces/interfaces
interfaces/create_interface_package

.. toctree::
:caption: ROS2 Messages in Python
:maxdepth: 2
:hidden:

publishers_and_subscribers
inspecting_topics
messages/publishers_and_subscribers
messages/inspecting_topics

.. toctree::
:caption: ROS2 Parameter/Launch
:maxdepth: 2
:hidden:

parameters_and_launch
launch_configurable_nodes
inspecting_parameters
parameters_and_launch/parameters_and_launch
parameters_and_launch/launch_configurable_nodes
parameters_and_launch/inspecting_parameters

.. toctree::
:caption: ROS2 Services in Python
:maxdepth: 2
:hidden:

service_servers_and_clients
inspecting_services
services/service_servers_and_clients
services/inspecting_services

.. toctree::
:caption: ROS2 Actions in Python
:maxdepth: 2
:hidden:

actions
action_servers
action_clients
actions/actions
actions/action_servers
actions/action_clients

.. toctree::
:caption: Frame transformations and tf2
Expand Down
Loading