Serial Wombat Arduino Library

Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | List of all members
SerialWombat18CapTouch Class Reference

A class that controls a Cap Touch Pin on the Serial Wombat 18AB chip. More...

`#include <SerialWombat18CapTouch.h>`

Inheritance diagram for SerialWombat18CapTouch:
[legend]
Collaboration diagram for SerialWombat18CapTouch:
[legend]

## Public Member Functions
| SerialWombat18CapTouch (SerialWombatChip &serialWombat)
| Instantiate a SerialWombat18CapTouch class on a specified Serial Wombat Chip.
int16_t | begin (uint8_t pin, uint16_t chargeTime, uint16_t delay=10)
| Initialize the SerialWombat18CapTouch instance with a given charge Time in uS.
int16_t | makeDigital (uint16_t touchLimit, uint16_t noTouchLimit)
| Make a cap touch behave like a digital button.
int16_t | makeDigital (uint16_t touchLimit, uint16_t noTouchLimit, uint16_t touchValue, uint16_t noTouchValue, bool invert, uint16_t debounceCount)
| Make a cap touch behave like a digital button.
int16_t | makeAnalog ()
bool | digitalRead ()
| Returns the debounced state of the input.
uint16_t | readDurationInTrueState_mS ()
| return the number of mS that the debounced input has been in true state
uint16_t | readDurationInFalseState_mS ()
| return the number of mS that the debounced input has been in false state
bool | readTransitionsState (bool resetTransitionCounts=true)
| Queries the number of transistions that have occured on the debounced input.
uint8_t | pin ()
| Used for inheritance.
uint8_t | swPinModeNumber ()
| Used for ineheritance.
Public Member Functions inherited from SerialWombatAbstractButton
| SerialWombatAbstractButton ()
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.
Public Member Functions inherited from SerialWombatAbstractProcessedInput
| SerialWombatAbstractProcessedInput (SerialWombatChip &sw)
| Constructor for the SerialWombatAbstractScaledOutput Class.
int16_t | writeInverted (bool inverted)
| if enabled subtract the input value from 65535 before doing any other processing.
int16_t | writeFirstOrderFilteringConstant (uint16_t constant)
| Set a first order filtering constant to be applied to the signal Higher is heavier filtering.
int16_t | writeAveragingNumberOfSamples (uint16_t numberOfSamples)
| Set a number of samples to average for each update of the downstream signal.
int16_t | writeExcludeBelowAbove (uint16_t low, uint16_t high)
| Sets input value ranges which are discarded rather than processed.
int16_t | configureQueue (SerialWombatQueue *queue, Period period, bool queueHighByte=true, bool queueLowByte=true)
| Sets up the queueing feature for this pin mode. Queue must have been initialized prior to this queue.
int16_t | configureOutputValue (OutputValue outputValue)
| Configures whether the pin's public data value is averaged, filtered, or neither.
int16_t | writeTransformScaleRange (uint16_t min, uint16_t max)
| Scale incoming values to a range of 0 to 65535.
int16_t | writeTransformLinearMXB (int32_t m, int32_t b)
| Scale incoming values based on an mx+b linear equation.
int16_t | configureIntegrator (uint16_t negativeMaxIndex, uint16_t negativeMidIndex, uint16_t negativeDeadZone, uint16_t positiveDeadZone, uint16_t positiveMidIndex, uint16_t positiveMaxIndex, uint16_t midIncrement, uint16_t maxIncrement, uint16_t initialValue, uint8_t updateFrequencyMask=0)
| Sort incoming data into one of 5 ranges, and integrate based on linear interpolation in those ranges.
int16_t | writeProcessedInputEnable (bool enabled)
| Enables or disables all input processing functions If disabled, the raw input value is placed directly in the pin's 16 bit public data buffer.
uint16_t | readMinimum (bool resetAfterRead=false)
| Retreive the maximum public data output value since the last call with reset= true.
uint16_t | readMaximum (bool resetAfterRead=false)
| Retreive the minimum public data output value since the last call with reset= true.
uint16_t | readAverage ()
| Retreive the last completed averaged value.
uint16_t | readFiltered ()
| Retreive the filtered value.

