Skip to content

Button

RoboBoard X3 buttons

RTS (Reset) - physical processor restart. Button state can't be read.
BOOT - user button. Also may be used to manually enter ESP32 bootloader.

Button control interface to read its state and events.
Can be used with internal RoboBoard button or external one connected to GPIO.

Code snippets

State read
// Is button currently pressed
bool isIn = Button.isPressed();
// Is button currently released
bool isOut = Button.isReleased();
// Is button pressed and holding for 1000 milliseconds
bool isInFor = Button.isPressedFor(1000);
// Is button released for 1000 milliseconds
bool isOutFor = Button.isReleasedFor(1000);
// Was button pressed before
bool wasIn = Button.wasPressed();
// Was button released before
bool wasOut = Button.wasReleased();
// Was button pressed and released
bool wasClick = Button.wasClick();
// Was button double clicked
bool wasDouble = Button.wasDoubleClick();
// Was button long pressed
bool wasLongPress = Button.wasLongPress();
Event usage
// Function called on button event
void buttonEvent(int evt) {
  if (evt == Button.evtPress) {
    // Button was pressed
  }
  else if (evt == Button.evtRelease) {
    // Button was released
  }
  else if (evt == Button.evtLongPress) {
    // Button was long pressed
  }
  else if (evt == Button.evtDoubleClick) {
    // Button was double clicked
  }
}
void setup() {
  // Register button state change event 
  Button.addEvent(buttonEvent);
}
void loop() { }
Map button to processor restart (click to expand)

Example to make user button work same as physical reset (RST) button. 

void setup() {
  // Map button as Reset
  Button.addEvent([]() { Board.restart(); });
}
void loop() {

}

Delay code start until button press (click to expand)

Example to delay any code execution until button is pressed. 

void setup() {
  // Run code and jump to loop()
  Serial.begin(115200);
  // Wait until button is pressed & print message
  while (!Button.waitClick(1000)) {
    Serial.println("Waiting for a button press...");
  }
}
void loop() {
  Serial.println("Code is running...");
  delay(500);
}

Functions

Current state

Read current button states (at the moment).

state Button.isPressed()

Check if button is pressed.
Returns:
state - yes / no [true:false]

state Button.isReleased()

Check if button is released.
Returns:
state - yes / no [true:false]

state Button.isPressedFor(time)

Check if button is pressed in for a certain amount of time.
Parameter: time - amount of milliseconds button is pressed [0:65535]ms
Returns: status - yes / no [true:false]

state Button.isReleasedFor(time)

Check if button is released in for a certain amount of time.
Parameter: time - amount of milliseconds button is released [0:65535]ms
Returns: status - yes / no [true:false]

state Button.isLongPress()

Check if button is pressed for 500ms.
Returns:
state - yes / no [true:false]

state Button.getState()

Get button state (pressed of not). Same as isPressed().
Returns:
state - true is pressed, false not pressed.

Previous state

Read past button states (current or already happened). Button actions are recorded and accessed with these functions (after event is already happened). Functions returns true only once. After that, recorded state is reset and waits for new event.

state Button.wasPressed()

Check if button was pressed earlier.
Returns:
state - yes / no [true:false]

state Button.wasReleased()

Check if button was released earlier.
Returns:
state - yes / no [true:false]

state Button.wasClick()

Check if button is was clicked shortly.
Returns:
state - yes / no [true:false]

state Button.wasLongPress()

Check if button is was pressed for 500ms.
Returns:
state - yes / no [true:false]

state Button.wasDoubleClick()

Check if button was was double clicked.
Returns:
state - yes / no [true:false]

time Button.getStateTime()

Get amount of time button is in current state.
Returns:
time - state time (milliseconds).

Events

Button events used to trigger some code execution when button is pressed. waitClick() is used to halt code execution until button is pressed. addEvent() is used to report button state change.

state Button.waitClick()

state Button.waitClick(time)

state Button.waitDobuleClick()

state Button.waitDobuleClick(time)

state Button.waitLongPress()

state Button.waitLongPress(time)

Halts code execution until button event is detected.
Contains timeout feature for maximum amount of time to wait.
Parameter: time - maximum time to wait (ms). 0 - disabled.
Returns: state - true if event detected, false if timeout.

Button.addEvent(function)

Register function, called on button event. Available event types:
• Button.evtRelease
• Button.evtPress
• Button.evtClick
• Button.evtLongPress
• Button.evtDoubleClick
Parameter: function - function name [buttonEvent].
Accepts two types of functions - with evt parameter and without. Event parameter is a convenient way to get event type without checking inside loop().
void buttonEvent() { } or void buttonEvent(int evt) { }.

void buttonEvent(int evt) {
  if (evt == Button.evtPress) Serial.println("Button: evtPress");
  if (evt == Button.evtRelease) Serial.println("Button: evtRelease");
}
void setup() {
  button.addEvent(buttonEvent);
}
void loop() { }

Configuration

Button.setDebounceTime(time )

Set debounce time to prevent false reading during button latching.
Parameters:
time - debounce time (ms). Default: 20ms.

Button.setLongPressTime(time )

Set custom long press time for isLongPress() wasLongPress() functions.
Parameters:
time - press in time (ms). Default: 500ms.

External GPIO button

IOButton gpioButton(IO33); // Button connected to pin IO33
gpioButton.isPressed(); // Read button state

IOButton gpioButton(GPIOA); // Button connected to pin GPIOA
gpioButton.isPressed(); // Read button state

IOButton can be used to control external button connected to any GPIO pin. It requires pin number and pin state on button press (for algorithm to know correct button position). All same functions are available as for Button object.

Note: for "longPress" detection to work - only single button can be pressed at a time.

Constructor:

IOButton(pin)

IOButton(pin,pressLevel)

Create button control object.
Parameter:
pin - GPIO pin number
pressLevel - pin state when button is pressed [LOW:HIGH]. Default - LOW. 

IOButton button1(IO33); // Button on pin IO33. LOW when pressed
IOButton button2(IO33, LOW); // Button on pin IO33. LOW when pressed
IOButton button3(IO33, HIGH); // Button on pin IO33. HIGH when pressed