io.github.robolib.module.sensor

Class Encoder

java.lang.Object

io.github.robolib.module.sensor.CounterBase

io.github.robolib.module.sensor.Encoder

All Implemented Interfaces:

CounterSource, PIDSource, RateSource, Module, SensorModule

public class Encoder
extends CounterBase
implements SensorModule, PIDSource, RateSource

Class to read quad 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.

Author:

noriah

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Encoder.IndexingType The different types of indexing available

Nested classes/interfaces inherited from class io.github.robolib.module.sensor.CounterBase

CounterBase.EncodingType

Nested classes/interfaces inherited from interface io.github.robolib.identifier.PIDSource

PIDSource.PIDSourceType

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	m_allocatedA
private boolean	m_allocatedB
private boolean	m_allocatedI
protected DigitalIO	m_aSource The a source
protected DigitalIO	m_bSource The b source
private Counter	m_counter
private double	m_distancePerPulse
private java.nio.ByteBuffer	m_encoder
private int	m_encodingScale
private CounterBase.EncodingType	m_encodingType
protected DigitalIO	m_indexSource The index source
private PIDSource.PIDSourceType	m_pidSType

Fields inherited from class io.github.robolib.module.sensor.CounterBase

m_index

Constructor Summary

Constructors

Modifier	Constructor and Description
	Encoder(DigitalIO.DigitalChannel aChannel, DigitalIO.DigitalChannel bChannel) Encoder constructor.
	Encoder(DigitalIO.DigitalChannel aChannel, DigitalIO.DigitalChannel bChannel, boolean reverseDirection) Encoder constructor.
	Encoder(DigitalIO.DigitalChannel aChannel, DigitalIO.DigitalChannel bChannel, boolean reverseDirection, CounterBase.EncodingType eType) Encoder constructor.
	Encoder(DigitalIO.DigitalChannel aChannel, DigitalIO.DigitalChannel bChannel, DigitalIO.DigitalChannel iChannel) Encoder constructor.
	Encoder(DigitalIO.DigitalChannel aChannel, DigitalIO.DigitalChannel bChannel, DigitalIO.DigitalChannel iChannel, boolean reverseDirection) Encoder constructor.
	Encoder(DigitalIO aSource, DigitalIO bSource) Encoder constructor.
	Encoder(DigitalIO aSource, DigitalIO bSource, boolean reverseDirection) Encoder constructor.
	Encoder(DigitalIO aSource, DigitalIO bSource, boolean reverseDirection, CounterBase.EncodingType eType) Encoder constructor.
	Encoder(DigitalIO aSource, DigitalIO bSource, DigitalIO iSource) Encoder constructor.
	Encoder(DigitalIO aSource, DigitalIO bSource, DigitalIO iSource, boolean reverseDirection) Encoder constructor.
private	Encoder(DigitalIO aSource, DigitalIO bSource, DigitalIO iSource, boolean reverseDirection, CounterBase.EncodingType eType) Encoder constructor.

Method Summary

Modifier and Type	Method and Description
double	decodingScaleFactor() The scale needed to convert a raw counter value into a number of encoder pulses.
void	disableModule() Disable the module
void	enableModule() Enable the module
void	free()
int	get() Gets the current count.
int	getCount() Gets the current count.
boolean	getDirection() The last direction the encoder value changed.
double	getDistance() Get the distance the robot has driven since the last reset.
int	getEncodingScale()
boolean	getModuleEnabled()
double	getPeriod() Returns the period of the most recent pulse.
double	getRate() Get the current rate of the encoder.
int	getRaw() Gets the raw value from the encoder.
int	getSamplesPerAverage() 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.
double	pidGet()
void	reset() Reset the Encoder distance to zero.
void	setDistancePerPulse(double distance) Set the distance per pulse for this encoder.
void	setIndexSource(DigitalIO.DigitalChannel channel) Set the index source for the encoder.
void	setIndexSource(DigitalIO.DigitalChannel channel, Encoder.IndexingType iType) Set the index source for the encoder.
void	setIndexSource(DigitalIO source) Set the index source for the encoder.
void	setIndexSource(DigitalIO source, Encoder.IndexingType iType) 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	setPIDSourceType(PIDSource.PIDSourceType sType) Set which parameter of the encoder you are using as a process control variable.
void	setReverseDirection(boolean reverse) Set the direction sensing for this encoder.
void	setSamplesPerAverage(int samples) Set the Samples to Average which specifies the number of samples of the timer to average when calculating the period.

