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¶
PinNamename - the physical pin on the processor that should be used as input.uint16_tid - 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¶
PinNamename - the physical pin on the processor that should be used as input.uint16_tid - the ID of the new MicroBitButton object.MicroBitButtonEventConfigurationeventConfiguration - 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¶
PinNamename - the physical pin on the processor that should be used as input.uint16_tid - the ID of the new MicroBitButton object.MicroBitButtonEventConfigurationeventConfiguration - Configures the events that will be generated by this MicroBitButton instance. Defaults to MICROBIT_BUTTON_ALL_EVENTS.PinModemode - 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¶
MicroBitButtonEventConfigurationconfig - 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);