From e1b6e5f21207d32ef6a1edaf49aacbc3209caf67 Mon Sep 17 00:00:00 2001 From: sciencewhiz Date: Sun, 20 Mar 2022 21:54:43 -0700 Subject: [PATCH] [wpilib] Improve MotorSafety documentation (NFC) (#4120) Remove OBE RobotDrive porting guide from MecanumDrive --- wpilibc/src/main/native/include/frc/MotorSafety.h | 7 +++++-- .../main/native/include/frc/drive/DifferentialDrive.h | 4 ++++ .../src/main/native/include/frc/drive/KilloughDrive.h | 3 +++ .../src/main/native/include/frc/drive/MecanumDrive.h | 11 ++--------- .../main/native/include/frc/drive/RobotDriveBase.h | 2 ++ .../main/java/edu/wpi/first/wpilibj/MotorSafety.java | 6 ++++-- .../wpi/first/wpilibj/drive/DifferentialDrive.java | 3 +++ .../edu/wpi/first/wpilibj/drive/KilloughDrive.java | 3 +++ .../edu/wpi/first/wpilibj/drive/MecanumDrive.java | 9 ++------- .../edu/wpi/first/wpilibj/drive/RobotDriveBase.java | 6 +++++- 10 files changed, 33 insertions(+), 21 deletions(-) diff --git a/wpilibc/src/main/native/include/frc/MotorSafety.h b/wpilibc/src/main/native/include/frc/MotorSafety.h index 1bfd34a81a..a17cdc0cab 100644 --- a/wpilibc/src/main/native/include/frc/MotorSafety.h +++ b/wpilibc/src/main/native/include/frc/MotorSafety.h @@ -14,8 +14,11 @@ namespace frc { /** - * This base class runs a watchdog timer and calls the subclass's StopMotor() - * function if the timeout expires. + * The Motor Safety feature acts as a watchdog timer for an individual motor. It + * operates by maintaining a timer that tracks how long it has been since the + * feed() method has been called for that actuator. Code in the Driver Station + * class initiates a comparison of these timers to the timeout values for any + * actuator with safety enabled every 5 received packets (100ms nominal). * * The subclass should call Feed() whenever the motor value is updated. */ diff --git a/wpilibc/src/main/native/include/frc/drive/DifferentialDrive.h b/wpilibc/src/main/native/include/frc/drive/DifferentialDrive.h index 2b5831b49c..0b793a7542 100644 --- a/wpilibc/src/main/native/include/frc/drive/DifferentialDrive.h +++ b/wpilibc/src/main/native/include/frc/drive/DifferentialDrive.h @@ -95,6 +95,10 @@ class SpeedController; * Inputs smaller then 0.02 will be set to 0, and larger values will be scaled * so that the full range is still used. This deadband value can be changed * with SetDeadband(). + * + * MotorSafety is enabled by default. The tankDrive, arcadeDrive, + * or curvatureDrive methods should be called periodically to avoid Motor + * Safety timeouts. */ class DifferentialDrive : public RobotDriveBase, public wpi::Sendable, diff --git a/wpilibc/src/main/native/include/frc/drive/KilloughDrive.h b/wpilibc/src/main/native/include/frc/drive/KilloughDrive.h index d4c5c5c2e4..c09f218574 100644 --- a/wpilibc/src/main/native/include/frc/drive/KilloughDrive.h +++ b/wpilibc/src/main/native/include/frc/drive/KilloughDrive.h @@ -53,6 +53,9 @@ class SpeedController; * The positive X axis points ahead, the positive Y axis points right, and the * and the positive Z axis points down. Rotations follow the right-hand rule, so * clockwise rotation around the Z axis is positive. + * + * MotorSafety is enabled by default. The DriveCartesian or DrivePolar + * methods should be called periodically to avoid Motor Safety timeouts. */ class KilloughDrive : public RobotDriveBase, public wpi::Sendable, diff --git a/wpilibc/src/main/native/include/frc/drive/MecanumDrive.h b/wpilibc/src/main/native/include/frc/drive/MecanumDrive.h index 757ae67570..7e447ef298 100644 --- a/wpilibc/src/main/native/include/frc/drive/MecanumDrive.h +++ b/wpilibc/src/main/native/include/frc/drive/MecanumDrive.h @@ -57,15 +57,8 @@ class SpeedController; * so that the full range is still used. This deadband value can be changed * with SetDeadband(). * - * RobotDrive porting guide: - *
DriveCartesian(double, double, double, double) is equivalent to - * RobotDrive's MecanumDrive_Cartesian(double, double, double, double) - * if a deadband of 0 is used, and the ySpeed and gyroAngle values are inverted - * compared to RobotDrive (eg DriveCartesian(xSpeed, -ySpeed, zRotation, - * -gyroAngle). - *
DrivePolar(double, double, double) is equivalent to - * RobotDrive's MecanumDrive_Polar(double, double, double) if a - * deadband of 0 is used. + * MotorSafety is enabled by default. The DriveCartesian or DrivePolar + * methods should be called periodically to avoid Motor Safety timeouts. */ class MecanumDrive : public RobotDriveBase, public wpi::Sendable, diff --git a/wpilibc/src/main/native/include/frc/drive/RobotDriveBase.h b/wpilibc/src/main/native/include/frc/drive/RobotDriveBase.h index 8ce5636709..662bdaebcf 100644 --- a/wpilibc/src/main/native/include/frc/drive/RobotDriveBase.h +++ b/wpilibc/src/main/native/include/frc/drive/RobotDriveBase.h @@ -16,6 +16,8 @@ namespace frc { /** * Common base class for drive platforms. + * + * MotorSafety is enabled by default. */ class RobotDriveBase : public MotorSafety { public: diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/MotorSafety.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/MotorSafety.java index 4e7693649d..5fb10b4ff8 100644 --- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/MotorSafety.java +++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/MotorSafety.java @@ -8,8 +8,10 @@ import java.util.LinkedHashSet; import java.util.Set; /** - * This base class runs a watchdog timer and calls the subclass's StopMotor() function if the - * timeout expires. + * The Motor Safety feature acts as a watchdog timer for an individual motor. It operates by + * maintaining a timer that tracks how long it has been since the feed() method has been called for + * that actuator. Code in the Driver Station class initiates a comparison of these timers to the + * timeout values for any actuator with safety enabled every 5 received packets (100ms nominal). * *

The subclass should call feed() whenever the motor value is updated. */ diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/DifferentialDrive.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/DifferentialDrive.java index cb8729200e..b6f38ffa4a 100644 --- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/DifferentialDrive.java +++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/DifferentialDrive.java @@ -83,6 +83,9 @@ import edu.wpi.first.wpilibj.SpeedController; *

Inputs smaller then {@value edu.wpi.first.wpilibj.drive.RobotDriveBase#kDefaultDeadband} will * be set to 0, and larger values will be scaled so that the full range is still used. This deadband * value can be changed with {@link #setDeadband}. + * + *

{@link edu.wpi.first.wpilibj.MotorSafety} is enabled by default. The tankDrive, arcadeDrive, + * or curvatureDrive methods should be called periodically to avoid Motor Safety timeouts. */ @SuppressWarnings("removal") public class DifferentialDrive extends RobotDriveBase implements Sendable, AutoCloseable { diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/KilloughDrive.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/KilloughDrive.java index 9915c87da6..6eb934ddef 100644 --- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/KilloughDrive.java +++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/KilloughDrive.java @@ -39,6 +39,9 @@ import edu.wpi.first.wpilibj.SpeedController; *

The positive X axis points ahead, the positive Y axis points right, and the positive Z axis * points down. Rotations follow the right-hand rule, so clockwise rotation around the Z axis is * positive. + * + *

{@link edu.wpi.first.wpilibj.MotorSafety} is enabled by default. The driveCartesian or + * drivePolar methods should be called periodically to avoid Motor Safety timeouts. */ @SuppressWarnings("removal") public class KilloughDrive extends RobotDriveBase implements Sendable, AutoCloseable { diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/MecanumDrive.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/MecanumDrive.java index d22593f0a8..af93f3997a 100644 --- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/MecanumDrive.java +++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/MecanumDrive.java @@ -47,13 +47,8 @@ import edu.wpi.first.wpilibj.SpeedController; * be set to 0, and larger values will be scaled so that the full range is still used. This deadband * value can be changed with {@link #setDeadband}. * - *

RobotDrive porting guide:
- * {@link #driveCartesian(double, double, double, double)} is equivalent to RobotDrive's - * mecanumDrive_Cartesian(double, double, double, double) if a deadband of 0 is used, and the ySpeed - * and gyroAngle values are inverted compared to RobotDrive (eg driveCartesian(xSpeed, -ySpeed, - * zRotation, -gyroAngle).
- * {@link #drivePolar(double, double, double)} is equivalent to RobotDrive's - * mecanumDrive_Polar(double, double, double)} if a deadband of 0 is used. + *

{@link edu.wpi.first.wpilibj.MotorSafety} is enabled by default. The driveCartesian or + * drivePolar methods should be called periodically to avoid Motor Safety timeouts. */ @SuppressWarnings("removal") public class MecanumDrive extends RobotDriveBase implements Sendable, AutoCloseable { diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/RobotDriveBase.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/RobotDriveBase.java index 569f94c8f5..82673ff055 100644 --- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/RobotDriveBase.java +++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/RobotDriveBase.java @@ -7,7 +7,11 @@ package edu.wpi.first.wpilibj.drive; import edu.wpi.first.math.MathUtil; import edu.wpi.first.wpilibj.MotorSafety; -/** Common base class for drive platforms. */ +/** + * Common base class for drive platforms. + * + *

{@link edu.wpi.first.wpilibj.MotorSafety} is enabled by default. + */ public abstract class RobotDriveBase extends MotorSafety { public static final double kDefaultDeadband = 0.02; public static final double kDefaultMaxOutput = 1.0;