Waypoint

Waypoint – definition

A waypoint is a defined target location that a mobile robot is expected to reach, pass through, inspect, or use as part of a route. In UGV robotics, a waypoint is usually represented as a pose in a known coordinate frame. The pose contains position and, when required, orientation.

In ROS 2 navigation, a waypoint is commonly expressed with geometry_msgs/msg/PoseStamped. This message combines a header containing a timestamp and coordinate-frame identifier with a geometry_msgs/msg/Pose object. Position is represented in metres, while orientation is conventionally represented by a normalized quaternion. The ROS message definition is maintained in the geometry_msgs documentation.

A waypoint is not necessarily a GPS coordinate. For indoor navigation, it is usually a pose in the map frame created by SLAM or loaded from a prior map. For outdoor operation, it may originate from latitude, longitude, and altitude measurements, then be transformed into a local Cartesian frame suitable for path planning.

Waypoints in ROS 2 navigation

ROS 2 does not define one universal waypoint service or topic. Instead, waypoint handling is typically implemented by a navigation framework such as Nav2. Nav2 provides actions for navigating to one pose and for following a sequence of poses.

The most relevant Nav2 action interfaces are listed below. Their definitions are part of the nav2_msgs package.

ROS 2 interface	Purpose	Waypoint data
`nav2_msgs/action/NavigateToPose`	Navigate to one target pose.	`geometry_msgs/PoseStamped pose`
`nav2_msgs/action/FollowWaypoints`	Execute an ordered sequence of waypoint goals.	`geometry_msgs/PoseStamped[] poses`
`nav2_msgs/action/ComputePathThroughPoses`	Plan a path through multiple intermediate poses.	`geometry_msgs/PoseStamped[] goals`

The FollowWaypoints action reports the current waypoint index as feedback and can return indices of missed waypoints. The exact action definitions should be checked against the Nav2 version deployed on the robot, because interfaces and behavior-tree integrations can change between ROS 2 distributions.

Source: Nav2 Waypoint Follower documentation and nav2_msgs API documentation.

Coordinate frames and waypoint validity

A waypoint has meaning only when its reference frame is known. In a typical ROS 2 mobile-robot system, global waypoints are specified in map, local odometry is maintained in odom, and the robot body frame is base_link. These frame roles are defined by ROS Enhancement Proposal 105.

The transform chain usually follows this structure:

map -> odom -> base_link -> sensor_frame

The localization subsystem publishes or enables the map -> odom transform. Wheel odometry, IMU integration, or an EKF commonly provides odom -> base_link. If the global transform is missing, stale, or inconsistent with the map, a waypoint may appear correct in RViz but cannot be reached reliably by Nav2.

Source: REP 105 – Coordinate Frames for Mobile Platforms.

Key waypoint parameters

A waypoint definition should contain enough information for a navigation client, planner, and local controller to interpret the goal consistently. The following attributes are practical for UGV deployments.

Frame ID: usually map for a global navigation goal.
Position: Cartesian x and y coordinates in metres; a z value may also be present in the pose message, although standard 2D Nav2 navigation does not use it for planning.
Orientation: a quaternion. For ground vehicles, the yaw angle is usually the operationally relevant component.
Timestamp: PoseStamped includes a timestamp field. When a non-zero timestamp is used, it must be compatible with the robot clock and available TF data.
Acceptance criteria: controller and goal-checker tolerances for position and heading determine when Nav2 considers the waypoint reached.
Task metadata: optional actions such as image capture, sensor sampling, waiting, or payload triggering.

For a planar UGV, yaw can be converted to a quaternion before sending the goal. With roll and pitch equal to zero, the quaternion components are:

qx = 0
qy = 0
qz = sin(yaw / 2)
qw = cos(yaw / 2)

Waypoint sequences for Leo Rover and Raph Rover

Leo Rover can execute waypoint missions after a localization source, costmaps, transforms, and a ROS 2 navigation stack have been integrated. Leo Rover supports ROS 2, including Humble-based software environments. It is a differential-drive platform, so Nav2 should be configured with motion constraints appropriate for non-holonomic ground motion.

A typical Leo Rover laboratory workflow uses a 2D LiDAR or depth sensor for mapping and obstacle detection, wheel odometry for short-term motion estimation, and an IMU for attitude and motion fusion. A saved occupancy map and AMCL, or a SLAM system operating in localization mode, can provide the global reference required for map-frame waypoints.

Raph Rover is appropriate when a waypoint mission requires a larger sensor payload, a higher-capacity compute stack, or operation over a larger outdoor area. In an outdoor survey, GNSS/RTK positions can define mission points, but they should be converted into a local navigation frame and validated against obstacle data. GNSS alone does not provide collision avoidance or guarantee that a physically reachable path exists.

Source: Leo Rover technical documentation, Nav2 documentation, and ROS 2 Humble documentation.

Example waypoint list in YAML

The following YAML structure is suitable as application-level mission data. A ROS 2 node can load the list, convert each item to PoseStamped, and send it through the Nav2 FollowWaypoints action.

frame_id: map
waypoints:
  - name: inspection_point_01
    x: 2.40
    y: -1.15
    yaw: 1.57
    task: capture_image
  - name: inspection_point_02
    x: 5.10
    y: -0.80
    yaw: 0.00
    task: wait

Limitations and failure modes

A waypoint is a target, not a guaranteed route. The global planner may reject it if it lies outside the map, inside an inflated obstacle region, or in disconnected free space. The local controller may also fail when the target is too close to an obstacle, the robot is poorly localized, or the required final orientation is infeasible in the available space.

Waypoint coordinates should therefore be reviewed in RViz, tested with the robot footprint and costmap configuration, and versioned together with the map and navigation parameters. A waypoint recorded on one map should not be assumed valid after a map origin, sensor transform, or localization configuration has changed.