Motors C++ API

Note

Additional example code for this module can be found in its Tutorial.

pros::Motor

Constructor(s)

This function uses the following values of errno when an error state is reached:

  • ENXIO - The given value is not within the range of V5 ports (1-21).
  • ENODEV - The port cannot be configured as a motor
pros::Motor::Motor ( const std::uint8_t port,
                     const pros::motor_gearset_e_t gearset,
                     const bool reverse,
                     const pros::motor_encoder_units_e_t encoder_units )
1
2
3
4
5
6
7
8
void opcontrol() {
  pros::Motor motor (1, E_MOTOR_GEARSET_18, false, E_MOTOR_ENCODER_DEGREES);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor.move(master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y));
    pros::delay(2);
  }
}
Parameters  
port The V5 port number from 1-21
gearset The new motor gearset
reverse 1 reverses the motor, 0 is default
encoder_units The new motor encoder units

pros::Motor::Motor ( const std::uint8_t port,
                     const pros::motor_gearset_e_t gearset,
                     const bool reverse )
1
2
3
4
5
6
7
8
void opcontrol() {
  pros::Motor motor (1, E_MOTOR_GEARSET_18, falseS);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor.move(master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y));
    pros::delay(2);
  }
}
Parameters  
port The V5 port number from 1-21
gearset The new motor gearset
reverse 1 reverses the motor, 0 is default

pros::Motor::Motor ( const std::uint8_t port,
                     const pros::motor_gearset_e_t gearset )
1
2
3
4
5
6
7
8
void opcontrol() {
  pros::Motor motor (1, E_MOTOR_GEARSET_18);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor.move(master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y));
    pros::delay(2);
  }
}
Parameters  
port The V5 port number from 1-21
gearset The new motor gearset

pros::Motor::Motor ( const std::uint8_t port,
                     const bool reverse )
1
2
3
4
5
6
7
8
void opcontrol() {
  pros::Motor motor (1, false);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor.move(master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y));
    pros::delay(2);
  }
}
Parameters  
port The V5 port number from 1-21
reverse 1 reverses the motor, 0 is default

pros::Motor::Motor ( const std::uint8_t port )
1
2
3
4
5
6
7
8
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor.move(master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y));
    pros::delay(2);
  }
}
Parameters  
port The V5 port number from 1-21

Operator Overloads

Sets the voltage for the motor from -127 to 127.

This is designed to map easily to the input from the controller’s analog stick for simple opcontrol use. The actual behavior of the motor is analogous to use of move_voltage, or motorSet from the PROS 2 API.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor
virtual std::int32_t operator= ( const std::int8_t voltage ) const
1
2
3
4
5
6
7
8
void opcontrol() {
  pros::Motor motor (1, E_MOTOR_GEARSET_18);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    pros::delay(2);
  }
}
Parameters  
voltage The new motor voltage from -127 to 127

Literal(s)

pros::Motor operator"" _m(const unsigned long long iport)
pros::Motor operator"" _rm(const unsigned long long iport)
1
2
3
4
5
void opcontrol() {
  using namespace pros::literals;
  auto motor1 = 1_m; // Motor in port 1
  auto motor1_reversed = 1_rm; // Reversed motor in port 1
}

Movement Functions

move

Sets the voltage for the motor from -127 to 127.

This is designed to map easily to the input from the controller’s analog stick for simple opcontrol use. The actual behavior of the motor is analogous to use of move_voltage, or motorSet from the PROS 2 API.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_move.

std::int32_t motor_move ( const std::int8_t voltage )
1
2
3
4
5
6
7
8
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor.move(master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y));
    pros::delay(2);
  }
}
Parameters  
voltage The new motor voltage from -127 to 127

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


move_absolute

Sets the target absolute position for the motor to move to.

This movement is relative to the position of the motor when initialized or the position when it was most recently reset with tare_position.

Note

This function simply sets the target for the motor, it does not block program execution until the movement finishes. The example code shows how to block until a movement is finished.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_move_absolute.

std::int32_t pros::Motor::move_absolute ( double position,
                                          std::int32_t velocity )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
void autonomous() {
  pros::Motor motor (1);
  motor.move_absolute(100, 100); // Moves 100 units forward
  while (!((motor.get_position() < 105) && (motor.get_position() > 95))) {
    // Continue running this loop as long as the motor is not within +-5 units of its goal
    pros::delay(2);
  }
  motor.move_absolute(100, 100); // This does not cause a movement
  while (!((motor.get_position() < 105) && (motor.get_position() > 95))) {
    pros::delay(2);
  }

  motor.tare_position();
  motor.move_absolute(100, 100); // Moves 100 units forward
  while (!((motor.get_position() < 105) && (motor.get_position() > 95))) {
    pros::delay(2);
  }
}
Parameters  
position The absolute position to move to in the motor’s encoder units
velocity The maximum allowable velocity for the movement

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


