| ButtonToSwitch Library for Arduino v4.5.0 A library that provides elaborated switch mechanism behavior simulation for digital signals inputs

Loading...
Searching...
No Matches
DbncdMPBttn Class Reference

Base class, models a Debounced Momentary Push Button (D-MPB). More...

`#include <ButtonToSwitch.h>`

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

## Public Member Functions
| DbncdMPBttn ()
| Default class constructor.
| DbncdMPBttn (const uint8_t &mpbttnPin, const bool &pulledUp=true, const bool &typeNO=true, const unsigned long int &dbncTimeOrigSett=0)
| Class constructor.
| DbncdMPBttn (const DbncdMPBttn &other)
| Copy constructor.
virtual | ~DbncdMPBttn ()
| Default virtual destructor.
virtual bool | begin (const unsigned long int &pollDelayMs=_StdPollDelay)
| Attaches the instantiated object to a timer that monitors the input pins and updates the object status.
void | clrStatus (bool clrIsOn=true)
| Clears and resets flags, timers and counters modified through the object's signals processing.
void | disable ()
| Disables the input signal processing, ignoring the changes of its values.
void | enable ()
| Enables the input signal processing.
bool | end ()
| Detaches the object from the timer that monitors the input pins, compute and updates the object's status.
const unsigned long int | getCurDbncTime () const
| Returns the current debounce period time set for the object.
fncPtrType | getFnWhnTrnOff ()
| Returns the function that is set to execute every time the object enters the Off State.
fncPtrType | getFnWhnTrnOn ()
| Returns the function that is set to execute every time the object enters the On State.
fncVdPtrPrmPtrType | getFVPPWhnTrnOff ()
| Returns a pointer to a function that is set to execute every time the object enters the Off State.
void * | getFVPPWhnTrnOffArgPtr ()
| Returns a pointer to the argument to be passed to the function set to execute every time the object enters the Off State.
fncVdPtrPrmPtrType | getFVPPWhnTrnOn ()
| Returns a pointer to a function that is set to execute every time the object enters the On State.
void * | getFVPPWhnTrnOnArgPtr ()
| Returns a pointer to the argument to be passed to the function set to execute every time the object enters the On State.
const bool | getIsEnabled () const
| Returns the value of the isEnabled attribute flag, indicating the Enabled or Disabled status of the object.
const bool | getIsOn () const
| Returns the value of the isOn attribute flag.
const bool | getIsOnDisabled () const
| Returns the value of the isOnDisabled attribute.
const unsigned long int | getLstPollTime ()
| Returns the time stamp of the last state update for the object.
const uint32_t | getOtptsSttsPkgd ()
| Returns the relevant attribute flags values for the object state encoded as a 32 bits value.
const bool | getOutputsChange () const
| Returns the value of the outputsChange attribute flag.
const unsigned long int | getPollPeriodMs ()
| Returns the poll period time setting attribute's value.
unsigned long int | getStrtDelay ()
| Returns the current value of strtDelay attribute.
bool | getUpdTmrAttchd ()
| Returns the value of the Attached to the update timer attribute.
bool | init (const uint8_t &mpbttnPin, const bool &pulledUp=true, const bool &typeNO=true, const unsigned long int &dbncTimeOrigSett=0)
| Initializes an object instantiated by the default constructor.
bool | pause ()
| Pauses the software timer updating the computation of the object's internal flags value (object's state).
void | resetDbncTime ()
| Resets the debounce process time of the object to the value used at instantiation.
void | resetFda ()
| Resets the MPB behavior automaton to it's Initial or Start State
bool | resume ()
| Restarts the software timer updating the calculation of the object internal flags.
void | setBeginDisabled (const bool &newBeginDisabled=false)
| Sets the starting isDisabled state.
bool | setDbncTime (const unsigned long int &newDbncTime)
| Sets the debounce process time.
void | setFnWhnTrnOffPtr (void(*newFnWhnTrnOff)())
| Sets the function that will be called to execute every time the object enters the Off State.
void | setFnWhnTrnOnPtr (void(*newFnWhnTrnOn)())
| Sets the function that will be called to execute every time the object enters the On State.
void | setFVPPWhnTrnOff (fncVdPtrPrmPtrType newFVPPWhnTrnOff, void *argPtr=nullptr)
| Sets a function to be executed every time the object enters the Off State.
void | setFVPPWhnTrnOffArgPtr (void *newFVPPWhnTrnOffArgPtr)
| Sets a pointer to an argument to be passed to the function set to execute every time the object enters the Off State.
void | setFVPPWhnTrnOn (fncVdPtrPrmPtrType newFVPPWhnTrnOn, void *argPtr=nullptr)
| Sets a function to be executed every time the object enters the On State.
void | setFVPPWhnTrnOnArgPtr (void *newFVPPWhnTrnOnArgPtr)
| Sets a pointer to an argument to be passed to the function set to execute every time the object enters the On State.
void | setIsOnDisabled (const bool &newIsOnDisabled)
| Sets the value of the isOnDisabled attribute.
void | setOutputsChange (bool newOutputsChange)
| Sets the value of the attribute flag indicating if a change took place in any of the output attribute flags (IsOn included).

