Skip to content

Commit b499248

Browse files
saikishorsaikishor
committed
move the documentation to introspection.rst
1 parent a5d8c60 commit b499248

File tree

3 files changed

+90
-89
lines changed

3 files changed

+90
-89
lines changed

‎doc/debugging.rst‎

Lines changed: 0 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -79,92 +79,3 @@ References
7979
* `ROS 2 and GDB <https://juraph.com/miscellaneous/ros2_and_gdb/>`_
8080
* `Using GDB to debug a plugin <https://stackoverflow.com/questions/10919832/how-to-use-gdb-to-debug-a-plugin>`_
8181
* `GDB CLI Tutorial <https://www.cs.umd.edu/~srhuang/teaching/cmsc212/gdb-tutorial-handout.pdf>`_
82-
83-
Introspection and Debugging of the ros2_control setup
84-
******************************************************
85-
86-
With the integration of the ``pal_statistics`` package, the ``controller_manager`` node publishes the registered variables within the same process to the ``~/introspection_data`` topics.
87-
By default, all ``State`` and ``Command`` interfaces in the ``controller_manager`` are registered when they are added, and are unregistered when they are removed from the ``ResourceManager``.
88-
The state of the all the registered entities are published at the end of every ``update`` cycle of the ``controller_manager``. For instance, In a complete synchronous ros2_control setup (with synchronous controllers and hardware components), this data in the ``Command`` interface is the command used by the hardware components to command the hardware.
89-
90-
All the registered variables are published over 3 topics: ``~/introspection_data/full``, ``~/introspection_data/names``, and ``~/introspection_data/values``.
91-
- The ``~/introspection_data/full`` topic publishes the full introspection data along with names and values in a single message. This can be useful to track or view variables and information from command line.
92-
- The ``~/introspection_data/names`` topic publishes the names of the registered variables. This topic contains the names of the variables registered. This is only published every time a a variables is registered and unregistered.
93-
- The ``~/introspection_data/values`` topic publishes the values of the registered variables. This topic contains the values of the variables registered.
94-
95-
The topics ``~/introspection_data/full`` and ``~/introspection_data/values`` are always published on every update cycle asynchronously, provided that there is at least one subscriber to these topics.
96-
97-
The topic ``~/introspection_data/full`` can be used to integrate with your custom visualization tools or to track the variables from the command line. The topic ``~/introspection_data/names`` and ``~/introspection_data/values`` are to be used for visualization tools like `PlotJuggler <https://plotjuggler.io/>`_ to visualize the data.
98-
99-
.. note::
100-
If you have a high frequency of data, it is recommended to use the ``~/introspection_data/names`` and ``~/introspection_data/values`` topic. So, that the data transferred and stored is minimized.
101-
102-
How to introspect internal variables of controllers and hardware components
103-
============================================================================
104-
105-
Any member variable of a controller or hardware component can be registered for the introspection. It is very important that the lifetime of this variable exists as long as the controller or hardware component is available.
106-
107-
.. note::
108-
If a variable's lifetime is not properly managed, it may be attempted to read, which in the worst case scenario will cause a segmentation fault.
109-
110-
How to register a variable for introspection
111-
---------------------------------------------
112-
113-
1. Include the necessary headers in the controller or hardware component header file.
114-
115-
.. code-block:: cpp
116-
117-
#include <hardware_interface/introspection.hpp>
118-
119-
2. Register the variable in the configure method of the controller or hardware component.
120-
121-
.. code-block:: cpp
122-
123-
void MyController::on_configure()
124-
{
125-
...
126-
// Register the variable for introspection
127-
REGISTER_ROS2_CONTROL_INTROSPECTION("my_variable_name", &my_variable_);
128-
...
129-
}
130-
131-
3. By default, The introspection of all the registered variables of the controllers and the hardware components is only activated, when they are active and it is deactivated when the controller or hardware component is deactivated.
132-
133-
.. code-block:: cpp
134-
135-
void MyController::on_configure()
136-
{
137-
...
138-
// Register the variable for introspection
139-
REGISTER_ROS2_CONTROL_INTROSPECTION("my_variable_name", &my_variable_, true);
140-
...
141-
}
142-
143-
.. note::
144-
If you want to keep the introspection active even when the controller or hardware component is not active, you can do that by calling ``this->enable_introspection(true)`` in the ``on_configure`` and ``on_deactivate`` method of the controller or hardware component after registering the variables.
145-
146-
Types of entities that can be introspected
147-
-------------------------------------------
148-
149-
- Any variable that can be cast to a double is suitable for registration.
150-
- A function that returns a value that can be cast to a double is also suitable for registration.
151-
- Variables of complex structures can be registered by having defined introspection for its every internal variable.
152-
- Introspection of custom types can be done by defining a `custom introspection function <https://github.com/pal-robotics/pal_statistics/blob/humble-devel/pal_statistics/include/pal_statistics/registration_utils.hpp>`_.
153-
154-
.. note::
155-
Registering the variables for introspection is not real-time safe. It is recommended to register the variables in the ``on_configure`` method only.
156-
157-
Data Visualization
158-
*******************
159-
160-
Data can be visualized with any tools that display ROS topics, but we recommend `PlotJuggler <https://plotjuggler.io/>`_ for viewing high resolution live data, or data in bags.
161-
162-
1. Open ``PlotJuggler`` running ``ros2 run plotjuggler plotjuggler``.
163-
.. image:: images/plotjuggler.png
164-
2. Visualize the data:
165-
- Importing from the ros2bag
166-
- Subscribing to the ROS2 topics live with the ``ROS2 Topic Subscriber`` option under ``Streaming`` header.
167-
3. Choose the topics ``~/introspection_data/names`` and ``~/introspection_data/values`` from the popup window.
168-
.. image:: images/plotjuggler_select_topics.png
169-
4. Now, select the variables that are of your interest and drag them to the plot.
170-
.. image:: images/plotjuggler_visualizing_data.png

