Class Encoder
- java.lang.Object
-
- edu.wpi.first.wpilibj.Encoder
-
- All Implemented Interfaces:
Sendable
,CounterBase
,AutoCloseable
- Direct Known Subclasses:
PIDEncoder
public class Encoder extends Object implements CounterBase, Sendable, AutoCloseable
Class to read quadrature encoders.Quadrature encoders are devices that count shaft rotation and can sense direction. The output of the Encoder class is an integer that can count either up or down, and can go negative for reverse direction counting. When creating Encoders, a direction can be supplied that inverts the sense of the output to make code more readable if the encoder is mounted such that forward movement generates negative values. Quadrature encoders have two digital outputs, an A Channel and a B Channel, that are out of phase with each other for direction sensing.
All encoders will immediately start counting - reset() them if you need them to be zeroed before use.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Encoder.IndexingType
-
Nested classes/interfaces inherited from interface edu.wpi.first.wpilibj.CounterBase
CounterBase.EncodingType
-
-
Field Summary
Fields Modifier and Type Field Description protected DigitalSource
m_aSource
The a source.protected DigitalSource
m_bSource
The b source.protected DigitalSource
m_indexSource
The index source.
-
Constructor Summary
Constructors Constructor Description Encoder(int channelA, int channelB)
Encoder constructor.Encoder(int channelA, int channelB, boolean reverseDirection)
Encoder constructor.Encoder(int channelA, int channelB, boolean reverseDirection, CounterBase.EncodingType encodingType)
Encoder constructor.Encoder(int channelA, int channelB, int indexChannel)
Encoder constructor.Encoder(int channelA, int channelB, int indexChannel, boolean reverseDirection)
Encoder constructor.Encoder(DigitalSource sourceA, DigitalSource sourceB)
Encoder constructor.Encoder(DigitalSource sourceA, DigitalSource sourceB, boolean reverseDirection)
Encoder constructor.Encoder(DigitalSource sourceA, DigitalSource sourceB, boolean reverseDirection, CounterBase.EncodingType encodingType)
Encoder constructor.Encoder(DigitalSource sourceA, DigitalSource sourceB, DigitalSource indexSource)
Encoder constructor.Encoder(DigitalSource sourceA, DigitalSource sourceB, DigitalSource indexSource, boolean reverseDirection)
Encoder constructor.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
close()
int
get()
Gets the current count.double
getDecodingScaleFactor()
Gets the decoding scale factor for scaling raw values to full counts.boolean
getDirection()
The last direction the encoder value changed.double
getDistance()
Get the distance the robot has driven since the last reset as scaled by the value fromsetDistancePerPulse(double)
.double
getDistancePerPulse()
Get the distance per pulse for this encoder.int
getEncodingScale()
Used to divide raw edge counts down to spec'd counts.int
getFPGAIndex()
Get the FPGA index of the encoder.double
getPeriod()
Deprecated.Use getRate() in favor of this method.double
getRate()
Get the current rate of the encoder.int
getRaw()
Gets the raw value from the encoder.int
getSamplesToAverage()
Get the Samples to Average which specifies the number of samples of the timer to average when calculating the period.boolean
getStopped()
Determine if the encoder is stopped.void
initSendable(SendableBuilder builder)
Initializes thisSendable
object.void
reset()
Reset the Encoder distance to zero.void
setDistancePerPulse(double distancePerPulse)
Set the distance per pulse for this encoder.void
setIndexSource(int channel)
Set the index source for the encoder.void
setIndexSource(int channel, Encoder.IndexingType type)
Set the index source for the encoder.void
setIndexSource(DigitalSource source)
Set the index source for the encoder.void
setIndexSource(DigitalSource source, Encoder.IndexingType type)
Set the index source for the encoder.void
setMaxPeriod(double maxPeriod)
Sets the maximum period for stopped detection.void
setMinRate(double minRate)
Set the minimum rate of the device before the hardware reports it stopped.void
setReverseDirection(boolean reverseDirection)
Set the direction sensing for this encoder.void
setSamplesToAverage(int samplesToAverage)
Set the Samples to Average which specifies the number of samples of the timer to average when calculating the period.void
setSimDevice(SimDevice device)
Indicates this input is used by a simulated device.
-
-
-
Field Detail
-
m_aSource
protected DigitalSource m_aSource
The a source.
-
m_bSource
protected DigitalSource m_bSource
The b source.
-
m_indexSource
protected DigitalSource m_indexSource
The index source.
-
-
Constructor Detail
-
Encoder
public Encoder(int channelA, int channelB, boolean reverseDirection)
Encoder constructor. Construct a Encoder given a and b channels.The encoder will start counting immediately.
- Parameters:
channelA
- The a channel DIO channel. 0-9 are on-board, 10-25 are on the MXP portchannelB
- The b channel DIO channel. 0-9 are on-board, 10-25 are on the MXP portreverseDirection
- represents the orientation of the encoder and inverts the output values if necessary so forward represents positive values.
-
Encoder
public Encoder(int channelA, int channelB)
Encoder constructor. Construct a Encoder given a and b channels.The encoder will start counting immediately.
- Parameters:
channelA
- The a channel digital input channel.channelB
- The b channel digital input channel.
-
Encoder
public Encoder(int channelA, int channelB, boolean reverseDirection, CounterBase.EncodingType encodingType)
Encoder constructor. Construct a Encoder given a and b channels.The encoder will start counting immediately.
- Parameters:
channelA
- The a channel digital input channel.channelB
- The b channel digital input channel.reverseDirection
- represents the orientation of the encoder and inverts the output values if necessary so forward represents positive values.encodingType
- either k1X, k2X, or k4X to indicate 1X, 2X or 4X decoding. If 4X is selected, then an encoder FPGA object is used and the returned counts will be 4x the encoder spec'd value since all rising and falling edges are counted. If 1X or 2X are selected then a m_counter object will be used and the returned value will either exactly match the spec'd count or be double (2x) the spec'd count.
-
Encoder
public Encoder(int channelA, int channelB, int indexChannel, boolean reverseDirection)
Encoder constructor. Construct a Encoder given a and b channels. Using an index pulse forces 4x encodingThe encoder will start counting immediately.
- Parameters:
channelA
- The a channel digital input channel.channelB
- The b channel digital input channel.indexChannel
- The index channel digital input channel.reverseDirection
- represents the orientation of the encoder and inverts the output values if necessary so forward represents positive values.
-
Encoder
public Encoder(int channelA, int channelB, int indexChannel)
Encoder constructor. Construct a Encoder given a and b channels. Using an index pulse forces 4x encodingThe encoder will start counting immediately.
- Parameters:
channelA
- The a channel digital input channel.channelB
- The b channel digital input channel.indexChannel
- The index channel digital input channel.
-
Encoder
public Encoder(DigitalSource sourceA, DigitalSource sourceB, boolean reverseDirection)
Encoder constructor. Construct a Encoder given a and b channels as digital inputs. This is used in the case where the digital inputs are shared. The Encoder class will not allocate the digital inputs and assume that they already are counted.The encoder will start counting immediately.
- Parameters:
sourceA
- The source that should be used for the a channel.sourceB
- the source that should be used for the b channel.reverseDirection
- represents the orientation of the encoder and inverts the output values if necessary so forward represents positive values.
-
Encoder
public Encoder(DigitalSource sourceA, DigitalSource sourceB)
Encoder constructor. Construct a Encoder given a and b channels as digital inputs. This is used in the case where the digital inputs are shared. The Encoder class will not allocate the digital inputs and assume that they already are counted.The encoder will start counting immediately.
- Parameters:
sourceA
- The source that should be used for the a channel.sourceB
- the source that should be used for the b channel.
-
Encoder
public Encoder(DigitalSource sourceA, DigitalSource sourceB, boolean reverseDirection, CounterBase.EncodingType encodingType)
Encoder constructor. Construct a Encoder given a and b channels as digital inputs. This is used in the case where the digital inputs are shared. The Encoder class will not allocate the digital inputs and assume that they already are counted.The encoder will start counting immediately.
- Parameters:
sourceA
- The source that should be used for the a channel.sourceB
- the source that should be used for the b channel.reverseDirection
- represents the orientation of the encoder and inverts the output values if necessary so forward represents positive values.encodingType
- either k1X, k2X, or k4X to indicate 1X, 2X or 4X decoding. If 4X is selected, then an encoder FPGA object is used and the returned counts will be 4x the encoder spec'd value since all rising and falling edges are counted. If 1X or 2X are selected then a m_counter object will be used and the returned value will either exactly match the spec'd count or be double (2x) the spec'd count.
-
Encoder
public Encoder(DigitalSource sourceA, DigitalSource sourceB, DigitalSource indexSource, boolean reverseDirection)
Encoder constructor. Construct a Encoder given a, b and index channels as digital inputs. This is used in the case where the digital inputs are shared. The Encoder class will not allocate the digital inputs and assume that they already are counted.The encoder will start counting immediately.
- Parameters:
sourceA
- The source that should be used for the a channel.sourceB
- the source that should be used for the b channel.indexSource
- the source that should be used for the index channel.reverseDirection
- represents the orientation of the encoder and inverts the output values if necessary so forward represents positive values.
-
Encoder
public Encoder(DigitalSource sourceA, DigitalSource sourceB, DigitalSource indexSource)
Encoder constructor. Construct a Encoder given a, b and index channels as digital inputs. This is used in the case where the digital inputs are shared. The Encoder class will not allocate the digital inputs and assume that they already are counted.The encoder will start counting immediately.
- Parameters:
sourceA
- The source that should be used for the a channel.sourceB
- the source that should be used for the b channel.indexSource
- the source that should be used for the index channel.
-
-
Method Detail
-
getFPGAIndex
public int getFPGAIndex()
Get the FPGA index of the encoder.- Returns:
- The Encoder's FPGA index.
-
getEncodingScale
public int getEncodingScale()
Used to divide raw edge counts down to spec'd counts.- Returns:
- The encoding scale factor 1x, 2x, or 4x, per the requested encoding type.
-
close
public void close()
- Specified by:
close
in interfaceAutoCloseable
-
getRaw
public int getRaw()
Gets the raw value from the encoder. The raw value is the actual count unscaled by the 1x, 2x, or 4x scale factor.- Returns:
- Current raw count from the encoder
-
get
public int get()
Gets the current count. Returns the current count on the Encoder. This method compensates for the decoding type.- Specified by:
get
in interfaceCounterBase
- Returns:
- Current count from the Encoder adjusted for the 1x, 2x, or 4x scale factor.
-
reset
public void reset()
Reset the Encoder distance to zero. Resets the current count to zero on the encoder.- Specified by:
reset
in interfaceCounterBase
-
getPeriod
@Deprecated public double getPeriod()
Deprecated.Use getRate() in favor of this method.Returns the period of the most recent pulse. Returns the period of the most recent Encoder pulse in seconds. This method compensates for the decoding type.Warning: This returns unscaled periods. Use getRate() for rates that are scaled using the value from setDistancePerPulse().
- Specified by:
getPeriod
in interfaceCounterBase
- Returns:
- Period in seconds of the most recent pulse.
-
setMaxPeriod
public void setMaxPeriod(double maxPeriod)
Sets the maximum period for stopped detection. Sets the value that represents the maximum period of the Encoder before it will assume that the attached device is stopped. This timeout allows users to determine if the wheels or other shaft has stopped rotating. This method compensates for the decoding type.- Specified by:
setMaxPeriod
in interfaceCounterBase
- Parameters:
maxPeriod
- The maximum time between rising and falling edges before the FPGA will report the device stopped. This is expressed in seconds.
-
getStopped
public boolean getStopped()
Determine if the encoder is stopped. Using the MaxPeriod value, a boolean is returned that is true if the encoder is considered stopped and false if it is still moving. A stopped encoder is one where the most recent pulse width exceeds the MaxPeriod.- Specified by:
getStopped
in interfaceCounterBase
- Returns:
- True if the encoder is considered stopped.
-
getDirection
public boolean getDirection()
The last direction the encoder value changed.- Specified by:
getDirection
in interfaceCounterBase
- Returns:
- The last direction the encoder value changed.
-
getDistance
public double getDistance()
Get the distance the robot has driven since the last reset as scaled by the value fromsetDistancePerPulse(double)
.- Returns:
- The distance driven since the last reset
-
getRate
public double getRate()
Get the current rate of the encoder. Units are distance per second as scaled by the value from setDistancePerPulse().- Returns:
- The current rate of the encoder.
-
setMinRate
public void setMinRate(double minRate)
Set the minimum rate of the device before the hardware reports it stopped.- Parameters:
minRate
- The minimum rate. The units are in distance per second as scaled by the value from setDistancePerPulse().
-
setDistancePerPulse
public void setDistancePerPulse(double distancePerPulse)
Set the distance per pulse for this encoder. This sets the multiplier used to determine the distance driven based on the count value from the encoder. Do not include the decoding type in this scale. The library already compensates for the decoding type. Set this value based on the encoder's rated Pulses per Revolution and factor in gearing reductions following the encoder shaft. This distance can be in any units you like, linear or angular.- Parameters:
distancePerPulse
- The scale factor that will be used to convert pulses to useful units.
-
getDistancePerPulse
public double getDistancePerPulse()
Get the distance per pulse for this encoder.- Returns:
- The scale factor that will be used to convert pulses to useful units.
-
setReverseDirection
public void setReverseDirection(boolean reverseDirection)
Set the direction sensing for this encoder. This sets the direction sensing on the encoder so that it could count in the correct software direction regardless of the mounting.- Parameters:
reverseDirection
- true if the encoder direction should be reversed
-
setSamplesToAverage
public void setSamplesToAverage(int samplesToAverage)
Set the Samples to Average which specifies the number of samples of the timer to average when calculating the period. Perform averaging to account for mechanical imperfections or as oversampling to increase resolution.- Parameters:
samplesToAverage
- The number of samples to average from 1 to 127.
-
getSamplesToAverage
public int getSamplesToAverage()
Get the Samples to Average which specifies the number of samples of the timer to average when calculating the period. Perform averaging to account for mechanical imperfections or as oversampling to increase resolution.- Returns:
- SamplesToAverage The number of samples being averaged (from 1 to 127)
-
setIndexSource
public void setIndexSource(int channel)
Set the index source for the encoder. When this source is activated, the encoder count automatically resets.- Parameters:
channel
- A DIO channel to set as the encoder index
-
setIndexSource
public void setIndexSource(DigitalSource source)
Set the index source for the encoder. When this source is activated, the encoder count automatically resets.- Parameters:
source
- A digital source to set as the encoder index
-
setIndexSource
public void setIndexSource(int channel, Encoder.IndexingType type)
Set the index source for the encoder. When this source rises, the encoder count automatically resets.- Parameters:
channel
- A DIO channel to set as the encoder indextype
- The state that will cause the encoder to reset
-
setIndexSource
public void setIndexSource(DigitalSource source, Encoder.IndexingType type)
Set the index source for the encoder. When this source rises, the encoder count automatically resets.- Parameters:
source
- A digital source to set as the encoder indextype
- The state that will cause the encoder to reset
-
setSimDevice
public void setSimDevice(SimDevice device)
Indicates this input is used by a simulated device.- Parameters:
device
- simulated device handle
-
getDecodingScaleFactor
public double getDecodingScaleFactor()
Gets the decoding scale factor for scaling raw values to full counts.- Returns:
- decoding scale factor
-
initSendable
public void initSendable(SendableBuilder builder)
Description copied from interface:Sendable
Initializes thisSendable
object.- Specified by:
initSendable
in interfaceSendable
- Parameters:
builder
- sendable builder
-
-