## Detailed Description

Base class, models a Debounced Momentary Push Button (D-MPB).

Note
  This ButtonToSwitch_AVR implementation relies on the TimerOne library by paulstoffregen to manage the time generated INT.

Being the facilities provided by the TimerOne library limited to the execution of only ONE timer interrupt, the setup selected for this development is the following:

- A static array of pointers to all the DbncdMPBttn class and subclasses objects -pointed by _mpbsInstncsLstPtr- to be kept updated is created automatically when the first element is added with the begin() method. This "list of MPBs to keep updated" will grow as more elements are added. The object elements will be taken out of the list by using the end() method. When the list is left with no elements it'll be deleted automatically.
- Each object will hold the attribute for it's time period between updates: _pollPeriodMs
- Each object will hold the attribute for the last time it was updated: _lstPollTime
- Each object will hold the attribute flag to be included or ignored for the periodic update -to be used by the pause() and resume() methods- _updTmrAttchd. Depending on that attribute flag value the object will or will be not updated albeit being present in the "list of MPBs to keep updated". This mechanism is included for temporary pausing, avoiding the time and resources needed to take out and replace back an object from the update list by using begin() or end() The begin() and end() will work the inclusion and exclusion of the object in the "list of MPBs to keep updated" -pointed to by _mpbsInstncsLstPtr- just verifying the object's _updTmrAttchd is set to true when the begin is executed.
- The timer interrupt period is a common attribute (static) to all the DbncdMPBttn class and subclasses objects _updTimerPeriod, it will be set as the MCD of each and every timer attached object in the "list of MPBs to keep updated". The use of a MCD calculated time period is resource optimization oriented, to reduce interrupts to the minimum strictly needed and avoiding a fixed time setting. The best use of the resources by using the longer periods still suitable to do the updating job and selecting different MPBs update time that have a higher MCD is left to the developer best knowledge. That implies that the _updTimerPeriod should be updated:
- With every begin() invocation.
- With every resume() invocation.
- With every end() invocation, taking care of the special case if the "list of MPBs to keep updated" is emptied (_updTimerPeriod = 0 and Timer1 stopped)

- With every pause() invocation, taking care of the special case if the "list of MPBs to keep updated" is emptied (_updTimerPeriod = 0 and Timer1 paused)

  The callback function duties:

- Verify for a valid _mpbsInstncsLstPtr, if it's nullptr something failed, correct it by disabling the timer
- Save the current time for reference and traverse the list till the end (nullptr).
- For each MPB in the list verify the _updTmrAttchd == true
- If _updTmrAttchd == true -> verify the ("current time" - _lstPollTime) >= _pollPeriodMs. If the condition is true:
  - Execute the objects mpbPollCallback()
  - Set _lstPollTime = "current time"

This class provides the resources needed to process a momentary digital input signal -as the one provided by a MPB (Momentary Push Button)- returning a clean signal to be used as a switch, implementing the needed services to replace a wide range of physical related switch characteristics: Debouncing, deglitching, disabling.

Note
  More physical switch situations can be emulated, like temporarily disconnecting it (isDisabled=true and isOnDisabled=false), short circuiting it (isDisabled=true and isOnDisabled=true) and others.

