9. Orangutan Pushbuttons

Reference

static unsigned char OrangutanPushbuttons::getSingleDebouncedPress(unsigned char buttons)

unsigned char get_single_debounced_button_press(unsigned char buttons)

This is a non-blocking function that makes it very easy to perform button-triggered activities from within your main loop. It uses a four-step finite-state machine to detect the transition of a button press and returns the value of the pressed button once such a transition is detected. It requires the button to be up for at least 15 ms and then down for at least 15 ms before it reports the press, at which point it resets and will not report another button until the next press is detected. This process takes care of button debouncing, so a bouncy button press will still only result in one reported press. This function should be called repeatedly (and often) in a loop with the same button mask argument buttons (i.e. do not call this function multiple times in the same loop with different button mask arguments).

The argument buttons can be a combination of the keywords TOP_BUTTON, MIDDLE_BUTTON, and BOTTOM_BUTTON (intended for use with the Orangutans) or BUTTON_A, BUTTON_B, and BUTTON_C (intended for use with the 3pi) separated by the bitwise OR operator | or the addition operator +. You can use the keyword ANY_BUTTON to wait for any of the three buttons to be pressed. The returned value is the ID of the button (or buttons) that was pressed. Calls to this function can be combined with calls to get_single_debounced_button_release() in the same loop.

The pushbuttons2 example shows how this function can be used to trigger events in your main loop.

Example

while (1)  // main loop (loop forever)
{
  // put main loop code here

  // the following line immediately returns 0 unless a button has just been pressed
  unsigned char button = get_single_debounced_button_press(ANY_BUTTON);
  // C++: unsigned char button = OrangutanPushbuttons::getSingleDebouncedPress(ANY_BUTTON);

  if (button & TOP_BUTTON)  // if top button pressed
    function1();
  if (button & MIDDLE_BUTTON)  // if middle button pressed
    function2();
  if (button & BOTTOM_BUTTON)  // if bottom button pressed
    function3();
}

static unsigned char OrangutanPushbuttons::getSingleDebouncedRelease(unsigned char buttons)

unsigned char get_single_debounced_button_release(unsigned char buttons)

This is a non-blocking function that makes it very easy to perform button-triggered activities from within your main loop. It uses a four-step finite-state machine to detect the transition of a button release and returns the value of the released button once such a transition is detected. It requires the button to be down for at least 15 ms and then up for at least 15 ms before it reports the release, at which point it resets and will not report another button until the next release is detected. This process takes care of button debouncing, so a bouncy button release will still only result in one reported release. This function should be called repeatedly (and often) in a loop with the same button mask argument buttons (i.e. do not call this function multiple times in the same loop with different button mask arguments). The returned value is the ID of the button (or buttons) that was pressed. Calls to this function can be combined with calls to get_single_debounced_button_press() in the same loop.

The pushbuttons2 example shows how this function can be used to trigger events in your main loop.

static unsigned char OrangutanPushbuttons::waitForPress(unsigned char buttons)

unsigned char wait_for_button_press(unsigned char buttons)

This function will wait for any of the buttons specified by buttons to be pressed, at which point execution will return. The argument buttons can be a combination of the keywords TOP_BUTTON, MIDDLE_BUTTON, and BOTTOM_BUTTON (intended for use with the Orangutans) or BUTTON_A, BUTTON_B, and BUTTON_C (intended for use with the 3pi) separated by the bitwise OR operator | or the addition operator +. You can use the keyword ANY_BUTTON to wait for any of the three buttons to be pressed. The returned value is the ID of the button that was pressed. Note that this method takes care of button debouncing.

Example:

unsigned char button = wait_for_button_press(TOP_BUTTON | BOTTOM_BUTTON);

unsigned char button = OrangutanPushbuttons::waitForPress(TOP_BUTTON | BOTTOM_BUTTON);

static unsigned char OrangutanPushbuttons::waitForRelease(unsigned char buttons)

unsigned char wait_for_button_release(unsigned char buttons)

This function will wait for any of the buttons specified by buttons to be released, at which point execution will return. The returned value is the ID of the button that was released. Note that this method takes care of button debouncing. Since the default state of the user buttons is up, you will typically not want to supply this function with the ANY_BUTTON argument, as execution will return immediately if any one of the three buttons is up. Rather, a common argument to this function is the return value of a function that detects a button press.

Example

unsigned char button = wait_for_button_press(ANY_BUTTON);
someFunction();  // do something as soon as button is pressed
wait_for_button_release(button);  // wait for pressed button to be released

unsigned char button = OrangutanPushbuttons::waitForPress(ANY_BUTTON);
someFunction();  // do something as soon as button is pressed
OrangutanPushbuttons::waitForRelease(button);  // wait for pressed button to be released

static unsigned char OrangutanPushbuttons::waitForButton(unsigned char buttons)

unsigned char wait_for_button(unsigned char buttons)

This function will wait for any of the buttons specified by buttons to be pressed, and then it will wait for the pressed button to be released, at which point execution will return. The returned value is the ID of the button that was pressed and released. Note that this method takes care of button debouncing.

static unsigned char OrangutanPushbuttons::isPressed(unsigned char buttons)

unsigned char button_is_pressed(unsigned char buttons)

This function will returns all of the buttons specified by buttons that are currently pressed. For example, if you call button_is_pressed(ANY_BUTTON) and both the top and middle buttons are pressed, the return value will be (TOP_BUTTON | MIDDLE_BUTTON). If none of the specified buttons is pressed, the returned value will be 0. The argument buttons can refer to a single button or multiple buttons (see the wait_for_button_press() function above). This function returns the immediate button input state and hence standard debouncing precautions should be taken by the user.