Inertial Sensor

Introduction

The inertial class is used to control and access data from the V5 Inertial Sensor. This sensor provides heading, rotation, and acceleration information to help your robot track orientation and movement.

Class Constructors

inertial(
  int32_t  index,
  turnType dir = turnType::right );

Class Destructor

Destroys the inertial object and releases associated resources.

~inertial();

Parameters

Parameter	Type	Description
index	int32_t	The Smart Port that the Inertial Sensor is connected to, written as PORTx, where x is the port number (for example, PORT1).
dir	turnType	The direction that will return a positive value when turning: right (default) — clockwise left

Examples

// Create the inertial instance
inertial myInertial = inertial(
    PORT1,      // Smart Port 1
    right);     // dir

Member Actions

The inertial class includes the following member functions:

• heading — Returns the current heading value.

• rotation — Returns the current rotation value.

• setHeading — Sets the sensor’s heading to a specified value.

• setRotation — Sets the sensor’s rotation to a specified value.

• calibrate — Calibrates the sensor for accurate heading tracking.

• resetHeading — Resets the heading to 0.

• resetRotation — Resets the rotation to 0.

• isCalibrating — Returns whether the sensor is currently calibrating.

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

• installed — Returns whether the sensor is installed.

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

• collision — Registers a callback function that runs when a collision is detected.

• setTurnType — Sets which turn direction returns positive heading values.

• getTurnType — Returns which turn direction produces positive heading values.

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

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

// Create the inertial instance
inertial myInertial = inertial(
    PORT1);      // Smart Port 1

heading

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

Available Functions

double heading( rotationUnits units = degrees );

Parameters

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

Return Values

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

Notes

• The heading value is wrapped between 0 and 360 degrees. Use rotation to access the continuous (unbounded) rotation value.

Examples

// Turn, then show the current heading
Drivetrain.turnFor(right, 450, degrees);
Brain.Screen.print("%f", myInertial.heading(degrees));

rotation

Returns the absolute rotation (yaw angle without limits) of the Inertial Sensor.

Available Functions

double rotation( rotationUnits units = degrees );

Parameters

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

Return Values

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

Notes

• The rotation value is continuous and does not wrap between 0 and 360 degrees. Use heading to access the wrapped heading value.

Examples

// Turn, then show the current rotation
Drivetrain.turnFor(right, 450, degrees);
Brain.Screen.print("%f", myInertial.rotation(degrees));

setHeading

Sets the heading of the Inertial Sensor to a specified value.

Available Functions

void setHeading( double value, rotationUnits units );

Parameters

Parameter	Type	Description
value	double	The new heading value to assign to the sensor.
units	rotationUnits	The unit of measurement for the heading value: deg / degrees — degrees turns / rev — revolutions

Return Values

This function does not return a value.

Examples

// Turn the robot around
myInertial.setHeading(180, degrees);
Drivetrain.turnToHeading(0, degrees);

setRotation

Sets the absolute rotation of the Inertial Sensor to a specified value.

Available Functions

void setRotation( double value, rotationUnits units );

Parameters

Parameter	Type	Description
value	double	The new absolute rotation value to assign to the sensor.
units	rotationUnits	The unit of measurement for the rotation value: deg / degrees — degrees turns / rev — revolutions

Return Values

This function does not return a value.

Examples

// Turn the robot around
myInertial.setRotation(-180, degrees);
Drivetrain.turnToRotation(0, degrees);

calibrate

Starts calibration of the Inertial Sensor.

Available Functions

void calibrate( );

Parameters

This function does not accept any parameters.

Return Values

This function does not return a value.

Notes

• The sensor should remain stationary while calibration is in progress.

• Use isCalibrating to determine when calibration has completed.

resetHeading

Sets the heading of the Inertial Sensor to 0.

Available Functions

void resetHeading();

Parameters

This function does not take any parameters.

Return Values

This function does not return a value.

resetRotation

Sets the rotation of the Inertial Sensor to 0.

Available Functions

void resetRotation();

Parameters

This function does not take any parameters.

Return Values

This function does not return a value.

isCalibrating

Returns whether the Inertial Sensor is currently calibrating.

Available Functions

bool isCalibrating();

Parameters

This function does not take any parameters.

Return Values

Returns a Boolean indicating whether the Inertial Sensor is calibrating:

• true — The sensor is currently calibrating.
• false — The sensor is not currently calibrating.

changed

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

Return Values

This function does not return a value.

Examples

// Called when the inertial sensor's heading value changes
void onHeadingChanged() {
  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
  Brain.Screen.print("Heading: %.2f", myInertial.heading());
}

myInertial.changed(onHeadingChanged);

installed

Returns whether the Inertial Sensor is connected.

Available Functions

bool installed();

Parameters

This function does not take any parameters.

Return Values

Returns a Boolean indicating whether the Inertial Sensor is connected:

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

acceleration

Returns the linear acceleration measured by the Inertial 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

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 Inertial 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

Return Values

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

Examples

// Display the rate of change of rotation while turning in dps
Drivetrain.turn(right);
wait(1, seconds);

Brain.Screen.print(myInertial.gyroRate(zaxis, dps));

Drivetrain.stop();

orientation

Returns the current orientation of the Inertial Sensor for the specified axis.

Available Functions

double orientation( 
  axisType      axis, 
  rotationUnits units );

Parameters

Parameter	Type	Description
axis	axisType	The axis for which orientation will be returned: xaxis yaxis zaxis
units	rotationUnits	The unit of measurement for the returned orientation value: deg / degrees — degrees turns / rev — revolutions

Return Values

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

Examples

while (true) {
  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1,1);
  // Show the Inertial Sensor's orientation value
  // for roll in degrees
  double orient = myInertial.orientation(xaxis, deg);
  Brain.Screen.print("%f", orient);
  wait(0.1, seconds);
}

collision

Registers a callback function that runs when the Inertial Sensor detects a collision.

Available Functions

void collision( void (* callback)(axisType, double, double, double) );

Parameters

Parameter	Type	Description
callback	void (*)(axisType, double, double, double)	A pointer to a function that will be called when a collision is detected. The callback function must accept the following parameters: axisType — The axis on which the collision was detected. Acceleration values at the time of impact, in order: double — Acceleration along the x-axis (in G). double — Acceleration along the y-axis (in G). double — Acceleration along the z-axis (in G). The function must return void.

Return Values

This function does not return a value.

Examples

// Called when the inertial sensor's detects a collision
void onCollision(axisType axis, double x, double y, double z) {
  Brain.Screen.print("Collision detected!");
}

// Firmly move the robot by hand briefly to simulate
// a collision and call the onCollision function
myInertial.collision(onCollision);

setTurnType

Sets which turn direction returns positive heading values.

Available Functions

void setTurnType( turnType dir );

Parameters

Parameter	Type	Description
dir	turnType	The direction that will return positive heading values: right left

Return Values

This function does not return a value.

Notes

• This setting affects how heading and rotation report positive and negative values.

• Calling this function overrides the dir value specified when constructing the inertial object.

getTurnType

Returns which turn direction produces positive heading values.

Available Functions

turnType getTurnType();

Parameters

This function does not take any parameters.

Return Values

Returns a turnType indicating which direction produces positive values:

• right — Clockwise rotation returns positive values.
• left — Counterclockwise rotation returns positive values.

Notes

• This value is set during construction of the inertial object or by calling setTurnType.