## Constructor & Destructor Documentation

## ◆ DbncdMPBttn() [1/2]

DbncdMPBttn::DbncdMPBttn | ( | const uint8_t & | mpbttnPin,
|  | const bool & | pulledUp = true,
|  | const bool & | typeNO = true,
|  | const unsigned long int & | dbncTimeOrigSett = 0 )

Class constructor.

Parameters

  mpbttnPin | Pin id number of the input signal pin
  pulledUp | (Optional) boolean, indicates if the input pin must be configured as INPUT_PULLUP (true, default value), or INPUT_PULLDOWN (false), to calculate correctly the expected voltage level in the input pin. The pin is configured by the constructor so no previous programming is needed. The pin must be free to be used as a digital input, and must be a pin with an internal pull-up circuit, as not every GPIO pin has the option.
  typeNO | (Optional) boolean, indicates if the MPB is a Normally Open (NO) switch (true, default value), or Normally Closed (NC) (false), to calculate correctly the expected level of voltage indicating the MPB is pressed.
  dbncTimeOrigSett | (Optional) unsigned long integer (uLong), indicates the time (in milliseconds) to wait for a stable input signal before considering the MPB to be pressed (or not pressed). If no value is passed the constructor will assign the minimum value provided in the class, that is 20 milliseconds as it is an empirical value obtained in various published tests.

## ◆ DbncdMPBttn() [2/2]

DbncdMPBttn::DbncdMPBttn | ( | const DbncdMPBttn & | other | ) |

Copy constructor.

Parameters

  other | DbncdMPBttn object to copy

Here is the call graph for this function:

## Member Function Documentation

## ◆ begin()

bool DbncdMPBttn::begin | ( | const unsigned long int & | pollDelayMs = _StdPollDelay | ) |
| virtual

Attaches the instantiated object to a timer that monitors the input pins and updates the object status.

The frequency of the periodic monitoring is passed as a parameter in milliseconds, and is a value that must be small (frequent) enough to keep the object updated, but not so frequent that wastes resources useful for other tasks. A default value is provided based on empirical results obtained in various published tests.

Attention
  Due to the fact that the available resources limits the timers available to a single one, attaching the timer to keep different instantiated objects status updated involves several steps:
  - The method adds the object to an array of MPBttns objects to keep updated (after checking the object was not already included in the array).
  - As every object in the array has an independent time setting to be updated, a calculus must be done to set the timer to the best suited time to reduce the number of interrupts of the normal execution of the main code to check if any MPBttn object is set to be updated, while keeping those status updated in the set time.
  - When the first object is added to the status update array (or all the objects in the array were in Paused State, so the timer interrupt was disabled), set the timer period and start the timer.
  - When is not the first active (not paused) object in the status update array modify (if required) the timer set period to the new calculated one.

Parameters

  pollDelayMs | (Optional) unsigned long integer (ulong), the time between polls in milliseconds.

Returns
  Boolean indicating if the object could be attached to a timer.

Return values

  true | the object could be attached to the timer -or it was already attached to a timer when the method was invoked-.
  false | the object could not be attached to the timer, because the parameter passed for the timer was invalid: 0 (zero).

Reimplemented in DblActnLtchMPBttn, HntdTmLtchMPBttn, LtchMPBttn, SnglSrvcVdblMPBttn, TmVdblMPBttn, and XtrnUnltchMPBttn.

Here is the caller graph for this function:

## ◆ clrStatus()

void DbncdMPBttn::clrStatus | ( | bool | clrIsOn = true | ) |

Clears and resets flags, timers and counters modified through the object's signals processing.

Resets object's attributes to its initialization values to safely resume operations, either after pausing the timer, enabling the object after disabling it or any disruptive activity that might generate unexpected distorsions. This avoids risky behavior of the object due to dangling flags or partially consumed time counters.

Parameters

  clrIsOn | Optional boolean value, indicates if the _isOn flag must be included to be cleared:

- true: (default value) includes the isOn flag.
- false: excludes the isOn flag.

Here is the caller graph for this function:

## ◆ disable()

void DbncdMPBttn::disable | ( |  | ) |

Disables the input signal processing, ignoring the changes of its values.