Methods inherited from class io.github.robolib.module.sensor.CounterBase

getFPGAIndex

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_aSource

protected DigitalIO m_aSource

The a source

m_bSource

protected DigitalIO m_bSource

The b source

m_indexSource

protected DigitalIO m_indexSource

The index source

m_encoder

private java.nio.ByteBuffer m_encoder

m_distancePerPulse

private double m_distancePerPulse

m_counter

private Counter m_counter

m_encodingType

private CounterBase.EncodingType m_encodingType

m_encodingScale

private int m_encodingScale

m_allocatedA

private boolean m_allocatedA

m_allocatedB

private boolean m_allocatedB

m_allocatedI

private boolean m_allocatedI

m_pidSType

private PIDSource.PIDSourceType m_pidSType

Constructor Detail

Encoder

public Encoder(DigitalIO.DigitalChannel aChannel,
               DigitalIO.DigitalChannel bChannel)

Encoder constructor. Construct a Encoder given a and b channels. The encoder will start counting immediately.

Parameters:

aChannel - The a channel DigitalIO.DigitalChannel.

bChannel - The b channel DigitalIO.DigitalChannel.

Encoder

public Encoder(DigitalIO aSource,
               DigitalIO bSource)

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:

aSource - The source that should be used for the a channel.

bSource - the source that should be used for the b channel.

Encoder

public Encoder(DigitalIO.DigitalChannel aChannel,
               DigitalIO.DigitalChannel bChannel,
               boolean reverseDirection)

Encoder constructor. Construct a Encoder given a and b channels. The encoder will start counting immediately.

Parameters:

aChannel - The a channel DigitalIO.DigitalChannel.

bChannel - The b channel DigitalIO.DigitalChannel.

reverseDirection - represents the orientation of the encoder and inverts the output values if necessary so forward represents positive values.

Encoder

