uBit.button[A,B,AB]

Overview

The two front-facing buttons on the micro:bit can be easily accessed through uBit.buttonA for the left button, and uBit.buttonB for the right button. You can also access an object representing the simulataneous pressing of buttons A and B through uBit.buttonAB.

Note

The three button classes share the same API and eventing scheme.

Hardware buttons are notoriously renowned for generating multiple open/close transitions for what a user perceives as a single press, which can make depending on the raw input of a button unreliable. To combat this, a technique called 'debouncing' is used, which periodically polls the state of the button, when a transition from open to close (and vice versa) is detected. Through periodically polling the button, we get a more accurate representation of the state of a button.

The buttons are debounced in software and provide a number of events that can be used to detect different variations of presses; see the available events.

Using the buttons

In the majority of cases, you do not need to concern yourself with the button classes; rather, you can subscribe to events on the message bus and act accordingly.

The following example shows how you could play a sound when the user clicks buttons A and B at the same time. This could, of course, be any of the buttons - just substitute the correct button name.

Example

void play_sound(Event) {
    uBit.audio.soundExpressions.play("hello");
}

int main() {
    uBit.init();
    uBit.messageBus.listen(DEVICE_ID_BUTTON_AB, DEVICE_BUTTON_EVT_CLICK, play_sound);
}

Note

Learn more about events and handlers on the message bus page.

Learn more about playing sounds on the micro:bit on the uBit.audio page.

Message Bus Info

Message Bus ID

Constant	Value
DEVICE_ID_BUTTON_A	1
DEVICE_ID_BUTTON_B	2
DEVICE_ID_BUTTON_AB	3

Message Bus Events

Constant	Value
DEVICE_BUTTON_EVT_DOWN	1
DEVICE_BUTTON_EVT_UP	2
DEVICE_BUTTON_EVT_CLICK	3
DEVICE_BUTTON_EVT_LONG_CLICK	4
DEVICE_BUTTON_EVT_HOLD	5
DEVICE_BUTTON_EVT_DOUBLE_CLICK	6

API

MultiButton

MultiButton(

uint16_t

button1,

uint16_t

button2,

uint16_t

id)

Description

Constructor.

Create a representation of a virtual button, that generates events based upon the combination of two given buttons.

Parameters

uint16_t

button1 - the unique ID of the first button to watch.

uint16_t

button2 - the unique ID of the second button to watch.

uint16_t

id - the unique EventModel id of this MultiButton instance.

Example

 multiButton(DEVICE_ID_BUTTON_A, DEVICE_ID_BUTTON_B, DEVICE_ID_BUTTON_AB); 

---

isPressed

int

isPressed

()

Description

Tests if this MultiButton instance is virtually pressed.

Returns

1 if both physical buttons are pressed simultaneously.

Example

 if(buttonAB.isPressed()) 
 display.scroll("Pressed!"); 

---

setEventConfiguration

void

setEventConfiguration

(

ButtonEventConfiguration

config)

Description

Changes the event configuration of this button to the given ButtonEventConfiguration. All subsequent events generated by this button will then be informed by this configuration.

Parameters

ButtonEventConfiguration

config - The new configuration for this button. Legal values are DEVICE_BUTTON_ALL_EVENTS or DEVICE_BUTTON_SIMPLE_EVENTS.

Example

 // Configure a button to generate all possible events. 
 buttonAB.setEventConfiguration(DEVICE_BUTTON_ALL_EVENTS); 

 // Configure a button to suppress DEVICE_BUTTON_EVT_CLICK and DEVICE_BUTTON_EVT_LONG_CLICK events. 
 buttonAB.setEventConfiguration(DEVICE_BUTTON_SIMPLE_EVENTS); 

---

isPressed

int

isPressed

()

Description

Tests if this Button is currently pressed.

Returns

1 if this button is pressed, 0 otherwise.

Example

 if(buttonA.isPressed()) 
 display.scroll("Pressed!"); 

---

wasPressed

int

wasPressed

()

Description

Determines if this button has been pressed.

Returns

the number of time this button has been pressed since the last time wasPressed() has been called.

Example

 if(buttonA.wasPressed()) 
 display.scroll("Pressed!"); 

---

enable

void

enable

()

Description

Enables this button. Buttons are normally created in an enabled state, but use this function to re-enable a previously disabled button.

---

disable

void

disable

()

Description

Disable this button. Buttons are normally created in an enabled state. Use this function to disable this button.

---

Component Constructor

Advanced users only

Do not use this unless you really know what you're doing. It's usually best to use uBit.

void

disable

()

Description

Disable this button. Buttons are normally created in an enabled state. Use this function to disable this button.

---