gps#

To make gps commands appear in VEXcode V5, a GPS Sensor must be configured in the Devices window.

For more information, refer to these articles:

Initializing the gps Class #

This gps constructor creates an object of the gps Class in the specified port with the specified rotational offset.

Parameter	Description
`port`	A valid Smart Port that the GPS Sensor is connected to.
`heading_offset`	The GPS Sensor’s rotational offset in degrees, from 0.00 to 359.99.

// Construct a GPS Sensor "GPS1" with the gps class, using
// a 180 degree offset.
gps GPS1 = gps(PORT1, 180);

This gps constructor creates an object of the gps Class in the specified port with a specified origin position and rotational offset.

Parameter	Description
`port`	A valid Smart Port that the GPS Sensor is connected to.
`ox`	The X location of the GPS Sensor with respect to origin (also known as the reference point) of the robot.
`oy`	The Y location of the GPS Sensor with respect to origin (also known as the reference point) of the robot.
`units`	A valid distanceUnit.
`heading_offset`	The GPS Sensor’s rotational offset in degrees, from 0.00 to 359.99.

// Construct a GPS Sensor "GPS1" with the gps class, with
// the origin at (10, 10) and using a 180 degree offset.
gps GPS1 = gps(PORT1, 10.00, 10.00, mm, 180);

This GPS1 object will be used in all subsequent examples throughout this API documentation when referring to gps class methods.

The calibrate() method calibrates the GPS Sensor when the sensor has been configured as a part of a V5 Drivetrain. This will set the GPS’ configured heading (according to its angle offset) as the current heading of the Drivetrain.

The GPS Sensor and Drivetrain must remain still during the calibration process.

In this example, the GPS Sensor will calibrate, then the heading of the sensor is used to turn the robot to the 180 degree heading of the Field.

// Turn to face the lower Field wall using data from the GPS Sensor.
DrivetrainGPS.calibrate()
Drivetrain.turnToHeading(180, degrees)

Returns: None.

isCalibrating()#

The isCalibrating() method returns true while the GPS Sensor is performing a requested recalibration, changing to false once recalibration has completed.

Returns: Returns true if GPS Sensor is still calibrating.

resetHeading()#

The resetHeading() method sets the heading of the GPS Sensor to 0.

Returns: None.

resetRotation()#

The resetRotation() method sets the rotation angle of the GPS Sensor to 0.

Returns: None.

setHeading()#

The setHeading(value, units) method sets the heading of the GPS Sensor to a new value.

Parameters	Description
value	The rotation value to set.
units	Optional. A valid rotationUnit. The default is `degrees`.

Returns: None.

setRotation()#

The setRotation(value, units) method sets the rotation of the GPS Sensor to a new value.

Parameters	Description
value	The rotation value to set.
units	Optional. A valid rotationUnit. The default is `degrees`.

Returns: None.

roll()#

The roll(units) method returns the roll of the GPS Sensor.

Parameters	Description
units	Optional. A valid rotationUnit. The default is `degrees`.

Returns: The roll of the GPS Sensor in the specified units.

pitch()#

The pitch(units) method returns the pitch of the GPS Sensor.

Parameters	Description
units	Optional. A valid rotationUnit. The default is `degrees`.

Returns: The pitch of the GPS Sensor in the specified units.

yaw()#

The yaw(units) method returns the yaw of the GPS Sensor.

Parameters	Description
units	Optional. A valid rotationUnit. The default is `degrees`.

Returns: The yaw of the GPS Sensor in the specified units.

xPosition()#

The xPosition(units) method returns the current x coordinate of a GPS Sensor on the Field.

Parameters	Description
units	Optional. A valid distanceUnit. The default is `mm`.

By default the xPosition() method returns the X coordinate location of a GPS Sensor.

If an offset is added when configuring the GPS Sensor, then the reported X position will be of the reference point on the robot.

Returns: The x coordinate of the GPS Sensor in the specified units.

In this example, the robot (starting on the righthand side of the Field), drives towards the center until the X position is reported as less than 0mm. Then the robot stops driving.

