https://github.com/egj-moorington/circuitpython_button_handler

A CircuitPython helper library that handles different types of button presses.
https://github.com/egj-moorington/circuitpython_button_handler

circuitpython

Last synced: 2 months ago
JSON representation

A CircuitPython helper library that handles different types of button presses.

• Host: GitHub
• URL: https://github.com/egj-moorington/circuitpython_button_handler
• Owner: EGJ-Moorington
• License: mit
• Created: 2024-08-04T22:42:51.000Z (5 months ago)
• Default Branch: main
• Last Pushed: 2024-09-02T13:27:29.000Z (4 months ago)
• Last Synced: 2024-10-09T22:40:59.536Z (2 months ago)
• Topics: circuitpython
• Language: Python
• Homepage:
• Size: 56.6 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        
Introduction

============

.. image:: https://readthedocs.org/projects/circuitpython-button-handler/badge/?version=latest

    :target: https://circuitpython-button-handler.readthedocs.io/

    :alt: Documentation Status

.. image:: https://img.shields.io/discord/327254708534116352.svg

    :target: https://adafru.it/discord

    :alt: Discord

.. image:: https://github.com/EGJ-Moorington/CircuitPython_Button_Handler/workflows/Build%20CI/badge.svg

    :target: https://github.com/EGJ-Moorington/CircuitPython_Button_Handler/actions

    :alt: Build Status

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json

    :target: https://github.com/astral-sh/ruff

    :alt: Code Style: Ruff

This helper library simplifies the usage of buttons with CircuitPython, by detecting and differentiating button inputs, returning a set of the inputs and calling their corresponding functions.

Dependencies

=============

This driver depends on:

* `Adafruit CircuitPython `_

Please ensure all dependencies are available on the CircuitPython filesystem.

This is easily achieved by downloading

`the Adafruit library and driver bundle `_

or individual libraries can be installed using

`circup `_.

Installing from PyPI

=====================

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from

PyPI `_.

To install for current user:

.. code-block:: shell

    pip3 install circuitpython-button-handler

To install system-wide (this may be required in some cases):

.. code-block:: shell

    sudo pip3 install circuitpython-button-handler

To install in a virtual environment in your current project:

.. code-block:: shell

    mkdir project-name && cd project-name

    python3 -m venv .venv

    source .env/bin/activate

    pip3 install circuitpython-button-handler

Installing to a Connected CircuitPython Device with Circup

==========================================================

Make sure that you have ``circup`` installed in your Python environment.

Install it with the following command if necessary:

.. code-block:: shell

    pip3 install circup

With ``circup`` installed and your CircuitPython device connected use the

following command to install:

.. code-block:: shell

    circup install button_handler

Or the following command to update an existing version:

.. code-block:: shell

    circup update

Usage Example

=============

This simple script showcases the usage of this library using a single button.

+---------------+

| Button wiring |

+===============+

| GND           |

+---------------+

| D9            |

+---------------+

.. code-block:: python

    import time

    import board

    from keypad import Keys

    from button_handler import ButtonHandler, ButtonInput

    def double_press():

        print("Double press detected!")

    def short_press():

        print("Short press detected!")

    def long_press():

        print("Long press detected!")

    def hold():

        print("The button began being held down!")

    actions = {

        ButtonInput(ButtonInput.DOUBLE_PRESS, callback=double_press),

        ButtonInput(ButtonInput.SHORT_PRESS, callback=short_press),

        ButtonInput(ButtonInput.LONG_PRESS, callback=long_press),

        ButtonInput(ButtonInput.HOLD, callback=hold),

    }

    scanner = Keys([board.D9], value_when_pressed=False)

    button_handler = ButtonHandler(scanner.events, actions)

    while True:

        button_handler.update()

        time.sleep(0.0025)

Documentation

=============

API documentation for this library can be found on `Read the Docs `_.

For information on building library documentation, please check out

`this guide `_.

Contributing

============

Contributions are welcome! Please read our `Code of Conduct

`_

before contributing to help this project stay welcoming.