diff --git a/docs/configuration_and_development/configuration_guide/.nav.yml b/docs/configuration_and_development/configuration_guide/.nav.yml index 5e3e12432..69552fbfb 100644 --- a/docs/configuration_and_development/configuration_guide/.nav.yml +++ b/docs/configuration_and_development/configuration_guide/.nav.yml @@ -27,4 +27,5 @@ nav: - Simple Smoother: smoother_plugins/configuring_simple_smoother.md - AMCL: others/configuring_amcl.md - Coverage Server: others/configuring_coverage_server.md + - Following Server: others/configuring_following_server.md - Loopback Simulator: others/configuring_loopback_sim.md diff --git a/docs/configuration_and_development/configuration_guide/core_servers/configuring_docking_server.md b/docs/configuration_and_development/configuration_guide/core_servers/configuring_docking_server.md index 274ece549..d847a55f7 100644 --- a/docs/configuration_and_development/configuration_guide/core_servers/configuring_docking_server.md +++ b/docs/configuration_and_development/configuration_guide/core_servers/configuring_docking_server.md @@ -156,6 +156,18 @@ Type: `double` Default: `0.25` : Radius to end goal to commense slow down. +### **`controller.rotate_to_heading_angular_vel`** + +Type: `double` Default: `1.0` + +: Angular velocity (rad/s) to rotate to the goal heading. + +### **`controller.rotate_to_heading_max_angular_accel`** + +Type: `double` Default: `3.2` + +: Maximum angular acceleration (rad/s^2) to rotate to the goal heading. + ### **`controller.use_collision_detection`** Type: `bool` Default: `true` diff --git a/docs/configuration_and_development/configuration_guide/index.md b/docs/configuration_and_development/configuration_guide/index.md index a4975dfa9..2f89ddb01 100644 --- a/docs/configuration_and_development/configuration_guide/index.md +++ b/docs/configuration_and_development/configuration_guide/index.md @@ -220,6 +220,13 @@ the best navigation performance. [:octicons-arrow-right-24: Go][coverage-server] +- :material-target-account: **Following Server** + + --- + Dynamic object following with tracking recovery. + + [:octicons-arrow-right-24: Go][following-server] + - :material-replay: **Loopback Simulator** --- diff --git a/docs/configuration_and_development/configuration_guide/others/configuring_following_server.md b/docs/configuration_and_development/configuration_guide/others/configuring_following_server.md new file mode 100644 index 000000000..5117cdab8 --- /dev/null +++ b/docs/configuration_and_development/configuration_guide/others/configuring_following_server.md @@ -0,0 +1,152 @@ +# Following Server { #following-server } + +Source code on [Github](https://github.com/ros-navigation/navigation2/tree/jazzy/nav2_following/opennav_following). + +The Following Server in `opennav_following` implements a server for following dynamic objects from a detection topic or specific reference frame. +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. +The server is designed to be called by a BT application or autonomy application to follow moving objects. + +
+ +
+ +## Parameters + +### **`controller_frequency`** + +Type: `double` Default: `50.0` + +: Control frequency (Hz) for the following control loop. + +### **`detection_timeout`** + +Type: `double` Default: `2.0` + +: Timeout (s) to wait for detection of the object to follow. + +### **`rotate_to_object_timeout`** + +Type: `double` Default: `10.0` + +: Timeout (s) to rotate searching for the object when detection is lost. + +### **`static_object_timeout`** + +Type: `double` Default: `-1.0` + +: Timeout (s) to stop following when the object remains static. If `-1.0`, the robot will follow indefinitely. + +### **`linear_tolerance`** + +Type: `double` Default: `0.15` + +: Linear tolerance (m) to consider that the target position has been reached. + +### **`angular_tolerance`** + +Type: `double` Default: `0.15` + +: Angular tolerance (rad) to consider that the target orientation has been reached. + +### **`max_retries`** + +Type: `int` Default: `3` + +: Maximum number of retries when detection or control fails. + +### **`base_frame`** + +Type: `string` Default: `"base_link"` + +: Robot's base frame for control law. + +### **`fixed_frame`** + +Type: `string` Default: `"odom"` + +: Fixed frame to use, recommended to be a smooth odometry frame **not** map. + +### **`filter_coef`** + +Type: `double` Default: `0.1` + +: Filter coefficient for smoothing object pose detections. + +### **`desired_distance`** + +Type: `double` Default: `1.0` + +: Desired distance (m) to maintain from the followed object. + +### **`skip_orientation`** + +Type: `bool` Default: `true` + +: If `true`, ignore the detected object's orientation and point toward it from the robot's position. + +### **`search_by_rotating`** + +Type: `bool` Default: `false` + +: If `true`, the robot will rotate in place when it loses object detection to try to find it again. + +### **`search_angle`** + +Type: `double` Default: `M_PI_2` + +: Maximum angle (rad) to rotate when searching for the object. + +### **`odom_topic`** + +Type: `string` Default: `"odom"` + +: Odometry topic to use for obtaining the robot's current velocity. + +### **`odom_duration`** + +Type: `double` Default: `0.3` + +: Time (s) to buffer odometry commands to estimate the robot speed. + +### **`transform_tolerance`** + +Type: `double` Default: `0.1` + +: Time with which to post-date the transform that is published, to indicate that this transform is valid into the future. + +## Example + +```yaml +following_server: + ros__parameters: + controller_frequency: 50.0 + detection_timeout: 2.0 + rotate_to_object_timeout: 10.0 + static_object_timeout: 30.0 # -1.0 for indefinite following + linear_tolerance: 0.15 + angular_tolerance: 0.15 + max_retries: 3 + base_frame: "base_link" + fixed_frame: "odom" + filter_coef: 0.1 + desired_distance: 1.0 + skip_orientation: true + search_by_rotating: false + odom_topic: "odom" + odom_duration: 0.3 + transform_tolerance: 0.1 + + # Controller configuration (inherited from docking controller) + controller: + k_phi: 3.0 + k_delta: 2.0 + beta: 0.4 + lambda: 2.0 + v_linear_min: 0.1 + v_linear_max: 0.5 + v_angular_max: 1.0 + slowdown_radius: 0.15 + use_collision_detection: false + transform_tolerance: 0.1 +```