Optical#

Introduction #

The Optical Sensor is a light-based sensor that uses reflected light to detect objects, identify colors, and measure brightness and hue.

You can also configure the brightness of the sensor’s internal light. These tools are ideal for programs that need to react to colored objects, lighting conditions, or sensor feedback in real time.

This page uses optical_1 as the example Optical Sensor name. Replace it with your own configured name as needed.

Below is a list of all methods:

Actions — Turn the Optical Sensor’s LED on or off.

set_light — Sets the on or off state of the LED.

Mutators — Adjust LED brightness and object detection settings.

set_light_power — Sets the brightness of the LED.
object_detect_threshold — Sets the threshold for detecting objects.

Getters — Read object presence, color, brightness, hue, RGB, and sensor status.

is_near_object — Returns whether a detected object is near the Optical Sensor.
color — Returns the closest detected color match.
brightness — Returns the brightness of a detected object.
hue — Returns the hue of a detected object.
rgb — Returns the RGB values detected by the Optical Sensor.
installed — Returns whether an Optical Sensor is connected to the Brain.

Callback — Run code when an object is detected or lost.

object_detected — Registers a function to be called when an object is detected.
object_lost — Registers a function to be called when an object is lost.

Constructors — Manually initialize and configure an Optical Sensor.

Optical — Creates an Optical Sensor.

Actions #

set_light #

set_light sets Optical Sensor’s LED to on, off, or a set brightness level.

Usage:
optical_1.set_light(state)

Parameters	Description
`state`	The state to set the light or the percentage of power in the range 0 to 100. The state can be either of the following: `LedStateType.OFF` (0 percent) `LedStateType.ON` (100 percent) `integer` — A brightness value given as an integer from 0 to 100.

Parameters

Description

state

The state to set the light or the percentage of power in the range 0 to 100. The state can be either of the following:

LedStateType.OFF (0 percent)
LedStateType.ON (100 percent)
integer — A brightness value given as an integer from 0 to 100.

# Turn the LED on and off forever
while True:
    optical_1.set_light(LedStateType.ON)
    wait(0.5, SECONDS)
    optical_1.set_light(LedStateType.OFF)
    wait(0.5, SECONDS)

# Turn the LED on and off forever
while True:
    optical_1.set_light(100)
    wait(0.5, SECONDS)
    optical_1.set_light(0)
    wait(0.5, SECONDS)

Mutators #

set_light_power #

set_light_power sets the brightness of the Optical Sensor’s light. If the LED is not already on, this method will also turn the LED on.

Usage:
optical_1.set_light_power(value)

Parameters	Description
`value`	The power level to set the light from 0 to 100 as a percent.

# Turn the LED light on at different
# intensities
optical_1.set_light(LedStateType.ON)
wait(2, SECONDS)
optical_1.set_light_power(10)
wait(2, SECONDS)
optical_1.set_light_power(100)

object_detect_threshold #

object_detect_threshold sets the range that the sensor can detect objects from. This method also returns the newly set threshold.

Numbers closer to 255 indicate a smaller range, while numbers closer to 0 indicate a larger range.

Usage:
optical_1.object_detect_threshold(value)

Parameters	Description
`value`	A number in the range 0 - 255. A value of 0 will just return the current value.

def detected():
    # The Brain will print that an object was detected on
    # the Brain's screen.
    brain.screen.print("object detected")
    brain.screen.next_row()
    optical_1.object_detect_threshold(254)
    optical_1.object_detected(detected_closer)

def detected_closer():
    # Detect an object closer to the sensor.
    brain.screen.print("Detected closer")
    
# Run detected when the Optical Sensor detects an object.
optical_1.object_detect_threshold(100)
optical_1.object_detected(detected)

# Detect an object first with the detect threshold at 100,
# then again at 254
stage = 0

def detected():
    global stage
    if stage == 0:
        brain.screen.print("Get closer...")
        brain.screen.next_row()
        stage = 1
        optical_1.object_detect_threshold(254)
        optical_1.object_detected(detected_closer)

def detected_closer():
    global stage
    if stage == 1:
        brain.screen.print("Too close!")
        brain.screen.next_row()
        stage = 2

optical_1.object_detect_threshold(100)
optical_1.object_detected(detected)
wait(15, MSEC)

Getters #

is_near_object #

is_near_object returns whether the Optical Sensor is nearby an object.

True — The sensor is near an object.
False — The sensor is not near an object.

Usage:
optical_1.is_near_object()

Parameters	Description
	This method has no parameters.

# Stop driving when Optical Sensor is 
# near an object
while True:
    if optical_1.is_near_object():
        drivetrain.stop()
    else:
        drivetrain.drive(FORWARD)

color #

color returns the predefined color detected by the Optical Sensor from the colors below:

