V5 Optical Sensor — Overview 🔮

1. Color Hue (0–360 degrees)

The hue is the angular position on the color wheel. Returned as a double from 0 to 359.99.

Detection works best when the object is < 100mm from the sensor. At greater distances, hue readings become inconsistent and noisy.

PROS function: optical.get_hue()

2. Saturation (0.0–1.0)

How "pure" the color is. 0.0 = grayscale (no color), 1.0 = fully saturated. Useful for distinguishing actual colored objects from ambient white reflections or grayscale field tiles.

PROS function: optical.get_saturation()

3. Brightness (0.0–1.0)

How bright the detected object is. Useful for distinguishing white from black, light from dark.

PROS function: optical.get_brightness()

4. Proximity (0–255)

The IR-based proximity reading. Higher values = closer object. Per PROS docs: range is 0 to 255. Per VEX docs: nominal sensor range is ~10cm.

Per VEX docs: proximity uses reflected IR (infrared) energy from an integrated IR LED, NOT the white LED. The white LED is for color detection only.

Important PROS limitation: Proximity is NOT available when gesture detection is enabled. Pick one or the other.

PROS function: optical.get_proximity()

5. Gesture Detection

Detects four directional motions of an object passing in front of the sensor: UP, DOWN, LEFT, RIGHT. Returned as optical_direction_e_t enum (NO_GESTURE, UP, DOWN, LEFT, RIGHT, ERROR).

PROS functions: optical.enable_gesture(), optical.get_gesture(), optical.disable_gesture()

Note: Useful for detecting things like a ring passing through your intake (motion event), but you lose proximity readings when gesture mode is on. For most competition uses, leave gestures disabled and use proximity directly.

6. RGB Components

If you need raw red/green/blue values (e.g., to do your own color matching with custom thresholds), PROS provides:

optical.get_rgb() — returns a struct with red, green, blue, and brightness fields.

PROS exposes saturation and full RGB separately; per Purdue SIGBots Wiki, this is more granular than VEXcode's API.

7. Integration Time (Update Rate)

How often the sensor updates internally. Lower = faster updates but noisier; higher = slower but more stable.

PROS functions: optical.set_integration_time(ms) — range 3–712ms. Default is fine for most use cases. Lower it if you need faster reaction (~10–20ms) for sorting fast-moving game elements.

The Cardinal Rule: Stay Within 100mm

Color detection works best when the object is < 100mm (~4 inches) from the sensor face. This is the single most important constraint. If you mount the sensor far from where game elements travel, you will get unreliable readings or no readings at all.

Recommended Mounting Locations

Mechanical Mounting Details

Per VEX Library on the Optical Sensor:

• The sensor housing has two mounting tabs with slotted holes.
• The width fits inside a C-channel.
• Use a 1/4″ standoff (part 275-1013) or 8mm plastic spacer (276-2019) when mounting to a C-channel — this provides clearance for the V5 Smart Port on the side of the sensor.
• The Smart Port is on the side of the sensor, not the bottom or back. Plan your cable routing accordingly.
• The optical window is on the face of the sensor — do not block this with structure or wires.

White LED Considerations

The integrated white LED is a critical feature. It illuminates objects close to the sensor for consistent color detection regardless of ambient light.

• Set LED to ~50–75% PWM for general use. optical.set_led_pwm(50) in PROS.
• The LED is what makes the sensor reliable across competition venues. Different gymnasiums have different lighting; the LED counters this by being your dominant light source for objects right next to the sensor.
• The LED is NOT used for proximity detection (the IR LED is used for that). Turning the white LED off does not disable proximity sensing.
• Don't leave the LED at 100% — it can wash out the colors of very close objects, leading to incorrect hue readings.

Calibration Pre-Match

Before every competition (or at least at every new venue):

1. Place each game element you care about (red ring, blue ring, mobile goal, etc.) at the position the sensor will see it during a match.
2. Read and log the hue, saturation, brightness, and proximity values for each.
3. Build a hue-range table: e.g., red rings = hue 350–15°, blue rings = hue 215–245°.
4. Use these ranges in your code for color classification, not raw equality.