Invoking the disable() method sends a message to the object requesting it to enter the Disabled state. Due to security and stability of the object's behavior the message will not be processed at every stage of the input signals detection and output computations, but in every safe and stable stage. When the message is processed the object will:

- Stop all input signal reading.
- Stop any new output flag computation.
- Reset all output flag values.
- Force the isOn flag according to the isOnDisabled flag setting.
- Keep this Disabled state behavior until an enabling message is received through a enable() method.

## ◆ enable()

void DbncdMPBttn::enable | ( |  | ) |

Enables the input signal processing.

Invoking the enable() method on a object in Disabled state sends it a message requesting to resume it's normal operation. The execution of the enabling of the object implies:

- Clearing all previous counters, timers, inputs readings and output calculations, including clearing the isOn state, see void clrStatus(bool)
- Resuming all input signals reading.
- Resuming all output flag computation from the "fresh startup" state
  Warning
    Due to strict security enforcement the object will not be allowed to enter the Enabled state if the MPB was pressed when the enable message was received and until a MPB release is efectively detected.

## ◆ end()

bool DbncdMPBttn::end | ( |  | ) |

Detaches the object from the timer that monitors the input pins, compute and updates the object's status.

Attention
  Due to the fact that the available resources limits the timers available to a single one (see bool begin(const unsigned long int) for details), dettaching the object from the timer involves several steps:
  - Pausing the object: that will take care of the recalculation of the the update time period, setting it and stop the timer if no active objects are left in the list.
  - Removing the object from the list of objects to keep updated.

Note
  The immediate detachment of the object from the timer that keeps it's state updated implies that the object's state will be kept, whatever that state is it. If a certain status is preferred some of the provided methods should be used for that including clrStatus(bool), resetFda(), disable(), setIsOnDisabled(), etc.

Returns
  Boolean indicating the success of the operation

Return values

  true | the object detachment procedure and timer entry removal was successful.
  false | the object detachment and/or entry removal was rejected.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ getCurDbncTime()

const unsigned long int DbncdMPBttn::getCurDbncTime | ( |  | ) | const

Returns the current debounce period time set for the object.

The original value for the debouncing process used at instantiation time might be changed with the setDbncTime(const unsigned long int) or with the resetDbncTime() methods. This method gets the current value of the attribute in use.

Returns
  The current debounce time in milliseconds

## ◆ getFnWhnTrnOff()

fncPtrType DbncdMPBttn::getFnWhnTrnOff | ( |  | ) |

Returns the function that is set to execute every time the object enters the Off State.

The function to be executed is an attribute that might be modified by the setFnWhnTrnOffPtr() method.

Returns
  A function pointer to the function set to execute every time the object enters the Off State.

Return values

  nullptr | if there is no function set to execute when the object enters the Off State.

Warning
  The function code execution will become part of the list of procedures the object executes when it enters the Off State, including the possibility to modify attribute flags and others. Making the function code too time demanding must be handled with care, using alternative execution schemes, for example (and not limited to) the function might set flags, modify counters and parameters to set the conditions to execute some code in the main loop, and that suspends itself at the end of its code, to let a new function calling event resume it once again.

## ◆ getFnWhnTrnOn()

fncPtrType DbncdMPBttn::getFnWhnTrnOn | ( |  | ) |

Returns the function that is set to execute every time the object enters the On State.

The function to be executed is an attribute that might be modified by the setFnWhnTrnOnPtr() method.

Returns
  A function pointer to the function set to execute every time the object enters the On State.

Return values

  nullptr | if there is no function set to execute when the object enters the On State.

Warning
  The function code execution will become part of the list of procedures the object executes when it enters the On State, including the possibility to modify attribute flags and others. Making the function code too time demanding must be handled with care, using alternative execution schemes, for example (and not limited to) the function might set flags, modify counters and parameters to set the conditions to execute some code in the main loop, and that suspends itself at the end of its code, to let a new function calling event resume it once again.

## ◆ getFVPPWhnTrnOff()

fncVdPtrPrmPtrType DbncdMPBttn::getFVPPWhnTrnOff | ( |  | ) |

Returns a pointer to a function that is set to execute every time the object enters the Off State.

