# `BB.Command.MoveTo`
[🔗](https://github.com/beam-bots/bb/blob/main/lib/bb/command/move_to.ex#L5)

Standard command handler for moving end-effectors to target positions.

This command uses inverse kinematics to compute joint angles and sends
position commands to all actuators controlling the affected joints.

Supports both single-target and multi-target modes for coordinated motion.

## Goal Parameters

### Single Target Mode

Required:
- `target` - Target position as `BB.Vec3.t()` in metres
- `target_link` - Name of the link to move (end-effector)
- `source_link` - Name of the link the chain starts at
- `solver` - Module implementing `BB.IK.Solver` behaviour

### Multi-Target Mode

Required:
- `targets` - Map of link names to target positions: `%{link: BB.Vec3.t()}`
- `source_link` - Name of the link the chain starts at
- `solver` - Module implementing `BB.IK.Solver` behaviour

### Optional (both modes)

- `max_iterations` - Maximum solver iterations (default: 50)
- `tolerance` - Convergence tolerance in metres (default: 1.0e-4)
- `respect_limits` - Whether to clamp to joint limits (default: true)
- `delivery` - Actuator command delivery: `:pubsub` (default) waits for each
  actuator to accept its command, `:direct` doesn't wait
- `velocity` - Velocity hint for actuators (rad/s or m/s)
- `duration` - Duration hint for actuators (milliseconds)
- `timeout` - How long to wait for each actuator to accept its command, in
  milliseconds (default: 5000). Unused under `delivery: :direct`

## Usage

### Single Target

    alias BB.Vec3

    {:ok, cmd} = MyRobot.move_to(%{
      target: Vec3.new(0.3, 0.2, 0.1),
      target_link: :gripper,
      source_link: :base_link,
      solver: BB.IK.FABRIK
    })
    {:ok, meta} = BB.Command.await(cmd)

### Multiple Targets (for gait, coordinated motion)

    {:ok, cmd} = MyRobot.move_to(%{
      targets: %{
        left_foot: Vec3.new(0.1, 0.0, 0.0),
        right_foot: Vec3.new(-0.1, 0.0, 0.0)
      },
      source_link: :body,
      solver: BB.IK.FABRIK
    })
    {:ok, results} = BB.Command.await(cmd)

## Return Value

### Single Target

On success, returns metadata from the IK solver:

    %{
      iterations: 12,
      residual: 0.00003,
      reached: true,
      reason: :converged
    }

### Multiple Targets

On success, returns a map of link → result:

    %{
      left_foot: {:ok, %{joint1: 0.5}, %{iterations: 10, ...}},
      right_foot: {:ok, %{joint2: 0.3}, %{iterations: 8, ...}}
    }

---

*Consult [api-reference.md](api-reference.md) for complete listing*