## Public Attributes
uint16_t | transitions = 0
| Number of transitions returned by last call to readTransitionsState()
Public Attributes inherited from SerialWombatAbstractButton
uint16_t | transitions = 0
| Number of transitions returned by last call to readTransitionsState()

## Additional Inherited Members
Public Types inherited from SerialWombatAbstractProcessedInput
enum | Period { PERIOD_1mS = 0 , PERIOD_2mS = 1 , PERIOD_4mS = 2 , PERIOD_8mS = 3 , PERIOD_16mS = 4 , PERIOD_32mS = 5 , PERIOD_64mS = 6 , PERIOD_128mS = 7 , PERIOD_256mS = 8 , PERIOD_512mS = 9 , PERIOD_1024mS = 10 }
enum | OutputValue { RAW = 0 , FIRST_ORDER_FILTERED = 1 , AVERAGE = 2 }
enum | Transform { NONE = 0 , SCALE_RANGE = 1 , LINEAR_MXB = 2 }
Protected Attributes inherited from SerialWombatPin
uint8_t | _pin = 255
SerialWombatChip & | _sw
uint8_t | _pinMode = 0

## Detailed Description

A class that controls a Cap Touch Pin on the Serial Wombat 18AB chip.

This class allows a metalic plate with a thin insulating layer to be used as a capacitive touch surface. Items like a coin, PCB board, metal plate, etc can be connected directly to the pin and covered by a thin insulating layer. A finger touch can be detected by the change in capacitance caused by its presence.

The mode can output either analog or digital values back to the host and as public data to other pins. In analog mode the A/D reading at the end of a charge cycle is presented. This value gets smaller when a finger or item causes the capacitance of the sensor to increase. (Smaller A/D values when finger present, higher values when absent).

In digital mode the class is configured with a high and low limit which cause a digital change in hysteresis manner. This is useful when treating the touch sensor like a button. In digital mode the class implements the same interfaces as the SerialWombatDebouncedInput class so that physical buttons and cap touch inputs can be treated equivalently. Settign the high and low limits further apart will decrease the chance of false transitions but will also typically decrease the responsiveness of the sensor.

Output public data values for touched and not touched are configurable. This allows other pin modes to react based on touch. For instance, the touch and not touched values might be set to 0x4000 and 0xC000 so that a servo set to monitor that public data would move back and forth between 25% and 75% of its range depending on whether or not a touch is present.

The final touch value is the result of 8 averaged samples in firmware remove noise.

For particularly noisy signals a debounce option is also avaialble. This requires the specified number of samples to match before a transition is detected. This can help eliminate false transitions but makes the system less reponsive in terms of time to transition after a touch is made or removed.

The Cap touch pin mode in the firmware takes exclusive access to the Microcontroller's A/D hardware for a few milliseconds at a time. This isn't an issue for most users if the default 5ms delay between samples is used. However, it should be considered if multiple Cap Touch pins are being used simultaneously or if the delay is decreased as they may combine to starve other analog chanels and make conversions sporadic, affecting filtering and averaging. This may also impact performance of real-time control pin modes run on the Serial Wombat chip such as PID control.

A Tutorial video is also avaialble:
https://youtu.be/c4B0_DRVHs0

Definition at line 85 of file SerialWombat18CapTouch.h.

## Constructor & Destructor Documentation

## ◆ SerialWombat18CapTouch()

SerialWombat18CapTouch::SerialWombat18CapTouch | ( | SerialWombatChip & | serialWombat | ) |
| inline

Instantiate a SerialWombat18CapTouch class on a specified Serial Wombat Chip.

Definition at line 90 of file SerialWombat18CapTouch.h.

## Member Function Documentation

## ◆ begin()

int16_t SerialWombat18CapTouch::begin | ( | uint8_t | pin,
|  | uint16_t | chargeTime,
|  | uint16_t | delay = 10 )
| inline

Initialize the SerialWombat18CapTouch instance with a given charge Time in uS.

Required Charge time will vary by touch plate size, insulation and material. See YouTube video and example for usage.

Parameters

  pin | The pin on which the Cap Touch should run. Needs to be an Analog Capable pin
  chargeTime | Charge time in uS for capacitive charging.
  delay | Sets how long to wait between samples in mS. This may be useful since the Cap Touch pin mode monopolizes the A/D converter while a measurement is in progress.

Definition at line 104 of file SerialWombat18CapTouch.h.

