[wpilib] Add/update documentation to PneumaticBase and subclasses (NFC) (#4881)

Co-authored-by: Starlight220 <53231611+Starlight220@users.noreply.github.com>
2026-06-22 01:11:42 +00:00 · 2023-01-02 13:23:59 -05:00
parent 9872e676d8
commit 83f1860047
8 changed files with 722 additions and 47 deletions
--- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/Compressor.java
+++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/Compressor.java
@@ -84,37 +84,42 @@ public class Compressor implements Sendable, AutoCloseable {
  }

  /**
-   * Get the pressure switch value.
+   * Returns the state of the pressure switch.
   *
-   * @return true if the pressure is low
+   * @return True if pressure switch indicates that the system is not full, otherwise false.
   */
  public boolean getPressureSwitchValue() {
    return m_module.getPressureSwitch();
  }

  /**
-   * Get the current being used by the compressor.
+   * Get the current drawn by the compressor.
   *
-   * @return current consumed by the compressor in amps
+   * @return Current drawn by the compressor in amps.
   */
  public double getCurrent() {
    return m_module.getCompressorCurrent();
  }

  /**
-   * Query the analog input voltage (on channel 0) (if supported).
+   * If supported by the device, returns the analog input voltage (on channel 0).
   *
-   * @return The analog input voltage, in volts
+   * <p>This function is only supported by the REV PH. On CTRE PCM, this will return 0.
+   *
+   * @return The analog input voltage, in volts.
   */
  public double getAnalogVoltage() {
    return m_module.getAnalogVoltage(0);
  }

  /**
-   * Query the analog sensor pressure (on channel 0) (if supported). Note this is only for use with
-   * the REV Analog Pressure Sensor.
+   * If supported by the device, returns the pressure (in PSI) read by the analog pressure sensor
+   * (on channel 0).
   *
-   * @return The analog sensor pressure, in PSI
+   * <p>This function is only supported by the REV PH with the REV Analog Pressure Sensor. On CTRE
+   * PCM, this will return 0.
+   *
+   * @return The pressure (in PSI) read by the analog pressure sensor.
   */
  public double getPressure() {
    return m_module.getPressure(0);
@@ -125,41 +130,71 @@ public class Compressor implements Sendable, AutoCloseable {
    m_module.disableCompressor();
  }

-  /** Enable compressor closed loop control using digital input. */
+  /**
+   * Enables the compressor in digital mode using the digital pressure switch. The compressor will
+   * turn on when the pressure switch indicates that the system is not full, and will turn off when
+   * the pressure switch indicates that the system is full.
+   */
  public void enableDigital() {
    m_module.enableCompressorDigital();
  }

  /**
-   * Enable compressor closed loop control using analog input. Note this is only for use with the
-   * REV Analog Pressure Sensor.
+   * If supported by the device, enables the compressor in analog mode. This mode uses an analog
+   * pressure sensor connected to analog channel 0 to cycle the compressor. The compressor will turn
+   * on when the pressure drops below {@code minPressure} and will turn off when the pressure
+   * reaches {@code maxPressure}. This mode is only supported by the REV PH with the REV Analog
+   * Pressure Sensor connected to analog channel 0.
   *
   * <p>On CTRE PCM, this will enable digital control.
   *
-   * @param minPressure The minimum pressure in PSI to enable compressor
-   * @param maxPressure The maximum pressure in PSI to disable compressor
+   * @param minPressure The minimum pressure in PSI. The compressor will turn on when the pressure
+   *     drops below this value.
+   * @param maxPressure The maximum pressure in PSI. The compressor will turn off when the pressure
+   *     reaches this value.
   */
  public void enableAnalog(double minPressure, double maxPressure) {
    m_module.enableCompressorAnalog(minPressure, maxPressure);
  }

  /**
-   * Enable compressor closed loop control using hybrid input. Note this is only for use with the
-   * REV Analog Pressure Sensor.
+   * If supported by the device, enables the compressor in hybrid mode. This mode uses both a
+   * digital pressure switch and an analog pressure sensor connected to analog channel 0 to cycle
+   * the compressor. This mode is only supported by the REV PH with the REV Analog Pressure Sensor
+   * connected to analog channel 0.
+   *
+   * <p>The compressor will turn on when <i>both</i>:
+   *
+   * <ul>
+   *   <li>The digital pressure switch indicates the system is not full AND
+   *   <li>The analog pressure sensor indicates that the pressure in the system is below the
+   *       specified minimum pressure.
+   * </ul>
+   *
+   * <p>The compressor will turn off when <i>either</i>:
+   *
+   * <ul>
+   *   <li>The digital pressure switch is disconnected or indicates that the system is full OR
+   *   <li>The pressure detected by the analog sensor is greater than the specified maximum
+   *       pressure.
+   * </ul>
   *
   * <p>On CTRE PCM, this will enable digital control.
   *
-   * @param minPressure The minimum pressure in PSI to enable compressor
-   * @param maxPressure The maximum pressure in PSI to disable compressor
+   * @param minPressure The minimum pressure in PSI. The compressor will turn on when the pressure
+   *     drops below this value and the pressure switch indicates that the system is not full.
+   * @param maxPressure The maximum pressure in PSI. The compressor will turn off when the pressure
+   *     reaches this value or the pressure switch is disconnected or indicates that the system is
+   *     full.
   */
  public void enableHybrid(double minPressure, double maxPressure) {
    m_module.enableCompressorHybrid(minPressure, maxPressure);
  }

  /**
-   * Gets the current operating mode of the Compressor.
+   * Returns the active compressor configuration.
   *
-   * @return true if compressor is operating on closed-loop mode
+   * @return The active compressor configuration.
   */
  public CompressorConfigType getConfigType() {
    return m_module.getCompressorConfigType();
--- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/PneumaticHub.java
+++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/PneumaticHub.java
@@ -128,7 +128,7 @@ public class PneumaticHub implements PneumaticsBase {
  private final DataStore m_dataStore;
  private final int m_handle;

-  /** Constructs a PneumaticHub with the default id (1). */
+  /** Constructs a PneumaticHub with the default ID (1). */
  public PneumaticHub() {
    this(SensorUtil.getDefaultREVPHModule());
  }
@@ -256,6 +256,11 @@ public class PneumaticHub implements PneumaticsBase {
    return raw & 0xFFFF;
  }

+  /**
+   * Disables the compressor. The compressor will not turn on until {@link
+   * #enableCompressorDigital()}, {@link #enableCompressorAnalog(double, double)}, or {@link
+   * #enableCompressorHybrid(double, double)} are called.
+   */
  @Override
  public void disableCompressor() {
    REVPHJNI.setClosedLoopControlDisabled(m_handle);
@@ -266,6 +271,16 @@ public class PneumaticHub implements PneumaticsBase {
    REVPHJNI.setClosedLoopControlDigital(m_handle);
  }

+  /**
+   * Enables the compressor in analog mode. This mode uses an analog pressure sensor connected to
+   * analog channel 0 to cycle the compressor. The compressor will turn on when the pressure drops
+   * below {@code minPressure} and will turn off when the pressure reaches {@code maxPressure}.
+   *
+   * @param minPressure The minimum pressure in PSI. The compressor will turn on when the pressure
+   *     drops below this value.
+   * @param maxPressure The maximum pressure in PSI. The compressor will turn off when the pressure
+   *     reaches this value.
+   */
  @Override
  public void enableCompressorAnalog(double minPressure, double maxPressure) {
    if (minPressure >= maxPressure) {
@@ -284,6 +299,32 @@ public class PneumaticHub implements PneumaticsBase {
    REVPHJNI.setClosedLoopControlAnalog(m_handle, minAnalogVoltage, maxAnalogVoltage);
  }

+  /**
+   * Enables the compressor in hybrid mode. This mode uses both a digital pressure switch and an
+   * analog pressure sensor connected to analog channel 0 to cycle the compressor.
+   *
+   * <p>The compressor will turn on when <i>both</i>:
+   *
+   * <ul>
+   *   <li>The digital pressure switch indicates the system is not full AND
+   *   <li>The analog pressure sensor indicates that the pressure in the system is below the
+   *       specified minimum pressure.
+   * </ul>
+   *
+   * <p>The compressor will turn off when <i>either</i>:
+   *
+   * <ul>
+   *   <li>The digital pressure switch is disconnected or indicates that the system is full OR
+   *   <li>The pressure detected by the analog sensor is greater than the specified maximum
+   *       pressure.
+   * </ul>
+   *
+   * @param minPressure The minimum pressure in PSI. The compressor will turn on when the pressure
+   *     drops below this value and the pressure switch indicates that the system is not full.
+   * @param maxPressure The maximum pressure in PSI. The compressor will turn off when the pressure
+   *     reaches this value or the pressure switch is disconnected or indicates that the system is
+   *     full.
+   */
  @Override
  public void enableCompressorHybrid(double minPressure, double maxPressure) {
    if (minPressure >= maxPressure) {
@@ -302,11 +343,23 @@ public class PneumaticHub implements PneumaticsBase {
    REVPHJNI.setClosedLoopControlHybrid(m_handle, minAnalogVoltage, maxAnalogVoltage);
  }

+  /**
+   * Returns the raw voltage of the specified analog input channel.
+   *
+   * @param channel The analog input channel to read voltage from.
+   * @return The voltage of the specified analog input channel.
+   */
  @Override
  public double getAnalogVoltage(int channel) {
    return REVPHJNI.getAnalogVoltage(m_handle, channel);
  }

+  /**
+   * Returns the pressure read by an analog pressure sensor on the specified analog input channel.
+   *
+   * @param channel The analog input channel to read pressure from.
+   * @return The pressure read by an analog pressure sensor on the specified analog input channel.
+   */
  @Override
  public double getPressure(int channel) {
    double sensorVoltage = REVPHJNI.getAnalogVoltage(m_handle, channel);
@@ -314,34 +367,70 @@ public class PneumaticHub implements PneumaticsBase {
    return voltsToPsi(sensorVoltage, supplyVoltage);
  }

+  /** Clears the sticky faults. */
  public void clearStickyFaults() {
    REVPHJNI.clearStickyFaults(m_handle);
  }

+  /**
+   * Returns the hardware and firmware versions of this device.
+   *
+   * @return The hardware and firmware versions.
+   */
  public REVPHVersion getVersion() {
    return REVPHJNI.getVersion(m_handle);
  }

+  /**
+   * Returns the faults currently active on this device.
+   *
+   * @return The faults.
+   */
  public REVPHFaults getFaults() {
    return REVPHJNI.getFaults(m_handle);
  }

+  /**
+   * Returns the sticky faults currently active on this device.
+   *
+   * @return The sticky faults.
+   */
  public REVPHStickyFaults getStickyFaults() {
    return REVPHJNI.getStickyFaults(m_handle);
  }

+  /**
+   * Returns the current input voltage for this device.
+   *
+   * @return The input voltage.
+   */
  public double getInputVoltage() {
    return REVPHJNI.getInputVoltage(m_handle);
  }

+  /**
+   * Returns the current voltage of the regulated 5v supply.
+   *
+   * @return The current voltage of the 5v supply.
+   */
  public double get5VRegulatedVoltage() {
    return REVPHJNI.get5VVoltage(m_handle);
  }

+  /**
+   * Returns the total current (in amps) drawn by all solenoids.
+   *
+   * @return Total current drawn by all solenoids in amps.
+   */
  public double getSolenoidsTotalCurrent() {
    return REVPHJNI.getSolenoidCurrent(m_handle);
  }

+  /**
+   * Returns the current voltage of the solenoid power supply.
+   *
+   * @return The current voltage of the solenoid power supply.
+   */
  public double getSolenoidsVoltage() {
    return REVPHJNI.getSolenoidVoltage(m_handle);
  }
--- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/PneumaticsBase.java
+++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/PneumaticsBase.java
@@ -45,7 +45,7 @@ public interface PneumaticsBase extends AutoCloseable {
  void setSolenoids(int mask, int values);

  /**
-   * Gets solenoid values.
+   * Gets a bitmask of solenoid values.
   *
   * @return values
   */
@@ -59,9 +59,9 @@ public interface PneumaticsBase extends AutoCloseable {
  int getModuleNumber();

  /**
-   * Get the disabled solenoids.
+   * Get a bitmask of disabled solenoids.
   *
-   * @return disabled list
+   * @return bitmask of disabled solenoids
   */
  int getSolenoidDisabledList();

@@ -80,24 +80,112 @@ public interface PneumaticsBase extends AutoCloseable {
   */
  void setOneShotDuration(int index, int durMs);

+  /**
+   * Returns whether the compressor is active or not.
+   *
+   * @return True if the compressor is on - otherwise false.
+   */
  boolean getCompressor();

+  /**
+   * Returns the state of the pressure switch.
+   *
+   * @return True if pressure switch indicates that the system is not full, otherwise false.
+   */
  boolean getPressureSwitch();

+  /**
+   * Returns the current drawn by the compressor in amps.
+   *
+   * @return The current drawn by the compressor.
+   */
  double getCompressorCurrent();

+  /** Disables the compressor. */
  void disableCompressor();

+  /**
+   * Enables the compressor in digital mode using the digital pressure switch. The compressor will
+   * turn on when the pressure switch indicates that the system is not full, and will turn off when
+   * the pressure switch indicates that the system is full.
+   */
  void enableCompressorDigital();

+  /**
+   * If supported by the device, enables the compressor in analog mode. This mode uses an analog
+   * pressure sensor connected to analog channel 0 to cycle the compressor. The compressor will turn
+   * on when the pressure drops below {@code minPressure} and will turn off when the pressure
+   * reaches {@code maxPressure}. This mode is only supported by the REV PH with the REV Analog
+   * Pressure Sensor connected to analog channel 0.
+   *
+   * <p>On CTRE PCM, this will enable digital control.
+   *
+   * @param minPressure The minimum pressure in PSI. The compressor will turn on when the pressure
+   *     drops below this value.
+   * @param maxPressure The maximum pressure in PSI. The compressor will turn off when the pressure
+   *     reaches this value.
+   */
  void enableCompressorAnalog(double minPressure, double maxPressure);

+  /**
+   * If supported by the device, enables the compressor in hybrid mode. This mode uses both a
+   * digital pressure switch and an analog pressure sensor connected to analog channel 0 to cycle
+   * the compressor. This mode is only supported by the REV PH with the REV Analog Pressure Sensor
+   * connected to analog channel 0.
+   *
+   * <p>The compressor will turn on when <i>both</i>:
+   *
+   * <ul>
+   *   <li>The digital pressure switch indicates the system is not full AND
+   *   <li>The analog pressure sensor indicates that the pressure in the system is below the
+   *       specified minimum pressure.
+   * </ul>
+   *
+   * <p>The compressor will turn off when <i>either</i>:
+   *
+   * <ul>
+   *   <li>The digital pressure switch is disconnected or indicates that the system is full OR
+   *   <li>The pressure detected by the analog sensor is greater than the specified maximum
+   *       pressure.
+   * </ul>
+   *
+   * <p>On CTRE PCM, this will enable digital control.
+   *
+   * @param minPressure The minimum pressure in PSI. The compressor will turn on when the pressure
+   *     drops below this value and the pressure switch indicates that the system is not full.
+   * @param maxPressure The maximum pressure in PSI. The compressor will turn off when the pressure
+   *     reaches this value or the pressure switch is disconnected or indicates that the system is
+   *     full.
+   */
  void enableCompressorHybrid(double minPressure, double maxPressure);

+  /**
+   * If supported by the device, returns the raw voltage of the specified analog input channel.
+   *
+   * <p>This function is only supported by the REV PH. On CTRE PCM, this will return 0.
+   *
+   * @param channel The analog input channel to read voltage from.
+   * @return The voltage of the specified analog input channel.
+   */
  double getAnalogVoltage(int channel);

+  /**
+   * If supported by the device, returns the pressure (in PSI) read by an analog pressure sensor on
+   * the specified analog input channel.
+   *
+   * <p>This function is only supported by the REV PH. On CTRE PCM, this will return 0.
+   *
+   * @param channel The analog input channel to read pressure from.
+   * @return The pressure (in PSI) read by an analog pressure sensor on the specified analog input
+   *     channel.
+   */
  double getPressure(int channel);

+  /**
+   * Returns the active compressor configuration.
+   *
+   * @return The active compressor configuration.
+   */
  CompressorConfigType getCompressorConfigType();

  /**
@@ -111,15 +199,15 @@ public interface PneumaticsBase extends AutoCloseable {
  /**
   * Check to see if the masked solenoids can be reserved, and if not reserve them.
   *
-   * @param mask The solenoid mask to reserve
-   * @return 0 if successful, mask of solenoids that couldn't be allocated otherwise
+   * @param mask The bitmask of solenoids to reserve
+   * @return 0 if successful; mask of solenoids that couldn't be allocated otherwise
   */
  int checkAndReserveSolenoids(int mask);

  /**
   * Unreserve the masked solenoids.
   *
-   * @param mask The solenoid mask to unreserve
+   * @param mask The bitmask of solenoids to unreserve
   */
  void unreserveSolenoids(int mask);

--- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/PneumaticsControlModule.java
+++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/PneumaticsControlModule.java
@@ -66,7 +66,7 @@ public class PneumaticsControlModule implements PneumaticsBase {
  private final DataStore m_dataStore;
  private final int m_handle;

-  /** Constructs a PneumaticsControlModule with the default id (0). */
+  /** Constructs a PneumaticsControlModule with the default ID (0). */
  public PneumaticsControlModule() {
    this(SensorUtil.getDefaultCTREPCMModule());
  }
@@ -101,26 +101,67 @@ public class PneumaticsControlModule implements PneumaticsBase {
    return CTREPCMJNI.getCompressorCurrent(m_handle);
  }

+  /**
+   * Return whether the compressor current is currently too high.
+   *
+   * @return True if the compressor current is too high, otherwise false.
+   * @see #getCompressorCurrentTooHighStickyFault()
+   */
  public boolean getCompressorCurrentTooHighFault() {
    return CTREPCMJNI.getCompressorCurrentTooHighFault(m_handle);
  }

+  /**
+   * Returns whether the compressor current has been too high since sticky faults were last cleared.
+   * This fault is persistent and can be cleared by {@link #clearAllStickyFaults()}
+   *
+   * @return True if the compressor current has been too high since sticky faults were last cleared.
+   * @see #getCompressorCurrentTooHighFault()
+   */
  public boolean getCompressorCurrentTooHighStickyFault() {
    return CTREPCMJNI.getCompressorCurrentTooHighStickyFault(m_handle);
  }

+  /**
+   * Returns whether the compressor is currently shorted.
+   *
+   * @return True if the compressor is currently shorted, otherwise false.
+   * @see #getCompressorShortedStickyFault()
+   */
  public boolean getCompressorShortedFault() {
    return CTREPCMJNI.getCompressorShortedFault(m_handle);
  }

+  /**
+   * Returns whether the compressor has been shorted since sticky faults were last cleared. This
+   * fault is persistent and can be cleared by {@link #clearAllStickyFaults()}
+   *
+   * @return True if the compressor has been shorted since sticky faults were last cleared,
+   *     otherwise false.
+   * @see #getCompressorShortedFault()
+   */
  public boolean getCompressorShortedStickyFault() {
    return CTREPCMJNI.getCompressorShortedStickyFault(m_handle);
  }

+  /**
+   * Returns whether the compressor is currently disconnected.
+   *
+   * @return True if compressor is currently disconnected, otherwise false.
+   * @see #getCompressorNotConnectedStickyFault()
+   */
  public boolean getCompressorNotConnectedFault() {
    return CTREPCMJNI.getCompressorNotConnectedFault(m_handle);
  }

+  /**
+   * Returns whether the compressor has been disconnected since sticky faults were last cleared.
+   * This fault is persistent and can be cleared by {@link #clearAllStickyFaults()}
+   *
+   * @return True if the compressor has been disconnected since sticky faults were last cleared,
+   *     otherwise false.
+   * @see #getCompressorNotConnectedFault()
+   */
  public boolean getCompressorNotConnectedStickyFault() {
    return CTREPCMJNI.getCompressorNotConnectedStickyFault(m_handle);
  }
@@ -153,6 +194,7 @@ public class PneumaticsControlModule implements PneumaticsBase {
    return CTREPCMJNI.getSolenoidVoltageStickyFault(m_handle);
  }

+  /** Clears all sticky faults on this device. */
  public void clearAllStickyFaults() {
    CTREPCMJNI.clearAllStickyFaults(m_handle);
  }
@@ -224,6 +266,10 @@ public class PneumaticsControlModule implements PneumaticsBase {
    }
  }

+  /**
+   * Disables the compressor. The compressor will not turn on until {@link
+   * #enableCompressorDigital()} is called.
+   */
  @Override
  public void disableCompressor() {
    CTREPCMJNI.setClosedLoopControl(m_handle, false);
@@ -234,11 +280,25 @@ public class PneumaticsControlModule implements PneumaticsBase {
    CTREPCMJNI.setClosedLoopControl(m_handle, true);
  }

+  /**
+   * Enables the compressor in digital mode. Analog mode is unsupported by the CTRE PCM.
+   *
+   * @param minPressure Unsupported.
+   * @param maxPressure Unsupported.
+   * @see #enableCompressorDigital()
+   */
  @Override
  public void enableCompressorAnalog(double minPressure, double maxPressure) {
    CTREPCMJNI.setClosedLoopControl(m_handle, false);
  }

+  /**
+   * Enables the compressor in digital mode. Hybrid mode is unsupported by the CTRE PCM.
+   *
+   * @param minPressure Unsupported.
+   * @param maxPressure Unsupported.
+   * @see #enableCompressorDigital()
+   */
  @Override
  public void enableCompressorHybrid(double minPressure, double maxPressure) {
    CTREPCMJNI.setClosedLoopControl(m_handle, false);
@@ -251,11 +311,23 @@ public class PneumaticsControlModule implements PneumaticsBase {
        : CompressorConfigType.Disabled;
  }

+  /**
+   * Unsupported by the CTRE PCM.
+   *
+   * @param channel Unsupported.
+   * @return 0
+   */
  @Override
  public double getAnalogVoltage(int channel) {
    return 0;
  }

+  /**
+   * Unsupported by the CTRE PCM.
+   *
+   * @param channel Unsupported.
+   * @return 0
+   */
  @Override
  public double getPressure(int channel) {
    return 0;