Distance Sensor

Introduction

The distance and sonar classes are used to control and access data from the IQ (2nd gen) 1st and 2nd Gen Distance Sensors. These sensors measure the distance between the sensor and nearby objects, allowing your robot to detect obstacles and determine proximity.

Class Constructors

1 — This constructor constructs a 1st Gen Distance Sensor.

sonar(
    int32_t index);

2 — This constructor constructs a 2nd Gen Distance Sensor.

distance(
    int32_t index);

Class Destructor

Destroys the distance object and releases associated resources.

1 — Destroys a 1st Gen Distance Sensor.

~sonar();

2 — Destroys a 2nd gen Distance Sensor.

~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 sonar instance in Port 1.

sonar Distance1 = sonar(PORT1);

2 — Create a distance instance in Port 1.

distance Distance1 = distance(PORT1);

Member Functions

The sonar class includes the following member functions:

• foundObject — Returns whether the sensor detects an object.

• distance — Returns the distance of the detected object.

The distance class includes the following member functions:

• objectDistance — Returns the distance currently detected by the sensor.

• objectVelocity — Returns the velocity of the detected object.

• objectSize — Returns an estimate of the detected object’s size.

• isObjectDetected — Returns whether an object is currently detected.

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

• installed — Returns whether the sensor is installed.

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 distance instance in Port 1
distance Distance1 = distance(PORT1);

foundObject

Returns whether an object is currently detected by the Distance Sensor.

Available Functions

bool foundObject();

Parameters

This function does not take any parameters.

Return Values

Returns a Boolean indicating whether an object is detected:

• true — An object is detected.
• false — No object is detected.

Notes - This is a 1st Gen Distance Sensor function.

distance

Returns the distance currently detected by the Distance Sensor.

Available Functions

double distance( distanceUnits units );

Parameters

Parameter	Type	Description
units	distanceUnits	The unit of measurement for the returned distance value: mm — millimeters cm — centimeters inches — inches

Return Values

Returns a double representing the distance to the detected object in the specified units.

Notes - This is a 1st Gen Distance Sensor function.

objectDistance

Returns the distance currently detected by the Distance Sensor.

Available Functions

double objectDistance( distanceUnits units );

Parameters

Parameter	Type	Description
units	distanceUnits	The unit of measurement for the returned distance value: mm — millimeters cm — centimeters inches — inches

Return Values

Returns a double representing the distance to the detected object in the specified units.

Notes - This is a 2nd Gen Distance Sensor function.

objectVelocity

Returns an estimate of the detected object’s velocity.

Available Functions

double objectVelocity();

Parameters

This function does not take any parameters.

Return Values

Returns a double representing the velocity of the detected object in meters per second.

Notes - This is a 2nd Gen Distance Sensor function.

objectSize

Returns an estimate of the detected object’s size.

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 — The detected object is small.
• medium — The detected object is medium in size.
• large — The detected object is large.

Notes - This is a 2nd Gen Distance Sensor function.

isObjectDetected

Returns whether an object is currently detected by the Distance Sensor.

Available Functions

bool isObjectDetected();

Parameters

This function does not take any parameters.

Return Values

Returns a Boolean indicating whether an object is detected:

• true — An object is detected.
• false — No object is detected.

Notes - This is a 2nd Gen Distance Sensor 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 1st and 2nd Gen Distance Sensor function.

installed

Returns whether the Distance Sensor is connected.

Available Functions

bool installed();

Parameters

This function does not take any parameters.

Return Values

Returns a Boolean indicating whether the Distance Sensor is connected:

• true — The sensor is connected and responding.
• false — The sensor is not connected or not detected.

Notes - This is a 1st and 2nd Gen Distance Sensor function.