|
| 1 | +.. _commanding: |
| 2 | + |
| 3 | + |
| 4 | +Sending Navigation Commands to EasyNav |
| 5 | +************************************** |
| 6 | + |
| 7 | +EasyNav is designed to be easy to control from user applications or higher-level decision-making modules. |
| 8 | +Instead of relying on ROS 2 Actions, which can be complex and hard to integrate across systems, EasyNav follows a simpler and more transparent communication model using topics and message protocols. |
| 9 | + |
| 10 | +Primary Method: `/easynav_control` Topic |
| 11 | +======================================== |
| 12 | + |
| 13 | +The main interface to control navigation is the topic `/easynav_control`, which uses the message type `easynav_interfaces/msg/NavigationControl`. |
| 14 | +This message encapsulates both commands and feedback for the navigation process. |
| 15 | + |
| 16 | +Here is the full definition of the message: |
| 17 | + |
| 18 | +.. code-block:: cpp |
| 19 | +
|
| 20 | + uint8 REQUEST=0 |
| 21 | + uint8 REJECT=1 |
| 22 | + uint8 ACCEPT=2 |
| 23 | + uint8 FEEDBACK=3 |
| 24 | + uint8 FINISHED=4 |
| 25 | + uint8 FAILED=5 |
| 26 | + uint8 CANCEL=6 |
| 27 | + uint8 CANCELLED=7 |
| 28 | + uint8 ERROR=8 |
| 29 | +
|
| 30 | + uint8 type |
| 31 | + std_msgs/Header header |
| 32 | + int64 seq |
| 33 | + string user_id |
| 34 | + string nav_current_user_id |
| 35 | + nav_msgs/Goals goals |
| 36 | + string status_message |
| 37 | + geometry_msgs/PoseStamped current_pose |
| 38 | + builtin_interfaces/Duration navigation_time |
| 39 | + builtin_interfaces/Duration estimated_time_remaining |
| 40 | + float32 distance_covered |
| 41 | + float32 distance_to_goal |
| 42 | +
|
| 43 | +Protocol Description |
| 44 | +-------------------- |
| 45 | + |
| 46 | +The communication protocol over `/easynav_control` is designed around a type-based message system. Each message indicates a specific type of interaction or feedback: |
| 47 | + |
| 48 | +- **REQUEST (0)**: A new navigation goal is requested. The `goals` field must be filled. |
| 49 | +- **REJECT (1)**: The system rejects the navigation goal. |
| 50 | +- **ACCEPT (2)**: The system has accepted the navigation goal and has started processing. |
| 51 | +- **FEEDBACK (3)**: Periodic updates including the current pose, distance covered, and estimated time remaining. |
| 52 | +- **FINISHED (4)**: Navigation completed successfully. |
| 53 | +- **FAILED (5)**: Navigation failed (e.g., due to unreachable goal or obstacle). |
| 54 | +- **CANCEL (6)**: The user requests to cancel the current navigation. |
| 55 | +- **CANCELLED (7)**: Navigation has been cancelled. |
| 56 | +- **ERROR (8)**: An error occurred during navigation. |
| 57 | + |
| 58 | +Each message has a sequence number (`seq`), user ID (`user_id`), and optionally contains feedback fields if it is of a type that requires them. |
| 59 | + |
| 60 | +To issue a navigation goal, a client should publish a message like: |
| 61 | + |
| 62 | +.. code-block:: cpp |
| 63 | +
|
| 64 | + geometry_msgs::msg::PoseStamped goal_pose; |
| 65 | + goal_pose.header = ... |
| 66 | + goal_pose.pose.position = .... |
| 67 | + goal_pose.pose.orientation = .... |
| 68 | + |
| 69 | + auto command = std::make_unique<easynav_interfaces::msg::NavigationControl>(); |
| 70 | + command->header = goal_pose.header; |
| 71 | + command->seq = 32; |
| 72 | + command->user_id = "nav_user_1"; |
| 73 | + command->type = easynav_interfaces::msg::NavigationControl::REQUEST; |
| 74 | + command->goals.header = goal_pose.header; |
| 75 | + command->goals.goals.push_back(goal_pose); |
| 76 | +
|
| 77 | +The system will then respond with messages of type ACCEPT, FEEDBACK, FINISHED, etc., according to the internal state. |
| 78 | + |
| 79 | +Using `GoalManagerClient` |
| 80 | +------------------------- |
| 81 | + |
| 82 | +Instead of manually implementing the communication protocol, developers are encouraged to use the `GoalManagerClient` class. It abstracts the handling of the `/easynav_control` topic and maintains the internal state machine automatically. |
| 83 | + |
| 84 | +- `send_goal(PoseStamped goal)` issues a goal with proper message formatting. |
| 85 | +- `cancel()` sends a CANCEL message. |
| 86 | +- `get_state()` returns the current state (e.g., `State::NAVIGATING`, `State::NAVIGATION_FINISHED`, etc.). |
| 87 | +- After receiving a terminal state (`FINISHED`, `FAILED`, `CANCELLED`, `REJECTED`, or `ERROR`), you **must** call `reset()` to clear the state before issuing a new command. |
| 88 | + |
| 89 | +Secondary Method: `/goal_pose` Topic |
| 90 | +==================================== |
| 91 | + |
| 92 | +For simplicity, EasyNav also listens to the topic `/goal_pose` of type `geometry_msgs/msg/PoseStamped`. |
| 93 | +Publishing a pose here is equivalent to publishing a `REQUEST` command on `/easynav_control`. |
| 94 | + |
| 95 | +This interface is ideal for manual tools (such as RViz2 "2D Goal Pose") or simple applications where feedback tracking is not required. |
| 96 | +However, users may still subscribe to `/easynav_control` to monitor navigation status and transitions. |
| 97 | + |
| 98 | +Conclusion |
| 99 | +========== |
| 100 | + |
| 101 | +- For complete command and feedback control, use the `/easynav_control` topic with the `GoalManagerClient`. |
| 102 | +- For basic use cases, publishing to `/goal_pose` is sufficient. |
| 103 | +- After receiving any terminal state (FINISHED, FAILED, etc.), a RESET command is mandatory before a new REQUEST. |
0 commit comments