diff --git a/hal/src/main/java/edu/wpi/first/hal/DutyCycleJNI.java b/hal/src/main/java/edu/wpi/first/hal/DutyCycleJNI.java index 6920b2970fb..5fabfe49bce 100644 --- a/hal/src/main/java/edu/wpi/first/hal/DutyCycleJNI.java +++ b/hal/src/main/java/edu/wpi/first/hal/DutyCycleJNI.java @@ -32,6 +32,9 @@ public class DutyCycleJNI extends JNIWrapper { /** * Get the frequency of the duty cycle signal. * + *

Warning: This will return inaccurate values for up to 2 seconds after the duty cycle + * input is initialized. + * * @param handle the duty cycle handle * @return frequency in Hertz * @see "HAL_GetDutyCycleFrequency" diff --git a/hal/src/main/native/include/hal/DutyCycle.h b/hal/src/main/native/include/hal/DutyCycle.h index d5e655b9cfe..4075877337d 100644 --- a/hal/src/main/native/include/hal/DutyCycle.h +++ b/hal/src/main/native/include/hal/DutyCycle.h @@ -51,6 +51,9 @@ void HAL_SetDutyCycleSimDevice(HAL_DutyCycleHandle handle, /** * Get the frequency of the duty cycle signal. * + * @warning This will return inaccurate values for up to 2 seconds after the + * duty cycle input is initialized. + * * @param[in] dutyCycleHandle the duty cycle handle * @param[out] status Error status variable. 0 on success. * @return frequency in Hertz diff --git a/wpilibc/src/main/native/include/frc/DutyCycle.h b/wpilibc/src/main/native/include/frc/DutyCycle.h index 96d783687f1..5f4965355cd 100644 --- a/wpilibc/src/main/native/include/frc/DutyCycle.h +++ b/wpilibc/src/main/native/include/frc/DutyCycle.h @@ -71,6 +71,9 @@ class DutyCycle : public wpi::Sendable, public wpi::SendableHelper { /** * Get the frequency of the duty cycle signal. * + * @warning This will return inaccurate values for up to 2 seconds after this + * duty cycle input is initialized. + * * @return frequency in Hertz */ int GetFrequency() const; diff --git a/wpilibc/src/main/native/include/frc/DutyCycleEncoder.h b/wpilibc/src/main/native/include/frc/DutyCycleEncoder.h index 7ee04c0d9a1..4f1606757ff 100644 --- a/wpilibc/src/main/native/include/frc/DutyCycleEncoder.h +++ b/wpilibc/src/main/native/include/frc/DutyCycleEncoder.h @@ -21,6 +21,12 @@ class DigitalSource; * Class for supporting duty cycle/PWM encoders, such as the US Digital MA3 with * PWM Output, the CTRE Mag Encoder, the Rev Hex Encoder, and the AM Mag * Encoder. + * + * @warning By default, position readings from Get() will be inaccurate for up + * to 2 seconds after this object is initialized. Setting the frequency of the + * encoder's output using {@link #setAssumedFrequency(double)} can be used to + * mitigate this, though users should verify the true frequency of the specific + * encoder in use as it can vary between devices. */ class DutyCycleEncoder : public wpi::Sendable, public wpi::SendableHelper { @@ -93,7 +99,7 @@ class DutyCycleEncoder : public wpi::Sendable, * * @param channel the channel to attach to * @param fullRange the value to report at maximum travel - * @param expectedZero the reading where you would expect a 0 from get() + * @param expectedZero the reading where you would expect a 0 from Get() */ DutyCycleEncoder(int channel, double fullRange, double expectedZero); @@ -102,7 +108,7 @@ class DutyCycleEncoder : public wpi::Sendable, * * @param dutyCycle the duty cycle to attach to * @param fullRange the value to report at maximum travel - * @param expectedZero the reading where you would expect a 0 from get() + * @param expectedZero the reading where you would expect a 0 from Get() */ DutyCycleEncoder(DutyCycle& dutyCycle, double fullRange, double expectedZero); @@ -111,7 +117,7 @@ class DutyCycleEncoder : public wpi::Sendable, * * @param dutyCycle the duty cycle to attach to * @param fullRange the value to report at maximum travel - * @param expectedZero the reading where you would expect a 0 from get() + * @param expectedZero the reading where you would expect a 0 from Get() */ DutyCycleEncoder(DutyCycle* dutyCycle, double fullRange, double expectedZero); @@ -120,7 +126,7 @@ class DutyCycleEncoder : public wpi::Sendable, * * @param dutyCycle the duty cycle to attach to * @param fullRange the value to report at maximum travel - * @param expectedZero the reading where you would expect a 0 from get() + * @param expectedZero the reading where you would expect a 0 from Get() */ DutyCycleEncoder(std::shared_ptr dutyCycle, double fullRange, double expectedZero); @@ -130,7 +136,7 @@ class DutyCycleEncoder : public wpi::Sendable, * * @param digitalSource the digital source to attach to * @param fullRange the value to report at maximum travel - * @param expectedZero the reading where you would expect a 0 from get() + * @param expectedZero the reading where you would expect a 0 from Get() */ DutyCycleEncoder(DigitalSource& digitalSource, double fullRange, double expectedZero); @@ -140,7 +146,7 @@ class DutyCycleEncoder : public wpi::Sendable, * * @param digitalSource the digital source to attach to * @param fullRange the value to report at maximum travel - * @param expectedZero the reading where you would expect a 0 from get() + * @param expectedZero the reading where you would expect a 0 from Get() */ DutyCycleEncoder(DigitalSource* digitalSource, double fullRange, double expectedZero); @@ -150,7 +156,7 @@ class DutyCycleEncoder : public wpi::Sendable, * * @param digitalSource the digital source to attach to * @param fullRange the value to report at maximum travel - * @param expectedZero the reading where you would expect a 0 from get() + * @param expectedZero the reading where you would expect a 0 from Get() */ DutyCycleEncoder(std::shared_ptr digitalSource, double fullRange, double expectedZero); @@ -163,6 +169,9 @@ class DutyCycleEncoder : public wpi::Sendable, /** * Get the frequency in Hz of the duty cycle signal from the encoder. * + * @warning This will return inaccurate values for up to 2 seconds after this + * encoder is initialized. + * * @return duty cycle frequency in Hz */ int GetFrequency() const; @@ -174,6 +183,9 @@ class DutyCycleEncoder : public wpi::Sendable, * By default, a value of 100 Hz is used as the threshold, and this value can * be changed with SetConnectedFrequencyThreshold. * + * @warning This will return inaccurate values for up to 2 seconds after this + * encoder is initialized. + * * @return true if the sensor is connected */ bool IsConnected() const; @@ -189,6 +201,9 @@ class DutyCycleEncoder : public wpi::Sendable, /** * Get the encoder value. * + * @warning This will return inaccurate values for up to 2 seconds after this + * encoder is initialized unless SetAssumedFrequency() is used. + * * @return the encoder value scaled by the full range input */ double Get() const; @@ -215,7 +230,8 @@ class DutyCycleEncoder : public wpi::Sendable, * input signal. This can result in both delayed readings and jumpy readings. * To solve this, you can pass the expected frequency of the sensor to this * function. This will use that frequency to compute the DutyCycle percentage, - * rather than the computed frequency. + * rather than the computed frequency. Users should verify the true frequency + * of the specific encoder in use as it can vary between devices. * * @param frequency the assumed frequency of the sensor */ diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/DutyCycle.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/DutyCycle.java index 8c26d55b80b..35d741acfe2 100644 --- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/DutyCycle.java +++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/DutyCycle.java @@ -56,6 +56,9 @@ public void close() { /** * Get the frequency of the duty cycle signal. * + *

Warning: This will return inaccurate values for up to 2 seconds after the duty cycle + * input is initialized. + * * @return frequency in Hertz */ public int getFrequency() { diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/DutyCycleEncoder.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/DutyCycleEncoder.java index 22cf1995c84..b390184a399 100644 --- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/DutyCycleEncoder.java +++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/DutyCycleEncoder.java @@ -15,6 +15,11 @@ /** * Class for supporting duty cycle/PWM encoders, such as the US Digital MA3 with PWM Output, the * CTRE Mag Encoder, the Rev Hex Encoder, and the AM Mag Encoder. + * + *

Warning: By default, position readings from {@link #get()} will be inaccurate for up to 2 + * seconds after this encoder is initialized. Setting the frequency of the encoder's output + * using {@link #setAssumedFrequency(double)} can be used to mitigate this, though users should + * verify the true frequency of the specific encoder in use as it can vary between devices. */ public class DutyCycleEncoder implements Sendable, AutoCloseable { private final DutyCycle m_dutyCycle; @@ -137,11 +142,12 @@ private double mapSensorRange(double pos) { } /** - * Get the encoder value since the last reset. + * Get the encoder value. * - *

This is reported in rotations since the last reset. + *

Warning: This will return inaccurate values for up to 2 seconds after this encoder is + * initialized unless {@link #setAssumedFrequency(double)} is used. * - * @return the encoder value in rotations + * @return the encoder value scaled by the full range input */ public double get() { if (m_simPosition != null) { @@ -191,6 +197,9 @@ public void setDutyCycleRange(double min, double max) { /** * Get the frequency in Hz of the duty cycle signal from the encoder. * + *

Warning: This will return inaccurate values for up to 2 seconds after this encoder is + * initialized. + * * @return duty cycle frequency in Hz */ public int getFrequency() { @@ -198,7 +207,8 @@ public int getFrequency() { } /** - * Get if the sensor is connected + * Get if the sensor is connected Warning: This will return inaccurate values for up to 2 + * seconds after the duty cycle input is initialized. * *

This uses the duty cycle frequency to determine if the sensor is connected. By default, a * value of 100 Hz is used as the threshold, and this value can be changed with {@link @@ -232,7 +242,8 @@ public void setConnectedFrequencyThreshold(int frequency) { *

By default, the DutyCycle engine has to compute the frequency of the input signal. This can * result in both delayed readings and jumpy readings. To solve this, you can pass the expected * frequency of the sensor to this function. This will use that frequency to compute the DutyCycle - * percentage, rather than the computed frequency. + * percentage, rather than the computed frequency. Users should verify the true frequency of the + * specific encoder in use as it can vary between devices. * * @param frequency the assumed frequency of the sensor */