move_relative

Sets the relative target position for the motor to move to.

This movement is relative to the current position of the motor as given in get_position.

Note

This function simply sets the target for the motor, it does not block program execution until the movement finishes. The example code shows how to block until a movement is finished.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_move_relative.

std::int32_t pros::Motor::move_relative ( double position,
                                          std::int32_t velocity )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
void autonomous() {
  pros::Motor motor (1);
  motor.move_relative(100, 100); // Moves 100 units forward
  while (!((motor.get_position() < 105) && (motor.get_position() > 95))) {
    // Continue running this loop as long as the motor is not within +-5 units of its goal
    pros::delay(2);
  }
  motor.move_relative(100, 100); // Also moves 100 units forward
  while (!((motor.get_position() < 205) && (motor.get_position() > 195))) {
    pros::delay(2);
  }
}
Parameters  
position The relative position to move to in the motor’s encoder units
velocity The maximum allowable velocity for the movement

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


move_velocity

Sets the velocity for the motor.

This velocity corresponds to different actual speeds depending on the gearset used for the motor. This results in a range of +-100 for E_MOTOR_GEARSET_36, +-200 for E_MOTOR_GEARSET_18, and +-600 for blue. The velocity is held with PID to ensure consistent speed, as opposed to setting the motor’s voltage.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_move_velocity.

std::int32_t pros::Motor::move_velocity ( std::uint8_t port,
                                          std::int16_t velocity )
1
2
3
4
5
6
void autonomous() {
  pros::Motor motor (1);
  motor.move_velocity(100);
  pros::delay(1000); // Move at 100 RPM for 1 second
  motor.move_velocity(0);
}
Parameters  
velocity The new motor velocity from +-100, +-200, or +-600 depending on the motor’s gearset

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


move_voltage

Sets the voltage for the motor from -12000 mV to 12000 mV.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_move_voltage.

std::int32_t pros::Motor::move_voltage ( std::int16_t voltage )
1
2
3
4
5
void autonomous() {
  motor.move_voltage(12000);
  pros::delay(1000); // Move at max voltage for 1 second
  motor.move_voltage(0);
}
Parameters  
voltage The new voltage for the motor from -12000 mV to 12000 mV

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


modify_profiled_velocity

Changes the output velocity for a profiled movement (move_absolute or move_relative). This will have no effect if the motor is not following a profiled movement.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_modify_profiled_velocity.

std::int32_t pros::Motor::modify_profiled_velocity ( const std::int32_t velocity )
1
2
3
4
5
6
void autonomous() {
  pros::Motor motor (1);
  motor.move_absolute(1, 100, 100);
  pros::delay(100);
  motor.modify_profiled_velocity(1, 0); // Stop the motor early
}
Parameters  
velocity The new motor velocity from +-100, +-200, or +-600 depending on the motor’s gearset

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


get_target_position

Gets the target position set for the motor by the user.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_target_position.

double pros::Motor::get_target_position ( )
1
2
3
4
5
6
void autonomous() {
  pros::Motor motor (1);
  motor.move_absolute(100, 100);
  std::cout << "Motor Target: " << motor.get_target_position();
  // Prints 100
}

Returns: The target position in its encoder units or PROS_ERR_F if the operation failed, setting errno.


get_target_velocity

Gets the velocity commanded to the motor by the user.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_target_velocity.

std::int32_t pros::Motor::get_target_velocity ( )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor.move_velocity(master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y));
    std::cout << "Motor Velocity: " << motor.get_target_velocity();
    // Prints the value of E_CONTROLLER_ANALOG_LEFT_Y
    pros::delay(2);
  }
}

Returns: The commanded motor velocity from +-100, +-200, +-600, or PROS_ERR if the operation failed, setting errno.


Telemetry Functions

get_actual_velocity

Gets the actual velocity of the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_actual_velocity.

double pros::Motor::get_actual_velocity ( )
1
2
3
4
5
6
7
8
void opcontrol() {
  pros::Motor motor (1);
  while (true) {
    motor = controller_get_analog(E_CONTROLLER_MASTER, E_CONTROLLER_ANALOG_LEFT_Y);
    printf("Actual velocity: %lf\n", motor.get_actual_velocity());
    pros::delay(2);
  }
}