## ◆ digitalRead()

bool SerialWombat18CapTouch::digitalRead | ( |  | ) |
| inline virtual

Returns the debounced state of the input.

This function reads from the public data of the pin which indicates the debounced and invert adjusted state of the input

Returns
  TRUE or FALSE. Meaning depends on inversion setting

Implements SerialWombatAbstractButton.

Definition at line 181 of file SerialWombat18CapTouch.h.

## ◆ makeAnalog()

int16_t SerialWombat18CapTouch::makeAnalog | ( |  | ) |
| inline

Definition at line 167 of file SerialWombat18CapTouch.h.

## ◆ makeDigital() [1/2]

int16_t SerialWombat18CapTouch::makeDigital | ( | uint16_t | touchLimit,
|  | uint16_t | noTouchLimit )
| inline

Make a cap touch behave like a digital button.

This method sets limits for touch present and absent, and makes the pin report digitally rather than analog. See video and example for calibration routine.

Parameters

  touchLimit | The calibrated value below which an A/D reading indicates touch present
  noTouchLimit | The calibrated value above which an A/D reading indicates no touch present

Definition at line 124 of file SerialWombat18CapTouch.h.

## ◆ makeDigital() [2/2]

int16_t SerialWombat18CapTouch::makeDigital | ( | uint16_t | touchLimit,
|  | uint16_t | noTouchLimit,
|  | uint16_t | touchValue,
|  | uint16_t | noTouchValue,
|  | bool | invert,
|  | uint16_t | debounceCount )
| inline

Make a cap touch behave like a digital button.

This method sets limits for touch present and absent, and makes the pin report digitally rather than analog. See video and example for calibration routine.

Parameters

  touchLimit | The calibrated value below which an A/D reading indicates touch present
  noTouchLimit | The calibrated value above which an A/D reading indicates no touch present
  invert | Invert the touch result
  debounceCount | number of consecutive digital samples that must match to change state

Definition at line 141 of file SerialWombat18CapTouch.h.

## ◆ pin()

uint8_t SerialWombat18CapTouch::pin | ( |  | ) |
| inline virtual

Used for inheritance.

Implements SerialWombatAbstractProcessedInput.

Definition at line 263 of file SerialWombat18CapTouch.h.

## ◆ readDurationInFalseState_mS()

uint16_t SerialWombat18CapTouch::readDurationInFalseState_mS | ( |  | ) |
| inline virtual

return the number of mS that the debounced input has been in false state

Note that this value starts incrementing after the debounce period, not after the physical pin transition.

Returns
  returns a value in mS which saturates at 65535. Returns 0 if currently true.

Implements SerialWombatAbstractButton.

Definition at line 223 of file SerialWombat18CapTouch.h.

## ◆ readDurationInTrueState_mS()

uint16_t SerialWombat18CapTouch::readDurationInTrueState_mS | ( |  | ) |
| inline virtual

return the number of mS that the debounced input has been in true state

Note that this value starts incrementing after the debounce period, not after the physical pin transition.

Returns
  returns a value in mS which saturates at 65535. Returns 0 if currently false.

Implements SerialWombatAbstractButton.

Definition at line 199 of file SerialWombat18CapTouch.h.

## ◆ readTransitionsState()

bool SerialWombat18CapTouch::readTransitionsState | ( | bool | resetTransitionCounts = true | ) |
| inline virtual

Queries the number of transistions that have occured on the debounced input.

This function queries the debounced input for current state and transitions since last call. transition count is put in the global member transitions. The debounced input in the Serial Wombat resets its count to zero after this call.

Returns
  TRUE or FALSE, current status of debounced input

Implements SerialWombatAbstractButton.

Definition at line 254 of file SerialWombat18CapTouch.h.

## ◆ swPinModeNumber()

uint8_t SerialWombat18CapTouch::swPinModeNumber | ( |  | ) |
| inline virtual

Used for ineheritance.

Implements SerialWombatAbstractProcessedInput.

Definition at line 264 of file SerialWombat18CapTouch.h.

## Member Data Documentation

## ◆ transitions

uint16_t SerialWombat18CapTouch::transitions = 0

Number of transitions returned by last call to readTransitionsState()

Definition at line 243 of file SerialWombat18CapTouch.h.