Buttons

Overview

The micro:bit has two forward facing buttons either side of the display, buttonA and buttonB. These are intuitively exposed on the MicroBit object as uBit.buttonA and uBit.buttonB. A third button, uBit.buttonAB is used to detect the combined input of buttonA and buttonB, and is an instance of the class MicroBitMultiButton.

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.

MicroBitButtons and MicroBitMultiButtons are debounced in software and provide a number of events that can be used to detect different variations of presses.

The MicroBitButton debouncing mechanism is used to provide resistive touch sensing on MicroBitPins and could also be used on external 'button-like' input if required.

Message Bus ID

Constant Value
MICROBIT_ID_BUTTON_A 1
MICROBIT_ID_BUTTON_B 2

Message Bus Events

Constant Value
MICROBIT_BUTTON_EVT_DOWN 1
MICROBIT_BUTTON_EVT_UP 2
MICROBIT_BUTTON_EVT_CLICK 3
MICROBIT_BUTTON_EVT_LONG_CLICK 4
MICROBIT_BUTTON_EVT_HOLD 5
MICROBIT_BUTTON_EVT_DOUBLE_CLICK 6

API

Constructor


MicroBitButton(
PinName
name,
uint16_t
id)

Description

Constructor.

Create a software representation of a button.

Parameters

PinName
name - the physical pin on the processor that should be used as input.

uint16_t
id - the ID of the new MicroBitButton object.

Example
 buttonA(MICROBIT_PIN_BUTTON_A, MICROBIT_ID_BUTTON_A); 


MicroBitButton(
PinName
name,
uint16_t
id,
MicroBitButtonEventConfiguration
eventConfiguration)

Description

Constructor.

Create a software representation of a button.

Parameters

PinName
name - the physical pin on the processor that should be used as input.

uint16_t
id - the ID of the new MicroBitButton object.

MicroBitButtonEventConfiguration
eventConfiguration - Configures the events that will be generated by this MicroBitButton instance. Defaults to MICROBIT_BUTTON_ALL_EVENTS.

Example
 buttonA(MICROBIT_PIN_BUTTON_A, MICROBIT_ID_BUTTON_A); 


MicroBitButton(
PinName
name,
uint16_t
id,
MicroBitButtonEventConfiguration
eventConfiguration,
PinMode
mode)

Description

Constructor.

Create a software representation of a button.

Parameters

PinName
name - the physical pin on the processor that should be used as input.

uint16_t
id - the ID of the new MicroBitButton object.

MicroBitButtonEventConfiguration
eventConfiguration - Configures the events that will be generated by this MicroBitButton instance. Defaults to MICROBIT_BUTTON_ALL_EVENTS.

PinMode
mode - the configuration of internal pullups/pulldowns, as defined in the mbed PinMode class. PullNone by default.

Example
 buttonA(MICROBIT_PIN_BUTTON_A, MICROBIT_ID_BUTTON_A); 

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!"); 

setEventConfiguration


void
setEventConfiguration
(
MicroBitButtonEventConfiguration
config)

Description

Changes the event configuration used by this button to the given MicroBitButtonEventConfiguration.

All subsequent events generated by this button will then be informed by this configuraiton.

Parameters

MicroBitButtonEventConfiguration
config - The new configuration for this button. Legal values are MICROBIT_BUTTON_ALL_EVENTS or MICROBIT_BUTTON_SIMPLE_EVENTS.

Example
 // Configure a button to generate all possible events. 
 buttonA.setEventConfiguration(MICROBIT_BUTTON_ALL_EVENTS); 

 // Configure a button to suppress MICROBIT_BUTTON_EVT_CLICK and MICROBIT_BUTTON_EVT_LONG_CLICK events. 
 buttonA.setEventConfiguration(MICROBIT_BUTTON_SIMPLE_EVENTS);