// Drive slowly towards the center of the Field.
Drivetrain.setDriveVelocity(20.0, percent);
Drivetrain.drive(forward);
// Stop driving when the GPS reports an x position near the center of the Field.
waitUntil((GPS20.xPosition(mm) < 0.0));
Drivetrain.stop();

yPosition()#

The yPosition(units) method returns the current y coordinate of a GPS Sensor on the Field.

Parameters	Description
units	Optional. A valid distanceUnit. The default is `mm`.

By default the yPosition() method returns the Y coordinate location of a GPS Sensor.

If an offset is added when configuring the GPS Sensor, then the reported Y position will be of the reference point on the robot.

Returns: The y coordinate of the GPS Sensor in the specified units.

// Get the current y coordinate for the GPS Sensor.
yPos = GPS1.yPosition();

In this example, the robot (starting at the top of the Field), drives towards the center until the Y position is reported as less than 0mm. Then the robot stops driving.

// Drive slowly towards the center of the Field.
Drivetrain.setDriveVelocity(20.0, percent);
Drivetrain.drive(forward);
// Stop driving when the GPS reports an y position near the center of the Field.
waitUntil((GPS20.yPosition(mm) < 0.0));
Drivetrain.stop();

orientation()#

The orientation(axis, units) method returns the orientation for one axis of the gps.

Parameters	Description
axis	A valid axisType.
units	Optional. A valid rotationUnit. The default is `degrees`.

The x, or roll axis reports a value between -180 to +180 degrees, representing the orientation when the GPS Sensor is tilted left or right.
The y, or pitch axis reports a value between -90 to +90 degrees, representing the orientation when the GPS Sensor is tilted forward or backwards.
The z, yaw axis reports a value between -180 to +180 degrees, representing the orientation when the GPS Sensor is rotated about the vertical axis.

Returns: A value for the axis orientation in the units specified.

// Get the orientation of the x axis on the GPS Sensor.
pitch = GPS1.orientation(xaxis);

heading()#

The heading(units) method returns the heading of a GPS Sensor on a Field based on the sensor’s readings from the GPS Field Code.

Parameters	Description
units	Optional. A valid rotationUnit. The default is `degrees`.

The heading method reports a range from 0.00 to 359.99 degrees.

The heading corresponds to the Field heading, which is a range of 0º to 359.9º in the clockwise direction. The 0º is in the 12 o’clock position.

set_gps_location_field

By default the heading method reports the heading of a GPS Sensor.

If an Angle Offset is added when configuring the GPS Sensor, then the reported heading will be of the reference point on the robot.

Returns: The current heading of the GPS Sensor in the specified units.

In this example, the robot (starting facing the 12 o-clock position of the Field), turns towards the right wall of the Field until the heading is reported as greater than 90 degrees. Then the robot stops driving.

// Turn slowly to face the right wall.
Drivetrain.setTurnVelocity(20.0, percent);
Drivetrain.turn(right);
// Stop turningwhen the GPS reports a heading greater than 90 degrees.
waitUntil((GPS20.heading() > 90.0));
Drivetrain.stop();

rotation()#

The rotation(units) method returns the current rotation of the GPS Sensor.

Parameters	Description
units	Optional. A valid rotationUnit. The default is `degrees`.

Returns: The current rotation of the GPS Sensor in the specified units.

// Get the current rotation for the GPS Sensor.
rotation = GPS1.rotation();

gyroRate()#

The gyroRate(axis, units) method returns the gyro rate for one axis of the GPS Sensor.

Parameters	Description
axis	A valid AxisType.
units	Optional. A valid velocityUnit. The default is `dps`.

Returns: A value for the gyro rate of the axis in the units specified.

// Get the gyro rate for the z axis of the GPS Sensor.
gyroRate = GPS1.gyroRate(zaxis);

acceleration()#

The acceleration(axis) method returns the acceleration for an axis of the GPS Sensor.

Parameters	Description
axis	A valid axisType.

Returns: A value for the acceleration of the axis in units of gravity.

// Get the acceleration for the Zz axis of the GPS Sensor.
accel = GPS1.acceleration(zaxis);

quality()#

The quality() method reports a numerical value from 0-100 representing the current signal quality of a GPS Sensor.

