GPS Sensor#

The gps class is used to control and access data from the V5 GPS (Game Positioning System™) Sensor. This sensor provides accurate position and orientation tracking for a robot on the VEX Field. It uses the GPS Field Code around the Field’s perimeter to calculate the robot’s X and Y coordinates and heading in real time.

The GPS Sensor returns the robot’s position using a reference point automatically calculated from the offsets entered when configuring the GPS Sensor in the Devices window.

For more information about the GPS Sensor, read Using the GPS Sensor with VEX V5 in the VEX Library.

The reference point acts as the GPS Sensor’s own (0, 0) position where all coordinates, headings, and movements returned by GPS methods are relative to this configured point.

The VEX V5 GPS Sensor.

Class Constructors #

1 — Creates a gps object on the specified Smart Port using the default origin (0, 0).
gps(
  int32_t  index,
  double   heading_offset = 0,
  turnType dir = right );

2 — Creates a gps object on the specified Smart Port and defines a custom origin position.
gps(
  int32_t       index,
  double        ox,
  double        oy,
  distanceUnits units = mm,
  double        heading_offset = 0,
  turnType      dir = right );

Class Destructor #

Destroys the gps object and releases associated resources.

~gps();

Parameters #

Parameter	Type	Description
`index`	`int32_t`	The Smart Port that the GPS Sensor is connected to, written as `PORTx`, where `x` is the port number (for example, `PORT1`).
`ox`	`double`	The X-coordinate of the origin position.
`oy`	`double`	The Y-coordinate of the origin position.
`units`	`distanceUnits`	The unit of measurement used for `ox` and `oy`: `mm` (default) — millimeters `distanceUnits::in` / `inches` — inches `distanceUnits::cm` — centimeters
`heading_offset`	`double`	The GPS Sensor’s rotational offset in degrees, from 0.00 to 359.99. Default is 0.
`dir`	`turnType`	The direction that will return positive heading values: `right` (default) `left`

Examples #

// Create the gps instance
gps GPS1 = gps(
    PORT1,      // Smart Port 1
    180);       // heading_offset

// Create the gps instance
gps GPS1 = gps(
    PORT1,   // Smart Port 1
    50.00,   // ox
    100.00,  // oy
    mm,      // units
    180 );   // heading_offset

Member Functions #

The gps class includes the following member functions:

calibrate — Calibrates the GPS Sensor.
setOrigin — Sets the origin position for the GPS coordinate system.
setLocation — Sets the current location and heading of the GPS Sensor.
xPosition — Returns the current X position.
yPosition — Returns the current Y position.
heading — Returns the current heading.
acceleration — Returns linear acceleration along the specified axis.
gyroRate — Returns the angular velocity for the specified axis.
orientation — Returns the orientation for the specified axis.
quality — Returns the current GPS signal quality.
changed — Registers a callback function that runs when GPS data changes.

Before calling any gps member functions, a gps instance must be created, as shown below:

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

// Create the gps instance in Smart Port 1
gps GPS1 = gps(PORT1);

Class Methods #

calibrate #

Calibrates the GPS Sensor. This will set the GPS’ configured heading (according to its angle offset) as the current heading of the Drivetrain.

The GPS Sensor must remain still during the calibration process.

Available Functions

void calibrate();

Parameters

This function does not take any parameters.

Return Values

This function does not return a value.

Examples

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

setOrigin #

Sets the origin of the GPS coordinate system.

Available Functions

1 — Sets the origin to the specified X and Y position.
void setOrigin( 
  double        x, 
  double        y, 
  distanceUnits units = mm );

2 — Sets the origin to the sensor’s current position.
void setOrigin();

Parameters

Parameter	Type	Description
`x`	`double`	The X-coordinate of the new origin position.
`y`	`double`	The Y-coordinate of the new origin position.
`units`	`distanceUnits`	The unit of measurement used for `x` and `y`: `mm` (default) — millimeters `distanceUnits::cm` — centimeters `distanceUnits::in` — inches

Parameter

Type

Description

x

double

The X-coordinate of the new origin position.

y

double

The Y-coordinate of the new origin position.

units

distanceUnits

The unit of measurement used for x and y:

mm (default) — millimeters
distanceUnits::cm — centimeters
distanceUnits::in — inches

Return Values

This function does not return a value.

Notes

Changing the origin affects values returned by xPosition and yPosition.

setLocation #

Sets the current GPS position and heading.

Available Functions

1 — Sets the current location using specified distance and rotation units.
void setLocation(
  double        x,
  double        y,
  distanceUnits units = mm,
  double        angle = 0,
  rotationUnits units_r = degrees );

2 — Sets the current location using millimeters and degrees.
void setLocation( double x, double y, double angle );

Parameters

Parameter	Type	Description
`x`	`double`	The X-coordinate of the current location.
`y`	`double`	The Y-coordinate of the current location.
`units`	`distanceUnits`	The unit of measurement used for `x` and `y`: `mm` (default) — millimeters `distanceUnits::in` / `inches` — inches `distanceUnits::cm` — centimeters
`angle`	`double`	The heading value for the current location.
`units_r`	`rotationUnits`	The unit of measurement used for `angle`: `deg` (default) — degrees `rev` — revolutions

