Limelight 3A for FTC

Limelight 3A is a vision processing camera for FTC robotics with on-device processing for AprilTags, color detection, and neural networks.

Quick Start

Hardware Configuration

In Robot Configuration, Limelight appears as a USB device:

• Name: limelight (default)
• Shows IP address as “serial number”

Basic Usage

import com.qualcomm.hardware.limelightvision.Limelight3A
import com.qualcomm.hardware.limelightvision.LLResult

val limelight = hardwareMap.get(Limelight3A::class.java, "limelight")

// MUST call start() before getting results
limelight.pipelineSwitch(0)
limelight.start()

// In loop
val result = limelight.latestResult
if (result.isValid) {
    val tx = result.tx  // Horizontal offset in degrees
    val ty = result.ty  // Vertical offset in degrees
}

// When done
limelight.stop()

Key Concepts

Pipelines

Configure pipelines in Limelight web interface (http://limelight.local:5801):

Switch pipelines: limelight.pipelineSwitch(1)

Coordinate Systems

Limelight Coordinates

• tx: Positive = target right of crosshair
• ty: Positive = target above crosshair
• Origin at camera optical center

Converting to Pedro Pathing

See COORDINATES.md for details.

// Limelight botpose to Pedro Pose
val botpose = result.botpose  // Pose3D in FTC coordinates
val pedroPose = Pose(
    botpose.position.x * INCHES_PER_METER,
    botpose.position.y * INCHES_PER_METER,
    Math.toRadians(botpose.orientation.yaw)
)

Conversion Scripts

Use uv run to execute conversion scripts:

# Convert Limelight botpose to Pedro coordinates
uv run scripts/convert.py botpose-to-pedro 0.5 1.2 45

# Calculate turret ticks from tx
uv run scripts/convert.py tx-to-turret -5.5
uv run scripts/convert.py tx-to-turret -5.5 12.0  # custom ticks/degree

# Calculate distance from ty (ty, cam_height, cam_angle, target_height)
uv run scripts/convert.py distance 15 12 20 36

Anti-Patterns

Don’t: Forget to call start()

// BAD - Results will never be valid
val limelight = hardwareMap.get(Limelight3A::class.java, "limelight")
val result = limelight.latestResult  // Always invalid!

// GOOD - Start before reading
limelight.pipelineSwitch(0)
limelight.start()
val result = limelight.latestResult

Don’t: Skip validity checks

// BAD - May use stale or invalid data
val tx = limelight.latestResult.tx
turret.aimAt(tx)

// GOOD - Always check validity
val result = limelight.latestResult
if (result.isValid) {
    turret.aimAt(result.tx)
}

Don’t: Leave camera running after OpMode

// BAD - Camera keeps running, wastes battery
override fun stop() {
    // Forgot to stop limelight
}

// GOOD - Clean up in stop()
override fun stop() {
    limelight.stop()
}

Reference Documentation

• API_REFERENCE.md – Full class/method reference
• COORDINATES.md – Coordinate system details
• MOUNTING.md – Camera mounting and calibration
• APRILTAG.md – AprilTag detection and localization