BB.Motion (bb v0.15.0)

View Source

High-level motion primitives that bridge IK solving and actuator commands.

This module provides functions for moving robot end-effectors to target positions using pluggable IK solvers. It handles the full workflow: solving IK, updating robot state, and sending commands to actuators.

Usage

Single-target functions:

  • move_to/4 - Solve IK for one target, update state, send actuator commands
  • solve_only/4 - Solve IK without sending commands (for planning/validation)

Multi-target functions (for coordinated motion like gait):

Utility:

Context Sources

Functions accept either:

  • A robot module (uses Runtime to get robot and state)
  • A BB.Command.Context struct (uses context fields directly)

The second form is useful when implementing custom commands that need to perform IK-based motion.

Examples

# Single target
case BB.Motion.move_to(MyRobot, :gripper, {0.3, 0.2, 0.1}, solver: BB.IK.FABRIK) do
  {:ok, meta} -> IO.puts("Reached target in #{meta.iterations} iterations")
  {:error, %{class: :kinematics} = error} -> IO.puts("Failed: #{BB.Error.message(error)}")
end

# Multiple targets (for gait, coordinated motion)
targets = %{left_foot: {0.1, 0.0, 0.0}, right_foot: {-0.1, 0.0, 0.0}}
case BB.Motion.move_to_multi(MyRobot, targets, solver: BB.IK.FABRIK) do
  {:ok, results} -> IO.puts("All targets reached")
  {:error, failed_link, error, _results} -> IO.puts("Failed: #{failed_link}")
end

# In a custom command handler
def handle_command(%{target: target}, context) do
  case BB.Motion.move_to(context, :gripper, target, solver: BB.IK.FABRIK) do
    {:ok, meta} -> {:ok, %{residual: meta.residual}}
    {:error, error} -> {:error, error}
  end
end

# Just solve without moving (for validation)
case BB.Motion.solve_only(MyRobot, :gripper, {0.3, 0.2, 0.1}, solver: BB.IK.FABRIK) do
  {:ok, positions, meta} -> IO.inspect(positions, label: "Would set")
  {:error, %BB.Error.Kinematics.Unreachable{}} -> IO.puts("Cannot reach target")
end

# Send pre-computed positions
positions = %{shoulder: 0.5, elbow: 1.2}
:ok = BB.Motion.send_positions(MyRobot, positions, delivery: :direct)

Summary

Types

delivery()
kinematics_error()
meta()
motion_result()
multi_motion_result()
multi_results()
multi_solve_result()
positions()
robot_or_context()
solve_result()
target()
targets()

Functions

move_to(robot_or_context, target_link, target, opts)

Move an end-effector to a target position.

move_to_multi(robot_or_context, targets, opts)

Move multiple end-effectors to target positions simultaneously.

send_positions(robot_or_context, positions, opts \\ [])

Send pre-computed joint positions to actuators.

solve_only(robot_or_context, target_link, target, opts)

Solve IK without moving the robot.

solve_only_multi(robot_or_context, targets, opts)

Solve IK for multiple targets without moving the robot.

Types

delivery()

@type delivery() :: :pubsub | :direct | :sync

kinematics_error()

@type kinematics_error() :: BB.IK.Solver.kinematics_error()

meta()

@type meta() :: BB.IK.Solver.meta()

motion_result()

@type motion_result() :: {:ok, meta()} | {:error, kinematics_error()}

multi_motion_result()

@type multi_motion_result() ::
  {:ok, multi_results()} | {:error, atom(), kinematics_error(), multi_results()}

multi_results()

@type multi_results() :: %{
  required(atom()) => {:ok, positions(), meta()} | {:error, kinematics_error()}
}

multi_solve_result()

@type multi_solve_result() ::
  {:ok, multi_results()} | {:error, atom(), kinematics_error(), multi_results()}

positions()

@type positions() :: BB.IK.Solver.positions()

robot_or_context()

@type robot_or_context() :: module() | BB.Command.Context.t()

solve_result()

@type solve_result() :: {:ok, positions(), meta()} | {:error, kinematics_error()}

target()

@type target() :: BB.IK.Solver.target()

targets()

@type targets() :: %{required(atom()) => target()}

Functions

move_to(robot_or_context, target_link, target, opts)

@spec move_to(robot_or_context(), atom(), target(), keyword()) :: motion_result()

Move an end-effector to a target position.

Solves inverse kinematics for the given target, updates the robot state, and sends position commands to all actuators controlling the affected joints.

Options

Required:

Optional:

  • :delivery - How to send actuator commands: :pubsub (default), :direct, or :sync
  • :max_iterations - Maximum solver iterations (passed to solver)
  • :tolerance - Convergence tolerance in metres (passed to solver)
  • :respect_limits - Whether to clamp to joint limits (passed to solver)

