Represents a single hardware button. Allows for button press event tracking.
Version: 111fc68
Canonical type name: codal::Button
Defined within: inc/drivers/Button.h
A very common use case for a generic button is to perform an event when a button is pressed down. This can be achieved one of two ways, either through hooking a function to the CODAL event system, or simply by checking the result of isPressed() (in a loop if you wish to wait for the press to occur). For this example, we will use the A button as defined from MicroBit for ease of use, instead of defining our own, but the process is identical. To detect if a button is currently pressed, we can simply do:
if (uBit.buttonA.isPressed()) {
uBit.display.scroll("A button!");
}
Pretty simple. If we want to avoid having to deal with looping and constantly checking for our event to occur, we can also schedule it via. the event system. Here we’ll set up our event connections in main() and then defer execution to the scheduler to process events.
//Do something on button A being pressed.
void onButtonA(MicroBitEvent)
{
uBit.display.scroll("A button!");
}
int main()
{
uBit.init();
uBit.messageBus.listen(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK, onButtonA);
//Release this fiber and enter the scheduler.
//If main() exits, the entire program will halt execution, which is not what we're aiming for.
//Doing this will avoid exiting, and simply release execution to the scheduler and idle until events appear.
release_fiber();
}
This will run onButtonA on every click trigger from button A on the micro:bit via. the event system.
Button(Pin &pin, uint16_t id, ButtonEventConfiguration eventConfiguration = DEVICE_BUTTON_ALL_EVENTS, ButtonPolarity polarity = ACTIVE_LOW, PullMode mode = PullMode::None);
Creates a generic button representation for the given pin, setting its micro:bit event system ID to the provided ID.
Parameters
- pin (Pin&): The pin this button is connected to.
- eventConfiguration (ButtonEventConfiguration): The events that will be generated by this button.
- polarity (ButtonPolarity): The active state of the button pin. By default, low.
- mode (PullMode): The pin’s configured pulldown/pullups. By default, none.
virtual int isPressed();
Tests whether the button is currently pressed down.
Returns - If the button is pressed, 1. If not, 0.
void setEventConfiguration(ButtonEventConfiguration config);
Configures the types of events the button should fire, given a ButtonEventConfiguration.
Parameters
- config (ButtonEventConfiguration): The types of events that will be generated by this button.
void periodicCallback();
This is a public function, however there is no need, and no obvious use case, for this to be called manually by the user. Avoid calling this manually and leave the work to the automatic update tick.
void wakeOnActive(int wake);
Configures whether pressing this button should trigger power manager wake-up if it is in a sleep mode.
Parameters
- wake (int): Whether the button should trigger wake-up. If yes, pass 1. If no, pass 0.
int isWakeOnActive();
Returns whether the button is currently set to trigger power manager wake-up on press.
Returns - If wake-up on press is enabled, 1. If not, 0.
Pin &_pin;
The pin that this button represents/is connected to.
The types of events that a button will emit.
DEVICE_BUTTON_SIMPLE_EVENTS will emit only the press, release and hold events.DEVICE_BUTTON_ALL_EVENTS will release the events from SIMPLE_EVENTS, in addition to the long click and click events.enum ButtonEventConfiguration
{
DEVICE_BUTTON_SIMPLE_EVENTS,
DEVICE_BUTTON_ALL_EVENTS
};
Represents the state at which a button is to be considered “active”. ACTIVE_LOW will mean the button is active when the pin is low, and ACTIVE_HIGH will mean the button is active when the pin is high.
enum ButtonPolarity
{
ACTIVE_LOW = 0,
ACTIVE_HIGH = 1
};
class Button : public AbstractButton
{
public:
Pin &_pin;
Button(Pin &pin, uint16_t id, ButtonEventConfiguration eventConfiguration = DEVICE_BUTTON_ALL_EVENTS, ButtonPolarity polarity = ACTIVE_LOW, PullMode mode = PullMode::None);
virtual int isPressed();
void setEventConfiguration(ButtonEventConfiguration config);
void periodicCallback();
void wakeOnActive(int wake);
int isWakeOnActive();
};