Skip to main content

ROS2 Actions Manager

The actions manager discovers, describes and executes registered ROS2 actions in the Agent's configured ROS2 domain. It supports Nav2 NavigateToPose and NavigateThroughPoses, and Spot Trajectory and NavigateTo. Servers can use namespaces or remapped names.

An action selector has two parts: the absolute server name and its exact ROS interface type. Commands that observe or cancel an accepted goal use its ROS goal UUID instead.

Discover servers and goal formats​

nimbus actions list
nimbus actions describe /trajectory spot_msgs/action/Trajectory
nimbus actions describe /navigate_to spot_msgs/action/NavigateTo
nimbus actions describe /navigate_to_pose nav2_msgs/action/NavigateToPose
nimbus actions describe /navigate_through_poses nav2_msgs/action/NavigateThroughPoses

list reports registered servers observed in the ROS2 graph, their readiness, and the configured domain. Readiness is an observation; submission checks service availability again. describe can return a registered goal template before a server is ready.

Responses are protobuf JSON. description.goal.templateJson contains an editable JSON object as a string; jsonFormat identifies its format. All four goal types use protobuf JSON, with lower camel case field names and protobuf timestamp/duration strings. ROS CLI YAML and raw ROS JSON are different formats. Follow the returned template instead of copying ros2 action send_goal arguments directly.

For example, save an editable Spot template to a file using jq:

nimbus actions describe /trajectory spot_msgs/action/Trajectory \
  | jq -r '.description.goal.templateJson' > trajectory-goal.json

Review and edit the goal before sending it. A template supplies a schema example; it does not establish that a movement is appropriate for the robot or its surroundings.

Submit a goal​

Pass one quoted goal JSON object, without a goal or SendGoal wrapper:

nimbus actions send /navigate_to spot_msgs/action/NavigateTo \
  '{"waypointId":"bitter-ewe-abc123"}'

Or read the object from a UTF-8 file:

nimbus actions send /trajectory spot_msgs/action/Trajectory \
  --goal-file trajectory-goal.json

Inline JSON and --goal-file are alternatives. The Agent validates the registered schema and rejects unknown fields. For Spot Trajectory, use targetPose.header.frameId: "body" and a positive whole-second protobuf duration such as "duration": "10s". Spot NavigateTo requires the driver to have an uploaded GraphNav graph and localization; use a waypoint ID from that graph.

For a namespaced Nav2 server:

nimbus actions describe /robot_1/navigate_to_pose nav2_msgs/action/NavigateToPose \
  | jq -r '.description.goal.templateJson' > nav-goal.json
# Edit nav-goal.json, then submit it:
nimbus actions send /robot_1/navigate_to_pose nav2_msgs/action/NavigateToPose \
  --goal-file nav-goal.json

The reply reports accepted, message, and an accepted goal snapshot containing goal.goalId. A normal server rejection has accepted: false and no goal snapshot. A transport error does not prove the server rejected or stopped the goal.

Observe status, feedback and result​

Use the UUID returned by submission, for example:

nimbus actions status f5ea831d-46b0-428d-99d7-1a2ebdd407e8
nimbus actions watch f5ea831d-46b0-428d-99d7-1a2ebdd407e8
nimbus actions result f5ea831d-46b0-428d-99d7-1a2ebdd407e8

status returns the retained snapshot. watch starts with a current snapshot, then emits one JSON object per event with a monotonically increasing revision. It includes feedback and a result that arrives after terminal ROS status. Pressing Ctrl+C ends observation only; the robot goal continues.

result returns immediately. goal.result.state explicitly reports pending, available, or unavailable. When available, payloadJson contains the complete application result as a JSON string, without the ROS protocol wrapper. The description identifies its JSON format: Spot results and feedback use protobuf JSON; Nav2 results and feedback use ROS JSON.

ROS terminal status and application results are separate. A ROS SUCCEEDED status does not imply a Spot result's success field is true. A terminal status can appear while the result is still pending. An interrupted observation is not confirmation of robot cancellation, failure, success, or standstill.

Goal snapshots are bounded and process-local. Unknown, expired or pre-restart UUIDs cannot be queried or cancelled through retained-goal commands. Reconnecting a watch gives a fresh snapshot, not replay of all previous feedback.

Request cancellation​

nimbus actions cancel f5ea831d-46b0-428d-99d7-1a2ebdd407e8

The reply acknowledges whether the ROS server accepted cancellation of that UUID. Continue watching for the final status; cancellation acknowledgment alone does not confirm the robot has stopped.

The existing nav2 manager remains available for its latest-goal status and cancellation commands. Its Nav2 goals run through the same execution engine.