/Button-Enhanced

ESP32/Arduino library for working with a button. Rich configuration and functionalities.

Primary LanguageC++MIT LicenseMIT

Button-Enhanced

License Version

image-20221004213143380

Functionalities:

  • Configure the separation between a single press and hold.
  • Manually check for a single press or hold
  • Set a callback for single press or hold
  • Disable a specific or all callbacks at once for single press or hold
  • Define how often to receive hold notification, which works for both checks - manually & callback
  • Tracking of total single presses.
  • Tracking of total holds.
  • Resume or pause the whole button logic.
  • Resume or pause the counting logic.
  • Resume or pause the callback notifications.
  • Change the button pin dynamically

For examples of a functionality usage, please see the examples.

Installation:

Simple Example:

Notification about single press or hold using callbacks:
#include <Arduino.h>
#include "ButtonEnhanced.h"

#define BUTTON_PIN 22

ButtonEnhanced buttonEnhanced;

void onButtonShot() {
    Serial.println("Button press detected!");
}

void onButtonHold() {
    Serial.println("Button hold detected!");
}

void setup() {
    Serial.begin(9600);

    buttonEnhanced = ButtonEnhanced(BUTTON_PIN);
    buttonEnhanced.setOnShotCallback(onButtonShot);
    buttonEnhanced.setOnHoldCallback(onButtonHold);
}

void loop() {
    buttonEnhanced.refreshReading();
}
Notification about single press or hold via methods:
#include <Arduino.h>
#include "ButtonEnhanced.h"

#define BUTTON_PIN 22

ButtonEnhanced buttonEnhanced;

void setup() {
    Serial.begin(9600);

    buttonEnhanced = ButtonEnhanced(BUTTON_PIN);
}

void loop() {

    if(buttonEnhanced.isShot()) {
        Serial.println("Button press detected!");
    }

    if(buttonEnhanced.isHold()) {
        Serial.println("Button hold detected!");
    }
}

Configuration:

  • There is a default configuration for the way that Button Enhanced works. That way you don't need to deal with something unclear to you. But if you want to customize how our library works - you can do it.
  • There are 3 core parameters that can be set upon ButtonEnhanced initialization or dynamically later in your program:
    //Preparing the configuration
    ButtonEnhanced::Configuration configuration = ButtonEnhanced::Configuration();
    configuration.shotThresholdMS = DEFAULT_SHOT_THRESHOLD_MS;
    configuration.holdThresholdMS = DEFAULT_HOLD_THRESHOLD_MS;
    configuration.holdNotificationMS = DEFAULT_HOLD_NOTIFICATION_MS;

    //During initialization. If not provided configuration, the default one is used.
    buttonEnhanced = ButtonEnhanced(BUTTON_PIN);

    //Dynamically, overwriting a piece of the existing one
    buttonEnhanced.setShotThresholdMs(DEFAULT_SHOT_THRESHOLD_MS);
    buttonEnhanced.setHoldThresholdMs(DEFAULT_HOLD_THRESHOLD_MS);
    buttonEnhanced.setHoldNotificationMs(DEFAULT_HOLD_NOTIFICATION_MS);

    //Dynamically, overwriting it at once
    ButtonEnhanced::Configuration anotherConfiguration = ButtonEnhanced::Configuration();
    anotherConfiguration.shotThresholdMS = DEFAULT_SHOT_THRESHOLD_MS;
    anotherConfiguration.holdThresholdMS = DEFAULT_HOLD_THRESHOLD_MS;
    anotherConfiguration.holdNotificationMS = DEFAULT_HOLD_NOTIFICATION_MS;
    
    buttonEnhanced.updateConfiguration(anotherConfiguration);
    
    //Resetting the configuration to the default one
    buttonEnhanced.resetConfiguration();
Shot Threshold:
  • Set minimal amount of time in milliseconds that the button must be in pressed state to be counted as single press (shot).
  • The default time is 15 milliseconds

image-20221005033245540

Hold Threshold:
  • Set minimal amount of time in milliseconds that the button must be in pressed state to be counted as hold.
  • The default time is 200 milliseconds

image-20221005034011271

Hold Notification:
  • Set minimal amount of interval time in milliseconds that the notification for hold is called
  • The default time is 500 milliseconds

image-20221005034612276

Other Functionalities:

  • pause() - That will pause the callbacks, counting, checking button readings and etc...

  • resume() - That will resume the callbacks, counting, checking button readings and etc...

  • clearTotalShots(), clearTotalHolds(), clearTotals() - Clear a specific total counting or all at once.

  • pauseTotalShotsCounting(), pauseTotalHoldsCounting(), pauseTotalsCounting() - Pause a specific total counting or all at once

  • resumeTotalShotsCounting(), resumeTotalHoldsCounting(), resumeTotalsCounting() - Resume a specific total counting or all at once

  • resumeShotCallback(), resumeHoldCallback(), resumeCallbacks() - Resume a specific callbacks or all at once

  • pauseShotCallback(), pauseHoldCallback(), pauseCallbacks() - Resume a specific callbacks or all at once

  • getIsCorePaused(), getIsTotalHoldsPaused(), getIsTotalShotsPaused(), getTotalHolds(), getTotalShots() - Retrieve information about different things in the library.

Additional Information:

  • The library was written with the idea to be used in another project.
  • While writing the library, most of the ideas and concepts were drawn in Excalidraw ,which is a sketching tool. You can find the latest sketches in the excali folder.

image-20221005040945841