public Encoder(DigitalIO aSource,
               DigitalIO bSource,
               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:

aSource - The source that should be used for the a channel.

bSource - 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(DigitalIO.DigitalChannel aChannel,
               DigitalIO.DigitalChannel bChannel,
               DigitalIO.DigitalChannel iChannel)

Encoder constructor. Construct a Encoder given a and b channels. Using an index pulse forces 4x encoding The encoder will start counting immediately.

Parameters:

aChannel - The a channel DigitalIO.DigitalChannel.

bChannel - The b channel DigitalIO.DigitalChannel.

iChannel - The index channel DigitalIO.DigitalChannel.

Encoder

public Encoder(DigitalIO aSource,
               DigitalIO bSource,
               DigitalIO iSource)

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:

aSource - The source that should be used for the a channel.

bSource - the source that should be used for the b channel.

iSource - the source that should be used for the index channel.

Encoder

public Encoder(DigitalIO.DigitalChannel aChannel,
               DigitalIO.DigitalChannel bChannel,
               boolean reverseDirection,
               CounterBase.EncodingType eType)

Encoder constructor. Construct a Encoder given a and b channels. The encoder will start counting immediately.

Parameters:

aChannel - The a channel DigitalIO.DigitalChannel.

bChannel - The b channel DigitalIO.DigitalChannel.

reverseDirection - represents the orientation of the encoder and inverts the output values if necessary so forward represents positive values.

eType - 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.

Encoder

public Encoder(DigitalIO aSource,
               DigitalIO bSource,
               boolean reverseDirection,
               CounterBase.EncodingType eType)

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:

aSource - The source that should be used for the a channel.

bSource - 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.

eType - 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.

Encoder

public Encoder(DigitalIO.DigitalChannel aChannel,
               DigitalIO.DigitalChannel bChannel,
               DigitalIO.DigitalChannel iChannel,
               boolean reverseDirection)

Encoder constructor. Construct a Encoder given a and b channels. Using an index pulse forces 4x encoding The encoder will start counting immediately.

Parameters:

aChannel - The a channel DigitalIO.DigitalChannel.

bChannel - The b channel DigitalIO.DigitalChannel.

iChannel - The index channel DigitalIO.DigitalChannel.

reverseDirection - represents the orientation of the encoder and inverts the output values if necessary so forward represents positive values.

Encoder

public Encoder(DigitalIO aSource,
               DigitalIO bSource,
               DigitalIO iSource,
               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:

aSource - The source that should be used for the a channel.

bSource - the source that should be used for the b channel.

iSource - 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

private Encoder(DigitalIO aSource,
                DigitalIO bSource,
                DigitalIO iSource,
                boolean reverseDirection,
                CounterBase.EncodingType eType)

Encoder constructor. The encoder will start counting immediately.

Parameters:

aSource - The source that should be used for the a channel.

bSource - the source that should be used for the b channel.

iSource - 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.

eType - 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.

Method Detail

getEncodingScale

public int getEncodingScale()

Returns:

the encoding scale factor 1x, 2x, or 4x, per the requested encodingType. Used to divide raw edge counts down to spec'd counts.

free

public void free()

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.

Overrides:

get in class CounterBase

Returns:

Current count from the Encoder adjusted for the 1x, 2x, or 4x scale factor.

getCount

public int getCount()

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

Specified by:

getCount in interface CounterSource

Specified by:

getCount in class CounterBase

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 interface CounterSource

Specified by:

reset in class CounterBase

getPeriod

public double getPeriod()

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.

Specified by:

getPeriod in class CounterBase

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 class CounterBase

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 class CounterBase

Returns:

True if the encoder is considered stopped.

getDirection

public boolean getDirection()

The last direction the encoder value changed.

Specified by:

getDirection in class CounterBase

Returns:

The last direction the encoder value changed.

decodingScaleFactor

public double decodingScaleFactor()

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

getDistance

public double getDistance()

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().

getRate

public double getRate()

Get the current rate of the encoder. Units are distance per second as scaled by the value from setDistancePerPulse().

Specified by:

getRate in interface RateSource

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 distance)

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:

distance - The scale factor that will be used to convert pulses to useful units.

setReverseDirection

public void setReverseDirection(boolean reverse)

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:

reverse - true if the encoder direction should be reversed

setSamplesPerAverage

public void setSamplesPerAverage(int samples)

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:

samples - The number of samples to average from 1 to 127.

getSamplesPerAverage

public int getSamplesPerAverage()

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)

setPIDSourceType

public void setPIDSourceType(PIDSource.PIDSourceType sType)

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

Parameters:

sType - An enum to select the parameter.

pidGet

public double pidGet()

Specified by:

pidGet in interface PIDSource

setIndexSource

public void setIndexSource(DigitalIO.DigitalChannel channel,
                           Encoder.IndexingType iType)

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

Parameters:

channel - A DigitalIO.DigitalChannel to set as the encoder index

iType - The state that will cause the encoder to reset

setIndexSource

public void setIndexSource(DigitalIO source,
                           Encoder.IndexingType iType)

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 index

iType - The state that will cause the encoder to reset

setIndexSource

public void setIndexSource(DigitalIO.DigitalChannel channel)

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

Parameters:

channel - A DigitalIO.DigitalChannel to set as the encoder index

setIndexSource

public void setIndexSource(DigitalIO 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

enableModule

public void enableModule()

Enable the module

Specified by:

enableModule in interface Module

disableModule

public void disableModule()

Disable the module

Specified by:

disableModule in interface Module

getModuleEnabled

public boolean getModuleEnabled()

Specified by:

getModuleEnabled in interface Module