Reported Value	Description
100	All reported positional and heading data from a GPS Sensor is valid.
~90	Any positional data is no longer being calculated by capturing information from the VEX Field Code, but rather through alternative means.
0 - 80	Only GPS Sensor heading values are valid, but as more time goes by where a GPS Sensor is not scanning enough of the VEX Field Code to accurately determine position and heading information, the reported signal quality will continue to drop until 0, where any GPS Sensor data is effectively frozen and no longer valid.

Returns: The quality of the GPS Sensor in the range 0 - 100.

In this code snippet, the signal quality will constantly be checked due to the while (true) loop. The TRUE branch will only run if the signal quality from the GPS Sensor is reporting values above 90, to ensure the GPS Sensor data being used in the project is valid.

while (true) {
    if (GPS20.quality() > 90.0) {} else {}
    wait(5, msec);
  }
  return 0;

setOrigin()#

The setOrigin(x, y, units) method sets the origin of the GPS Sensor.

Parameters	Description
x	The X location of the GPS with respect to the origin of the robot.
y	The Y location of the GPS with respect to the origin of the robot.
units	Optional. A valid distanceUnit. The default is `mm`.

Returns: None.

// Set the origin of the GPS Sensor.
GPS1.setOrigin(6, -6, inches);

setLocation()#

The setLocation(x, y, units, angle, units_r) method sets the X, Y coordinates, and heading of a GPS Sensor to a known value at the beginning of a project. This can be done to help reduce GPS data inaccuracies due a the sensor’s proximity to field walls when a project is started.

Parameters	Description
x	The initial x coordinate.
y	The initial y coordinate.
units	Optional. A valid distanceUnit. The default is `mm`.
angle	Optional. The initial heading of the robot.
units_r	Optional. A valid rotationUnit. The default is `degrees`.

When a GPS Sensor is too close to the field walls to read the Field Code (for example, when a robot is in a game’s starting position on a field), unexpected behaviors can often occur if the code relies on the GPS’s coordinate and heading data.

set_gps_location_field

The x and y parameters are the X and Y coordinates of the reference point on your robot on the field in this known location. The reference point on your robot is the same location that was used to calculate the offsets when configuring the GPS Sensor.

The heading parameter is the heading of the reference point on your robot. Using the example image above, the GPS Sensor is mounted facing behind the robot, while the reference point is at the end of the arm on the robot. Because the reference point is facing the right wall (heading of 90), the heading value that should be input is 90.

Returns: None.

The example shown here sets the position of the reference point on the robot, the arm, to match the location of the robot on the Field.

// Wait so the GPS has time to initialize.
  wait(0.5, seconds)
  // Set the starting position to the bottom left corner of the Field facing the right wall.
  DrivetrainGPS.setLocation(-1200, -1200, mm, 90)

changed()#

The changed(callback) method registers a callback function for when the value for the GPS heading changes.

Parameters	Description
callback	The callback function to be called when the GPS heading changes.

Returns: An instance of the Event class.

// Define the headingChanged function with a void return
// type, showing it doesn't return a value.
void headingChanged() {
  // The Brain will print that the GPS Sensor's heading
  // changed on the Brain's screen.
  Brain.Screen.print("GPS heading changed");
}

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

  // Turn the robot right.
  Drivetrain.turn(right);

  // Run headingChanged when the value of the GPS Sensor's
  // heading changes.
  GPS1.changed(headingChanged);
}

timestamp()#

The timestamp() method requests the timestamp of the last received status packet from the GPS Sensor.

Returns: Timestamp of the last status packet as an unsigned 32-bit integer in milliseconds.

installed()#

The installed() method checks if the GPS Sensor is installed.

Returns: true if the GPS Sensor is installed. false if it is not.

gps#

Initializing the gps Class #

Class Methods #

calibrate()#

isCalibrating()#

resetHeading()#

resetRotation()#

setHeading()#

setRotation()#

roll()#

pitch()#

yaw()#

xPosition()#

yPosition()#

orientation()#

heading()#

rotation()#

gyroRate()#

acceleration()#

quality()#

setOrigin()#

setLocation()#

changed()#

timestamp()#

installed()#