Optical Sensor#

Introduction #

The optical class is used to access data from the Optical Sensor. It uses reflected light to detect objects, identify colors, and measure brightness and hue.

Class Constructor #

optical Optical = optical(index);

Class Destructor #

Destroys the optical object and releases associated resources.

virtual ~optical();

Parameters #

Parameter	Type	Description
`index`	`int32_t`	The Smart Port that the Optical Sensor is connected to, written as `PORTx`, where `x` is the port number (for example, `PORT1`).

Examples #

// Create an optical instance in Port 1
optical Optical1 = optical(PORT1);

Member Functions #

The optical class includes the following member functions:

setLight — Turns the Optical Sensor’s LED on or off.
setLightPower — Sets the Optical Sensor’s light power level.
isNearObject — Returns whether or not the Optical Sensor detects an object within range.
color — Returns the color detected by the Optical Sensor.
brightness — Returns the amount of light reflected from the object.
hue — Returns the hue detected by the Optical Sensor.
objectDetected — Registers a function to be called when the Optical Sensor detects an object.
objectLost — Registers a function to be called when the Optical Sensor loses an object.

Before calling any optical member functions, an optical instance must be created, as shown below:

/* This constructor is required when using VS Code.
Optical Sensor configuration is generated automatically
in VEXcode using the Device Menu. Replace the values
as needed. */

// Create an optical object in Port 1
optical Optical1 = optical(PORT1);

setLight #

Sets Optical Sensor’s LED to on or off. The light can help the Optical Sensor detect objects and colors more clearly.

Available Functions

void  setLight(ledState state);

Parameters

Parameter	Type	Description
`state`	`ledState`	Sets the LED on or off. `ledState::on` turns the LED on at 100% brightness. `ledState::off` turns it off.

Return Values

This function does not return a value.

Examples

// Turn on LED with previous intensity.
Optical.setLight(ledState::on);

setLightPower #

Sets how bright the Optical Sensor’s light is. The light can help the Optical Sensor detect objects and colors more clearly.

A higher percentage makes the light brighter. A lower percentage makes the light dimmer.

If the Optical Sensor’s light is off, setting the light power above 0% will turn the light on.

If the Optical Sensor’s light is on, setting the light power at 0% will turn the light off.

Available Functions

void setLightPower( 
      int32_t      intensity, 
      percentUnits units = percent );

Parameters

Parameter	Type	Description
`intensity`	`int32_t`	The power level to set the light from 0 – 100.
`units`	`percentUnits`	The unit that represents the light intensity: `percent` / `pct` — percent

Return Values

This function does not return a value.

Examples

// Set the light power to 50 percent.
Optical.setLightPower(50, percent);

isNearObject #

Returns whether or not the Optical Sensor detects an object within range.

Available Functions

bool  isNearObject();

Parameters

This function does not accept any parameters.

Return Values

This function returns a Boolean indicating if a nearby object is detected:

true — An object is detected nearby.
false — An object is not detected.

Examples

// If an object is detected by the Optical Sensor, print
// "near object".
if (Optical.isNearObject()){
  Brain.Screen.print("near object");
}

color #

Returns the color detected by the Optical Sensor, based on the detected hue value.

Available Functions

vex::color  color();

Parameters

This function does not accept any parameters.

Return Values

The color detected by the Optical Sensor as an instance of the color class.

Possible colors are:

blue – Hue value between 196° and 229°
blue_green – Hue value between 140° and 195°
blue_violet – Hue value between 230° and 239°
green – Hue value between 84° and 139°
orange – Hue value between 21° and 30°
red – Hue value between 350° and 14°
red_orange – Hue value between 15° and 20°
red_violet – Hue value between 281° and 350°
violet – Hue value between 240° and 280°
yellow – Hue value between 54° and 74°
yellow_green – Hue value between 75° and 83°
yellow_orange – Hue value between 31° and 53°

Examples

// Set a variable, detectColor, to the color detected by the
// Optical Sensor
color detectColor = Optical.color();

// Print the color detected by the Optical Sensor
// to the Brain's screen
Brain.Screen.print(detectColor);

brightness #

Returns how much light is reflected back to the Optical Sensor.

A higher percentage means more light is reflected back to the Optical Sensor. A lower percentage means less light is reflected back.

Available Functions

double  brightness(bool bRaw = false);

Parameters

Parameter	Type	Description
`bRaw`	`bool`	A Boolean value to read raw brightness data instead of percentage. The default is `false`.

Return Values

A double representing the brightness detected by the Optical Sensor in the range 0 - 100%, or a double representing the raw data detected by the sensor.

Examples

// Set a variable, brightness, to the value of the brightness
// detected by the Optical Sensor
double brightness = Optical.brightness();

// Print the brightness detected by the Optical Sensor to the
// Brain's screen
Brain.Screen.print(brightness);

hue #

Returns the hue detected by the Optical Sensor.

Hue is a way to describe color using numbers around a color wheel.

The VEX Color Wheel showing the degrees of colors around a circle, with red at 0 degrees and transitioning through the rainbow as the value increases.

Available Functions

double hue();

Parameters

This function does not accept any parameters.

Return Values

A double representing the value of the hue detected by the Optical Sensor in the range 0 — 359.00.

Examples

// Set a variable, hue, to the value of the hue detected
// by the Optical Sensor.
double hue = Optical.hue();

objectDetected #

Registers a callback function for when an object is detected.

Available Functions

void objectDetected(void (* callback)(void));

Parameters

Parameter	Type	Description
`callback`	`void (*)(void)`	A previously defined function that executes when the Optical Sensor detects a new object.

Return Values

This function does not return a value.

Examples

Define the callback function (outside of int main())

// Called when the Optical Sensor detects an object
void detected() {
  // The Brain will print that the Optical Sensor detected an
  // object to the Brain's screen.
  Brain.Screen.print("object detected");
}

/* vexcodeInit() is only required when using VEXcode.
Remove vexcodeInit() if compiling in VS Code. */
int main() {

  // Run when the Optical Sensor detects an object.
  Optical.objectDetected(detected);
}

objectLost #

Registers a callback function for when an object is lost.

Available Functions

void objectLost(void (* callback)(void));

Parameters

Parameter	Type	Description
`callback`	`void (*)(void)`	A previously defined function that executes when the Optical Sensor loses a detected object.

Return Values

This function does not return a value.

Examples

Define the callback function (outside of int main())

// Called when the Optical Sensor loses an object
void lost() {
  // The Brain will print that the Optical Sensor lost an
  // object to the Brain's screen.
  Brain.Screen.print("object lost");
}

/* vexcodeInit() is only required when using VEXcode.
Remove vexcodeInit() if compiling in VS Code. */
int main() {

  // Run lost when the Optical Sensor loses an object.
  Optical.objectLost(lost);
}