Returns: The motor’s actual velocity in RPM or PROS_ERR_F if the operation failed, setting errno.


get_current_draw

Gets the current drawn by the motor in mA.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_current_draw.

std::int32_t pros::Motor::get_current_draw ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Current Draw: " << motor.get_current_draw();
    pros::delay(2);
  }
}

Returns: The motor’s current in mA or PROS_ERR if the operation failed, setting errno.


get_direction

Gets the direction of movement for the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_direction.

std::int32_t pros::Motor::get_direction ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Direction: " << motor.get_direction();
    pros::delay(2);
  }
}

Returns: 1 for moving in the positive direction, -1 for moving in the negative direction, and PROS_ERR if the operation failed, setting errno.


get_efficiency

Gets the efficiency of the motor in percent.

An efficiency of 100% means that the motor is moving electrically while drawing no electrical power, and an efficiency of 0% means that the motor is drawing power but not moving.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_efficiency.

std::int32_t pros::Motor::get_efficiency ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Efficiency: " << motor.get_efficiency();
    pros::delay(2);
  }
}

Returns: The motor’s efficiency in percent or PROS_ERR_F if the operation failed, setting errno.


get_faults

Gets the faults experienced by the motor.

Compare this bitfield to the bitmasks in pros::motor_fault_e_t.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_faults.

std::uint32_t pros::Motor::get_faults ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Faults: " << motor.get_faults();
    pros::delay(2);
  }
}

Returns: Currently unknown bitfield.


get_flags

Gets the flags set by the motor’s operation.

Compare this bitfield to the bitmasks in pros::motor_flag_e_t.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_flags.

std::uint32_t pros::Motor::get_flags ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Flags: " << motor.get_flags();
    pros::delay(2);
  }
}

Returns: A currently unknown bitfield


get_position

Gets the absolute position of the motor in its encoder units.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_position.

double pros::Motor::get_position ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Position: " << motor.get_position();
    pros::delay(2);
  }
}

Returns: The motor’s absolute position in its encoder units or PROS_ERR_F if the operation failed, setting errno.


get_power

Gets the power drawn by the motor in Watts.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_power.

double pros::Motor::get_power ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Power: " << motor.get_power();
    pros::delay(2);
  }
}

Returns: The motor’s power draw in Watts or PROS_ERR_F if the operation failed, setting errno.


get_raw_position

Gets the raw encoder count of the motor at a given timestamp.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_raw_position.

std::int32_t pros::Motor::get_raw_position ( std::uint32_t* timestamp )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
void opcontrol() {
  std::uint32_t now = pros::millis();
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Position: " << motor.get_raw_position(&now);
    pros::delay(2);
  }
}
Parameters  
timestamp A pointer to a time in milliseconds for which the encoder count will be returned

Returns: The raw encoder count at the given timestamp or PROS_ERR if the operation failed, setting errno.


get_temperature

Gets the temperature of the motor in degrees Celsius. The resolution of this reading is 5 degrees Celsius. The motor will start to reduce its power when the temperature reading is greater than or equal to 55 C.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_temperature.

double pros::Motor::get_temperature ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Temperature: " << motor.get_temperature();
    pros::delay(2);
  }
}

Returns: The motor’s temperature in degrees Celsius or PROS_ERR_F if the operation failed, setting errno.


get_torque

Gets the torque generated by the motor in Nm.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_torque.

double pros::Motor::get_torque ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Torque: " << motor.get_torque();
    pros::delay(2);
  }
}

Returns: The motor’s torque in NM or PROS_ERR_F if the operation failed, setting errno.


get_voltage

Gets the voltage delivered to the motor in mV.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_voltage.

double pros::Motor::get_voltage ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Motor Voltage: " << motor.get_voltage();
    pros::delay(2);
  }
}

Returns: The motor’s voltage in mV or PROS_ERR_F if the operation failed, setting errno.


get_zero_position_flag

Gets the zero position flag for the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_zero_position_flag.

std::int32_t pros::Motor::get_zero_position_flag ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Is the motor at zero position?: " << motor.get_zero_position_flag();
    pros::delay(2);
  }
}

Returns: 1 if the motor is at zero absolute position and 0 if the motor has moved from its absolute zero, or PROS_ERR if the operation failed setting errno.


is_stopped

Gets the zero velocity flag for the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_is_stopped.

std::int32_t motor_is_stopped ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Is the motor stopped?: " << motor.is_stopped();
    pros::delay(2);
  }
}