‎doc/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,4 @@ Guidelines and Best Practices
3737
:titlesonly:
3838

3939
Debugging the Controller Manager and Plugins <debugging.rst>
40+
Introspecting Controllers and Hardware Components <introspection.rst>

‎doc/introspection.rst‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
2+
Introspection of the ros2_control setup
3+
***************************************
4+
5+
With the integration of the ``pal_statistics`` package, the ``controller_manager`` node publishes the registered variables within the same process to the ``~/introspection_data`` topics.
6+
By default, all ``State`` and ``Command`` interfaces in the ``controller_manager`` are registered when they are added, and are unregistered when they are removed from the ``ResourceManager``.
7+
The state of the all the registered entities are published at the end of every ``update`` cycle of the ``controller_manager``. For instance, In a complete synchronous ros2_control setup (with synchronous controllers and hardware components), this data in the ``Command`` interface is the command used by the hardware components to command the hardware.
8+
9+
All the registered variables are published over 3 topics: ``~/introspection_data/full``, ``~/introspection_data/names``, and ``~/introspection_data/values``.
10+
- The ``~/introspection_data/full`` topic publishes the full introspection data along with names and values in a single message. This can be useful to track or view variables and information from command line.
11+
- The ``~/introspection_data/names`` topic publishes the names of the registered variables. This topic contains the names of the variables registered. This is only published every time a a variables is registered and unregistered.
12+
- The ``~/introspection_data/values`` topic publishes the values of the registered variables. This topic contains the values of the variables registered.
13+
14+
The topics ``~/introspection_data/full`` and ``~/introspection_data/values`` are always published on every update cycle asynchronously, provided that there is at least one subscriber to these topics.
15+
16+
The topic ``~/introspection_data/full`` can be used to integrate with your custom visualization tools or to track the variables from the command line. The topic ``~/introspection_data/names`` and ``~/introspection_data/values`` are to be used for visualization tools like `PlotJuggler <https://plotjuggler.io/>`_ to visualize the data.
17+
18+
.. note::
19+
If you have a high frequency of data, it is recommended to use the ``~/introspection_data/names`` and ``~/introspection_data/values`` topic. So, that the data transferred and stored is minimized.
20+
21+
How to introspect internal variables of controllers and hardware components
22+
============================================================================
23+
24+
Any member variable of a controller or hardware component can be registered for the introspection. It is very important that the lifetime of this variable exists as long as the controller or hardware component is available.
25+
26+
.. note::
27+
If a variable's lifetime is not properly managed, it may be attempted to read, which in the worst case scenario will cause a segmentation fault.
28+
29+
How to register a variable for introspection
30+
---------------------------------------------
31+
32+
1. Include the necessary headers in the controller or hardware component header file.
33+
34+
.. code-block:: cpp
35+
36+
#include <hardware_interface/introspection.hpp>
37+
38+
2. Register the variable in the configure method of the controller or hardware component.
39+
40+
.. code-block:: cpp
41+
42+
void MyController::on_configure()
43+
{
44+
...
45+
// Register the variable for introspection
46+
REGISTER_ROS2_CONTROL_INTROSPECTION("my_variable_name", &my_variable_);
47+
...
48+
}
49+
50+
3. By default, The introspection of all the registered variables of the controllers and the hardware components is only activated, when they are active and it is deactivated when the controller or hardware component is deactivated.
51+
52+
.. code-block:: cpp
53+
54+
void MyController::on_configure()
55+
{
56+
...
57+
// Register the variable for introspection
58+
REGISTER_ROS2_CONTROL_INTROSPECTION("my_variable_name", &my_variable_, true);
59+
...
60+
}
61+
62+
.. note::
63+
If you want to keep the introspection active even when the controller or hardware component is not active, you can do that by calling ``this->enable_introspection(true)`` in the ``on_configure`` and ``on_deactivate`` method of the controller or hardware component after registering the variables.
64+
65+
Types of entities that can be introspected
66+
-------------------------------------------
67+
68+
- Any variable that can be cast to a double is suitable for registration.
69+
- A function that returns a value that can be cast to a double is also suitable for registration.
70+
- Variables of complex structures can be registered by having defined introspection for its every internal variable.
71+
- Introspection of custom types can be done by defining a `custom introspection function <https://github.com/pal-robotics/pal_statistics/blob/humble-devel/pal_statistics/include/pal_statistics/registration_utils.hpp>`_.
72+
73+
.. note::
74+
Registering the variables for introspection is not real-time safe. It is recommended to register the variables in the ``on_configure`` method only.
75+
76+
Data Visualization
77+
*******************
78+
79+
Data can be visualized with any tools that display ROS topics, but we recommend `PlotJuggler <https://plotjuggler.io/>`_ for viewing high resolution live data, or data in bags.
80+
81+
1. Open ``PlotJuggler`` running ``ros2 run plotjuggler plotjuggler``.
82+
.. image:: images/plotjuggler.png
83+
2. Visualize the data:
84+
- Importing from the ros2bag
85+
- Subscribing to the ROS2 topics live with the ``ROS2 Topic Subscriber`` option under ``Streaming`` header.
86+
3. Choose the topics ``~/introspection_data/names`` and ``~/introspection_data/values`` from the popup window.
87+
.. image:: images/plotjuggler_select_topics.png
88+
4. Now, select the variables that are of your interest and drag them to the plot.
89+
.. image:: images/plotjuggler_visualizing_data.png

0 commit comments

Comments
 (0)