Metadata-Version: 2.1
Name: rpi-rotary-encoder
Version: 0.1.0
Summary: A rotary encoder library for the raspberry pi that "just works"
License: MIT
Author: Momo Eissenhauer
Author-email: momo.eissenhauer@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: rotary-encoder-gpio-core (>=0.1.0,<0.2.0)
Description-Content-Type: text/markdown

# Rotary Encoder

A rotary encoder package for the Raspberry pi that "just works".

Tested with a [KY-040 Rotary Encoder](https://www.rcscomponents.kiev.ua/datasheets/ky-040-datasheet.pdf) on a Raspberry pi 3 B+

## Installation

Install via pip:
```
pip install rpi-rotary-encoder
```

## Example

```python
import rotary_encoder


counter = 0

def increment():
    global counter
    counter += 1
    print(counter)


def decrement():
    global counter
    counter -= 1
    print(counter)


with rotary_encoder.connect(
    clk_pin=20,
    dt_pin=21,
    on_clockwise_turn=increment,
    on_counter_clockwise_turn=decrement,
):
    input("press enter to quit\n")
```


## Advanced Usage

When calling `connect` you can pass in an optional `callback_handling` argument. This controls how the callbacks are executed. The options are:

- `CallbackHandling.GLOBAL_WORKER_THREAD`: The default. Callbacks are called in a global worker thread. This means all callbacks across all rotary encoders are called in the same thread. This ensures that all callbacks are executed sequentially. This is the least likely to cause problems with race conditions.
- `CallbackHandling.LOCAL_WORKER_THREAD`: Similar to the above, except that each individual rotary encoders callbacks are executed on a different thread. This means that sequential execution of the callbacks of one encoder is still guaranteed, but not across several encoders. The responsiveness of the individual encoders may be slightly improved.
- `CallbackHandling.SPAWN_THREAD`: Spawn a new thread for every callback. The execution of your callbacks is no longer sequential, and you will have to make sure that your callbacks are thread safe.
- `CallbackHandling.GPIO_INTERUPT_THREAD`:  Not recommended. Similar in behavior to `CallbackHandling.SPAWN_THREAD` except that the threads are spawned by the underlying C extension library.

## Similar Projects:

The [pigpio-encoder](https://pypi.org/project/pigpio-encoder/) is a similar library based on pigpio.

