| ButtonToSwitch Library for ESP32 (Arduino) v4.6.1 A library that provides elaborated switch mechanism behavior simulation for digital signals inputs

Loading...
Searching...
No Matches
DblActnLtchMPBttn Class Referenceabstract

Abstract class, base to model Double Action LDD-MPBs (DALDD-MPBs). More...

`#include <ButtonToSwitch_ESP32.h>`

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

## Public Member Functions
| DblActnLtchMPBttn ()
| Abstract Class default constructor.
| DblActnLtchMPBttn (const int8_t &mpbttnPin, const bool &pulledUp=true, const bool &typeNO=true, const unsigned long int &dbncTimeOrigSett=0, const unsigned long int &strtDelay=0)
| Abstract Class constructor.
| ~DblActnLtchMPBttn ()
| Virtual destructor.
virtual bool | begin (const unsigned long int &pollDelayMs=_StdPollDelay)
| See DbncdMPBttn::begin(const unsigned long int)
void | clrStatus (bool clrIsOn=true)
| See DbncddMPBttn::clrStatus(bool)
fncPtrType | getFnWhnTrnOffScndry ()
| returns the function that is set to execute every time the object enters the Secondary Off State.
fncPtrType | getFnWhnTrnOnScndry ()
| Returns the function that is set to execute every time the object enters the Secondary On State.
fncVdPtrPrmPtrType | getFVPPWhnTrnOffScndry ()
| Returns a pointer to a function that is set to execute every time the object enters the Secondary Mode Off State.
void * | getFVPPWhnTrnOffScndryArgPtr ()
| Returns a pointer to the argument to be passed to the function set to execute every time the object enters the Secondary Mode Off State.
fncVdPtrPrmPtrType | getFVPPWhnTrnOnScndry ()
| Returns a pointer to a function that is set to execute every time the object enters the Secondary Mode On State.
void * | getFVPPWhnTrnOnScndryArgPtr ()
| Returns a pointer to the argument to be passed to the function set to execute every time the object enters the Secondary Mode On State.
bool | getIsOnScndry ()
| Returns the current value of the isOnScndry attribute flag.
unsigned long | getScndModActvDly ()
| Returns the current value of the scndModActvDly class attribute.
const TaskHandle_t | getTaskWhileOnScndry ()
| Returns the task to be run while the object is in the Secondary On state.
void | setFnWhnTrnOffScndryPtr (void(*newFnWhnTrnOff)())
| Sets the function that will be called to execute every time the object enters the Secondary Off State.
void | setFnWhnTrnOnScndryPtr (void(*newFnWhnTrnOn)())
| Sets the function that will be called to execute every time the object enters the Secondary On State.
void | setFVPPWhnTrnOffScndry (fncVdPtrPrmPtrType newFVPPWhnTrnOff, void *argPtr=nullptr)
| Sets a function to be executed every time the object enters the Secondary Mode Off State.
void | setFVPPWhnTrnOffScndryArgPtr (void *newFVPPWhnTrnOffArgPtr)
| Sets a pointer to an argument to be passed to the function set to execute every time the object enters the Secondary Mode Off State.
void | setFVPPWhnTrnOnScndry (fncVdPtrPrmPtrType newFVPPWhnTrnOn, void *argPtr=nullptr)
| Sets a function to be executed every time the object enters the Secondary Mode On State.
void | setFVPPWhnTrnOnScndryArgPtr (void *newFVPPWhnTrnOnArgPtr)
| Sets a pointer to an argument to be passed to the function set to execute every time the object enters the Secondary Mode On State.
bool | setScndModActvDly (const unsigned long &newVal)
| Sets a new value for the scndModActvDly class attribute.
void | setTaskWhileOnScndry (const TaskHandle_t &newTaskHandle)
| Sets the task to be run while the object is in the On state.
Public Member Functions inherited from LtchMPBttn
| LtchMPBttn ()
| Default constructor.
| LtchMPBttn (const int8_t &mpbttnPin, const bool &pulledUp=true, const bool &typeNO=true, const unsigned long int &dbncTimeOrigSett=0, const unsigned long int &strtDelay=0)
| Class constructor.
| LtchMPBttn (const LtchMPBttn &other)
| Copy constructor.
virtual | ~LtchMPBttn ()
| Class virtual destructor.
void | clrStatus (bool clrIsOn=true)
| See DbncdMPBttn::clrStatus(bool)
const bool | getIsLatched () const
| Returns the value of the isLatched attribute flag, indicating the Latched or Unlatched condition of the object.
bool | getTrnOffASAP ()
| Returns the value of the trnOffASAP attribute flag.
const bool | getUnlatchPend () const
| Returns the value of the "Valid Unlatch Pending" attribute.
const bool | getUnlatchRlsPend () const
| Returns the value of the "Valid Unlatch Release Pending" attribute.
void | setTrnOffASAP (const bool &newVal)
| Sets the value of the trnOffASAP attribute.
void | setUnlatchPend (const bool &newVal)
| Sets the value of the "Valid Unlatch Pending" attribute.
void | setUnlatchRlsPend (const bool &newVal)
| Sets the value of the "Valid Unlatch Release Pending" attribute.
bool | unlatch ()
| Sets the values of the flags needed to unlatch a latched MPB.
Public Member Functions inherited from DbncdDlydMPBttn
| DbncdDlydMPBttn ()
| Default constructor.
| DbncdDlydMPBttn (const int8_t &mpbttnPin, const bool &pulledUp=true, const bool &typeNO=true, const unsigned long int &dbncTimeOrigSett=0, const unsigned long int &strtDelay=0)
| Class constructor.
| DbncdDlydMPBttn (const DbncdDlydMPBttn &other)
| Copy constructor.
virtual | ~DbncdDlydMPBttn ()
| Class destructor.
bool | init (const int8_t &mpbttnPin, const bool &pulledUp=true, const bool &typeNO=true, const unsigned long int &dbncTimeOrigSett=0, const unsigned long int &strtDelay=0)
| see DbncdMPBttn::init(const int8_t, const bool, const bool, const unsigned long int)
void | setStrtDelay (const unsigned long int &newStrtDelay)
| Sets a new value to the "Start Delay" strtDelay attribute.
Public Member Functions inherited from DbncdMPBttn
| DbncdMPBttn ()
| Default class constructor.
| DbncdMPBttn (const int8_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.
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. The timer daemon entry is deleted for the object.
const unsigned long int | getCurDbncTime () const
| Returns the current debounce period time set for the object.
fncPtrType | getFnWhnTrnOff ()
| Returns a pointer to a function that is set to execute every time the object enters the Off State.
fncPtrType | getFnWhnTrnOn ()
| Returns a pointer to a 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 flag.
const DbncdMPBttn * | getMpbInstnc () const
| Returns a pointer to the present instanced object.
const uint32_t | getOtptsSttsPkgd ()
| Returns the relevant attribute flags values for the object state encoded as a 32 bits value, required to pass current state of the object to another thread/task managing the outputs.
const bool | getOutputsChange () const
| Returns the value of the outputsChange attribute flag.
unsigned long int | getStrtDelay ()
| Returns the current value of strtDelay attribute.
const TaskHandle_t | getTaskToNotify () const
| Returns the task to be notified by the object when its output flags changes.
const TaskHandle_t | getTaskWhileOn ()
| Returns the task to be run (resumed) while the object is in the On state.
bool | init (const int8_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.
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 (fncPtrType newFnWhnTrnOff)
| Sets the function that will be called to execute every time the object enters the Off State.
void | setFnWhnTrnOnPtr (fncPtrType 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 flag.
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).
void | setTaskToNotify (const TaskHandle_t &newTaskHandle)
| Sets the handle to the task to be notified by the object when its output attribute flags changes.
virtual void | setTaskWhileOn (const TaskHandle_t &newTaskHandle)
| Sets the task to be run while the object is in the On state.

## Detailed Description

Abstract class, base to model Double Action LDD-MPBs (DALDD-MPBs).

Double Action Latched DD-MPB are MPBs whose distinctive characteristic is that implement switches that present different behaviors based on the time length of the presses detected and the sequence of the presses. The pattern selected for this class is the following:

- A short press makes the MPB to behave as a Toggle LDD-MPB Switch (ToLDD-MPB) -designated as the main behavior-, swapping from the Off state to the On state and back as usual LDD-MPB.
- A long press activates another behavior, allowing the only MPB to be used as a second MPB. That different behavior -designated as the secondary behavior- defines the sub-classes of the DALDD-MPB class. Using a notation where the first component is the Off/On state of the main behavior and the second component the state of the secondary behavior the only possible combinations would be:
- 1. Off-Off
- 2. On-Off
- 3. On-On

The presses patterns are:

- 1. -> 2.: short press.
- 1. -> 3.: long press.
- 2. -> 3.: long press.
- 2. -> 1.: short press.
- 3. -> 2.: secondary behavior unlatch (subclass dependent, maybe release, external unlatch, etc.)

Note
  The short press will always be calculated as the Debounce + Delay set attributes.
  The long press is a configurable attribute of the class, the Secondary Mode Activation Delay (scndModActvDly) that holds the time after the Debounce + Delay period that the MPB must remain pressed to activate the mentioned mode. The same time will be required to keep pressed the MPB while in Main Behavior to enter the Secondary behavior.

## Constructor & Destructor Documentation

## ◆ DblActnLtchMPBttn()

DblActnLtchMPBttn::DblActnLtchMPBttn | ( | const int8_t & | mpbttnPin,
|  | const bool & | pulledUp = true,
|  | const bool & | typeNO = true,
|  | const unsigned long int & | dbncTimeOrigSett = 0,
|  | const unsigned long int & | strtDelay = 0 )

Abstract Class constructor.

Note
  For parameters see DbncdDlydMPBttn(const int8_t, const bool, const bool, const unsigned long int, const unsigned long int)

Here is the call graph for this function:

## Member Function Documentation

## ◆ getFnWhnTrnOffScndry()

fncPtrType DblActnLtchMPBttn::getFnWhnTrnOffScndry | ( |  | ) |

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

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

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

Return values

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

## ◆ getFnWhnTrnOnScndry()

fncPtrType DblActnLtchMPBttn::getFnWhnTrnOnScndry | ( |  | ) |

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

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

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

Return values

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

## ◆ getFVPPWhnTrnOffScndry()

fncVdPtrPrmPtrType DblActnLtchMPBttn::getFVPPWhnTrnOffScndry | ( |  | ) |

Returns a pointer to a function that is set to execute every time the object enters the Secondary Mode 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 Secondary Mode Off State.

Return values

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

## ◆ getFVPPWhnTrnOffScndryArgPtr()

void * DblActnLtchMPBttn::getFVPPWhnTrnOffScndryArgPtr | ( |  | ) |

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

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

## ◆ getFVPPWhnTrnOnScndry()

fncVdPtrPrmPtrType DblActnLtchMPBttn::getFVPPWhnTrnOnScndry | ( |  | ) |

Returns a pointer to a function that is set to execute every time the object enters the Secondary Mode 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 Secondary Mode On State.

Return values

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

## ◆ getFVPPWhnTrnOnScndryArgPtr()

void * DblActnLtchMPBttn::getFVPPWhnTrnOnScndryArgPtr | ( |  | ) |

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

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

## ◆ getIsOnScndry()

bool DblActnLtchMPBttn::getIsOnScndry | ( |  | ) |

Returns the current value of the isOnScndry attribute flag.

The isOnScndry attribute flag holds the secondary On state, when the MPB is pressed for the seted long press time from the Off-Off or the On-Off state as described in the DblActnLtchMPBttn class.

Returns
  The current value of the isOnScndry flag.

## ◆ getScndModActvDly()

unsigned long DblActnLtchMPBttn::getScndModActvDly | ( |  | ) |

Returns the current value of the scndModActvDly class attribute.

The scndModActvDly attribute defines the time length a MPB must remain pressed to consider it a long press, needed to activate the secondary mode.

Returns
  The current scndModActvDly value, i.e. the delay in milliseconds.

## ◆ getTaskWhileOnScndry()

const TaskHandle_t DblActnLtchMPBttn::getTaskWhileOnScndry | ( |  | ) |

Returns the task to be run while the object is in the Secondary On state.

Returns the task handle of the task to be resumed every time the object enters the Secondary On state, and will be paused when the object enters the Secondary Off state. This task execution mechanism dependent of the Secondary On state extends the concept of the Switch object far away of the simple turning On/Off a single hardware signal, attaching to it all the task execution capabilities of the MCU.

Returns
  The TaskHandle_t value of the task to be resumed while the object is in Secondary On state.

Return values

  NULL | if there is no task configured to be resumed while the object is in Secondary On state.

Warning
  Free-RTOS has no mechanism implemented to notify a task that it is about to be set in paused state, so there is no way to that task to ensure it will be set to pause in an orderly fashion. The task to be designated to be used by this mechanism has to be task that can withstand being interrupted at any point of it's execution, and be restarted from that same point next time the isOnScndry flag is set. For tasks that might need attaching resources or other issues every time it is resumed and releasing resources of any kind before being paused, using the function attached by using setFnWhnTrnOnScndryPtr() to gain control of the resources before resuming a task, and the function attached by using setFnWhnTrnOffScndryPtr() to release the resources and pause the task in an orderly fashion, or use those functions to manage a binary semaphore for managing the execution of a task.

## ◆ setFnWhnTrnOffScndryPtr()

void DblActnLtchMPBttn::setFnWhnTrnOffScndryPtr | ( | void(* | newFnWhnTrnOff )() | ) |

Sets the function that will be called to execute every time the object enters the Secondary 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 instantiated the attribute value is set to nullptr.

Parameters

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

## ◆ setFnWhnTrnOnScndryPtr()

void DblActnLtchMPBttn::setFnWhnTrnOnScndryPtr | ( | void(* | newFnWhnTrnOn )() | ) |

Sets the function that will be called to execute every time the object enters the Secondary 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 Secondary On State. Passing nullptr as parameter deactivates the function execution mechanism.

## ◆ setFVPPWhnTrnOffScndry()

void DblActnLtchMPBttn::setFVPPWhnTrnOffScndry | ( | fncVdPtrPrmPtrType | newFVPPWhnTrnOff,
|  | void * | argPtr = nullptr )

Sets a function to be executed every time the object enters the Secondary Mode 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 Secondary Mode 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.

## ◆ setFVPPWhnTrnOffScndryArgPtr()

void DblActnLtchMPBttn::setFVPPWhnTrnOffScndryArgPtr | ( | void * | newFVPPWhnTrnOffArgPtr | ) |

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

The argument pointer is passed to the function set to execute when the object enters the Secondary Mode 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 Secondary Mode Off State.

## ◆ setFVPPWhnTrnOnScndry()

void DblActnLtchMPBttn::setFVPPWhnTrnOnScndry | ( | fncVdPtrPrmPtrType | newFVPPWhnTrnOn,
|  | void * | argPtr = nullptr )

Sets a function to be executed every time the object enters the Secondary Mode 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 Secondary Mode 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.

## ◆ setFVPPWhnTrnOnScndryArgPtr()

void DblActnLtchMPBttn::setFVPPWhnTrnOnScndryArgPtr | ( | void * | newFVPPWhnTrnOnArgPtr | ) |

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

The argument pointer is passed to the function set to execute when the object enters the Secondary Mode 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 Secondary Mode On State.

## ◆ setScndModActvDly()

bool DblActnLtchMPBttn::setScndModActvDly | ( | const unsigned long & | newVal | ) |

Sets a new value for the scndModActvDly class attribute.

The scndModActvDly attribute defines the time length a MPB must remain pressed after the end of the debounce&delay period to consider it a long press, needed to activate the secondary mode. The value setting must be newVal >= _MinSrvcTime to ensure correct signal processing. See TmLtchMPBttn::setSrvcTime(const unsigned long int) for details.

Parameters

  newVal | The new value for the scndModActvDly attribute.

Return values

  true | The new value is in the valid range, the value was updated.
  false | The new value is not in the valid range, the value was not updated.

## ◆ setTaskWhileOnScndry()

void DblActnLtchMPBttn::setTaskWhileOnScndry | ( | const TaskHandle_t & | newTaskHandle | ) |

Sets the task to be run while the object is in the On state.

Sets the task handle of the task to be resumed when the object enters the On state, and will be paused when the object enters the Off state. This task execution mechanism dependent of the On state extends the concept of the Switch object far away of the simple turning On/Off a single hardware signal, attaching to it all the task execution capabilities of the MCU.

If the existing value for the task handle was not NULL before the invocation, the method will verify the Task Handle was pointing to a deleted or suspended task, in which case will proceed to suspend that task before changing the Task Handle to the new provided value.

Setting the value to NULL will disable the task execution mechanism.

Return values

  true | the task indicated by the parameter was successfuly asigned to be executed while in isOn state, or the mechanism was deactivated by setting the task handle to NULL.

Note
  The method does not implement any task handle validation for the new task handle, a valid handle to a valid task is assumed as parameter.
  Consider the implications of the task that's going to get suspended every time the MPB goes to the Off state, so that the the task to be run might be interrupted at any point of its execution. This implies that the task must be designed with that consideration in mind to avoid dangerous situations generated by a task not completely done when suspended.

Warning
  Take special consideration about the implications of the execution priority of the task to be executed while the MPB is in On state and its relation to the priority of the calling task, as it might affect the normal execution of the application.