TDuino
Convenient functionality for Arduino
Public Member Functions | Protected Member Functions | Protected Attributes
TPinInput Class Reference

Attach events to handle input from a pin. More...

#include <TPinInput.h>

Public Member Functions

 TPinInput ()
 The default contructor for the TPinInput class. More...
 
virtual ~TPinInput ()
 The destructor for the class. More...
 
virtual void attach (byte pin, byte mode=INPUT)
 Attach the instance of TPinInput to a pin. More...
 
int read (byte samples)
 Get the average value of multiple readings from the pin. More...
 
unsigned int getDebounce ()
 Get the amount of debounce used with events. More...
 
void setDebounce (unsigned int debounce)
 Sets the debounce value. More...
 
byte getDeviation ()
 Get the amount of deviation used with events. More...
 
void setDeviation (byte deviation, bool fixedSteps=false)
 Set the amount of deviation used to detect state change. More...
 
int getBufferedValue (byte sampleIndex=0)
 Get buffered value of the sample buffer. More...
 
byte getSamples ()
 Get the number of samples used with events. More...
 
void setSamples (byte samples, bool buffered=false)
 Set number of samples (reads) used with events. More...
 
virtual void loop ()
 The pin's loop method. More...
 
void onFalling (TPinInputCallback callback)
 Assign a callback to handle falling pin state. More...
 
void onRising (TPinInputCallback callback)
 Assign a callback for rising pin state. More...
 
int read ()
 Read the value from the pin. More...
 
- Public Member Functions inherited from TPin
 TPin ()
 Default constructor for the TPin class. More...
 
void enable (byte on)
 Enable / disable a digital pin. More...
 
void flip ()
 Flip pin state. More...
 
void off ()
 Turn off the pin. More...
 
void on ()
 Turn on the pin. More...
 
void pwm (int value)
 Set the pin to a PWM value. More...
 
int read ()
 Read the value from the pin. More...
 
byte state ()
 Get the digital state of the pin. More...
 
bool isAnalog ()
 Checks if the pin is analog. More...
 
bool hasPwm ()
 Checkt if the pin has PWM capabilities. More...
 
byte getMode ()
 Get the pin's mode. More...
 
byte getPin ()
 Get the pin's number. More...
 
- Public Member Functions inherited from TBase
 TBase ()
 Constructor for class TBase. More...
 
virtual ~TBase ()
 Destructor for class TBase. More...
 

Protected Member Functions

virtual void falling ()
 Method called when the pins state is falling. More...
 
virtual void rising ()
 Method called when the pins state is rising. More...
 
- Protected Member Functions inherited from TPin
bool isPinValid (const char *token=NULL)
 
bool isPwmValid (int &value, const char *token=NULL)
 
- Protected Member Functions inherited from TBase
virtual void defaults ()
 Method used to reset all class internal variables. More...
 

Protected Attributes

TPinInputCallback callbacks [2]
 Callbacks for onFalling and onRising.
 
byte deviation
 The amount of deviation required to trigger an event.
 
bool fixedDeviation
 If deviation is to be handled as fixed steps.
 
byte samples
 The number of samples to use for events.
 
int * sampleBuffer
 Buffer used for storing multiple samples.
 
int lastState
 The last known state of the pin. See loop().
 
unsigned int debounce
 The amount of debounce used with the pin.
 
unsigned long changeMillis
 The time of the last state change.
 
- Protected Attributes inherited from TPin
byte pin
 The pin assigned to this instance.
 
byte mode
 The mode used for the pin (INPUT / INPUT_PULLUP / OUTPUT). The two high order bits are used to store additional info about the pin.
 
- Protected Attributes inherited from TBase
unsigned long loopMillis
 The value of millis() to be used within loop()
 

Detailed Description

Attach events to handle input from a pin.

TPinInput is used to monitor changes on a digital or analog input pin and whenever a change is registred on the specific pin, an event is triggered.

Constructor & Destructor Documentation

◆ TPinInput()

TPinInput::TPinInput ( )

The default contructor for the TPinInput class.

Please see docs for the default constructor of TPin.

See also
TPin::TPin() attach()

◆ ~TPinInput()

TPinInput::~TPinInput ( )
virtual

The destructor for the class.

Releases any memory used for sample buffer.

Member Function Documentation

◆ attach()

void TPinInput::attach ( byte  pin,
byte mode  = INPUT 
)
virtual

Attach the instance of TPinInput to a pin.

Parameters
pinSee TPin::attach()
modeSee TPin::attach()

Valid values for mode are INPUT and INPUT_PULLUP - if any other value if provided, INPUT is used.

See also
TPin::attach()

Reimplemented from TPin.

Reimplemented in TButton.

◆ falling()

void TPinInput::falling ( )
protectedvirtual

Method called when the pins state is falling.

This method is called whenever the pin state is detected as being lower than the last time (minding debounce and deviation). You can override this method in order to change the functionality a falling pin state. By default this method calls the event handler stored in callbacks [0].

◆ getBufferedValue()

int TPinInput::getBufferedValue ( byte  sampleIndex = 0)

Get buffered value of the sample buffer.

Parameters
sampleIndexIndex of sample to get.
Returns
The buffered value from the sample buffer or -1 if buffering is not used.

If sampleIndex is zero (default value), the average of the samples in the buffer is returned. If sampleIndex is non-zero, the single sample at the index (1..SampleBufferSize) is returned.

