async_button

a library for reading buttons using asyncio

  • Author(s): Phil Underwood

Implementation Notes

Software and Dependencies:

class async_button.SimpleButton(pin: microcontroller.Pin, value_when_pressed: bool, *, pull: bool = True, interval=0.05)

Asynchronous interface to a button or other IO input. This does not create a background task.

Parameters:

  • pin (Pin) – Pin to wait for

  • value_when_pressed (bool) – True if the pin reads high when the key is pressed. False if the pin reads low (is grounded) when the key is pressed.

  • pull (bool) – True if an internal pull-up or pull-down should be enabled on the pin. A pull-up will be used if value_when_pressed is False; a pull-down will be used if it is True. If an external pull is already provided for the pin, you can set pull to False. However, enabling an internal pull when an external one is already present is not a problem; it simply uses slightly more current.

  • interval (float) – How long to wait between checks of whether the button has changed. Default is 0.05s (human experience of “instantaneous” is up to 0.1s). This parameter can be set to zero and the button will be checked as often as possible, although other coroutines will still be able to run.

async pressed()

Wait until button is pressed

async released()

Wait until button is released

class async_button.TaskWrapper(coro: Awaitable, event: asyncio.Event)

Create a task to run coro, then trigger event when finished Shouldn’t really need this but CircuitPython does not have asyncio.wait or Task.result()

Parameters:
done()

Check whether task has completed

Returns:

True if task has completed

result()

Get return value from task

Returns:

Whatever the task returned.

cancel()

Cancel the task :return:

class async_button.Button(pin: microcontroller.Pin, value_when_pressed: bool, *, pull: bool = True, interval: float = 0.020, double_click_max_duration=0.5, long_click_min_duration=2.0, double_click_enable: bool = True, triple_click_enable: bool = False, long_click_enable: bool = False)

This object will monitor the specified pin for changes and will report single, double, triple and long_clicks. It creates a background asyncio process that will monitor the button. The Events chapter in the documentation shows when the various events are triggered

Create the button object and start the background async process, this object must be created only when the asyncio event loop is running

Parameters:

  • pin (Pin) – the pin to be monitored

  • value_when_pressed (bool) – True if the pin reads high when the key is pressed. False if the pin reads low (is grounded) when the key is pressed.

  • pull (bool) – True if an internal pull-up or pull-down should be enabled on the pin. A pull-up will be used if value_when_pressed is False; a pull-down will be used if it is True. If an external pull is already provided for the pins, you can set pull to False. However, enabling an internal pull when an external one is already present is not a problem; it simply uses slightly more current. Default is True.

  • interval (float) – How long we wait between checking the state of the button. Default is 0.02 (20 milliseconds), which is a good value for debouncing.

  • double_click_max_duration (float) – how long in seconds before a second click is registered as a double click (this is also the value used for triple clicks. Default is 0.5 seconds.

  • long_click_min_duration (float) – how long in seconds the button must be pressed before a long_click is triggered. Default is 2 seconds.

  • double_click_enable (bool) – Whether double clicks are detected. Default is True.

  • triple_click_enable (bool) – Whether triple clicks are detected. Default is False.

  • long_click_enable (bool) – Whether long clicks are detected. Default is False.

PRESSED = 1

Button has been pressed

RELEASED = 2

Button has been released

SINGLE = 4

Single click

DOUBLE = 8

Double click

TRIPLE = 16

Triple click

LONG = 32

Long click

ANY_CLICK = (4, 8, 16, 32)

Any of SINGLE, DOUBLE, TRIPLE or LONG

ALL_EVENTS = (1, 2, 4, 8, 16, 32)

Any event

double_click_max_duration

Maximum separation between two clicks to register as double in seconds (default is 0.5s)

long_click_min_duration

Minimum duration for a click to register as a long click in seconds. Default is 2s

async wait(click_types: int | Sequence[int] = ALL_EVENTS)

Wait for the first of the specified events.

Parameters:

click_types ((List[int] | int)) – List of events to listen for. You can also pass a single event type in. Default is to listen for all events.

Returns:

A list of the clicks that actually happened.

Example:
>>> async def get_click():
>>>     # wait for a double or triple click
>>>     clicks = await button.wait((Button.DOUBLE, Button.TRIPLE))
>>>     if Button.DOUBLE in clicks:
>>>         # do something
async wait_for_click()

Wait for any click and return it

Returns:

Which click happened i.e. one of SINGLE, DOUBLE, TRIPLE or LONG

deinit()

Deinitialise object and stop the background task

class async_button.MultiButton(**kwargs)

This class allows you to await the first click from any of two or more buttons

Parameters:

kwargs – pass each button that you want to be able to listen to with its name

Example:
>>> multi = MultiButton(a = button_a, b=button_b)
>>> button, result = await multi.wait(a=Button.SINGLE, b= (Button.DOUBLE, Button.LONG))
>>> # Long click on button B
>>> print(button, result) # "b", Button.Long
async wait(**kwargs)

Wait for any specified clicks

Parameters:

kwargs – pass by keyword what clicks you want to listen for

Returns:

button, click type

Example:
>>> multi = MultiButton(a = button_a, b=button_b)
>>> button, result = await multi.wait(a=Button.SINGLE, b= (Button.DOUBLE, Button.LONG))
>>> # Long click on button B
>>> print(button, result) # "b", Button.Long