Distance Sensor#

Introduction#

The sonar class is used with the VEX IQ Distance Sensor (1st gen). The distance class is used with the VEX IQ Distance Sensor (2nd gen).

Both Distance Sensors can detect whether an object is in front of the sensor and return how far away that object is. The VEX IQ Distance Sensor (2nd gen) can also return the detected object’s relative velocity and estimate whether the object is small, medium, or large.

Class Constructors#

1 — This constructor creates a VEX IQ Distance Sensor (1st gen).

sonar(
    int32_t index);

2 — This constructor creates a VEX IQ Distance Sensor (2nd gen).

distance(
    int32_t index);

Class Destructor#

Destroys the distance object and releases associated resources.

1 — Destroys a VEX IQ Distance Sensor (1st gen).

~sonar();

2 — Destroys a VEX IQ Distance Sensor (2nd gen).

~distance();

Parameters#

Parameter

Type

Description

index

int32_t

The Smart Port that the Distance Sensor is connected to, written as PORTx, where x is the port number (for example, PORT1).

Examples#

1 — Create a VEX IQ Distance Sensor (1st gen) instance in Port 1.

sonar Distance1 = sonar(PORT1);

2 — Create a VEX IQ Distance Sensor (2nd gen) instance in Port 1.

distance Distance1 = distance(PORT1);

Member Functions#

The sonar class includes the following member functions:

  • foundObject — Returns whether the Distance Sensor currently detects an object.

  • distance — Returns the distance between the Distance Sensor and the nearest detected object.

The distance class includes the following member functions:

  • objectDistance — Returns the distance between the Distance Sensor and the nearest detected object.

  • objectVelocity — Returns how quickly the detected object is moving toward or away from the Distance Sensor.

  • objectSize — Returns the estimated size of the detected object.

  • isObjectDetected — Returns whether the Distance Sensor currently detects an object.

  • changed — Registers a callback function that runs when the detected distance value changes.

  • installed — Returns whether the Distance Sensor is installed and connected.

Before calling any distance or sonar member functions, a distance or sonar instance must be created, as shown below:

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

// Create a VEX IQ Distance Sensor (2nd gen) instance in Port 1
distance Distance1 = distance(PORT1);

foundObject#

Returns whether the Distance Sensor currently detects an object.

Available Functions 
bool foundObject();
Parameters

This function does not take any parameters.

Return Values

Returns a Boolean indicating whether the Distance Sensor detects an object:

  • true — The Distance Sensor detects an object.
  • false — The Distance Sensor does not detect an object.
Notes - This is a VEX IQ Distance Sensor (1st gen) function.

distance#

Returns the distance between the Distance Sensor and the nearest detected object.

Available Functions 
double distance( distanceUnits units );
Parameters

Parameter

Type

Description

units

distanceUnits

The distance unit:

  • mm — millimeters (24 mm to 1000 mm)
  • cm — centimeters (2.4 cm to 100 cm)
  • inches — inches (1 inch to 40 inches)
Return Values

Returns a double representing the distance between the Distance Sensor and the nearest detected object in the specified units.

Notes - This is a VEX IQ Distance Sensor (1st gen) function.

objectDistance#

Returns the distance between the Distance Sensor and the nearest detected object.

Available Functions 
double objectDistance( distanceUnits units );
Parameters

Parameter

Type

Description

units

distanceUnits

The distance unit:

  • mm — millimeters (20 mm to 2000 mm)
  • cm — centimeters (2 cm to 200 cm)
  • inches — inches (0.78 inches to 78 inches)
Return Values

Returns a double representing the distance between the Distance Sensor and the nearest detected object in the specified units.

Notes - This is a VEX IQ Distance Sensor (2nd gen) function.

objectVelocity#

Returns the relative velocity of the detected object.

Velocity shows how quickly the object is moving toward or away from the Distance Sensor. A value near 0 means the object is not moving much relative to the sensor.

Available Functions 
double objectVelocity();
Parameters

This function does not take any parameters.

Return Values

Returns a double representing the relative velocity of the detected object in m/s (meters per second).

Notes - This is a VEX IQ Distance Sensor (2nd gen) function.

objectSize#

Returns the estimated size of the object detected by the Distance Sensor.

The Distance Sensor estimates object size based on how much of the sensor’s view is taken up by the detected object.

Available Functions 
sizeType objectSize();
Parameters

This function does not take any parameters.

Return Values

Returns a sizeType indicating the estimated size of the detected object:

  • none — No object is detected.
  • small — A small object is detected.
  • medium — A medium object is detected.
  • large — A large object is detected.
Notes - This is a VEX IQ Distance Sensor (2nd gen) function.

isObjectDetected#

Returns whether the Distance Sensor currently detects an object.

Available Functions 
bool isObjectDetected();
Parameters

This function does not take any parameters.

Return Values

Returns a Boolean indicating whether the Distance Sensor detects an object:

  • true — The Distance Sensor detects an object.
  • false — The Distance Sensor does not detect an object.
Notes - This is a VEX IQ Distance Sensor (2nd gen) function.

changed#

Registers a callback function that runs when the detected distance value changes.

Available Functions 
void changed( void (* callback)(void) );
Parameters

Parameter

Type

Description

callback

void (*)(void)

A pointer to a function that will be called when the detected distance value changes. The function must take no parameters and return void.
Return Values

This function does not return a value.

Notes - This is a VEX IQ Distance Sensor (1st gen) or (2nd gen) function.

installed#

Returns whether the Distance Sensor is installed and connected.

Available Functions 
bool installed();
Parameters

This function does not take any parameters.

Return Values

Returns a Boolean indicating whether the Distance Sensor is installed and connected:

  • true — The Distance Sensor is installed and connected.
  • false — The Distance Sensor is not installed or not connected.
Notes - This is a VEX IQ Distance Sensor (1st gen) or (2nd gen) function.
On this page