Returns: 1 if the motor is not moving and 0 if the motor is moving, or PROS_ERR if the operation failed, setting errno.


is_over_current

Detects if the motor is drawing over its current limit.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_is_over_current.

std::int32_t pros::Motor::is_over_current ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Is the motor over its current limit?: " << motor.is_over_current();
    pros::delay(2);
  }
}

Returns: 1 if the motor’s current limit is being exceeded and 0 if the current limit is not exceeded, or PROS_ERR if the operation failed, setting errno.


is_over_temp

Gets the temperature limit flag for the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_is_over_temp.

std::int32_t pros::Motor::is_over_temp ( )
1
2
3
4
5
6
7
8
9
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    std::cout << "Is the motor over its temperature limit?: " << motor.is_over_temp();
    pros::delay(2);
  }
}
Parameters  
port The V5 port number from 1-21

Returns: 1 if the temperature limit is exceeded and 0 if the the temperature is below the limit, or PROS_ERR if the operation failed, setting errno.


Configuration Functions

convert_pid

Takes in floating point values and returns a properly formatted pid struct. The pros::motor_pid_s_t struct is in 4.4 format, i.e. 0x20 is 2.0, 0x21 is 2.0625, etc.

This function will convert the floating point values to the nearest 4.4 value.

Analogous to motor_convert_pid.

pros::motor_pid_s_t pros::Motor::convert_pid ( double kf,
                                               double kp,
                                               double ki,
                                               double kd )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
#define KF 0
#define KP 1.0f
#define KI 0.001f
#define KD 0.1f

void initialize() {
  pros::Motor motor (1);
  pros:motor_pid_s_t pid = pros::Motor::convert_pid(KF, KP, KI, KD);
  motor.set_pos_pid(pid);
}
Parameters  
kf The feedforward constant
kp The proportional constant
ki The integral constant
kd The derivative constant

Returns: A pros::motor_pid_s_t struct formatted properly in 4.4.


convert_pid_full

Takes in floating point values and returns a properly formatted pid struct. The pros::motor_pid_full_s_t struct is in 4.4 format, i.e. 0x20 is 2.0, 0x21 is 2.0625, etc.

This function will convert the floating point values to the nearest 4.4 value.

Analogous to motor_convert_pid_full.

1
2
3
4
5
6
7
8
pros::motor_pid_full_s_t pros::Motor::convert_pid_full ( double kf,
                                                         double kp,
                                                         double ki,
                                                         double kd,
                                                         double filter,
                                                         double limit,
                                                         double threshold,
                                                         double loopspeed )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
#define KF 0
#define KP 1.0f
#define KI 0.001f
#define KD 0.1f
#define FILTER 1.0f
#define LIMIT 1.0f
#define THRESHOLD 1.0f
#define LOOPSPEED 10

void initialize() {
  pros::Motor motor (1);
  pros::motor_pid_full_s_t pid = pros::Motor::convert_pid_full(KF, KP, KI, KD,
                                 FILTER, LIMIT, THRESHOLD, LOOPSPEED);
  motor.set_pos_pid_full(1, pid);
}
Parameters  
kf The feedforward constant
kp The proportional constant
ki The integral constant
kd The derivative constant
filter A constant used for filtering the profile acceleration
limit The integral limit
threshold

The threshold for determining if a position movement has reached its goal.

This has no effect for velocity PID controllers.

loopspeed The rate at which the PID computation is run (in ms)

Returns: A pros::motor_pid_s_t struct formatted properly in 4.4.


get_brake_mode

Gets the brake mode of the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_brake_mode.

pros::motor_brake_mode_e_t pros::Motor::get_brake_mode ( )
1
2
3
4
5
void initialize() {
  pros::Motor motor (1);
  motor.set_brake_mode(pros::E_MOTOR_BRAKE_HOLD);
  std::cout << "Brake Mode: " << motor.get_brake_mode();
}

Returns: One of motor_brake_mode_e_t, according to what was set for the motor, or E_MOTOR_BRAKE_INVALID if the operation failed, setting errno.


get_current_limit

Gets the current limit for the motor in mA.

The default limit is 2500 mA.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_current_limit.

std::int32_t pros::Motor::get_current_limit ( )
1
2
3
4
5
6
7
void opcontrol() {
  pros::Motor motor (1);
  while (true) {
    std::cout << "Motor Current Limit: " << motor.get_current_limit();
    pros::delay(2);
  }
}

Returns: The motor’s current limit in mA or PROS_ERR if the operation failed, setting errno.


