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:

• Configuring the GPS Sensor in VEXcode V5

• Using the GPS Sensor with VEX V5

• Best Practices with the GPS Sensor

Initializing the Gps Class

A GPS Sensor is created by using the following constructor:

Gps(port, origin_x, origin_y, units, heading_offset)

This constructor uses five parameters:

Parameter	Description
port	A valid Smart Port that the Distance Sensor is connected to.
origin_x	Optional. The X location of the GPS Sensor with respect to origin (also known as the reference point) of the robot. By default, this is 0. Note: If the Y location is provided, the origin_x parameter must also be provided.
origin_y	Optional. The Y location of the GPS Sensor with respect to origin (also known as the reference point) of the robot. By default, this is 0. Note: If the Y location is provided, the origin_x parameter must also be provided.
units	Optional. The units that X and Y location are specified in. By default this is MM.
heading_offset	Optional. The angle to offset the GPS Sensor’s heading by in degrees. By default this is 180.

# Create a GPS Sensor "gps_1" with the
# Gps class.
gps_1 = Gps(Ports.PORT1, 0.00, 0.00, MM, 180)

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

Class Methods

calibrate()

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.

Returns: None

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.
drivetrain_gps.calibrate()
drivetrain.turn_to_heading(180, DEGREES)

is_calibrating()

The is_calibrating() method checks if the GPS Sensor is currently calibrating or not.

Returns: True if the GPS Sensor is currently calibrating. False if it is not.

set_heading()

The set_heading() method sets the GPS Sensor’s heading to a new value. The new value for heading should be in the range 0 - 359.99 degrees.

Parameters	Description
value	The new value to use for heading.
units	Optional. A valid RotationUnit. The default is DEGREES.

Returns: None

# Set the current GPS Sensor's heading to 180 degrees.
gps_1.set_heading(180)

reset_heading()

The reset_heading() method sets the GPS Sensor’s heading to 0 degrees.

Returns: None

heading()

The heading() method reports 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 gps.heading command 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.

By default the gps.heading command 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: A value for heading in the range that is specified by the 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.set_turn_velocity(20, PERCENT)
drivetrain.turn(RIGHT)
# Stop turning when the GPS reports a heading greater than 90 degrees.
while not gps_20.heading() > 90:
    wait(5, MSEC)
drivetrain.stop()

set_rotation()

The set_rotation() method sets the GPS Sensor’s rotation to a new value.

Parameters	Description
value	The new value to use for rotation.
units	Optional. A valid RotationUnit. The default is DEGREES.

Returns: None

# Set the current rotation of the GPS Sensor to 400 degrees.
gps_1.set_rotation(400)

reset_rotation()

The reset_rotation() method resets the GPS Sensor’s rotation to 0 degrees.

Returns: None

rotation()

The rotation() method reads the current rotation of the GPS Sensor. Rotation is not limited; it can be both positive and negative and shows the absolute angle of the GPS Sensor.

Parameters	Description
units	Optional. A valid RotationUnit. The default is DEGREES.

Returns: A value for heading in the range that is specified by the units.

# Report the current rotation of the GPS Sensor.
rotation = gps_1.rotation()

x_position()

The x_position() 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 x_position 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: A value for the x coordinate in the units specified.

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.set_drive_velocity(20, PERCENT)
drivetrain.drive(FORWARD)
# Stop driving when the GPS reports an X position near the center of the Field.
while not gps_20.x_position(MM) < 0:
    wait(5, MSEC)
drivetrain.stop()

y_position()

The y_position() 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 y_position 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: A value for the y coordinate in the units specified.

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.set_drive_velocity(20, PERCENT)
drivetrain.drive(FORWARD)
# Stop driving when the GPS reports an Y position near the center of the Field.
while not gps_20.y_position(MM) < 0:
    wait(5, MSEC)
drivetrain.stop()

quality()

The quality() method returns 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: A value of quality in the range 0 to 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 gps_20.quality() > 90:
        pass
    else:
        pass
    wait(5, MSEC)

set_origin()

The set_origin() method sets the origin of the GPS Sensor. An alternate way of setting sensor origin if not provided in the Gps class constructor.

Parameters	Description
x	The X location of the GPS Sensor with respect to origin of the robot.
y	The Y location of the GPS Sensor with respect to origin of the robot.
units	Optional. A valid DistanceUnit. The default is MM.

Returns: None

# Set the GPS Sensor's origin +6 inches on the x axis and
# -6 inches on the y axis.
gps_1.set_origin(6, -6, INCHES)

set_location()

The set_location() 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 X coordinate.
y	The Y coordinate.
units	Optional. A valid DistanceUnit. The default is MM.
angle	Optional. The 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.

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.
drivetrain_gps.set_location(-1200, -1200, MM, 90)

Returns: False

orientation()

The orientation() method reads the orientation for one axis of the GPS Sensor.

Parameters	Description
axis	A valid OrientationType.
units	Optional. A valid RotationUnit. The default is DEGREES.

• The OrientationType.ROLL axis reports a value between -180 to 180 degrees, representing the orientation when the GPS Sensor is tilted left or right.

• The OrientationType.PITCH axis reports a value between -90 to 90 degrees, representing the orientation when the GPS Sensor is tilted forward or backwards.

• The OrientationType.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.

gyro_rate()

The gyro_rate() method reads 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.

acceleration()

The acceleration() method reads the acceleration for one axis of the GPS Sensor.

Parameters	Description
axis	A valid AxisType.

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

set_sensor_rotation()

The set_sensor_rotation() method sets the sensor rotation of the GPS Sensor with respect to the robot. This allows heading and rotation methods to return angles relative to the robot rather than the GPS Sensor itself.

Parameters	Description
value	The angle of the GPS Sensor with respect to the robot.
units	Optional. A valid RotationUnit. The default is DEGREES.

Returns: None

changed()

The changed() method registers a function to be called when the value of the GPS Sensor’s heading changes. This is not particularly useful as GPS Sensor’s heading is not stable and will cause many events.

Parameters	Description
callback	A function that will be called when the value of the GPS Sensor’s heading changes.
arg	Optional. A tuple that is used to pass arguments to the callback function.

Returns: An instance of the Event class.

# Define the function to occur when the GPS Sensor's
# heading changes.
def heading_changed():
    brain.screen.print("heading changed")

# Set the function to occur when the GPS Sensor's
# heading changes.
gps_1.changed(heading_changed())

set_turn_type()

The set_turn_type(turntype) method sets the direction that returns positive values for heading.

Parameters	Description
turntype	A valid TurnType.

Returns: None

get_turn_type()

The get_turn_type() method gets the direction that returns positive values for heading.

Returns: The current TurnType, LEFT or RIGHT.

installed()

The installed() method checks for device connection.

Returns: True or False

timestamp()

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

Returns: Timestamp of the last received status packet in milliseconds.