SerialWombatQuadEnc Class Reference

A class that uses two Serial Wombat input pins to read quadrature encoder input. More...

#include <SerialWombatQuadEnc.h>

Inheritance diagram for SerialWombatQuadEnc:

Public Member Functions
	SerialWombatQuadEnc (SerialWombatChip &serialWombatChip)
	Constructor for the SerialWombatQuadEnc class. More...
void	begin (uint8_t pin, uint8_t secondPin, uint16_t debounce_mS=10, bool pullUpsEnabled=true, QE_READ_MODE_t readState=QE_ONBOTH_POLL)
	Initialization for SerialWombatQuadEnc that allows configuration of debounce time, pullUps and transition detection mode. More...
uint16_t	read ()
	Read the quadrature encoder position from the Serial Wombat chip. More...
uint16_t	read (uint16_t replacementValue)
	Read the quadrature encoder position from the Serial Wombat chip then set the position value. More...
void	write (uint16_t value)
	This function initializes the position of the encoder. More...
Public Member Functions inherited from SerialWombatPin
	SerialWombatPin (SerialWombatChip &serialWombatChip)
	Instantiates a Serial Wombat Pin. More...
	SerialWombatPin (SerialWombatChip &serialWombatChip, uint8_t pin)
	Instantiates a Serial Wombat Pin. More...
uint16_t	readPublicData ()
	Read the 16 Bit public data associated with this pin. More...
void	pinMode (uint8_t mode, bool pullDown=false, bool openDrain=false)
	Set pin to INPUT or OUTPUT, with options for pull Ups and open Drain settings. More...
void	digitalWrite (uint8_t val)
	Set output pin High or Low. More...
int	digitalRead ()
	Reads the state of the Pin. More...
uint16_t	writePublicData (uint16_t value)
	Write a 16 bit value to this pin. More...
uint8_t	pin ()
	Returns the current SW pin number. Used primarily for virtual calls by derived classes. More...
uint8_t	swPinModeNumber ()
	Returns the Mode number. Used primarily by derived classes to populate packet data. More...
int16_t	initPacketNoResponse (uint8_t packetNumber, uint8_t param0=0x55, uint8_t param1=0x55, uint8_t param2=0x55, uint8_t param3=0x55, uint8_t param4=0x55)
int16_t	initPacketNoResponse (uint8_t packetNumber, uint16_t param0=0x55, uint8_t param1=0x55, uint8_t param2=0x55, uint8_t param3=0x55)
int16_t	initPacketNoResponse (uint8_t packetNumber, uint16_t param0, uint16_t param1, uint8_t param2=0x55)
int16_t	disable ()
	Disables the pin mode (if applicable) More...

Additional Inherited Members
Protected Attributes inherited from SerialWombatPin
uint8_t	_pin = 255
SerialWombatChip &	_sw
uint8_t	_pinMode = 0

Detailed Description

A class that uses two Serial Wombat input pins to read quadrature encoder input.

The SerialWombatQuadEnc class configures two pins on the Serial Wombat chip to work together to read quadrature encoder inputs.

By offloading the reading of an encoder to the Serial Wombat chip, it makes it easy for the host to track multiple encoders at once. The host need only periodically retreive the net change in rotary encoder position from the Serial Wombat chip rather than monitoring for every signal change.

Video Tutorial:

https://youtu.be/_wO8cOada3w

An instance of the SerialWombatQuadEnc class should be declared for each encoder (2 pins) connected to the Serial Wombat chip.

The quadrature encoder is capable of running in either polled or interrupt/DMA driven modes.

Polled mode is recommended for manual inputs such as rotary encoder knobs. It polls at 1 kHz which is fast enough for most applications.

Interrupt driven mode on the Serial Wombat 4A/4B is capable of correctly decoding very fast signals. However, the signals need to be properly filtered in order to eliminate any bouncing.