You can build a small calibration utility that prints values to the V5 Brain screen and runs in opcontrol — press a button to log the current readings.

Verified PROS API Reference

Pattern 1: Color Classification (Alliance Sort)

Determine if a detected object is a red ring, blue ring, or unknown. Use hue ranges from your pre-match calibration.

Pattern 2: Proximity-Triggered Intake Stop

Run intake until proximity hits a threshold (object detected), then stop. Avoids over-stuffing the intake.

Pattern 3: Auto-Sort (Reject Wrong-Color Rings)

Combine color detection with intake control to ONLY keep alliance-colored rings.

Pattern 4: Calibration Helper

A simple opcontrol-mode utility that prints live sensor values to the V5 Brain screen. Use it during pit setup to record values for your hue ranges.

Hold a red ring in front of the sensor: hue should read ~0° (or ~360). Try a blue ring: ~230. Try a mobile goal in your alliance color: log it. Build your tables from this.

The Honest Picture

EZ-Template and LemLib are chassis movement libraries. They handle:

• Drivetrain PID (drive, turn, swing turns, arcs)
• Odometry with Pure Pursuit and Boomerang motion
• Asynchronous PID with blocking and non-blocking calls
• Joystick control modes (tank, arcade, single-stick)
• Autonomous selectors with SD-card-saved selections
• The IMU is wrapped (it's part of the chassis constructor)

They do NOT wrap:

• The Optical Sensor
• The AI Vision Sensor
• The Distance Sensor (for non-drivetrain uses)
• The Rotation Sensor (for non-drivetrain uses)
• Custom subsystems (intake, lift, climb)

For sensors and custom mechanisms, you use the standard PROS API directly. Integration with EZ-Template happens in your autonomous code — you compose chassis motion calls with sensor reads.

Pattern A: Sensor-Triggered Motion Exit

Start an EZ-Template chassis motion, watch a sensor in parallel, cancel the motion when sensor condition met.

Pattern B: Pre-Move Sensor Check

Before issuing a chassis movement, check if the sensor reports the expected condition. Use this for preconditions in auton sequences.

Pattern C: Background Sensor Task + Chassis Auton

Run sensor monitoring in a background task; main auton calls EZ-Template chassis motions in sequence. Sensor task can preempt or signal main flow.

LemLib Equivalent Pattern

The same patterns apply with LemLib. Method names differ:

• EZ-Template chassis.pid_drive_set → LemLib chassis.moveTo or chassis.moveToPoint
• EZ-Template chassis.pid_targets_reset → LemLib chassis.cancelMotion
• EZ-Template chassis.pid_wait → LemLib chassis.waitUntilDone

Both libraries support async motion with sensor-triggered exits. Pick the library your team is most comfortable with — the integration patterns work in either.

Where to Define Your Sensor

In an EZ-Template-based PROS project, the standard convention is to declare global sensor instances in subsystems.hpp (declared extern) and define them in subsystems.cpp. EZ-Template's example project follows this convention.

Application 1: Cup Orientation Detection (Primary Override Use)

This is the most distinctive Override application of the Optical Sensor — it doesn't exist in past V5RC games and it matters more than any other use here.

The problem: A cup is hourglass-shaped with one transparent half and one opaque half. When the cup is stacked over a pin in a goal, only the half facing the transparent side of the cup is visible to scoring. If your manipulator places the cup with the opaque side over the wrong pin half, you've just suppressed scoring on that half. For yellow halves with an active toggle, that's a 10-point loss per accidental misplacement.

The fix: Mount an Optical Sensor inside the cup-handling part of the manipulator. As the cup is held, the sensor reads the brightness of the surface adjacent to it:

• Opaque (gray) side near sensor: low light return, characteristic gray RGB signature.
• Transparent (clear) side near sensor: high light return (passes through to whatever is behind), or significantly different RGB.

From the reading, the code knows the cup's current orientation. Before placement, the manipulator can flip the cup if needed (a single-acting pneumatic on a paddle works well; see advanced-robot Chapter 5 for the cup-flip mechanism pattern).

// Read cup orientation from optical sensor mounted on manipulator
double hue = cup_optical.get_hue();
double brightness = cup_optical.get_brightness();

bool is_opaque_side = (brightness < 0.30);

if (is_opaque_side && should_show_yellow_half) {
    // Wrong orientation. Flip the cup before placing.
    cup_flip_solenoid.set_value(true);
    pros::delay(200);
    cup_flip_solenoid.set_value(false);
}

Application 2: Pin Color Identification

Pins come in 4 color combinations: red/yellow, blue/yellow, yellow/yellow, and red/blue (4 scarce ones). Each pin has 2 halves. Knowing which half is which lets your robot decide:

• Whether to pick up this pin (your alliance color present? skip if it's opponent-only).
• Which way to rotate the pin before placing (so the high-value half faces correctly).
• Whether the "rare" red/blue pin is in front of you (highest strategic priority — only 4 exist).

Mount an Optical Sensor inside the pin gripper or near the intake throat. Read hue:

Application 3: 1+1 Possession State Detection

Override's possession limit (SG6) is 1 cup + 1 pin maximum. The Optical Sensor's proximity reading confirms what your robot is holding:

• Pin gripper sensor: proximity high → pin held; proximity low → gripper empty.
• Cup gripper sensor: same pattern, separate sensor.
• Code checks both before allowing intake of a third object — refuse to intake if SG6 would be violated.

This is identical to the "loaded vs empty" pattern in past V5RC games but specifically gated on Override's 1+1 limit. The two-sensor configuration (one per gripper) is canonical for dual-grip manipulators; single-grip manipulators only need one.

Application 4: Toggle Color Confirmation (Optional)

Toggles in each quadrant change which alliance owns yellow halves. After your robot activates a toggle, you may want to confirm it actually flipped to your color (in case the activation was incomplete or the toggle bounced back). An Optical Sensor mounted to face the toggle housing can read the active color from a few inches away.

Less critical than Applications 1-3 (drivers can usually see the toggle from the field), but useful for autonomous routines where the robot can't pause to verify visually.

Pattern: Multi-Sensor Override Robot

A competitive Override robot uses Optical Sensors in two specific locations:

• In the cup-handling part of the manipulator — Application 1 (orientation detection). This is the highest-leverage placement.
• In the pin gripper or intake throat — Applications 2 and 3 (color ID + possession state).

Plus typically one AI Vision Sensor on the chassis front for navigation (color-based goal/element identification, AprilTag fiducials if confirmed). See sensors-apriltags for the navigation half of the sensor stack.

The V5 Brain has 21 Smart Ports, so port count is rarely the constraint. Two Optical Sensors + one AI Vision + one IMU + drivetrain motors fit comfortably.

Override Hardware Order Plan

For Spartan teams ordering Override sensors:

1. Order at least 1 AI Vision Sensor (276-8659). One per robot is sufficient for chassis-front navigation.
2. Order at least 2 Optical Sensors (276-7043). One for cup orientation (Application 1), one for pin gripper (Applications 2 + 3).
3. Order Smart Cables and the right standoffs/spacers (1/4″ standoff 275-1013 or 8mm spacer 276-2019 for Optical mounting).
4. If AprilTag deployment is confirmed (watch May 14 Q&A), print AprilTag PDF for practice (kb.vex.com).
5. Forum discussion notes that AI Vision Sensor demand exceeds supply at season starts — order early.

Auton Skills (60-second Programming Skills)

Driver Skills (60-second Driver Skills)

Implementation Tips

1. Always have a sensor failure fallback. If the Optical Sensor unplugs (loose Smart Cable, contact damage), all sensor-dependent macros stop working. Provide manual override buttons that bypass sensor checks.
2. Run sensor logic in a dedicated PROS task. Don't poll sensors inline in opcontrol — you'll cause control delays. Background task pattern (shown in Pattern C above) is the right approach.
3. Match-time recalibration. Some teams add a hidden controller-button combination that re-runs hue calibration mid-pit-time. If lighting changes between rounds, you can recalibrate without restarting.
4. Test under tournament-typical lighting BEFORE the tournament. Gym lighting is often dimmer or more orange-tinted than classroom LED lighting. The white LED helps but doesn't fully compensate. Practice in conditions like the venue when possible.

Common Pitfalls

Related Guides