Returns

  • {:ok, meta} - Successfully moved; meta contains solver info (iterations, residual, etc.)
  • {:error, error} - Failed; error is a struct from BB.Error.Kinematics

Examples

BB.Motion.move_to(MyRobot, :gripper, {0.3, 0.2, 0.1}, solver: BB.IK.FABRIK)

BB.Motion.move_to(context, :gripper, target,
  solver: BB.IK.FABRIK,
  delivery: :direct,
  max_iterations: 100
)

move_to_multi(robot_or_context, targets, opts)

@spec move_to_multi(robot_or_context(), targets(), keyword()) :: multi_motion_result()

Move multiple end-effectors to target positions simultaneously.

Useful for coordinated motion like walking gaits where multiple limbs must move together. Each target is solved independently and all actuator commands are sent together.

If any target fails to solve, the operation stops and returns an error with information about which target failed. Targets solved before the failure are included in the results.

Options

Required:

Optional:

  • :delivery - How to send actuator commands: :pubsub (default), :direct, or :sync
  • :max_iterations - Maximum solver iterations (passed to solver)
  • :tolerance - Convergence tolerance in metres (passed to solver)
  • :respect_limits - Whether to clamp to joint limits (passed to solver)

Returns

  • {:ok, results} - All targets solved; results is a map of link → {:ok, positions, meta}
  • {:error, failed_link, error, results} - A target failed; error is from BB.Error.Kinematics

Examples

targets = %{
  left_foot: {0.1, 0.0, 0.0},
  right_foot: {-0.1, 0.0, 0.0}
}

case BB.Motion.move_to_multi(MyRobot, targets, solver: BB.IK.FABRIK) do
  {:ok, results} ->
    IO.puts("All targets reached")

  {:error, failed_link, error, _results} ->
    IO.puts("Failed to reach #{failed_link}: #{BB.Error.message(error)}")
end

send_positions(robot_or_context, positions, opts \\ [])

@spec send_positions(robot_or_context(), positions(), keyword()) :: :ok

Send pre-computed joint positions to actuators.

Bypasses IK solving entirely - useful when you've already computed positions through other means (e.g., trajectory planning, manual input).

Updates the robot state and sends commands to all actuators controlling the specified joints.

Options

  • :delivery - How to send actuator commands: :pubsub (default), :direct, or :sync
  • :velocity - Velocity hint for actuators (rad/s or m/s)
  • :duration - Duration hint for actuators (milliseconds)

Examples

positions = %{shoulder: 0.5, elbow: 1.2, wrist: 0.3}
:ok = BB.Motion.send_positions(MyRobot, positions)

# With direct delivery for lower latency
:ok = BB.Motion.send_positions(MyRobot, positions, delivery: :direct)

solve_only(robot_or_context, target_link, target, opts)

@spec solve_only(robot_or_context(), atom(), target(), keyword()) :: solve_result()

Solve IK without moving the robot.

Useful for:

  • Validating that a target is reachable before committing
  • Planning multi-step motions
  • Visualising solutions before execution

Options

Same as move_to/4 except :delivery is not used.

Returns

  • {:ok, positions, meta} - Successfully solved; positions is a joint name → value map
  • {:error, error} - Failed to solve; error is a struct from BB.Error.Kinematics

Examples

# Check if target is reachable
case BB.Motion.solve_only(MyRobot, :gripper, target, solver: BB.IK.FABRIK) do
  {:ok, _positions, %{reached: true}} -> :reachable
  {:error, _} -> :unreachable
end

solve_only_multi(robot_or_context, targets, opts)

@spec solve_only_multi(robot_or_context(), targets(), keyword()) ::
  multi_solve_result()

Solve IK for multiple targets without moving the robot.

Useful for validating that a set of coordinated targets are all reachable before committing to motion.

Options

Same as move_to_multi/3 except :delivery is not used.

Returns

  • {:ok, results} - All targets solved; results is a map of link → {:ok, positions, meta}
  • {:error, failed_link, error, results} - A target failed; error is from BB.Error.Kinematics

Examples

targets = %{left_foot: {0.1, 0.0, 0.0}, right_foot: {-0.1, 0.0, 0.0}}

case BB.Motion.solve_only_multi(MyRobot, targets, solver: BB.IK.FABRIK) do
  {:ok, results} ->
    Enum.each(results, fn {link, {:ok, _positions, meta}} ->
      IO.puts("#{link}: residual=#{meta.residual}")
    end)

  {:error, failed_link, error, _results} ->
    IO.puts("#{failed_link} is unreachable: #{BB.Error.message(error)}")
end