BT primitives¶

A behaviour-tree mission in this workspace is built out of a small vocabulary of reusable pieces. This page is the dictionary. Every mission page below references these names.

If words like "action server", "blackboard", "TF" or "behaviour tree" are unfamiliar, read Concepts first.

The three pieces every mission rests on¶

1. goto.py: the action-client template. Every "move the robot" leg in every mission goes through this module.
2. LocomotionActionServer: the action server that actually drives the vehicle. Listens on /bluerov/controls.
3. shared_trees/search.py: reusable search behaviours (single-layer square, layered square, front-camera yaw scan) that wrap goto with cluster_tf bookkeeping.

The rest of this page goes through each in detail.

goto.py. Action-client template¶

bluerov_sim/scripts/goto.py is a thin py_trees action-client layer between behaviour code and the locomotion action server. Every "drive to a pose" leg is one of four classes from this module.

What goto does on each tick¶

When a goto leaf is ticked for the first time:

1. Builds (or reads from the blackboard) a PoseStamped in some frame. base_link for body-relative, map for world-relative, front_cam_optical or another vehicle frame to "place the camera on" a target.
2. Calls /bluerov/convert_to_controls_pose (provided by frames) to resolve the pose against the chosen anchor frame and convert it to a map-frame ENU pose ready for the action server.
3. Sends the converted pose as a Locomotion goal to /bluerov/controls.

On subsequent ticks, it polls the action future. The behaviour returns RUNNING until the action server says the goal succeeded (SUCCESS) or failed (FAILURE).

The four goto classes¶

Common goto parameters¶

These appear on every goto call. Get comfortable with them. Most "why did the vehicle do that?" debugging starts with checking these.

Adding a new BT leg. Recipe¶

1. Build a PoseStamped in the right frame:
   • frame_id="base_link" for body-relative.
   • frame_id="map" for world-absolute.
   • frame_id="<some_target>/view" for "land the anchor on <some_target>".
2. Wrap it in goto.FromConstant(name=..., pose=..., anchor_frame_name=...).
3. Add depth_override_value=Z (negative in ENU) if you want depth clamped during the move.
4. Set is_relative_movement=True only for body-frame deltas (yaw-only scans).
5. Drop the leaf into your Sequence(memory=True) and tick the tree.

LocomotionActionServer. What actually drives the vehicle¶

bluerov_sim/scripts/locomotion_action_server.py implements the /bluerov/controls action. This is the only component that talks to MAVROS in the output direction (everyone else just subscribes to MAVROS topics). Its _build_target method (:215–297) is where each goal turns into a MAVROS setpoint.

How _build_target resolves a goal¶

Each axis is resolved on its own boolean flag. The three flags do not interact.

Why 1 Hz?¶

Setpoints publish at PUBLISH_RATE_HZ = 1.0. Higher rates make ArduSub keep replanning, and the vehicle stalls in place because it never gets time to execute the previous setpoint. Do not change this.

Success condition¶

A goal succeeds when:

distance < dist_threshold
AND (not specified_heading OR yaw_error < yaw_threshold)

Default thresholds: 0.2 m position, 5.0° yaw, 60 s timeout. The feedback published on every tick contains per-axis errors, total distance error, and yaw error. Handy in Foxglove when debugging an alignment that won't close.

Topics & services the action server uses¶

shared_trees/search.py. Reusable search behaviours¶

When perception can't see the target yet, you need a search pattern. bluerov_sim/bluerov_sim/shared_trees/search.py ships several plug-and-play wrappers. Each one is a small subtree (start_cluster → goto_pattern → end_cluster) that the mission tree just drops in.

Available search builders¶

Anatomy of a search subtree¶

Every search builder produces a subtree of roughly the same shape:

flowchart TD
  ROOT["Selector(memory=True)"]
  TF["TF-checker:<br/>has the clustered TF appeared yet?"]
  RETRY["Retry(N) on Sequence(memory=True)"]
  START_CL["Start clustering<br/>(call cluster_tf action)"]
  GOTO["Goto pattern<br/>(NFromConstant or NFromBlackboard)"]
  END_CL["End clustering<br/>(wait for cluster_tf to finish)"]

  ROOT --> TF
  ROOT --> RETRY
  RETRY --> START_CL
  START_CL --> GOTO
  GOTO --> END_CL

• The Selector at the root short-circuits the moment the clustered TF appears in the TF tree. You don't need to finish the pattern if you've already got a good fix.
• The Retry lets the pattern run again if the cluster didn't hold (spread too wide).
• Start / end clustering sandwich the goto pattern: the goal is to keep the cluster_tf action running while the vehicle is moving so detections from across the whole scan are pooled.

Key parameters across the search builders¶

Putting it together. Example flow for a perception-driven leg¶

A typical "find a target and approach it" leg in the bin or torpedo tree looks like this (in pseudo-Python):

Sequence(memory=True, children=[
    # 1. Start in a known coarse pose.
    goto.FromConstant(
        name="goto_vicinity",
        pose=PoseStamped(frame_id="map", x=-6.0, y=4.5),
        depth_override_value=SEARCH_DEPTH,
    ),

    # 2. Run a search pattern. Internally clusters detections into
    #    bin/yolo/clustered. Short-circuits as soon as the cluster
    #    converges.
    create_search_bot_layered_square_root(
        object_frame="bin/yolo",
        object_frame_clustered="bin/yolo/clustered",
        search_depth=SEARCH_DEPTH,
        ...
    ),

    # 3. Switch anchor frame to dropper_link and approach the clustered
    #    target. Now "land on it" means "put the dropper on it".
    goto.FromBlackboard(
        name="goto_align",
        key="...",  # contains a pose stamped on bin/yolo/clustered
        anchor_frame_name="dropper_link",
        depth_override_value=BIN_DEPTH_OVERRIDE_VALUE,
        x_threshold=0.05, y_threshold=0.05, z_threshold=0.05,
    ),

    # 4. Stabilise + actuate.
    Wait(5.0),
    fire_dropper_1,
])

You'll see this pattern in slightly different forms on the Bin and Torpedo mission pages.

See also¶

• Architecture: the layered pipeline this BT vocabulary sits on top of.
• Conventions: frame, sign and naming rules.
• bb_msgs: the actual Locomotion.action schema.
• filters: what cluster_tf does under the hood.