See also
setSamples()

◆ getDebounce()

unsigned int TPinInput::getDebounce ( )

Get the amount of debounce used with events.

See also
setDebounce() debounce.

◆ getDeviation()

byte TPinInput::getDeviation ( )

Get the amount of deviation used with events.

See also
setDeviation()

◆ getSamples()

byte TPinInput::getSamples ( )

Get the number of samples used with events.

See also
setSamples()

◆ loop()

void TPinInput::loop ( )
virtual

The pin's loop method.

Must be called in order to read an calculate pin state as requested. If loop() is not called, no events will be triggered by the pin.

See also
onRising() onFalling() rising() falling() TPin::loop()

Reimplemented from TBase.

Reimplemented in TButton.

◆ onFalling()

void TPinInput::onFalling ( TPinInputCallback  callback)

Assign a callback to handle falling pin state.

Parameters
callbackThe callback to be used.

Assigns the argument given as being the callback used whenever the pin's state is registred as falling (lower than last poll). You can clear a previously set callback by using NULL as argument.

The arguments passed to the callback are the pin number and the new state which has been detected on the pin.

See also
onRising() setSamples() setDeviation() falling() rising().
void pinStateChange(byte pin, int newState)
{
//React to the new pin state
}
TPinInput pinInput(pinNumber);
pinInput.onFalling(pinStateChange);

◆ onRising()

void TPinInput::onRising ( TPinInputCallback  callback)

Assign a callback for rising pin state.

Parameters
callbackThe callback to be used.

Is the same as onFalling() but for a rising pin state. Note that if deviation is set to 0, rising event will fire even if there is no change in pin state.

See also
onFalling() setDeviation()

◆ read() [1/2]

int TPinInput::read ( byte  samples)

Get the average value of multiple readings from the pin.

Parameters
samplesThe number of samples to get (MUST be above 2).
Returns
The average value of the pin.

This will return the average value of samples readings from the pin with analogRead for analog pins and digitalRead for digital pins. If any debounce has been specified, the debounce will cause a (blocking!) delay of debounce length before each read.

See also
setDebounce()

◆ read() [2/2]

int TPin::read

Read the value from the pin.

Returns
The value from the pin.

This will return the value retreived with analogRead for analog pins and digitalRead for digital pins.

See also
state()

◆ rising()

void TPinInput::rising ( )
protectedvirtual

Method called when the pins state is rising.

This has inverted functionality of falling() and by default it does nothing but calling callbacks [1].

◆ setDebounce()

void TPinInput::setDebounce ( unsigned int  debounce)

Sets the debounce value.

Parameters
debounceThe debounce value to be used.

Sets the debounce value to be used when detecting changes in the pins state. The value is defined in milliseconds and is used as the minimum amount of time there has to elapse between state changes.

Please not that the specified debounce is only used for events and by the read(byte) function. All other methods used for reading the pin does not mind the debounce.

See also
getDebounce() debounce

◆ setDeviation()

void TPinInput::setDeviation ( byte  deviation,
bool  fixedSteps = false 
)

Set the amount of deviation used to detect state change.

Parameters
deviationThe amount of deviation to use.
fixedStepsSet to true if you want events to use fixed steps.

By default deviation is set to 1 and this means than any change in pin state will cause an event to fire. Because readings from analog pins may fluctuate, a tolerance of 1 may have the result that you are flooded with events. By changing the value of deviation, events will only be triggered when the pin state differs by at least the amount of deviation specified.

If "fixedSteps" is enabled, events will fire with fixed increments / decrements, so if "deviation" is 5 and the pin state rises from 10 to 20 then an event will be fired for 15 and 20. If "fixedSteps" is disabled, you would only get an event for 20.

NOTES: 1) Setting deviation to 0 will cause onRising events to fire even if there are no changes in pin state. 2) Setting deviation to values above 1 for digital pins will be truncated to 0 (even values) or 1. 3) When deviation is above 1 and "fixedSteps" is true, some values from the pin may never cause an event to fire.

See also
onRising() onFalling()

◆ setSamples()

void TPinInput::setSamples ( byte  samples,
bool  buffered = false 
)

Set number of samples (reads) used with events.

Parameters
samplesThe number of samples to use (2..60).
bufferedIf true the samples will be buffered.

By default the pin is read once and if the state differs (minding any deviation) from the previously read state, an event is triggered. In order to increase accuracy and reduce electrical fluctuations, you can specify how many samples (reads) should be retreived in order to calculate an average value which will increase accuracy.

If samples is not in the valid range 2..60, sampling will be disabled! The low limit is obvious, the high level is set because the state is stored as an unsigned int with a max value of 65535 (1023*60 = 61380).

If buffered is false, the pin will be read samples times in order to calculate an average which is then used to trigger an event. This means that whenever an event is triggered, the value passed to it will be calculated from samples new readings.

If buffered is true, samples readings from the pin will be stored in a buffer (BEWARE: dynamic memory usage!) in order to calculate an average reading for the event. This means that the value passed to the event is an average of one new reading combined with samples-1 old readings.

If any debounce is defined for the pin, the debounce will be the minimum amount of time there has to elapse between each sample. For non-buffered sampling, the event rate will be approximately pin_read_time + (debounce * samples), for buffered sampling the rate will be pin_read_time + debounce

See also
read(byte) onRising() onFalling() setDebounce()