The pointer is one to a function with the signature void (fncPtr*) (void*) to allow for passing a void* argument to the function.

Returns
  fncVdPtrPrmPtrType The pointer to the function set to execute every time the object enters the Off State.

Return values

  nullptr | if there is no function with the described signature set to execute when the object enters the Off State.

## ◆ getFVPPWhnTrnOffArgPtr()

void * DbncdMPBttn::getFVPPWhnTrnOffArgPtr | ( |  | ) |

Returns a pointer to the argument to be passed to the function set to execute every time the object enters the Off State.

Returns
  void* Pointer to the argument to be passed to the function set to execute every time the object enters the Off State.

## ◆ getFVPPWhnTrnOn()

fncVdPtrPrmPtrType DbncdMPBttn::getFVPPWhnTrnOn | ( |  | ) |

Returns a pointer to a function that is set to execute every time the object enters the On State.

The pointer is one to a function with the signature void (fncPtr*) (void*) to allow for passing a void* argument to the function.

Returns
  fncVdPtrPrmPtrType The pointer to the function set to execute every time the object enters the On State.

Return values

  nullptr | if there is no function with the described signature set to execute when the object enters the On State.

## ◆ getFVPPWhnTrnOnArgPtr()

void * DbncdMPBttn::getFVPPWhnTrnOnArgPtr | ( |  | ) |

Returns a pointer to the argument to be passed to the function set to execute every time the object enters the On State.

Returns
  void* Pointer to the argument to be passed to the function set to execute every time the object enters the On State.

## ◆ getIsEnabled()

const bool DbncdMPBttn::getIsEnabled | ( |  | ) | const

Returns the value of the isEnabled attribute flag, indicating the Enabled or Disabled status of the object.

The isEnabled flag might be modified by the enable() and the disable() methods.

Return values

  true | the object is in Enabled state.
  false | The object is in Disabled state.

## ◆ getIsOn()

const bool DbncdMPBttn::getIsOn | ( |  | ) | const

Returns the value of the isOn attribute flag.

The isOn attribute flag is the fundamental attribute of the object, it might be considered the "Raison d'etre" of all this classes design: the isOn signal is not just the detection of an expected voltage value of a mcu pin, but the combination of that voltage level, filtered and verified, for a determined period of time and until a new event modifies that situation. While other mechanism are provided to execute code when the status of the object changes, all but the isOn flag value update might be optionally executed.

Return values

  true | The object is in On state.
  false | The object is in Off state.

## ◆ getIsOnDisabled()

const bool DbncdMPBttn::getIsOnDisabled | ( |  | ) | const

Returns the value of the isOnDisabled attribute.

When instantiated the class, the object is created in Enabled state. That might be changed when needed. In the Disabled state the input signals for the MPB are not processed, and the output will be set to the On state or the Off state depending on this attribute's value. The reasons to disable the ability to change the output, and keep it on either state until re-enabled are design and use dependent. The flag value might be changed by the use of the setIsOnDisabled() method.

Return values

  true | the object is configured to be set to the On state while it is in Disabled state.
  false | the object is configured to be set to the Off state while it is in Disabled state.

## ◆ getLstPollTime()

const unsigned long int DbncdMPBttn::getLstPollTime | ( |  | ) |

Returns the time stamp of the last state update for the object.

The use of a unique timer to keep updated the state of all MPB objects forces each object to keep track of the time passed since it's last update. This is due to the fact that each MPB can be configured to have it's status updated at it's own rate. Keeping a register of the last update gives each MPB the possibility to compute at each Timer interruption signaling if it's the time to get the state update done.

Returns
  An unsigned long int representing the time stamp in milliseconds for the last time the state update was executed for the current object.

## ◆ getOtptsSttsPkgd()

const uint32_t DbncdMPBttn::getOtptsSttsPkgd | ( |  | ) |

Returns the relevant attribute flags values for the object state encoded as a 32 bits value.

Having a standard single data unit holding the all the relevant information describing the object's status is useful to pass current state to a function and for transmission purposes. The function otptsSttsUnpkg(uint32_t) is provided to unpackage the data into a MpbOtpts_t structure holding the information decoded.

Returns
  A 32-bit unsigned value representing the object's attribute flags current values.

## ◆ getOutputsChange()

