MicroPython-Button

An easy to use MicroPython library to handle Buttons and other devices with digital (LOW/HIGH) output.

Instantiate an object of this Class to easily handle its behaviour via PRESSED and RELEASED events.

The instance supports a callback or just retrieving its active state using instance.active. State will be True when activated (pressed) and False when deactivated (released) or not yet pressed.

By default the object instance assumes a pull-down (external or internal) resistor, hence the rest_state is False (LOW). In case of pull-up (external or internal), when the Pin is triggered shorting it to GND, create an instance adding the argument rest_state = True

In addition it is possible to leverage internal pull-up_ or pull-down resistors if the MicroPython implementation supports it. By simply adding internal_pullup = True or internal_pulldown = True to the initialisation arguments, they will be internally set. This also renders the need for rest_state redundant, since it will be set based on the above two options for pull-up/down.

The library supports debouncing with a default of 50ms, but for more finicky/noisy switches such as tilt sensors, a longer time to stabilise can be passed via the debounce_time parameter (see the dual_debounced_button.py example).

Installation

The library can be installed in several ways:

Manual

Simply copy the file mp_button.py to your board's /lib folder (or to any location which is part of the search path)

mip

1. Make sure your board has a connection to internet
2. Open a REPL session and run the following commands

import mip
mip.install('github:ubidefeo/MicroPython-Button')

mpremote mip

1. Make sure you have mpremote installed
2. Connect the board to your computer
3. Open a shell and run mpremote mip install "github:ubidefeo/MicroPython-Button"

Examples

Button connected to GPIO17 with an external pull-down resistor. When using external pull-down resistors the extra argument for rest_state is not required, since rest_state defaults to False. Polling the state, not using a callback.

from mp_button import Button
my_button = Button(17)

while(True):
    my_button.update()
    print(my_button.active)

Button connected to GPIO17 with an external pull-up resistor. When using external pull-up resistors the extra argument for rest_state is mandatory, since rest_state defaults to False and a pull-up would set it to True. Polling the state, not using a callback.

from mp_button import Button
my_button = Button(17, rest_state = True)

while(True):
    my_button.update()
    print(my_button.active)

Button connected to GPIO17 with an external pull-down resistor. When using external pull-down resistors the extra argument for rest_state is not required, since rest_state defaults to False. Using a callback function.

from mp_button import Button

def button_action(pin, event):
    print(f'Button connected to Pin {pin} has been {event}')
    if event == Button.PRESSED:
        print('Button pressed')
    if event == Button.RELEASED:
        print('Button released')

my_button = Button(17, callback = button_action)
while(True):
    my_button.update()

Button connected to GPIO17 with an external pull-up resistor. When using external pull-up resistors the extra argument for rest_state is mandatory, since rest_state defaults to False and a pull-up would set it to True. Using a callback function.

from mp_button import Button

def button_action(pin, event):
    print(f'Button connected to Pin {pin} has been {event}')
    if event == Button.PRESSED:
        print('Button pressed')
    if event == Button.RELEASED:
        print('Button released')

my_button = Button(17, rest_state = True, callback = button_action)

while(True):
    my_button.update()
  

Button connected to GPIO17, internal pull-down resistor enabled. The argument internal_pulldown = True will override the default rest_state, hence passing in rest_state = False is not required and would anyway be overridden. Using a callback function.

from mp_button import Button

def button_action(pin, event):
    print(f'Button connected to Pin {pin} has been {event}')
    if event == Button.PRESSED:
        print('Button pressed')
    if event == Button.RELEASED:
        print('Button released')

my_button = Button(17, callback = button_action, internal_pulldown = True)

while(True):
    my_button.update()
  

Button connected to GPIO17, internal pull-up resistor enabled. The argument internal_pullup = True will override the default rest_state, hence passing in rest_state = True is not required and would anyway be overridden. Using a callback function.

from mp_button import Button

def button_action(pin, event):
    print(f'Button connected to Pin {pin} has been {event}')
    if event == Button.PRESSED:
        print('Button pressed')
    if event == Button.RELEASED:
        print('Button released')

my_button = Button(17, callback = button_action, internal_pullup = True)

while(True):
    my_button.update()