get_encoder_units

Gets the encoder units set for the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_encoder_units.

pros::motor_encoder_units_e_t pros::Motor::get_encoder_units ( )
void initialize() {
  pros::Motor motor (1, E_MOTOR_GEARSET_06, false, E_MOTOR_ENCODER_COUNTS);
  std::cout << "Motor Encoder Units: " << motor.get_encoder_units();
}

Returns: One of motor_encoder_units_e_t according to what is set for the motor or E_MOTOR_ENCODER_INVALID if the operation failed.


get_gearing

Gets the gearset <motor_gearset_e_t_>`_ that was set for the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_gearing.

pros::motor_gearset_e_t pros::Motor::get_gearing ( )
void initialize() {
  pros::Motor motor (1, E_MOTOR_GEARSET_06, false, E_MOTOR_ENCODER_COUNTS);
  std::cout << "Motor Gearing: " << motor.get_gearing();
}

Returns: One of motor_gearset_e_t according to what is set for the motor, or E_GEARSET_INVALID if the operation failed.


get_voltage_limit

Gets the voltage limit set by the user.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_get_voltage_limit.

std::int32_t pros::Motor::get_voltage_limit ( )
void initialize() {
  pros::Motor motor (1);
  std::cout << "Motor Voltage Limit: " << motor.get_voltage_limit();
}

Returns: The motor’s voltage limit in V or PROS_ERR if the operation failed, setting errno.


motor_get_pos_pid

Gets the position PID that was set for the motor. This function will return zero for all of the parameters if the pros::Motor::set_pos_pid() or pros::Motor::set_pos_pid_full() functions have not been used.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Additionally, in an error state all values of the returned struct are set to their negative maximum values.

Analogous to motor_get_pos_pid.

pros::motor_pid_full_s_t pros::Motor::get_pos_pid ( )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
#define KF 0
#define KP 1.0f
#define KI 0.001f
#define KD 0.1f
#define FILTER 1.0f
#define LIMIT 1.0f
#define THRESHOLD 1.0f
#define LOOPSPEED 10

void initialize() {
  pros::Motor motor (1);
  pros::motor_pid_full_s_t pid = pros::Motor::convert_pid_full(KF, KP, KI, KD,
                                 FILTER, LIMIT, THRESHOLD, LOOPSPEED);
  motor.set_pos_pid_full(pid);
  pros::motor_pid_full_s_t pid_returned = motor.get_pos_pid();
  // pid_returned will be equal to pid
}

Returns: A pros::motor_pid_full_s_t containing the position PID constants last set * to the given motor


motor_get_vel_pid

Gets the velocity PID that was set for the motor. This function will return zero for all of the parameters if the pros::Motor::set_vel_pid() or pros::Motor::set_vel_pid_full() functions have not been used.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Additionally, in an error state all values of the returned struct are set to their negative maximum values.

Analogous to motor_get_vel_pid.

pros::motor_pid_full_s_t pros::Motor::get_vel_pid ( )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
#define KF 0
#define KP 1.0f
#define KI 0.001f
#define KD 0.1f
#define FILTER 1.0f
#define LIMIT 1.0f
#define THRESHOLD 1.0f
#define LOOPSPEED 10

void initialize() {
  pros::Motor motor (1);
  pros::motor_pid_full_s_t pid = pros::Motor::convert_pid_full(KF, KP, KI, KD,
                                 FILTER, LIMIT, THRESHOLD, LOOPSPEED);
  motor.set_vel_pid_full(pid);
  pros::motor_pid_full_s_t pid_returned = motor.get_vel_pid();
  // pid_returned will be equal to pid
}

Returns: A pros::motor_pid_full_s_t containing the velocity PID constants last set to the given motor


is_reversed

Gets the operation direction of the motor as set by the user.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_is_reversed.

std::int32_t pros::Motor::is_reversed ( )
1
2
3
4
5
void initialize() {
  pros::Motor motor (1);
  std::cout << "Is the motor reversed? " << motor.is_reversed();
  // Prints "0"
}

Returns: 1 if the motor has been reversed and 0 if the motor was not reversed, or PROS_ERR if the operation failed, setting errno.


set_brake_mode

Sets one of motor_brake_mode_e_t to the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_brake_mode.

std::int32_t pros::Motor::set_brake_mode ( pros::motor_brake_mode_e_t mode )
1
2
3
4
5
void initialize() {
  pros::Motor motor (1);
  motor.set_brake_mode(pros::E_MOTOR_BRAKE_HOLD);
  std::cout << "Brake Mode: " << motor.get_brake_mode();
}
Parameters  
mode The motor_brake_mode_e_t to set for the motor

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_current_limit

Sets the current limit for the motor in mA.

The default limit is 2500 mA.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_current_limit.

std::int32_t pros::Motor::set_current_limit ( std::int32_t limit )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
void opcontrol() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);

  motor.set_current_limit(1000);
  while (true) {
    motor = controller_get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    // The motor will reduce its output at 1000 mA instead of the default 2500 mA
    pros::delay(2);
  }
}
Parameters  
limit The new current limit in mA

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_encoder_units

Sets one of motor_encoder_units_e_t for the motor encoder.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_encoder_units.

std::int32_t pros::Motor::set_encoder_units ( pros::motor_encoder_units_e_t units )
1
2
3
4
5
void initialize() {
  pros::Motor motor (1);
  motor.set_encoder_units(E_MOTOR_ENCODER_DEGREES);
  std::cout << "Encoder Units: " << motor.get_encoder_units();
}
Parameters  
units The new motor encoder units

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_gearing

Sets one of motor_gearset_e_t for the motor.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_gearing.

std::int32_t pros::Motor::set_gearing ( pros::motor_gearset_e_t_ gearset )
1
2
3
4
5
void initialize() {
  pros::Motor motor (1);
  motor.set_gearing(E_MOTOR_GEARSET_06);
  std::cout << "Brake Mode: " << motor.get_gearing();
}
Parameters  
gearset The new motor gearset

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_pos_pid

Sets one of pros::motor_pid_s_t for the motor. This intended to just modify the main PID constants.

Only non-zero values of the struct will change the existing motor constants.

Warning

This feature is in beta, it is advised to use caution when modifying the PID values. The motor could be damaged by particularly large constants.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_pos_pid.

std::int32_t pros::Motor::set_pos_pid ( const pros::motor_pid_s_t pid )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
#define KF 0
#define KP 1.0f
#define KI 0.001f
#define KD 0.1f

void initialize() {
  pros::Motor motor (1);
  pros::motor_pid_s_t pid = pros::Motor::convert_pid(KF, KP, KI, KD);
  motor.set_pos_pid(pid);
}
Parameters  
pid The new motor PID constants

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_pos_pid_full

Sets one of pros::motor_pid_full_s_t for the motor.

Only non-zero values of the struct will change the existing motor constants.

Warning

This feature is in beta, it is advised to use caution when modifying the PID values. The motor could be damaged by particularly large constants.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_pos_pid_full.

std::int32_t pros::Motor::set_pos_pid_full ( const pros::motor_pid_full_s_t pid )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
#define KF 0
#define KP 1.0f
#define KI 0.001f
#define KD 0.1f
#define FILTER 1.0f
#define LIMIT 1.0f
#define THRESHOLD 1.0f
#define LOOPSPEED 10

void initialize() {
  pros::Motor motor (1);
  pros::motor_pid_full_s_t pid = pros::Motor::convert_pid_full(KF, KP, KI, KD,
                                 FILTER, LIMIT, THRESHOLD, LOOPSPEED);
  motor.set_pos_pid_full(pid);
}
Parameters  
pid The new motor PID constants

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_reversed

Sets the reverse flag for the motor.

This will invert its movements and the values returned for its position.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_reversed.

std::int32_t pros::Motor::set_reversed ( bool reverse )
1
2
3
4
5
void initialize() {
  pros::Motor motor (1);
  motor.set_reversed(true);
  std::cout << "Is this motor reversed? " << motor.is_reversed();
}
Parameters  
reverse 1 reverses the motor, 0 is default

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_vel_pid

Sets one of pros::motor_pid_s_t for the motor. This intended to just modify the main PID constants.

Only non-zero values of the struct will change the existing motor constants.

Warning

This feature is in beta, it is advised to use caution when modifying the PID values. The motor could be damaged by particularly large constants.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_vel_pid.

std::int32_t pros::Motor::set_vel_pid ( const pros::motor_pid_s_t pid )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
#define KF 0
#define KP 1.0f
#define KI 0.001f
#define KD 0.1f

void initialize() {
  pros::Motor motor (1);
  pros::motor_pid_s_t pid = pros::Motor::convert_pid(KF, KP, KI, KD);
  motor.set_vel_pid(pid);
}
Parameters  
pid The new motor PID constants

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_vel_pid_full

Sets one of pros::motor_pid_full_s_t for the motor.

Only non-zero values of the struct will change the existing motor constants.

Warning

This feature is in beta, it is advised to use caution when modifying the PID values. The motor could be damaged by particularly large constants.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_vel_pid_full.

std::int32_t pros::Motor::set_vel_pid_full ( const pros::motor_pid_full_s_t pid )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
#define KF 0
#define KP 1.0f
#define KI 0.001f
#define KD 0.1f
#define FILTER 1.0f
#define LIMIT 1.0f
#define THRESHOLD 1.0f
#define LOOPSPEED 10

void initialize() {
  pros::Motor motor (1);
  pros::motor_pid_full_s_t pid = pros::Motor::convert_pid_full(KF, KP, KI, KD,
                                 FILTER, LIMIT, THRESHOLD, LOOPSPEED);
  motor.set_vel_pid_full(pid);
}
Parameters  
pid The new motor PID constants

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_voltage_limit

Sets the voltage limit for the motor in mV.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_voltage_limit.

std::int32_t pros::Motor::set_voltage_limit ( std::int32_t limit )
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
void autonomous() {
  pros::Motor motor (1);
  pros::Controller master (E_CONTROLLER_MASTER);

  motor.set_voltage_limit(10000);
  while (true) {
    motor = master.get_analog(E_CONTROLLER_ANALOG_LEFT_Y);
    // The motor will not output more than 10 V
    pros::delay(2);
  }
}
Parameters  
limit The new voltage limit in Volts

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


set_zero_position

Sets the zero position for the motor in its encoder units.

This will be the future reference point for the motor’s “absolute” position.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_set_zero_position.

std::int32_t pros::Motor::set_zero_position ( double position )
1
2
3
4
5
6
7
8
void autonomous() {
  pros::Motor motor (1);
  motor.move_absolute(100, 100); // Moves 100 units forward
  motor.move_absolute(100, 100); // This does not cause a movement

  motor.set_zero_position(80);
  motor.move_absolute(100, 100); // Moves 120 units forward
}
Parameters  
position The new reference position in its encoder units

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


tare_position

Sets the “absolute” zero position of the motor to its current position.

This function uses the following values of errno when an error state is reached:

  • ENODEV - The port cannot be configured as a motor

Analogous to motor_tare_position.

std::int32_t pros::Motor::tare_position ( )
1
2
3
4
5
6
7
8
void autonomous() {
  pros::Motor motor (1);
  motor.move_absolute(100, 100); // Moves 100 units forward
  motor.move_absolute(100, 100); // This does not cause a movement

  motor.tare_position();
  motor.move_absolute(100, 100); // Moves 100 units forward
}

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.


Macros

None.

Enumerated Values

pros::motor_brake_mode_e_t

Indicates the current ‘brake mode’ of the motor.

1
2
3
4
5
6
typedef enum motor_brake_mode_e {
  E_MOTOR_BRAKE_COAST = 0, // Motor coasts when stopped, traditional behavior
  E_MOTOR_BRAKE_BRAKE = 1, // Motor brakes when stopped
  E_MOTOR_BRAKE_HOLD = 2, // Motor actively holds position when stopped
  E_MOTOR_BRAKE_INVALID = INT32_MAX
} motor_brake_mode_e_t;
Value  
pros::E_MOTOR_BRAKE_COAST Motor coasts when stopped, traditional behavior
pros::E_MOTOR_BRAKE_BRAKE Motor brakes when stopped
pros::E_MOTOR_BRAKE_HOLD Motor actively holds position when stopped
pros::E_MOTOR_BRAKE_INVALID Invalid brake mode

pros::motor_encoder_units_e_t

Indicates the units used by the motor’s encoder.

1
2
3
4
5
6
7
8
9
typedef enum motor_encoder_units_e {
  E_MOTOR_ENCODER_DEGREES = 0,   // Position is recorded as angle in degrees
                                 // as a floating point number
  E_MOTOR_ENCODER_ROTATIONS = 1, // Position is recorded as angle in rotations
                                 // as a floating point number
  E_MOTOR_ENCODER_COUNTS = 2,    // Position is recorded as raw encoder ticks
                                 // as a whole number
  E_MOTOR_ENCODER_INVALID = INT32_MAX
} motor_encoder_units_e_t;
Value  
pros::E_MOTOR_ENCODER_DEGREES Position is recorded as angle in degrees as a floating point number
pros::E_MOTOR_ENCODER_ROTATIONS Position is recorded as angle in rotations as a floating point number
pros::E_MOTOR_ENCODER_COUNTS Position is recorded as raw encoder ticks as a whole number
pros::E_MOTOR_BRAKE_INVALID Invalid motor encoder units

pros::motor_fault_e_t

1
2
3
4
5
6
7
typedef enum motor_fault_e {
      E_MOTOR_FAULT_NO_FAULTS = 0x00,
      E_MOTOR_FAULT_MOTOR_OVER_TEMP = 0x01,  // Analogous to motor_is_over_temp()
      E_MOTOR_FAULT_DRIVER_FAULT = 0x02,     // Indicates a motor h-bridge fault
      E_MOTOR_FAULT_OVER_CURRENT = 0x04,     // Analogous to motor_is_over_current()
      E_MOTOR_FAULT_DRV_OVER_CURRENT = 0x08  // Indicates an h-bridge over current
} motor_fault_e_t;
Value  
pros::E_MOTOR_FAULT_NO_FAULTS No faults
pros::E_MOTOR_FAULT_MOTOR_OVER_TEMP Analogous to motor_is_over_temp()
pros::E_MOTOR_FAULT_DRIVER_FAULT Indicates a motor h-bridge fault
pros::E_MOTOR_FAULT_OVER_CURRENT Analogous to motor_is_over_current()
pros::E_MOTOR_FAULT_DRV_OVER_CURRENT Indicates an h-bridge over current

pros::motor_flag_e_t

1
2
3
4
5
6
typedef enum motor_flag_e {
  E_MOTOR_FLAGS_NONE = 0x00,
  E_MOTOR_FLAGS_BUSY = 0x01,           // Cannot currently communicate to the motor
  E_MOTOR_FLAGS_ZERO_VELOCITY = 0x02,  // Analogous to motor_is_stopped()
  E_MOTOR_FLAGS_ZERO_POSITION = 0x04   // Analogous to motor_get_zero_position_flag()
} motor_flag_e_t;
Value  
pros::E_MOTOR_FLAGS_NONE There are no flags raised
pros::E_MOTOR_FLAGS_BUSY Cannot currently communicate to the motor
pros::E_MOTOR_FLAGS_ZERO_VELOCITY Analogous to pros::Motor::is_stopped()
pros::E_MOTOR_FLAGS_ZERO_POSITION Analogous to pros::Motor::get_zero_position_flag()

pros::motor_gearset_e_t

Indicates the internal gearing used by the motor.

1
2
3
4
5
6
typedef enum motor_gearset_e {
      E_MOTOR_GEARSET_36 = 0, // 36:1, 100 RPM, Red gear set
      E_MOTOR_GEARSET_18 = 1, // 18:1, 200 RPM, Green gear set
      E_MOTOR_GEARSET_06 = 2, // 6:1, 600 RPM, Blue gear set
      E_MOTOR_GEARSET_INVALID = INT32_MAX
} motor_gearset_e_t;
Value  
pros::E_MOTOR_GEARSET_36 36:1, 100 RPM, Red gear set
pros::E_MOTOR_GEARSET_18 18:1, 200 RPM, Green gear set
pros::E_MOTOR_GEARSET_06 6:1, 600 RPM, Blue Gear Set
pros::E_MOTOR_GEARSET_INVALID Error return code

Typedefs

motor_pid_full_s_t

Holds the information about a Motor’s position or velocity PID controls.

These values are in 4.4 format, meaning that a value of 0x20 represents 2.0, 0x21 represents 2.0625, 0x22 represents 2.125, etc.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
typedef struct motor_pid_full_s {
  uint8_t kf;        // The feedforward constant
  uint8_t kp;        // The proportional constant
  uint8_t ki;        // The integral constants
  uint8_t kd;        // The derivative constant
  uint8_t filter;    // A constant used for filtering the profile acceleration
  uint16_t limit;    // The integral limit
  uint8_t threshold; // The threshold for determining if a position movement has
                     // reached its goal. This has no effect for velocity PID
                     // calculations.
  uint8_t loopspeed; // The rate at which the PID computation is run in ms
} motor_pid_full_s_t;

motor_pid_s_t

Holds just the constants for a Motor’s position or velocity PID controls.

These values are in 4.4 format, meaning that a value of 0x20 represents 2.0, 0x21 represents 2.0625, 0x22 represents 2.125, etc.

1
2
3
4
5
6
typedef struct motor_pid_s {
  uint8_t kf;        // The feedforward constant
  uint8_t kp;        // The proportional constant
  uint8_t ki;        // The integral constants
  uint8_t kd;        // The derivative constant
} motor_pid_s_t;