Glossary

Fictionlab > Glossary > ROS 2 action

ROS 2 action

ROS 2 action – definition

A ROS 2 action is a communication pattern for asynchronous, goal-oriented tasks that may take a measurable amount of time to complete. It is used when a robot must accept a goal, provide progress feedback while executing it, return a final result, and optionally allow the client to cancel the operation.

Actions are part of the ROS 2 client library API and are implemented through a combination of ROS 2 services and topics. Unlike a topic, an action is not intended for continuous data streaming. Unlike a service, it is not limited to a short request-response transaction. An action is appropriate for operations such as driving a UGV to a target pose, executing a waypoint sequence, rotating for a sensor scan, or collecting data over a defined route.

On a mobile robot, an action server usually runs on the robot or its onboard compute unit. An action client may run on the same computer, on a remote workstation, or inside an orchestration node. For Leo Rover, this pattern is commonly used with ROS 2 navigation components running on the integrated Raspberry Pi or on an additional external computer. Raph Rover can use the same model for larger sensor payloads, longer inspection missions, and payload-specific task execution.

How ROS 2 actions work

A ROS 2 action interface is defined in a .action file. The file contains three message definitions separated by ---: a goal definition, a result definition, and a feedback definition. ROS 2 generates language-specific message and service types used by the action protocol during the build process.

An action server exposes the following logical communication channels. Their names are derived from the action name and are visible in the ROS graph.

Channel Purpose ROS 2 mechanism
send_goal Accepts or rejects a requested goal. The request includes the goal UUID. Service
get_result Returns the terminal result after completion, cancellation, or abortion. Service
cancel_goal Requests cancellation of one goal, all goals, or goals before a timestamp. Service
feedback Publishes progress data for active goals. Topic
status Publishes the state of known goals. Topic

Goal identity is represented by a UUID. The status protocol is defined by the action_msgs package. A goal may be accepted, executing, canceling, succeeded, canceled, or aborted. The client should not assume that acceptance guarantees successful execution. For example, a navigation goal may be accepted and later aborted because the planner cannot find a collision-free path.

Action interfaces and message design

An action definition should contain only data required to describe the requested task, its final outcome, and useful progress. Feedback should be informative but bounded in size. Sending high-bandwidth point clouds, images, or LiDAR scans through action feedback is inefficient. Those data streams should normally remain on dedicated ROS 2 topics.

The following simplified interface describes a UGV motion task. It is suitable for a custom node that drives a differential-drive platform for a requested distance while reporting progress.

# DriveDistance.action

float32 distance_m
float32 max_linear_velocity_mps
---
bool success
string message
float32 final_distance_m
---
float32 distance_remaining_m
float32 current_linear_velocity_mps

The action type is built from an interface package, for example fictionlab_interfaces/action/DriveDistance. In a production UGV system, the server must validate goal values before execution. Validation should include velocity limits, available localization, motor-controller state, obstacle conditions, and watchdog status.

ROS 2 actions for UGV navigation

The most common action in an autonomous ROS 2 mobile-robot stack is Nav2’s NavigateToPose action. Its action server receives a target pose, typically in the map frame, and coordinates planning, control, recovery behaviors, and progress reporting. A client can cancel the navigation task if an operator changes the mission or if a safety subsystem detects an invalid operating condition.

For Leo Rover, a typical workflow combines a localization or SLAM node, wheel odometry, a TF tree, a 2D LiDAR or depth sensor, and Nav2. Leo Rover has a four-wheel differential-drive configuration, so its navigation controller is generally configured for non-holonomic ground motion. The platform does not provide autonomous navigation by default. A working action-based navigation system requires integration and tuning of sensors, transforms, costmaps, controller parameters, and motor interfaces.

Raph Rover can use the same ROS 2 action API while carrying larger compute units or payloads. The action abstraction remains independent of payload size. However, parameters such as maximum velocity, acceleration, footprint, clearance, battery thresholds, and stopping distance must be adapted to the configured platform and mission.

Calling and inspecting an action

The ROS 2 command-line interface can inspect available actions and send a test goal. This is useful during integration because it separates action-server verification from application-specific client code.

ros2 action list
ros2 action info /navigate_to_pose
ros2 interface show nav2_msgs/action/NavigateToPose

ros2 action send_goal /navigate_to_pose \
  nav2_msgs/action/NavigateToPose \
  "{pose: {header: {frame_id: map}, pose: {position: {x: 2.0, y: 0.0, z: 0.0}, orientation: {w: 1.0}}}}" \
  --feedback

The command requires a valid TF relationship between the navigation frame and the robot base frame. In Nav2 deployments, this commonly includes map, odom, and base_link. Missing, stale, or inconsistent transforms can cause a goal to be rejected or aborted.

Key engineering considerations

Action behavior depends on application logic, executor scheduling, DDS configuration, and network conditions. ROS 2 does not define a universal feedback rate, timeout, or maximum action duration. These values must be selected for the mission and implemented explicitly.

When designing actions for field robotics, engineers should define the following behavior before deployment.

  • Goal acceptance criteria, including localization quality and hardware readiness.
  • Cancellation behavior, including controlled deceleration and motor-stop confirmation.
  • Feedback rate and payload size, especially on Wi-Fi links with limited bandwidth.
  • Timeouts for stalled motion, unavailable transforms, and unresponsive sensor pipelines.
  • Terminal result semantics for success, cancellation, and safety-related aborts.
  • Recovery behavior when navigation, perception, or motor control reports an error.

ROS 1 and ROS 2 differences

ROS 1 actions are commonly implemented with actionlib. ROS 2 actions use the ROS 2 middleware layer and client-library implementations such as rclcpp_action and rclpy.action. The conceptual model is similar, but ROS 1 action clients and servers are not wire-compatible with ROS 2 action clients and servers.

Leo Rover can be used with ROS 2 distributions such as ROS 2 Humble, subject to compatibility with the installed software image and packages. Projects migrating from ROS 1 should update package dependencies, launch files, parameter handling, QoS configuration, and action-client code rather than treating a ROS 1 action server as directly interchangeable with a ROS 2 implementation.

Normative references and documentation

The ROS 2 action communication model, generated interfaces, and client-library APIs are documented by Open Robotics in the ROS 2 documentation. The action status and goal metadata messages are specified by the action_msgs interface package.

See also