Encoder

class wpilib.Encoder(*args, **kwargs)[source]

Bases: wpilib.SensorBase

Reads from quadrature encoders.

Quadrature encoders are devices that count shaft rotation and can sense direction. The output of the QuadEncoder class is an integer that can count either up or down, and can go negative for reverse direction counting. When creating QuadEncoders, a direction is supplied that changes 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 to allow the FPGA to do direction sensing.

All encoders will immediately start counting - reset() them if you need them to be zeroed before use.

Instance variables:

  • aSource: The A phase of the quad encoder
  • bSource: The B phase of the quad encoder
  • indexSource: The index source (available on some encoders)

Encoder constructor. Construct a Encoder given a and b channels and optionally an index channel.

The encoder will start counting immediately.

The a, b, and optional index channel arguments may be either channel numbers or DigitalSource sources. There may also be a boolean reverseDirection, and an encodingType according to the following list.

  • aSource, bSource
  • aSource, bSource, reverseDirection
  • aSource, bSource, reverseDirection, encodingType
  • aSource, bSource, indexSource, reverseDirection
  • aSource, bSource, indexSource
  • aChannel, bChannel
  • aChannel, bChannel, reverseDirection
  • aChannel, bChannel, reverseDirection, encodingType
  • aChannel, bChannel, indexChannel, reverseDirection
  • aChannel, bChannel, indexChannel

For positional arguments, if the passed object has a getChannelForRouting function, it is assumed to be a DigitalSource.

Alternatively, sources and/or channels may be passed as keyword arguments. The behavior of specifying both a source and a number for the same channel is undefined, as is passing both a positional and a keyword argument for the same channel.

In addition, keyword parameters may be provided for reverseDirection and inputType.

Parameters:
  • aSource – The source that should be used for the a channel.
  • bSource – The source that should be used for the b channel.
  • indexSource – The source that should be used for the index channel.
  • aChannel – The digital input index that should be used for the a channel.
  • bChannel – The digital input index that should be used for the b channel.
  • indexChannel – The digital input index 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. Defaults to False if unspecified.
  • encodingType (Encoder.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 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. Defaults to k4X if unspecified.
class EncodingType

Bases: object

The number of edges for the counterbase to increment or decrement on

k1X = 0
k2X = 1
k4X = 2
class Encoder.IndexingType[source]

Bases: object

kResetOnFallingEdge = 2
kResetOnRisingEdge = 3
kResetWhileHigh = 0
kResetWhileLow = 1
class Encoder.PIDSourceType

Bases: object

A description for the type of output value to provide to a PIDController

kDisplacement = 0
kRate = 1
Encoder.decodingScaleFactor()[source]

The scale needed to convert a raw counter value into a number of encoder pulses.

Encoder.encoder
Encoder.free()[source]
Encoder.get()[source]

Gets the current count. Returns the current count on the Encoder. This method compensates for the decoding type.

Returns:Current count from the Encoder adjusted for the 1x, 2x, or 4x scale factor.
Encoder.getDirection()[source]

The last direction the encoder value changed.

Returns:The last direction the encoder value changed.
Encoder.getDistance()[source]

Get the distance the robot has driven since the last reset.

Returns:The distance driven since the last reset as scaled by the value from setDistancePerPulse().
Encoder.getEncodingScale()[source]
Returns:The encoding scale factor 1x, 2x, or 4x, per the requested encodingType. Used to divide raw edge counts down to spec’d counts.
Encoder.getFPGAIndex()[source]
Returns:The Encoder’s FPGA index
Encoder.getPIDSourceType()[source]
Encoder.getPeriod()[source]

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.

Deprecated since version Use: getRate() in favor of this method. This returns unscaled periods and getRate() scales using value from getDistancePerPulse().

Returns:Period in seconds of the most recent pulse.
Encoder.getRate()[source]

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.
Encoder.getRaw()[source]

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
Encoder.getSamplesToAverage()[source]

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:The number of samples being averaged (from 1 to 127)
Encoder.getStopped()[source]

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.

Returns:True if the encoder is considered stopped.
Encoder.pidGet()[source]

Implement the PIDSource interface.

Returns:The current value of the selected source parameter.
Encoder.reset()[source]

Reset the Encoder distance to zero. Resets the current count to zero on the encoder.

Encoder.setDistancePerPulse(distancePerPulse)[source]

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.
Encoder.setIndexSource(source, indexing_type=3)[source]

Set the index source for the encoder. When this source rises, the encoder count automatically resets.

Parameters:
  • source – Either an initialized DigitalSource or a DIO channel number
  • indexing_type – The state that will cause the encoder to reset
Type:

Either a DigitalInput or number

Type:

A value from wpilib.IndexingType

Encoder.setMaxPeriod(maxPeriod)[source]

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.

Parameters:maxPeriod – The maximum time between rising and falling edges before the FPGA will report the device stopped. This is expressed in seconds.
Encoder.setMinRate(minRate)[source]

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().
Encoder.setPIDSourceType(pidSource)[source]

Set which parameter of the encoder you are using as a process control variable. The encoder class supports the rate and distance parameters.

Parameters:pidSource – An enum to select the parameter.
Encoder.setReverseDirection(reverseDirection)[source]

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
Encoder.setSamplesToAverage(samplesToAverage)[source]

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.

TODO: Should this raise an exception, so that the user has to deal with giving an incorrect value?

Parameters:samplesToAverage – The number of samples to average from 1 to 127.