Boomerang Controller Documentation

Overview

The Boomerang Controller is an advanced path-following algorithm implemented in LemLib that allows robots to smoothly navigate to target positions while maintaining optimal heading throughout the movement. Unlike simple point-to-point movement, Boomerang creates curved, efficient paths.

What is Boomerang Control?

Basic Concept

Boomerang control combines position control and heading control to create smooth, curved paths that:

• Minimize total travel time
• Reduce wheel slippage
• Provide predictable, repeatable motion
• Allow for dynamic obstacle avoidance

Why "Boomerang"?

The algorithm is called "Boomerang" because the robot's path often resembles the curved flight path of a boomerang - smooth, arcing motions rather than sharp turns.

How Boomerang Works

Algorithm Steps

1. Calculate target vector from current position to goal
2. Determine optimal heading based on target direction and desired final heading
3. Generate smooth path using carrot-following technique
4. Apply motion commands to follow the generated path

Key Parameters

// Example Boomerang movement
chassis.moveToPoint(24, 24,     // Target X, Y coordinates (inches)
                   2000,        // Timeout (ms)
                   {.forwards = false,    // Drive backwards
                    .maxSpeed = 100});    // Maximum speed

Boomerang vs. Other Controllers

Controller Type	Path Shape	Use Case	Pros	Cons
Point-to-Point	Straight line	Simple movements	Fast, direct	Sharp turns, wheel slip
Pure Pursuit	Smooth curves	Complex paths	Very smooth	Requires pre-planned path
Boomerang	Curved arcs	Dynamic targets	Smooth + flexible	More complex tuning

Configuration and Tuning

Movement Options

lemlib::MoveToPointParams params;
params.forwards = true;        // Drive forwards (false = backwards)
params.maxSpeed = 127;         // Maximum speed (0-127)
params.minSpeed = 20;          // Minimum speed to prevent stalling
params.earlyExitRange = 2;     // Distance to start slowing down (inches)

Advanced Parameters

• Lead Distance: How far ahead to "look" for path planning
• Settle Range: Distance tolerance for reaching target
• Settle Time: Time to remain within settle range
• Timeout: Maximum time allowed for movement

Practical Applications

Autonomous Routines

void autonomous() {
    // Move to scoring position with optimal path
    chassis.moveToPoint(48, 24, 3000, {.forwards = true, .maxSpeed = 100});
    
    // Turn to face goal while moving
    chassis.turnToHeading(90, 1000);
    
    // Move to next position
    chassis.moveToPoint(24, 48, 3000, {.forwards = false, .maxSpeed = 80});
}

Field Navigation

• Scoring runs: Smooth approach to goals
• Game piece collection: Efficient pickup patterns
• Defensive positioning: Quick repositioning
• Multi-point paths: Chaining multiple movements

Advantages of Boomerang

Mechanical Benefits

• Reduced wheel wear: Smooth curves vs. sharp turns
• Less motor strain: Gradual acceleration/deceleration
• Improved traction: Minimizes wheel slippage
• Consistent timing: Predictable movement duration

Programming Benefits

• Simple interface: Single function call for complex movements
• Automatic optimization: Algorithm finds efficient paths
• Robust performance: Handles odometry errors gracefully
• Flexible parameters: Customizable for different situations

Common Use Cases

1. Scoring Sequences

// Approach scoring zone smoothly
chassis.moveToPoint(scoreX, scoreY, 2000, {.forwards = true});
// Score game piece
scoreGamePiece();
// Back away efficiently
chassis.moveToPoint(safeX, safeY, 1500, {.forwards = false});

2. Game Piece Collection

// Navigate to game piece with optimal approach angle
chassis.moveToPoint(pieceX, pieceY, 2500, {.forwards = true, .maxSpeed = 90});
// Collect piece
collectPiece();

3. Defensive Positioning

// Quick repositioning for defense
chassis.moveToPoint(defenseX, defenseY, 1000, {.maxSpeed = 127});

Tuning Guidelines

Speed Settings

• High speed: Use for long, open movements
• Medium speed: Use for precision positioning
• Low speed: Use near obstacles or for final approach

Direction Selection

• Forwards: When robot front has intake/mechanisms
• Backwards: When robot back is more maneuverable
• Choose based on: Next action, obstacle avoidance, time efficiency

Timeout Values

• Conservative: 3-4 seconds for most movements
• Aggressive: 1-2 seconds for quick repositioning
• Safety: Always include timeout to prevent infinite loops

Troubleshooting

Robot Doesn't Reach Target

Possible Causes:

• Timeout too short
• Obstacles blocking path
• Odometry drift
• Mechanical issues

Solutions:

• Increase timeout value
• Check for physical obstructions
• Recalibrate odometry
• Verify motor and sensor function

Path Too Aggressive

Symptoms: Robot overshoots, loses traction, or moves erratically Solutions:

• Reduce maximum speed
• Increase settle range
• Check PID tuning
• Verify wheel condition

Inconsistent Performance

Causes: Odometry errors, battery voltage, field conditions Solutions:

• Regular odometry calibration
• Monitor battery levels
• Adjust for field variations

Integration with Other Systems

Sensor Feedback

// Use vision to refine target position
if (visionTargetDetected()) {
    auto target = getVisionTarget();
    chassis.moveToPoint(target.x, target.y, 2000);
}

State Machines

switch (autonomousState) {
    case MOVE_TO_SCORE:
        chassis.moveToPoint(scorePos.x, scorePos.y, 2000);
        if (chassis.isSettled()) {
            autonomousState = SCORE_PIECE;
        }
        break;
}

Performance Optimization

Path Efficiency

• Plan movements to minimize total distance
• Consider robot orientation for next action
• Chain movements smoothly
• Avoid unnecessary direction changes

Timing Optimization

• Use appropriate speeds for each segment
• Overlap movements with mechanism actions
• Minimize settle times where possible
• Plan for consistent cycle times

Future Enhancements

• Dynamic obstacle avoidance
• Multi-point path planning
• Velocity profiling integration
• Real-time path optimization
• Integration with vision systems

---

Last updated: 2025-08-25