The V5 Distance Sensor is a Time of Flight (ToF) sensor that measures an object’s distance, relative size, and approach speed using a VCSEL Class 1 Laser that reflects off of nearby objects. Distance sensors are commonly used for object detection and robot localization (position tracking).

Creating a Distance Sensor

Using the Peripherals struct passed to our main function, we can a Distance Sensor from any one of the 21 SmartPort fields on it.

{...}
use vexide::prelude::*;
#[vexide::main]async fn main(peripherals: Peripherals) {    let mut sensor = DistanceSensor::new(peripherals.port_1);
Create a Distance Sensor on port 1.
}

Object Measurements

If a distance sensor is within range of an object, it will report four things:

• The object’s distance from the front of the sensor in millimeters.
• The object’s approach velocity in meters per second.
• A guess at the object’s “relative size”. This value is a unitless score from 0-400, where an 18“ x 30“ grey card will return a value of approximately 75 in typical room lighting.
• A “confidence score” of how accurate its measurements are from 0.0 to 1.0.

To read data about an object from a distance sensor, we can use the object method.

{...}
use vexide::prelude::*;
#[vexide::main]async fn main(peripherals: Peripherals) {    let mut sensor = DistanceSensor::new(peripherals.port_1);    if let Ok(Some(object)) = sensor.object() {        println!("Found an object!");        println!("Distance: {}mm", object.distance);        println!("Velocity: {}m/s", object.velocity);        println!("Relative Size: {}", object.relative_size);        println!("Confidence in readings: {}%", object.confidence * 100.0);    } else {        println!("No object found :(");    }}

Error Handling

The object method returns a Result<Option<DistanceObject>>, so there are two cases where we won’t get a DistanceObject back when calling this method:

• Err(DistanceError): An error occurred that caused the sensor to be unavailable. This can happen when the sensor gets unplugged, the wrong type of device is in the port, or the sensor is still initializing itself.
• Ok(None): There is no object in range. Presumably, the distance sensor is too far from whatever it needs to see.

If we want to handle these cases separately, we can instead use a nested match expression or similar:

{...}
use vexide::prelude::*;
#[vexide::main]async fn main(peripherals: Peripherals) {    let sensor = DistanceSensor::new(peripherals.port_1);    match sensor.object() {        Ok(object) => match object {            // We got an object reading back!            Some(data) => println!("Found an object! {data:?}"),                        // Object was not in range.            None => println!("No object found."),        },        // Something went wrong with the sensor.        Err(error) => println!("An error occurred. {error}"),    }}