Search documentation of bb

# BB.Motion (bb v0.8.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):

- `move_to_multi/3` - Solve IK for multiple targets simultaneously
- `solve_only_multi/3` - Solve multiple targets without sending commands

Utility:

- `send_positions/3` - Send pre-computed positions to actuators (bypasses IK)

## 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, reason, _meta} -> IO.puts("Failed: #{reason}")
    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, reason, 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, reason, _meta} -> {:error, reason}
      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, reason, _meta} -> IO.puts("Cannot reach: #{reason}")
    end

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

# Summary

## Types

delivery()
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

# meta()

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

# motion_result()

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

# multi_motion_result()

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

# multi_results()

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

# multi_solve_result()

    @type multi_solve_result() ::
      {:ok, multi_results()} | {:error, atom(), atom(), 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, atom(), meta()}

# 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:

- `:solver` - Module implementing `BB.IK.Solver` behaviour

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, reason, meta}` - Failed; reason is `:ik_failed`, `:unreachable`, etc.

## 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:

- `:solver` - Module implementing `BB.IK.Solver` behaviour

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, reason, results}` - A target failed; results contains successful solves

## 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, reason, _results} ->
        IO.puts("Failed to reach #{failed_link}: #{reason}")
    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, reason, meta}` - Failed to solve

## Examples

    # Check if target is reachable
    case BB.Motion.solve_only(MyRobot, :gripper, target, solver: BB.IK.FABRIK) do
      {:ok, _positions, %{reached: true}} -> :reachable
      _ -> :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, reason, results}` - A target failed; results contains successful solves

## 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, reason, _results} ->
        IO.puts("#{failed_link} is unreachable: #{reason}")
    end