Optical#

Introduction #

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

For the examples below, the configured Optical Sensor will be named optical_1 and will be used in all subsequent examples throughout this API documentation when referring to Optical class methods.

Below is a list of all available methods:

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

set_light – Set the on or off state of the LED.

Mutators – Adjust LED brightness and object detection settings.

set_light_power – Set 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 or not 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 or not an Optical Sensor is connected to the Brain.

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

object_detected – Calls a function when an object is detected.
object_lost – Calls a function 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 or off.

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 a percent 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 a percent 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)

Mutators #

set_light_power #

set_light_power sets the light power of the Optical Sensor’s LED.

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 object detection threshold. This method also returns the newly set threshold.

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 or not 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 color detected by the Optical Sensor.

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.

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` – 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 – Return brightness as a percentage.

# 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())

hue #

hue returns the value of the hue detected by the Optical Sensor.

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 Optical Sensor’s RGB value.

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` – 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 the axis’ value changes.
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 an object is lost.

Usage:
optical_1.object_lost(callback, arg)

Parameters	Description
callback	A function that is previously defined to execute when the axis’ value changes.
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(port)

Parameter	Description
`port`	Which Smart Port that the Optical Sensor is connected to as `PORT` followed by the port number, ranging from 1 to 12.

# 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())