const bool DbncdMPBttn::getOutputsChange | ( |  | ) | const

Returns the value of the outputsChange attribute flag.

The instantiated objects include attributes linked to their computed state, which represent the behavior expected from their respective electromechanical simulated counterparts. When any of those attributes values change, the outputsChange flag is set. The flag only signals changes have happened -not which flags, nor how many times changes have taken place- since the last outputsChange flag reset. The outputsChange flag must be reset through the setOutputsChange(false) method after the outputs processing code is executed.

Return values

  true | any of the object's behavior flags have changed value since last time outputsChange flag was reseted.
  false | no object's behavior flags have changed value since last time outputsChange flag was reseted.

## ◆ getPollPeriodMs()

const unsigned long int DbncdMPBttn::getPollPeriodMs | ( |  | ) |

Returns the poll period time setting attribute's value.

The poll period time in milliseconds (pollPeriodMs) attribute sets the time period between state updates for the current object. The time period, in milliseconds, is set when the object begin(unsigned long int) method is called, and will be held through the use of the pause() and resume() methods. The only way to change it is by calling the end() method and then restarting the timer polling with a new begin() with a different value as parameter.

Attention
  The value passed in the begin(const unsigned long int) method is very important for the object and the system behavior. Setting a very small value will be resource consuming, as the timer will be interrupting the normal code execution to keep the object state updated, surely more frequently than really needed. Setting a very large value will result in a very slow updated object, making the execution less responsive than needed. See virtual bool begin(const unsigned long int) for more details. If not provided in the begin() method a standard value of 10 milliseconds is used.

Returns
  The time setting for the poll period time in milliseconds.

## ◆ getStrtDelay()

unsigned long int DbncdMPBttn::getStrtDelay | ( |  | ) |

Returns the current value of strtDelay attribute.

Returns the current value of time used by the object to rise the isOn attribute flag, after the debouncing process ends, in milliseconds. If the MPB is released before completing the debounce and the strtDelay time, no press will be detected by the object, and the isOn flag will not be affected. The original value for the delay process used at instantiation time might be changed with the setStrtDelay() method, so this method is provided to get the current value in use.

Returns
  The current strtDelay time in milliseconds.

Attention
  The strtDelay attribute is forced to a 0 ms value at instantiation of DbncdMPBttn class objects, and no setter mechanism is provided in this class. The inherited DbncdDlydMPBttn class objects (and all it's subclasses) constructor includes a parameter to initialize the strtDelay value, and a method to set that attribute to a new value. This implementation is needed to keep backwards compatibility to old versions of the library.

## ◆ getUpdTmrAttchd()

bool DbncdMPBttn::getUpdTmrAttchd | ( |  | ) |

Returns the value of the Attached to the update timer attribute.

Even when the instantiated object might be included in the "list of MPBs to keep updated", the final element that defines if an object is intended to have it's status updated is the attribute "Attached to the updating timer" updTmrAttchd. This value is used to include or exclude the object from the updating process without having to eliminate it or include it in the mentioned array list -both activities are time and resources consuming-, specially useful for situations like the pause() and resume() methods.

Returns
  The value of the updTmrAttchd attribute value

Return values

  true | The object is set up to be updated by the timer events
  false | The object is set up NOT to be updated by the timer events

## ◆ init()

bool DbncdMPBttn::init | ( | const uint8_t & | mpbttnPin,
|  | const bool & | pulledUp = true,
|  | const bool & | typeNO = true,
|  | const unsigned long int & | dbncTimeOrigSett = 0 )

Initializes an object instantiated by the default constructor.

All the parameters correspond to the non-default constructor of the class, DbncdMPBttn(const uint8_t, const bool, const bool, const unsigned long int)

Here is the caller graph for this function:

## ◆ pause()

bool DbncdMPBttn::pause | ( |  | ) |

Pauses the software timer updating the computation of the object's internal flags value (object's state).

The immediate exclusion from the timer that keeps the object's state updated implies that the object's state will be kept, whatever that state is it. The same consideration as the end() method applies referring to options to modify the state in which the object will be while in the Pause state.

Return values

  true | the object was set not to be updated by the timer.
  false | the object was not included in the "List of MPBttns to keep updated", so it couldn't be paused.