DMA driven mode on the Serial Wombat 18AB samples at 57600 Hz rather than 1 kHz and can decode pulse inputs from rapidly spinning encoders, but using DMA mode consumes much more CPU throughtput on the Serial Wombat 18AB chip.

The SerialWombatQuadEnc can make use of the Serial Wombat chip's built in pull-up resistors to make connecting a rotary encoder knob very simple. Debouncing is available which prevents additional transitions from being measured for a specified number of mS after a transition.

Rotational direction measurement can be changed by switching the "pin" and "second pin" parameters in the begin call.

The reported position can be changed on low to high transitions of "pin", high to low transitions, or both transitions. This allows knobs that make and break connection on each click/detent and knobs that either make or break connection on each detent to report one change per detent to the host.

The default mode for simple initialization is to measure both, which will result in 2 increments per detent for encoders that make and break connection on each detent.

Warning

Care must be taken in interrupt mode on Serial Wombat 4A/4B chips when using this pinmode with high frequency ( > 5 kHz) signals or pins that may be left floating on the Serial Wombat 4A / 4B because the Serial Wombat uses an interrupt internally to capture transitions between state machine updates. Excessively frequent pin transitions may cause the interrupt handler to starve the main processing loop, impacting function of all pin modes and communications.

The Serial Wombat chip can be queried for overflow frames. If overflow frames are occuring, then the system is overloaded.

The Serial Wombat 4A and 4B chips can measure a maxium of 8 transitions per mS across all pulse input pins. More frequent transitions than this may result pin mode malfunction.

Constructor & Destructor Documentation

SerialWombatQuadEnc()

SerialWombatQuadEnc::SerialWombatQuadEnc ( SerialWombatChip &  serialWombatChip )

inline

Constructor for the SerialWombatQuadEnc class.

Parameters

serialWombatChip

The Serial Wombat chip running the quadrature encoder

Member Function Documentation

begin()

void SerialWombatQuadEnc::begin ( uint8_t  pin, uint8_t  secondPin, uint16_t  debounce_mS = 10, bool  pullUpsEnabled = true, QE_READ_MODE_t  readState = QE_ONBOTH_POLL  )

inline

Initialization for SerialWombatQuadEnc that allows configuration of debounce time, pullUps and transition detection mode.

Parameters

pin	The first pin to be used as a Quadrature Encoder input. All 4 pins on the SW4A/SW4B may be used. All 20 pins on the SW18AB chip may be used
secondPin	The second pin to be used as a Quadrature Encoder input. All I/O pins on Serial Wombat chip may be used, except the first specified pin.
debounce_mS	The number of mS after a transition is detected and increment occurs before another increment is allowed.
pullUpsEnabled	TRUE: both pins have weak pull ups enabled. FALSE: Neither pin has weak pull up enabled.
readState	QE_READ_MODE_t determine if Polling or Interrupt/DMA mode is used, and which transitions cause increments.

Position is initialized to 0.

read() [1/2]

uint16_t SerialWombatQuadEnc::read ( )

inline

Read the quadrature encoder position from the Serial Wombat chip.

Returns

a 16 bit unsigned value indicating position. Rolls from 0 to 65535 when decrementing below 0

read() [2/2]

uint16_t SerialWombatQuadEnc::read ( uint16_t  replacementValue )

inline

Read the quadrature encoder position from the Serial Wombat chip then set the position value.

Returns

a 16 bit unsigned value indicating position. Rolls from 0 to 65535 when decrementing below 0

Parameters

replacementValue

The 16 bit value to set the position to after read.

This method is useful when looking for relative change since last call. By setting the position to center (32768) after each read, the net postion change can easily be measured. This is conceptually simplier than using read() and adjusting for rollover between 65535 and 0.

write()

void SerialWombatQuadEnc::write ( uint16_t  value )

inline

This function initializes the position of the encoder.

Parameters

value

A starting value between 0 and 65535 for the encoder