Serial Wombat Arduino Library

Loading...
Searching...
No Matches
Public Member Functions | List of all members
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:
[legend]
Collaboration diagram for SerialWombatQuadEnc:
[legend]

## Public Member Functions
| SerialWombatQuadEnc (SerialWombatChip &serialWombatChip)
| Constructor for the SerialWombatQuadEnc class.
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.
uint16_t | read ()
| Read the quadrature encoder position from the Serial Wombat chip.
uint16_t | read (uint16_t replacementValue)
| Read the quadrature encoder position from the Serial Wombat chip then set the position value.
void | write (uint16_t value)
| This function initializes the position of the encoder.
Public Member Functions inherited from SerialWombatPin
| SerialWombatPin (SerialWombatChip &serialWombatChip)
| Instantiates a Serial Wombat Pin.
| SerialWombatPin (SerialWombatChip &serialWombatChip, uint8_t pin)
| Instantiates a Serial Wombat Pin.
uint16_t | readPublicData ()
| Read the 16 Bit public data associated with this pin.
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.
void | digitalWrite (uint8_t val)
| Set output pin High or Low.
int | digitalRead ()
| Reads the state of the Pin.
uint16_t | writePublicData (uint16_t value)
| Write a 16 bit value to this pin.
uint8_t | pin ()
| Returns the current SW pin number. Used primarily for virtual calls by derived classes.
uint8_t | swPinModeNumber ()
| Returns the Mode number. Used primarily by derived classes to populate packet data.
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)
int16_t | enablePullup (bool enabled)
| Enables the weak pull up on a pin. Implemented on SW18AB and SW8B only.
int16_t | enablePulldown (bool enabled)
| Enables the weak pull down on a pin. Implemented on SW18AB and SW8B only.
int16_t | enableOpenDrain (bool enabled)
| Enables open drain mode on a pin. Implemented on SW18AB and SW8B only.
int16_t | forceDMA (bool enabled)
| Forces use of DMA instead of hardware timing resources on SW18AB.
void | setPinNumberForTesting (uint8_t pin)
| A function designed for testing only. May have unpredictable results if used in real time. Not intended for general use.

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

Definition at line 104 of file SerialWombatQuadEnc.h.

## Constructor & Destructor Documentation

## ◆ SerialWombatQuadEnc()

SerialWombatQuadEnc::SerialWombatQuadEnc | ( | SerialWombatChip & | serialWombatChip | ) |
| inline

Constructor for the SerialWombatQuadEnc class.

Parameters

  serialWombatChip | The Serial Wombat chip running the quadrature encoder

Definition at line 112 of file SerialWombatQuadEnc.h.

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

Definition at line 127 of file SerialWombatQuadEnc.h.

## ◆ 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

Definition at line 141 of file SerialWombatQuadEnc.h.

## ◆ 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.

Definition at line 155 of file SerialWombatQuadEnc.h.

## ◆ 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

Definition at line 164 of file SerialWombatQuadEnc.h.