Return Values

This function does not return a value.

Notes

Calling this function updates the internal position and heading values reported by xPosition, yPosition, and heading.

xPosition #

Returns the current X position of the GPS Sensor.

Available Functions

double xPosition( distanceUnits units = distanceUnits::mm );

Parameters

Parameter	Type	Description
`units`	`distanceUnits`	The unit of measurement for the returned X position: `mm` (default) — millimeters `distanceUnits::cm` — centimeters `distanceUnits::in` — inches

Parameter

Type

Description

units

distanceUnits

The unit of measurement for the returned X position:

mm (default) — millimeters
distanceUnits::cm — centimeters
distanceUnits::in — inches

Return Values

Returns a double representing the x positional offset from the origin in the specified units.

Notes

The X position is measured relative to the current origin.
The origin may be changed using setOrigin.

Examples

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

yPosition #

Returns the current Y position of the GPS Sensor.

Available Functions

double yPosition( distanceUnits units = distanceUnits::mm );

Parameters

Parameter	Type	Description
`units`	`distanceUnits`	The unit of measurement for the returned Y position: `mm` (default) — millimeters `distanceUnits::cm` — centimeters `distanceUnits::in` — inches

Parameter

Type

Description

units

distanceUnits

The unit of measurement for the returned Y position:

mm (default) — millimeters
distanceUnits::cm — centimeters
distanceUnits::in — inches

Return Values

Returns a double representing the Y positional offset from the origin in the specified units.

Notes

The Y position is measured relative to the current origin.
The origin may be changed using setOrigin().

Examples

// 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((GPS1.yPosition(mm) < 0.0));
Drivetrain.stop();

heading #

Returns the current heading (yaw angle) of the GPS Sensor.

Available Functions

double heading( rotationUnits units = rotationUnits::deg );

Parameters

Parameter	Type	Description
`units`	`rotationUnits`	The unit of measurement for the returned heading value: `deg` (default) — degrees `rev` — revolutions

Parameter

Type

Description

units

rotationUnits

The unit of measurement for the returned heading value:

deg (default) — degrees
rev — revolutions

Return Values

Returns a double representing the current heading in the specified units.

Notes

The heading value is wrapped between 0 and 360 degrees.
The positive rotation direction is determined by the dir parameter specified during construction.

Examples

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

acceleration #

Returns the linear acceleration measured by the GPS Sensor along the specified axis.

Available Functions

double acceleration( 
  axisType axis );

Parameters

Parameter	Type	Description
`axis`	`axisType`	The axis for which acceleration will be returned: `xaxis` `yaxis` `zaxis`

Parameter

Type

Description

axis

axisType

The axis for which acceleration will be returned:

xaxis
yaxis
zaxis

Return Values

Returns a double representing the acceleration along the specified axis in G (gravitational units).

Notes

Acceleration values are reported in units of G, where 1 G is equal to the acceleration due to gravity at Earth’s surface.

gyroRate #

Returns the angular velocity measured by the GPS Sensor along the specified axis.

Available Functions

double gyroRate( 
  axisType      axis, 
  velocityUnits units );

Parameters

Parameter	Type	Description
`axis`	`axisType`	The axis for which angular velocity will be returned: `xaxis` `yaxis` `zaxis`
`units`	`velocityUnits`	The unit of measurement for the returned angular velocity: `dps` — degrees per second `rpm` — revolutions per minute

Parameter

Type

Description

axis

axisType

The axis for which angular velocity will be returned:

xaxis
yaxis
zaxis

units

velocityUnits

The unit of measurement for the returned angular velocity:

dps — degrees per second
rpm — revolutions per minute

Return Values

Returns a double representing the angular velocity along the specified axis in the selected units.

orientation #

Returns the orientation angle of the GPS Sensor for the specified axis.

Available Functions

double orientation( 
  orientationType axis, 
  rotationUnits   units );

Parameters

Parameter	Type	Description
`axis`	`orientationType`	The orientation axis to retrieve: `roll` `pitch` `yaw`
`units`	`rotationUnits`	The unit of measurement for the returned orientation value: `deg` — degrees `rev` — revolutions

Parameter

Type

Description

axis

orientationType

The orientation axis to retrieve:

roll
pitch
yaw

units

rotationUnits

The unit of measurement for the returned orientation value:

deg — degrees
rev — revolutions

Return Values

Returns a double representing the orientation of the specified axis in the selected units.

quality #

Returns the perceived GPS signal quality.

Available Functions

int32_t quality();

Parameters

This function does not take any parameters.

Return Values

Returns an int32_t representing the GPS signal quality as a percentage:

Possible Values	Description
`100`	All reported positional and heading data from the GPS Sensor is valid.
`~90`	Positional data is no longer being calculated directly from the GPS Field Code and is instead being estimated through alternative means.
`0 – 80`	Only heading values are valid. As time passes without sufficient scanning of the GPS Field Code, signal quality continues to decrease until `0`, at which point GPS data is effectively frozen and no longer valid.

changed #

Registers a callback function that runs when the GPS heading 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 GPS heading value changes. The function must take no parameters and return `void`.

Return Values

This function does not return a value.