Skip to content

Commit 514e85b

Browse files
ajtudelaSteveMacenski
ajtudela
and
SteveMacenski
authored
Following (#787)
* Added following server doc Signed-off-by: Alberto Tudela <ajtudela@gmail.com> * Update configuration/packages/configuring-following-server.rst Co-authored-by: Steve Macenski <stevenmacenski@gmail.com> Signed-off-by: Alberto Tudela <ajtudela@gmail.com> * Update tutorials/docs/navigation2_dynamic_point_following.rst Co-authored-by: Steve Macenski <stevenmacenski@gmail.com> Signed-off-by: Alberto Tudela <ajtudela@gmail.com> * Update links Signed-off-by: Alberto Tudela <ajtudela@gmail.com> * Update migration guide Signed-off-by: Alberto Tudela <ajtudela@gmail.com> * Added functions to the Simple Commander API Signed-off-by: Alberto Tudela <ajtudela@gmail.com> --------- Signed-off-by: Alberto Tudela <ajtudela@gmail.com> Co-authored-by: Steve Macenski <stevenmacenski@gmail.com>
1 parent 2ddefca commit 514e85b

5 files changed

Lines changed: 371 additions & 9 deletions

File tree

‎commander_api/index.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,12 @@ New as of September 2023: the simple navigator constructor will accept a `namesp
147147
+---------------------------------------+----------------------------------------------------------------------------+
148148
| toggleCollisionMonitor(enable) | Toggles the collision monitor on (`True`) or off (`False`). |
149149
+---------------------------------------+----------------------------------------------------------------------------+
150+
| followObjectByTopic(topic, | Requests the robot to follow an object by subscribing to a given topic. |
151+
| max_duration=0) | |
152+
+---------------------------------------+----------------------------------------------------------------------------+
153+
| followObjectByFrame(frame, | Requests the robot to follow an object by a given frame. |
154+
| max_duration=0) | |
155+
+---------------------------------------+----------------------------------------------------------------------------+
150156
| waitUntilNav2Active( | Blocks until Nav2 is completely online and lifecycle nodes are in the |
151157
| navigator='bt_navigator', | active state. To be used in conjunction with autostart or external |
152158
| localizer='amcl') | lifecycle bringup. Custom navigator and localizer nodes can be specified |

‎configuration/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,4 +67,5 @@ Others
6767

6868
packages/configuring-amcl.rst
6969
packages/configuring-coverage-server.rst
70+
packages/configuring-following-server.rst
7071
packages/configuring-loopback-sim.rst

‎configuration/packages/configuring-following-server.rst‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
.. _configuring_following_server:
2+
3+
Following Server
4+
################
5+
6+
Source code on Github_.
7+
8+
.. _Github: https://github.com/ros-navigation/navigation2/nav2_following/opennav_following
9+
10+
The Following Server in ``opennav_following`` implements a server for following dynamic objects from a detection topic or specific reference frame.
11+
This server allows the robot to follow and maintain a determined distance from a detected object or specific frame,
12+
using topic-based detection techniques or coordinate frame tracking.
13+
The server is designed to be called by a BT application or autonomy application to follow moving objects.
14+
15+
.. raw:: html
16+
17+
<h1 align="center">
18+
<div style="position: relative; padding-bottom: 0%; overflow: hidden; max-width: 100%; height: auto;">
19+
<iframe width="700" height="450" src="https://www.youtube.com/embed/g-g58J1g9Ww?autoplay=1" frameborder="1" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
20+
</div>
21+
</h1>
22+
23+
Parameters
24+
**********
25+
26+
:controller_frequency:
27+
28+
============== ==============
29+
Type Default
30+
-------------- --------------
31+
double 50.0
32+
============== ==============
33+
34+
Description
35+
Control frequency (Hz) for the following control loop.
36+
37+
:detection_timeout:
38+
39+
============== ==============
40+
Type Default
41+
-------------- --------------
42+
double 2.0
43+
============== ==============
44+
45+
Description
46+
Timeout (s) to wait for detection of the object to follow.
47+
48+
:rotate_to_object_timeout:
49+
50+
============== ==============
51+
Type Default
52+
-------------- --------------
53+
double 10.0
54+
============== ==============
55+
56+
Description
57+
Timeout (s) to rotate searching for the object when detection is lost.
58+
59+
:static_object_timeout:
60+
61+
============== ==============
62+
Type Default
63+
-------------- --------------
64+
double -1.0
65+
============== ==============
66+
67+
Description
68+
Timeout (s) to stop following when the object remains static. If -1.0, the robot will follow indefinitely.
69+
70+
:linear_tolerance:
71+
72+
============== ==============
73+
Type Default
74+
-------------- --------------
75+
double 0.15
76+
============== ==============
77+
78+
Description
79+
Linear tolerance (m) to consider that the target position has been reached.
80+
81+
:angular_tolerance:
82+
83+
============== ==============
84+
Type Default
85+
-------------- --------------
86+
double 0.15
87+
============== ==============
88+
89+
Description
90+
Angular tolerance (rad) to consider that the target orientation has been reached.
91+
92+
:max_retries:
93+
94+
============== ==============
95+
Type Default
96+
-------------- --------------
97+
int 3
98+
============== ==============
99+
100+
Description
101+
Maximum number of retries when detection or control fails.
102+
103+
:base_frame:
104+
105+
============== ==============
106+
Type Default
107+
-------------- --------------
108+
string "base_link"
109+
============== ==============
110+
111+
Description
112+
Robot's base frame for control law.
113+
114+
:fixed_frame:
115+
116+
============== ==============
117+
Type Default
118+
-------------- --------------
119+
string "odom"
120+
============== ==============
121+
122+
Description
123+
Fixed frame to use, recommended to be a smooth odometry frame **not** map.
124+
125+
:filter_coef:
126+
127+
============== ==============
128+
Type Default
129+
-------------- --------------
130+
double 0.1
131+
============== ==============
132+
133+
Description
134+
Filter coefficient for smoothing object pose detections.
135+
136+
:desired_distance:
137+
138+
============== ==============
139+
Type Default
140+
-------------- --------------
141+
double 1.0
142+
============== ==============
143+
144+
Description
145+
Desired distance (m) to maintain from the followed object.
146+
147+
:skip_orientation:
148+
149+
============== ==============
150+
Type Default
151+
-------------- --------------
152+
bool true
153+
============== ==============
154+
155+
Description
156+
If true, ignore the detected object's orientation and point toward it from the robot's position.
157+
158+
:search_by_rotating:
159+
160+
============== ==============
161+
Type Default
162+
-------------- --------------
163+
bool false
164+
============== ==============
165+
166+
Description
167+
If true, the robot will rotate in place when it loses object detection to try to find it again.
168+
169+
:search_angle:
170+
171+
============== ==============
172+
Type Default
173+
-------------- --------------
174+
double M_PI_2
175+
============== ==============
176+
177+
Description
178+
Maximum angle (rad) to rotate when searching for the object.
179+
180+
:odom_topic:
181+
182+
============== ==============
183+
Type Default
184+
-------------- --------------
185+
string "odom"
186+
============== ==============
187+
188+
Description
189+
Odometry topic to use for obtaining the robot's current velocity.
190+
191+
:odom_duration:
192+
193+
============== ===========================
194+
Type Default
195+
-------------- ---------------------------
196+
double 0.3
197+
============== ===========================
198+
199+
Description
200+
Time (s) to buffer odometry commands to estimate the robot speed.
201+
202+
:transform_tolerance:
203+
204+
============== =============================
205+
Type Default
206+
-------------- -----------------------------
207+
double 0.1
208+
============== =============================
209+
210+
Description
211+
Time with which to post-date the transform that is published, to indicate that this transform is valid into the future.
212+
213+
Example
214+
*******
215+
.. code-block:: yaml
216+
217+
following_server:
218+
ros__parameters:
219+
controller_frequency: 50.0
220+
detection_timeout: 2.0
221+
rotate_to_object_timeout: 10.0
222+
static_object_timeout: 30.0 # -1.0 for indefinite following
223+
linear_tolerance: 0.15
224+
angular_tolerance: 0.15
225+
max_retries: 3
226+
base_frame: "base_link"
227+
fixed_frame: "odom"
228+
filter_coef: 0.1
229+
desired_distance: 1.0
230+
skip_orientation: true
231+
search_by_rotating: false
232+
odom_topic: "odom"
233+
odom_duration: 0.3
234+
transform_tolerance: 0.1
235+
236+
# Controller configuration (inherited from docking controller)
237+
controller:
238+
k_phi: 3.0
239+
k_delta: 2.0
240+
beta: 0.4
241+
lambda: 2.0
242+
v_linear_min: 0.1
243+
v_linear_max: 0.5
244+
v_angular_max: 1.0
245+
slowdown_radius: 0.15
246+
use_collision_detection: false
247+
transform_tolerance: 0.1

‎migration/Kilted.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -421,3 +421,15 @@ An example usage in a Behavior Tree XML file:
421421
.. code-block:: xml
422422
423423
<ToggleCollisionMonitor enable="false" service_name="collision_monitor/toggle"/>
424+
425+
426+
Following Server
427+
----------------
428+
429+
`PR #5565 <https://github.com/ros-navigation/navigation2/pull/5565>`_ adds a new Following Server into the ``opennav_following`` package.
430+
The Following Server implements a server for following dynamic objects or specific reference frames.
431+
This server allows the robot to follow and maintain a determined distance from a detected object or specific frame, using topic-based detection techniques or coordinate frame tracking.
432+
433+
The information about Following Server parameters set-up could be found at :ref:`configuring_following_server` configuration guide.
434+
435+
The tutorial for the Following Server has been recently updated. For the latest instructions and examples, see :ref:`navigation2-dynamic-point-following`.

0 commit comments

Comments
 (0)