Getting Started
Welcome to TurtleTracerLib! This guide will walk you through creating your first autonomous program using the library.
Prerequisites
Section titled “Prerequisites”Before you begin, ensure you have:
- Installed TurtleTracerLib in your project (see Installation).
- Configured your robot's hardware map (motors, sensors) in the Driver Station or
FtcRobotController.
The Recommended Workflow
Section titled “The Recommended Workflow”The modern TurtleTracerLib workflow is "Visualizer-First":
- Design your path in TurtleTracer.
- Export the path as a complete Java OpMode.
- Run the generated code on your robot.
This approach eliminates the need to manually write complex geometry code and ensures your paths are visualized correctly before you even touch the robot.
Creating Your First Path
Section titled “Creating Your First Path”1. Open TurtleTracer
Section titled “1. Open TurtleTracer”Go to the TurtleTracer (or your hosted instance).
2. Draw a Path
Section titled “2. Draw a Path”- Click the + (Add Path) button or press
P. - Click on the field to place your starting point.
- Click again to place the end point.
- Drag the control handles to shape the curve if desired.
3. Export Your Code
Section titled “3. Export Your Code”When you are ready to export, you have two options: a standard Java OpMode or a Command-Based structure.
Use this option if you want a standalone OpMode that handles the path following logic directly.
- Click the Export button in the top right corner.
- Choose Java Code from the menu, or Kotlin Code if your team writes Kotlin.
- Check "Generate Full Class".
- Enter your team's package name (e.g.,
org.firstinspires.ftc.teamcode). - Click Copy Code.
- Paste the code into a new Java (or Kotlin) file in your Android Studio project.
Example Output
Section titled “Example Output”Below is the OpMode generated for a project with one path, in Java and in Kotlin. Note the use of PanelsTelemetry and Constants.
package org.firstinspires.ftc.teamcode;
import static com.pedropathing.api.Paths.curve;import static com.pedropathing.api.Paths.line;import static com.pedropathing.api.Paths.path;
import com.bylazar.configurables.annotations.Configurable;import com.bylazar.telemetry.PanelsTelemetry;import com.bylazar.telemetry.TelemetryManager;import com.pedropathing.api.PoseFactory;import com.pedropathing.follower.Follower;import com.pedropathing.math.Pose;import com.pedropathing.paths.Path;import com.pedropathing.paths.interpolator.Interpolator;import com.qualcomm.robotcore.eventloop.opmode.Autonomous;import com.qualcomm.robotcore.eventloop.opmode.OpMode;import com.qualcomm.robotcore.util.ElapsedTime;import org.firstinspires.ftc.teamcode.pedro.Constants;
@Autonomous(name = "Turtle Tracer Autonomous", group = "Autonomous")@Configurable // Panelspublic class TurtleTracerAutonomous extends OpMode {
private TelemetryManager panelsTelemetry; // Panels Telemetry instance public Follower follower; // Pathing follower instance private final PoseFactory p = PoseFactory.degrees(); private int pathState; // Current autonomous path state (state machine) private ElapsedTime pathTimer; // Timer for path state machine private Paths paths; // Paths defined in the Paths class
@Override public void init() { panelsTelemetry = PanelsTelemetry.INSTANCE.getTelemetry(); // ... panelsTelemetry.debug("Status", "Initialized"); panelsTelemetry.update(telemetry);
follower = Constants.create(hardwareMap); follower.setPose(p.of(56.000, 8.000, 90.000));
pathTimer = new ElapsedTime(); paths = new Paths(follower); // Build paths }
@Override public void loop() { follower.update(); // Update follower pathState = autonomousPathUpdate(); // Update autonomous state machine
// Log values to Panels and Driver Station panelsTelemetry.debug("Path State", pathState); panelsTelemetry.debug("X", follower.pose().x()); panelsTelemetry.debug("Y", follower.pose().y()); panelsTelemetry.debug("Heading", follower.pose().heading()); panelsTelemetry.update(telemetry); }
public static class Paths {
private static final PoseFactory p = PoseFactory.degrees(); public Path line1;
public Paths(Follower follower) { line1 = line(p.of(56.000, 8.000, 0.0), p.of(56.000, 36.000, 0.0)).linear( Math.toRadians(90), Math.toRadians(180) ); } }
public int autonomousPathUpdate() { switch (pathState) { case 0: follower.follow(paths.line1); setPathState(1); break; case 1: if (!follower.isBusy()) { setPathState(2); } break; case 2: requestOpModeStop(); pathState = -1; break; } return pathState; }
public void setPathState(int pState) { pathState = pState; pathTimer.reset(); }}package org.firstinspires.ftc.teamcode
import com.qualcomm.robotcore.eventloop.opmode.OpModeimport com.qualcomm.robotcore.eventloop.opmode.Autonomousimport com.qualcomm.robotcore.util.ElapsedTimeimport org.firstinspires.ftc.teamcode.pedro.Constants
import com.bylazar.configurables.annotations.Configurableimport com.bylazar.telemetry.TelemetryManagerimport com.bylazar.telemetry.PanelsTelemetryimport com.pedropathing.api.PoseFactoryimport com.pedropathing.follower.Followerimport com.pedropathing.paths.Pathimport com.pedropathing.api.Paths.curveimport com.pedropathing.api.Paths.lineimport com.pedropathing.api.Paths.pathimport com.pedropathing.math.Poseimport com.pedropathing.paths.interpolator.Interpolator
@Autonomous(name = "Turtle Tracer Autonomous", group = "Autonomous")@Configurable // Panelsclass TurtleTracerAutonomous : OpMode() { private lateinit var panelsTelemetry: TelemetryManager // Panels Telemetry instance lateinit var follower: Follower // Pathing follower instance private val p = PoseFactory.degrees() private var pathState = 0 // Current autonomous path state (state machine) private lateinit var pathTimer: ElapsedTime // Timer for path state machine private lateinit var paths: Paths // Paths defined in the Paths class
override fun init() { panelsTelemetry = PanelsTelemetry.telemetry // ... panelsTelemetry.debug("Status", "Initialized") panelsTelemetry.update(telemetry)
follower = Constants.create(hardwareMap) follower.setPose(p.of(56.000, 8.000, 90.000))
pathTimer = ElapsedTime() paths = Paths() // Build paths }
override fun loop() { follower.update() // Update follower pathState = autonomousPathUpdate() // Update autonomous state machine
// Log values to Panels and Driver Station panelsTelemetry.debug("Path State", pathState) panelsTelemetry.debug("X", follower.pose().x()) panelsTelemetry.debug("Y", follower.pose().y()) panelsTelemetry.debug("Heading", follower.pose().heading()) panelsTelemetry.update(telemetry) }
class Paths { val line1: Path
init { line1 = line( p.of(56.000, 8.000, 0.0), p.of(56.000, 36.000, 0.0) ).linear(Math.toRadians(90.0), Math.toRadians(180.0)) }
companion object { private val p = PoseFactory.degrees() } }
fun autonomousPathUpdate(): Int { when (pathState) { 0 -> { follower.follow(paths.line1) setPathState(1) } 1 -> { if(!follower.isBusy()) { setPathState(2) } } 2 -> { requestOpModeStop() pathState = -1 } } return pathState }
fun setPathState(pState: Int) { pathState = pState pathTimer.reset() }}Key Components
Section titled “Key Components”pathState: A state machine variable that tracks which segment of the path is currently running.PathsClass: Contains all your generatedPathdefinitions.autonomousPathUpdate(): The logic that switches between paths and waits for completion.
Use this option if you are using a Command-Based framework (like SolversLib). This generates a SequentialCommandGroup rather than a full OpMode.
- Click the Export button in the top right corner.
- Select Sequential Command as the format, then choose SolversLib, NextFTC, or Ivy as the target library. NextFTC and Ivy output is experimental.
- Enter your team's package name, and use the Language switch to choose Java or Kotlin.
- Click Copy Code (or Save to File).
- Important: Unless you turn on Embed Pose Data, this method requires you to put the project file (
.turt) on your robot as well, because it usesTurtleTracerReaderto load points dynamically. The example below uses SolversLib.
Ivy output: Ivy builds commands with static factories rather than subclassing, so the generated class returns a Command instead of extending one. Call Scheduler.reset() in init(), start the routine with new AutoPath(follower, hardwareMap).command().schedule(), and call follower.update() and Scheduler.execute() every loop.
Example Output
Section titled “Example Output”This is the class generated for a three-path routine with a wait and two event markers. It reads its poses from AutoPath.turt, and registers each path's event markers just before that path runs.
package org.firstinspires.ftc.teamcode.Commands.AutoCommands;
import static com.pedropathing.api.Paths.curve;import static com.pedropathing.api.Paths.line;import static com.pedropathing.api.Paths.path;
import com.pedropathing.api.PoseFactory;import com.pedropathing.follower.Follower;import com.pedropathing.math.Pose;import com.pedropathing.paths.Path;import com.pedropathing.paths.interpolator.Interpolator;import com.qualcomm.robotcore.hardware.HardwareMap;import com.seattlesolvers.solverslib.command.InstantCommand;import com.seattlesolvers.solverslib.command.ParallelRaceGroup;import com.seattlesolvers.solverslib.command.RunCommand;import com.seattlesolvers.solverslib.command.SequentialCommandGroup;import com.seattlesolvers.solverslib.command.WaitCommand;import com.seattlesolvers.solverslib.command.WaitUntilCommand;import com.seattlesolvers.solverslib.pedroCommand.FollowPathCommand;import com.turtletracerlib.TurtleTracerReader;import com.turtletracerlib.auto.TurtleAuto;import com.turtletracerlib.pathing.NamedCommands;import com.turtletracerlib.pathing.ProgressTracker;import java.io.IOException;import org.firstinspires.ftc.robotcore.external.Telemetry;
@TurtleAuto(name = "AutoPath")public class AutoPath extends SequentialCommandGroup {
private final Follower follower; private final PoseFactory p = PoseFactory.degrees(); private TurtleTracerReader pp; private ProgressTracker tracker;
// Poses private Pose startPoint; private Pose DriveToShoot; private Pose DriveToShoot_line0_control1; private Pose CollectRow1; private Pose CollectRow1_line1_control1; private Pose ReturnToShoot;
// Path chains private Path startPointTODriveToShoot; private Path DriveToShootTOCollectRow1; private Path CollectRow1TOReturnToShoot;
public AutoPath(final Follower follower, HardwareMap hw, Telemetry telemetry) throws IOException { this.follower = follower;
pp = new TurtleTracerReader("AutoPath.turt", hw.appContext); pp.onEvent("SpinUp", NamedCommands.getCommand("SpinUp")).onEvent( "Intake", NamedCommands.getCommand("Intake") );
tracker = new ProgressTracker(follower, telemetry);
// Load poses startPoint = pp.get("startPoint"); DriveToShoot = pp.get("DriveToShoot"); DriveToShoot_line0_control1 = pp.get("DriveToShoot_line0_control1"); CollectRow1 = pp.get("CollectRow1"); CollectRow1_line1_control1 = pp.get("CollectRow1_line1_control1"); ReturnToShoot = pp.get("ReturnToShoot");
follower.setPose(startPoint);
buildPaths();
addCommands( new InstantCommand(() -> { tracker.clearPathEvents(); pp.registerLineEvents(tracker, 0, 0); tracker.setCurrentPath(startPointTODriveToShoot); }), new ParallelRaceGroup( new FollowPathCommand(follower, startPointTODriveToShoot), new RunCommand(() -> tracker.update()) ), new WaitCommand(1500), new FollowPathCommand(follower, DriveToShootTOCollectRow1), new InstantCommand(() -> { tracker.clearPathEvents(); pp.registerLineEvents(tracker, 2, 0); tracker.setCurrentPath(CollectRow1TOReturnToShoot); }), new ParallelRaceGroup( new FollowPathCommand(follower, CollectRow1TOReturnToShoot), new RunCommand(() -> tracker.update()) ) ); }
public void buildPaths() { startPointTODriveToShoot = curve( startPoint, p.of(28.000, 22.000, 0.0), DriveToShoot ).linear(Math.toRadians(0), Math.toRadians(45));
DriveToShootTOCollectRow1 = curve( DriveToShoot, p.of(30.000, 58.000, 0.0), CollectRow1 ).tangent();
CollectRow1TOReturnToShoot = line(CollectRow1, ReturnToShoot).linear( Math.toRadians(90), Math.toRadians(45) ); }}package org.firstinspires.ftc.teamcode.Commands.AutoCommands
import com.pedropathing.api.PoseFactoryimport com.pedropathing.follower.Followerimport com.pedropathing.paths.Pathimport com.pedropathing.api.Paths.curveimport com.pedropathing.api.Paths.lineimport com.pedropathing.api.Paths.pathimport com.pedropathing.math.Poseimport com.pedropathing.paths.interpolator.Interpolatorimport com.qualcomm.robotcore.hardware.HardwareMapimport com.turtletracerlib.auto.TurtleAuto
import com.seattlesolvers.solverslib.command.SequentialCommandGroupimport com.seattlesolvers.solverslib.command.ParallelRaceGroupimport com.seattlesolvers.solverslib.command.WaitCommandimport com.seattlesolvers.solverslib.command.WaitUntilCommandimport com.seattlesolvers.solverslib.command.InstantCommandimport com.seattlesolvers.solverslib.command.RunCommandimport com.seattlesolvers.solverslib.pedroCommand.FollowPathCommand
import org.firstinspires.ftc.robotcore.external.Telemetryimport com.turtletracerlib.TurtleTracerReaderimport com.turtletracerlib.pathing.ProgressTrackerimport com.turtletracerlib.pathing.NamedCommands
@TurtleAuto(name = "AutoPath")class AutoPath( private val follower: Follower, hw: HardwareMap, telemetry: Telemetry,) : SequentialCommandGroup() { private val p = PoseFactory.degrees() private val pp: TurtleTracerReader private val tracker: ProgressTracker
// Poses private val startPoint: Pose private val DriveToShoot: Pose private val DriveToShoot_line0_control1: Pose private val CollectRow1: Pose private val CollectRow1_line1_control1: Pose private val ReturnToShoot: Pose
// Path chains private lateinit var startPointTODriveToShoot: Path private lateinit var DriveToShootTOCollectRow1: Path private lateinit var CollectRow1TOReturnToShoot: Path
init { pp = TurtleTracerReader("AutoPath.turt", hw.appContext) pp.onEvent("SpinUp", NamedCommands.getCommand("SpinUp")) .onEvent("Intake", NamedCommands.getCommand("Intake"))
tracker = ProgressTracker(follower, telemetry)
// Load poses startPoint = pp.get("startPoint") DriveToShoot = pp.get("DriveToShoot") DriveToShoot_line0_control1 = pp.get("DriveToShoot_line0_control1") CollectRow1 = pp.get("CollectRow1") CollectRow1_line1_control1 = pp.get("CollectRow1_line1_control1") ReturnToShoot = pp.get("ReturnToShoot")
follower.setPose(startPoint)
buildPaths()
addCommands( InstantCommand({ tracker.clearPathEvents() pp.registerLineEvents(tracker, 0, 0) tracker.setCurrentPath(startPointTODriveToShoot) }), ParallelRaceGroup( FollowPathCommand(follower, startPointTODriveToShoot), RunCommand({ tracker.update() }) ), WaitCommand(1500), FollowPathCommand(follower, DriveToShootTOCollectRow1), InstantCommand({ tracker.clearPathEvents() pp.registerLineEvents(tracker, 2, 0) tracker.setCurrentPath(CollectRow1TOReturnToShoot) }), ParallelRaceGroup( FollowPathCommand(follower, CollectRow1TOReturnToShoot), RunCommand({ tracker.update() }) ) ) }
fun buildPaths() { startPointTODriveToShoot = curve(startPoint, p.of(28.000, 22.000, 0.0), DriveToShoot) .linear(Math.toRadians(0.0), Math.toRadians(45.0))
DriveToShootTOCollectRow1 = curve(DriveToShoot, p.of(30.000, 58.000, 0.0), CollectRow1) .tangent()
CollectRow1TOReturnToShoot = line(CollectRow1, ReturnToShoot) .linear(Math.toRadians(90.0), Math.toRadians(45.0)) }}Key Components
Section titled “Key Components”SequentialCommandGroup: The base class for the entire routine.TurtleTracerReader: Used to load named poses from the saved path file, and to register each path's event markers.ProgressTracker: Triggers the event markers. TheParallelRaceGrouprunstracker.update()while each path is followed.FollowPathCommand: A command from SolversLib that wraps the path following logic.
Next Steps
Section titled “Next Steps”- Explore Command-Based Programming for integrating paths into a larger robot framework.
- Learn about Live View to see your robot's position in real-time.