BLACK
BLUE
CYAN
GREEN
ORANGE
PURPLE
RED
TRANSPARENT
WHITE
YELLOW

Usage:
optical_1.color()

Parameters	Description
	This method has no parameters.

# Stop the robot if the Optical Sensor 
# detects red
while True:
    if optical_1.color() == Color.RED:
        drivetrain.stop()
    else:
        drivetrain.turn(RIGHT)

brightness #

brightness returns the brightness detected by the Optical Sensor.

A higher percentage means the Optical Sensor detects more light. A lower percentage means the Optical Sensor detects less light.

Usage:
optical_1.brightness(readraw)

Parameters	Description
`readraw`	Optional. A Boolean value to read raw brightness data instead of percentage: `True` — Return the raw data. `False` (default) — Return brightness as a percentage.

Parameters

Description

readraw

Optional. A Boolean value to read raw brightness data instead of percentage:

True — Return the raw data.
False (default) — Return brightness as a percentage.

hue #

hue returns the value of the hue detected by the Optical Sensor as a float in the range of 0 to 359.99 degrees.

Hue is a way to describe color using numbers around a color wheel, as shown below.

A circular color wheel displaying a full spectrum of hues labeled with degree values around the perimeter, increasing in 30-degree increments from 0° at the top to 360°.

Usage:
optical_1.hue()

Parameters	Description
	This method has no parameters.

# Check the hue of a detected object
# to determine if it is pink
while True:
    brain.screen.clear_screen()
    brain.screen.set_cursor(1, 1)
    if 290 < optical_1.hue() < 350:
        brain.screen.print("Pink!")
        wait(0.1,SECONDS)
    else:
        brain.screen.print("Not pink.")
        wait(0.1,SECONDS)

rgb #

rgb returns the red, green, blue, and brightness values detected by the Optical Sensor as a Tuple.

Usage:
optical_1.rgb(raw)

Parameters	Description
`raw`	Optional. A Boolean value to determine if you return raw or processed values: `True` — Return the raw value. `False` (default) — Do not return the raw value.

Parameters

Description

raw

Optional. A Boolean value to determine if you return raw or processed values:

True — Return the raw value.
False (default) — Do not return the raw value.

# Display the rgb values and brightness detected
# by the Optical Sensor.
brain.screen.set_font(FontType.MONO12)
while True:
    brain.screen.clear_screen()
    brain.screen.set_cursor(1, 1)
    brain.screen.print(optical_1.rgb())
    wait(0.1, SECONDS)

installed #

installed returns a Boolean indicating whether the Optical Sensor is connected to the Brain.

True — The Optical Sensor is connected to the Brain.
False — The Optical Sensor is not connected to the Brain.

Usage:
optical_1.installed()

Parameters	Description
	This method has no parameters.

# Display a message if the Optical Sensor
# is installed.
if optical_1.installed():
    brain.screen.print("Installed!")

Callback #

object_detected #

object_detected registers a callback function for when an object is detected.

Usage:
optical_1.object_detected(callback, arg)

Parameters	Description
`callback`	A function that is previously defined to execute when an object is detected.
`arg`	Optional. A tuple containing arguments to pass to the callback function. See Functions with Parameters for more information.

def detected():
    drivetrain.stop()
    brain.screen.set_cursor(1, 1)
    brain.screen.print("object detected")
    wait(0.5,SECONDS)
    brain.screen.clear_screen()

# Display a message when the 
# Optical Sensor detects an object
drivetrain.drive(FORWARD)
optical_1.object_detected(detected)

object_lost #

object_lost registers a callback function for when the Optical Sensor loses a detected object.

Usage:
optical_1.object_lost(callback, arg)

Parameters	Description
`callback`	A function that is previously defined to execute when an object is lost.
`arg`	Optional. A tuple containing arguments to pass to the callback function. See Functions with Parameters for more information.

def lost():
    drivetrain.stop()
    brain.screen.set_cursor(1, 1)
    brain.screen.print("object lost")
    wait(0.5,SECONDS)
    brain.screen.clear_screen()

# Display a message when the Optical 
# Sensor loses sight of on object
drivetrain.drive(REVERSE)
optical_1.object_lost(lost)

Constructors #

Constructors are used to manually create Optical objects, which are necessary for configuring an Optical Sensor outside of VEXcode.

Optical #

Optical creates an Optical Sensor.

Usage:
Optical(smartport)

Parameter	Description
`smartport`	The Smart Port that the Optical Sensor is connected to, written as PORTx where x is the number of the port.

# Construct an Optical Sensor "optical_1" with the
# Optical class
optical_1 = Optical(Ports.PORT1)

# Display the brightness of a red object detected
# by the Optical Sensor
drivetrain.turn(RIGHT)
while not optical_1.color() == Color.RED:
    wait(50, MSEC)
drivetrain.stop()
brain.screen.print(optical_1.brightness())