Note
  For better understanding on the timer update mechanism used and it's management see begin(const unsigned long int) for details.

Here is the caller graph for this function:

## ◆ resetDbncTime()

void DbncdMPBttn::resetDbncTime | ( |  | ) |

Resets the debounce process time of the object to the value used at instantiation.

The debounce process time used at instantiation might be changed with the setDbncTime() as needed, as many times as needed. This method reverts the value to the instantiation time value. In case the value was not specified at instantiation time the default debounce time value will be used.

Here is the call graph for this function:

## ◆ resetFda()

void DbncdMPBttn::resetFda | ( |  | ) |

Resets the MPB behavior automaton to it's Initial or Start State

This method is provided for security and for error handling purposes, so that in case of unexpected situations detected, the driving Deterministic Finite Automaton used to compute the MPB objects states might be reset to it's initial state to safely restart it, maybe as part of an Error Handling procedure.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ resume()

bool DbncdMPBttn::resume | ( |  | ) |

Restarts the software timer updating the calculation of the object internal flags.

The timer will stop calling the functions for computing the flags values after calling the pause() method and will not be updated until the object is reatached to the timer with this method.

Return values

  true | the object's timer updating could be resumed.
  false | the object was not included in the "List of MPBttns to keep updated", so it's updating couldn't be resumed.

Warning
  This method will restart the inactive timer after a pause() method. If the object's timer was modified by an end()* method then a **begin() method will be needed to restart it's timer.

Here is the call graph for this function:

## ◆ setBeginDisabled()

void DbncdMPBttn::setBeginDisabled | ( | const bool & | newBeginDisabled = false | ) |

Sets the starting isDisabled state.

This method adds the possibility to start the object either in Enabled or Disabled state. The default is to be started in Enabled state (isEnabled = true). The selected state must be set before the object update timer is started, i.e. before the .begin() method is executed. Once the update timer is started the use of this method has no consequences over the object behavior.

Parameters

  newBeginDisabled | States if the object must be started in the default Enabled state (false), or in the Disabled state (true).

## ◆ setDbncTime()

bool DbncdMPBttn::setDbncTime | ( | const unsigned long int & | newDbncTime | ) |

Sets the debounce process time.

Sets a new time for the debouncing period. The value must be equal or greater than the minimum empirical value set as a property for all the classes, that value is defined in the _HwMinDbncTime constant (20 milliseconds). A long debounce time will produce a delay in the press event generation, making it less "responsive".

Parameters

  newDbncTime | unsigned long integer, the new debounce value for the object.

Returns
  A boolean indicating if the debounce time setting was successful.

Return values

  true | the new value is in the accepted range, the attribute value is updated.
  false | the value was out of the accepted range, no change was made.

Here is the caller graph for this function:

## ◆ setFnWhnTrnOffPtr()

void DbncdMPBttn::setFnWhnTrnOffPtr | ( | void(* | newFnWhnTrnOff )() | ) |

Sets the function that will be called to execute every time the object enters the Off State.

The function to be executed must be of the form void (*newFnWhnTrnOff)(), meaning it must take no arguments and must return no value, it will be executed only once by the object (recursion must be handled with the usual precautions). When the object is instantiated the attribute value is set to nullptr.

Parameters

  newFnWhnTrnOff | Function pointer to the function intended to be called when the object enters the Off State. Passing nullptr as parameter deactivates the function execution mechanism.

## ◆ setFnWhnTrnOnPtr()

void DbncdMPBttn::setFnWhnTrnOnPtr | ( | void(* | newFnWhnTrnOn )() | ) |

Sets the function that will be called to execute every time the object enters the On State.

The function to be executed must be of the form void (*newFnWhnTrnOff)(), meaning it must take no arguments and must return no value, it will be executed only once by the object (recursion must be handled with the usual precautions). When instantiated the attribute value is set to nullptr.

Parameters

  newFnWhnTrnOn | function pointer to the function intended to be called when the object enters the On State. Passing nullptr as parameter deactivates the function execution mechanism.

## ◆ setFVPPWhnTrnOff()

