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`

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

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

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

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

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`

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

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

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

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`

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.