piripherals.button module

Things that have to do with buttons, digital inputs.

Use GPIO pins as button inputs with debouncing and multi-click and hold-detection.

class piripherals.button.ClickButton(pin=0, when_clicked=None, when_held=None, click_time=0.025, double_click_time=0.2, hold_time=1, hold_repeat=0, name=None)[source]

Bases: object

Representation of a button with multi-click and hold-detection.

This was inspired by http://www.mathertel.de/Arduino/OneButtonLibrary.aspx, but extended to n-clicks and click-hold.

Note

Most debouncing code out there is wrong. The debounce functionality of RPi.GPIO just suppresses events, but does not debounce. Debouncing correctly in software is tricky but doable. Read this http://www.ganssle.com/debouncing.htm.

This button can be bound to GPIO pins but it can be used with other input sources as well.

What is click, hold, up/down, pressed/released?

The state of the button is updated by calling update() with True or False as argument (equivalently just calling the button, calling press(), release()). Updating the state to True is called press, updating the state to False is called release.

The state is changed when update() was called with a parameter different from the previous call. If the state did not change for a time > click_time, the button in considered down (stated changed to pressed) or up (state changed to released). This effectivly debounces the input. The final state wins, but quick jumps between states are filtered out.

The button is considered clicked when

  1. it was pressed for > click_time (click is counted)
  2. and then released for > double_click_time (click is fired)

If it was pressed again after beeing released within < double_click_time, another click may be counted (start again at 1.). This way n-clicks can be detected.

The button is considered held when it was pressed for > hold_time (enter hold state). There might have been preceding clicks, that have been counted, but not fired. This way we get n-hold, with n beeing the number of clicks preceding the hold. Hold events are fired as long as the button stays held with hold_repeat delay, if hold_repeat > 0.

Attention

Setting when_clicked or when_held disables any handlers registered with on_click() or on_hold(). So there is either a single click/hold handler or a handler for each type of click/hold.

Parameters:
  • pin (int) – BCM pin to bind to, 0 = do not use GPIO
  • when_clicked (callable(n)) – click handler, n = # of clicks
  • when_held (callable(n)) – hold handler, n = # of clicks before hold
  • click_time (float) – seconds button needs to stay in pressed/released state to consider it a click (this does the debouncing)
  • double_click_time (float) – max. seconds between clicks to count them as double clicks (or triple, or quadruple, …)
  • hold_time (float) – seconds in pressed state after which button is considered held
  • hold_repeat (float) – seconds between repeated hold events, when button stays held, 0 = disable hole repeat
  • name (str) – name of the button for str() and debugging
bind(pin, low_active=1, pullup=1, delay=0.01, count=100)[source]

bind to GPIO pin.

Note

The state of the GPIO will be polled regularly, but the polling is only started on demand after edge detection and runs for a limited time.

Parameters:
  • pin (int) – BCM pin number
  • low_active (bool) – low means pressed
  • pullup (int) – 1 = pullup, -1 = pulldown, 0 = nothing
  • delay (float) – delay between polls in seconds
  • count (int) – # of polls after button was released, this allows the polling to be paused if the button is untouched
is_down()[source]

check if button is down, respecting click_time

The button itself evaluated as bool(button) is equivalent to is_down():

Returns:if down for > click_time
Return type:bool
is_held()[source]

check if button is held, respecting hold_time

Returns:if down for > hold_time
Return type:bool
is_up()[source]

check if button is up, respecting click_time

Returns:if up for > click_time
Return type:bool
on_click(n, callback, *args, **kwargs)[source]

register a click handler.

Parameters:
  • n (int) – # of click to register the handler with, see when_clicked()
  • callback (callable) – the handler
  • *args – args passed to handler
  • **kwargs – kwargs passed to handler
on_hold(n, callback, *args, **kwargs)[source]

register a hold handler.

Parameters:
  • n (int) – # of click to register the handler with, see when_held()
  • callback (callable) – the handler
  • *args – args passed to handler
  • **kwargs – kwargs passed to handler
press()[source]

update() with pressed=True

release()[source]

update() with pressed=False

update(pressed, now=None)[source]

update state.

When bound to GPIO this called automatically. You need to call this, when you want bind this button a different input source.

This can (and must be) call ed repeatedly (even with teh same pressed state) to allow the click and hold detection to work.

The button itself is callable, calling the button is equivalent to call update().

Parameters:
  • pressed (bool) – True = button is down, False = button is up
  • now (float) – time when it change state (optional)
when_clicked(n)[source]

fired when clicked.

Parameters:n (int) – # of clicks, 1 = single click, 2 = double click, …
when_held(n)[source]

fired when held.

Parameters:n (int) – # of clicks before hold, 0 = hold, 1 = click + hold 2 = double click + hold