Optical

Introduction

The Optical Sensor provides methods to return data from different objects. This allows the Brain to detect colors as well as their hue and brightness.

For the examples below, the configured Optical Sensor will be named Optical1 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 – Detect objects with the Optical Sensor.

• objectDetected – Registers a function to call when the Optical Sensor detects an object.

• objectLost – Registers a function to call when the Optical Sensor loses an object.

Mutators – Modify the Optical Sensor lights and detection ranges.

• setLight – Turns the Optical Sensor’s LED on or off.

• setLightPower – Sets the Optical Sensor’s LED to a specific brightness.

• objectDetectThreshold – Sets the distance an object has to be from the Optical Sensor for it to be detected.

Getters – Return object data with the Optical Sensor.

• isNearObject – Returns whether or not an object is close to the sensor.

• color – Return the detected color as a predefined color object.

• brightness – Returns the detected brightness of an object.

• hue – Returns the detected hue value as a float from 0 to 359.99 degrees.

• installed – Returns whether or not the Optical Sensor is connected to the Brain.

Constructors – Manually initialize the Optical Sensor.

• optical – Create an Optical Sensor.

Actions

objectDetected

objectDetected registers a function to be called when the Optical Sensor detects an object.

Usage:
Optical1.objectDetected(callback);

Parameters	Description
callback	A function that is previously defined to execute when the Optical Sensor detects an object.

// Display a message when an object is detected
void onObjectDetected() {
  Brain.Screen.print("Object detected!");
}

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Call onObjectDetected when an object is detected
  Optical1.objectDetected(onObjectDetected);
}

objectLost

objectLost registers a function to be called when the Optical Sensor loses a detected object.

Usage:
Optical1.objectLost(callback);

Parameters	Description
callback	A function that is previously defined to execute when the Optical Sensor loses an object.

// Display a message when an object is lost
void onObjectLost() {
  Brain.Screen.print("Object lost!");
}

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Call onObjectLost when an object is lost
  Optical1.objectLost(onObjectLost);

  // Keep the program running
  while (true) {
    wait(20, msec);
  }
}

Mutators

setLight

setLight turns the Optical Sensor’s LED lights on or off.

Usage:
Optical1.setLight(state);

Parameters	Description
state	The state to set the LED lights to: ledState::off ledState::on

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Blink the Optical Sensor LED on and off
  while (true) {
    Optical1.setLight(ledState::on);
    wait(0.5, seconds);
    Optical1.setLight(ledState::off);
    wait(0.5, seconds);
  }
}

setLightPower

setLightPower sets the specific brightness of the Optical Sensor’s LED lights.

Usage:
Optical1.setLightPower(power, units);

Parameters	Description
power	The brightness that the LED lights will be set to from 0 to 100.
units	The units that represent the LED brightness: percent

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Set the Optical Sensor LED to 25% power
  Optical1.setLightPower(25, percent);
  wait(1, seconds);

  // Set the LED to 75% power
  Optical1.setLightPower(75, percent);
  wait(1, seconds);

  // Turn the LED off
  Optical1.setLightPower(0, percent);
}

objectDetectThreshold

objectDetectThreshold sets the distance away an object must be before the Optical Sensor will detect it.

Usage:
Optical1.objectDetectThreshold(value);

Parameters	Description
value	The new detection threshold as an integer from 0 to 255. A value of 0 means no change to the threshold.

Getters

isNearObject

isNearObject returns a Boolean indicating whether or not the Optical Sensor detects a close object.

• 1 – The Optical Sensor detects a close object.

• 0 – The Optical Sensor does not detect a close object.

Usage:
Optical1.isNearObject()

Parameters	Description
	This method has no parameters.

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Continuously check for nearby objects
  while (true) {
    Brain.Screen.clearScreen();
    Brain.Screen.setCursor(1, 1);

    if (Optical1.isNearObject()) {
      Brain.Screen.print("Object close!");
    } else {
      Brain.Screen.print("No object");
    }

    wait(0.25, seconds);
  }
}

color

color returns the detected color from the Optical Sensor as an instance of a predefined color object, as shown below:

• red

• green

• blue

• white

• yellow

• orange

• purple

• cyan

• red_violet

• violet

• blue_violet

• blue_green

• yellow_green

• yellow_orange

• red_orange

• black

• transparent

Usage:
Optical1.color()

Parameters	Description
	This method has no parameters.

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Continuously check the detected color
  while (true) {

    // Compare the color with "green"
    if (convertColorToString(Optical1.color()) == "green") {
      Brain.Screen.print("Green object!");
    } else {
      Brain.Screen.print("Not green");
    }

    wait(0.5, seconds);
    Brain.Screen.clearScreen();
    Brain.Screen.setCursor(1, 1);
  }
}

Note: The function convertColorToString is automatically created by VEXcode when an Optical Sensor is configured in the Devices window. It is only available inside VEXcode IQ (2nd gen) projects and will not work in other environments.

When using color outside of VEXcode, comparisons should be made directly with a colorType value — any color that begins with colorType:: (for example, colorType::green or colorType::red).

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Continuously check the detected color
  while (true) {

    // Compare the color with the colorType
    if (Optical1.color() == colorType::green) {
      Brain.Screen.print("Green object!");
    } else {
      Brain.Screen.print("Not green");
    }

    wait(0.5, seconds);
    Brain.Screen.clearScreen();
    Brain.Screen.setCursor(1, 1);
  }
}

brightness

brightness returns the brightness value from the Optical Sensor as a double from 0 to 100.

Usage:
Optical1.brightness()

Parameters	Description
	This method has no parameters.

hue

hue returns the hue value detected by the Optical Sensor as a double from 0 to 359.99.

Usage:
Optical1.hue()

Parameters	Description
	This method has no parameters.

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Continuously show hue readings
  while (true) {
    Brain.Screen.clearScreen();
    Brain.Screen.setCursor(1, 1);
    
    Brain.Screen.print("Hue: %f", Optical1.hue());

    wait(0.25, seconds);
  }
}

installed

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

• 1 – The Optical Sensor is connected to the Brain.

• 0 – The Optical Sensor is not connected to the Brain.

Usage:
Optical1.installed()

Parameters	Description
	This method has no parameters.

Constructors

optical

optical creates an object of the optical Class in the specified port.

Usage:
optical Optical1 = 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.

int main() {
  // Initializing Robot Configuration. DO NOT REMOVE!
  vexcodeInit();

  // Create an Optical Sensor in Port 1
  optical CustomOptical = optical(PORT1);
}