void DbncdMPBttn::setFVPPWhnTrnOff | ( | fncVdPtrPrmPtrType | newFVPPWhnTrnOff,
|  | void * | argPtr = nullptr )

Sets a function to be executed every time the object enters the Off State.

The function to be executed must be of the form void (newFVPPWhnTrnOff)(void), meaning it must take a void pointer as argument and must return no value, it will be executed only once by the object (recursion must be handled with the usual precautions). When the object is instantiated the attribute value is set to nullptr.

Parameters

  newFVPPWhnTrnOff | Function pointer to the function intended to be called when the object enters the Off State. Passing nullptr as parameter deactivates the function execution mechanism.
  argPtr | void pointer to an argument to be passed to the function when it is called.

## ◆ setFVPPWhnTrnOffArgPtr()

void DbncdMPBttn::setFVPPWhnTrnOffArgPtr | ( | void * | newFVPPWhnTrnOffArgPtr | ) |

Sets a pointer to an argument to be passed to the function set to execute every time the object enters the Off State.

The argument pointer is passed to the function set to execute when the object enters the Off State. The pointer is set to nullptr when the object is instantiated.

Parameters

  newFVPPWhnTrnOffArgPtr | Pointer to an argument to be passed to the function set to execute every time the object enters the Off State.

## ◆ setFVPPWhnTrnOn()

void DbncdMPBttn::setFVPPWhnTrnOn | ( | fncVdPtrPrmPtrType | newFVPPWhnTrnOn,
|  | void * | argPtr = nullptr )

Sets a function to be executed every time the object enters the On State.

The function to be executed must be of the form void (newFVPPWhnTrnOn)(void), meaning it must take a void pointer as argument and must return no value, it will be executed only once by the object (recursion must be handled with the usual precautions). When the object is instantiated the attribute value is set to nullptr.

Parameters

  newFVPPWhnTrnOn | Function pointer to the function intended to be called when the object enters the On State. Passing nullptr as parameter deactivates the function execution mechanism.
  argPtr | void pointer to an argument to be passed to the function when it is called.

## ◆ setFVPPWhnTrnOnArgPtr()

void DbncdMPBttn::setFVPPWhnTrnOnArgPtr | ( | void * | newFVPPWhnTrnOnArgPtr | ) |

Sets a pointer to an argument to be passed to the function set to execute every time the object enters the On State.

The argument pointer is passed to the function set to execute when the object enters the On State. The pointer is set to nullptr when the object is instantiated.

Parameters

  newFVPPWhnTrnOnArgPtr | Pointer to an argument to be passed to the function set to execute every time the object enters the On State.

## ◆ setIsOnDisabled()

void DbncdMPBttn::setIsOnDisabled | ( | const bool & | newIsOnDisabled | ) |

Sets the value of the isOnDisabled attribute.

When instantiated the class, the object is created in Enabled state. That might be changed as needed. While in the Disabled state the input signals for the MPB are not processed, and the output will be set to the On state or the Off state depending on this attribute value.

Note
  The reasons to disable the ability to change the output, and keep it on either state until re-enabled are design and use dependent, being an obvious one security reasons, disabling the ability of the users to manipulate the switch while keeping the desired On/Off state. A simple example would be to keep a light on in a place where a meeting is taking place, disabling the lights switches and keeping the On State. Another obvious one would be to keep a machine off while servicing it's internal mechanisms, disabling the possibility of turning it on.

Warning
  If the method is invoked while the object is disabled, and the isOnDisabled attribute flag is changed, then the isOn attribute flag will have to change accordingly. Changing the isOn flag value implies that all the implemented mechanisms related to the change of the isOn attribute flag value will be executed.

## ◆ setOutputsChange()

void DbncdMPBttn::setOutputsChange | ( | bool | newOutputsChange | ) |

Sets the value of the attribute flag indicating if a change took place in any of the output attribute flags (IsOn included).

The usual path for the outputsChange flag is to be set by any method changing an output attribute flag, the callback function signaled to take care of the hardware actions because of this changes clears back outputsChange after taking care of them. In the unusual case the developer wants to "intercept" this sequence, this method is provided to set (true) or clear (false) outputsChange value.

Parameters

  newOutputChange | The new value to set the outputsChange flag to.

Here is the caller graph for this function: