{"id":14978097,"url":"https://github.com/vash3d/pigpio_encoder","last_synced_at":"2025-10-28T08:31:49.071Z","repository":{"id":50503416,"uuid":"164038694","full_name":"vash3d/pigpio_encoder","owner":"vash3d","description":"Python module for the KY040 rotary encoder.","archived":false,"fork":false,"pushed_at":"2022-07-29T16:01:14.000Z","size":62,"stargazers_count":14,"open_issues_count":9,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-09-29T01:01:19.833Z","etag":null,"topics":["gpio","python-library","python3","raspberry","raspberry-pi-3","rotary","rotary-encoder","switch"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vash3d.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-04T00:51:37.000Z","updated_at":"2023-11-07T22:39:52.000Z","dependencies_parsed_at":"2022-09-19T11:00:48.679Z","dependency_job_id":null,"html_url":"https://github.com/vash3d/pigpio_encoder","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vash3d%2Fpigpio_encoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vash3d%2Fpigpio_encoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vash3d%2Fpigpio_encoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vash3d%2Fpigpio_encoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vash3d","download_url":"https://codeload.github.com/vash3d/pigpio_encoder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219859904,"owners_count":16556031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gpio","python-library","python3","raspberry","raspberry-pi-3","rotary","rotary-encoder","switch"],"created_at":"2024-09-24T13:56:51.614Z","updated_at":"2025-10-28T08:31:43.788Z","avatar_url":"https://github.com/vash3d.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pigpio Encoder\n\nVersion: 0.2.4\n### Requires Python 3\n\n#### Python module for the KY040 rotary encoder.\nThis module has been developed for quickly interface a rotary encoder with Raspberry Pi.\nIt's based on the [pigpio library](http://abyz.me.uk/rpi/pigpio/python.html) (cause it proved to be faster than rpi.GPIO or gpiozero libraries) so you need to install pigpio library and run pigpio daemon before starting your script.\n\n## Features\n- Easy to setup callback functions for the Rotary Encoder and the Switch.\n- The Rotary Encoder has customizable min and max values (default 0-100).\n- The Rotary Encoder increase/decrease value is customizable (default 1).\n- The Switch can be activated or not.\n- The Switch can have two different functions for short press or long press.\n- Both Rotary and Switch have a customizable debounce value (default 300ms)\n\n## Installation\n- Install the pigpio library *(check [pigpio documentation](http://abyz.me.uk/rpi/pigpio/download.html) for alternative installation method)*\n - `sudo apt-get update`\n - `sudo apt-get install pigpio python-pigpio python3-pigpio`\n- Install the pigpio_encoder library\n - `python3 -mpip install pigpio_encoder` (consider add --user option)\n- start pigpio daemon\n - `sudo pigpiod`\n\n## How to use\n- import the module\n    ```python\n    from pigpio_encoder.rotary import Rotary\n    ```\n- create a callback function for the Rotary Encoder counter.\n    \u003e You must pass a positional argument to retrieve the counter value.\n\n    ```python\n    def rotary_callback(counter):\n        # some action with counter...\n    ```\n\n- create a callback function for Up-Rotation events.\n\n    ```python\n    def up_callback():\n        # some action if rotated upward\n    ```\n\n- create a callback function for Down-Rotation events.\n\n    ```python\n    def down_callback():\n        # some action if rotated downward\n    ```\n\n- create callbacks functions for the Switch\n    \u003e If you intend to use the switch you must create at least the \"short press\" callback. The \"long press\" callback is necessary if you want to use that feature.\n\n    ```python\n    def sw_short_callback():\n        # some action...\n    ```\n    ```python\n    def sw_long_callback():\n        # some action...\n      ```\n- create the rotary object\n    \u003e here you setup the gpio id as keyword argument. If you don't pass the switch parameter the switch won't be activated.\n\n    ```python\n    my_rotary = Rotary(\n            clk_gpio=\u003cgpio_id of clk signal\u003e,\n            dt_gpio=\u003cgpio_id of dt signal\u003e,\n            sw_gpio=\u003cgpio_id of switch signal\u003e\n            )\n    ```\n- setup the rotary encoder for counting\n    \u003e here you can setup min and max values for the encoder, the increase/decrease value, a debounce value (default 300ms) and the callback function.\n\n    ```python\n    my_rotary.setup_rotary(\n            min=\u003cmin_value\u003e,\n            max=\u003cmax_value\u003e,\n            scale=\u003cscale_value\u003e,\n            debounce=\u003cdebounce_value\u003e,\n            rotary_callback=\u003crotary_callback\u003e\n            )\n    ```\n\n- Optional setup for up and down rotation events\n    \u003e here you can setup min and max values for the encoder, the increase/decrease value, a debounce value (default 300ms) and the callback functions.\n\n    ```python\n    my_rotary.setup_rotary(\n            min=\u003cmin_value\u003e,\n            max=\u003cmax_value\u003e,\n            scale=\u003cscale_value\u003e,\n            debounce=\u003cdebounce_value\u003e,\n            up_callback=\u003cup_callback\u003e\n            down_callback=\u003cdown_callback\u003e\n            )\n    ```\n\n\n- setup the switch\n    \u003e if you have specified the switch pin when creating the encoder object, here you can setup the debounce value, the long press option and the callbacks.\n\n    ```python\n    my_rotary.setup_switch(\n            debounce=\u003cdebounce_value\u003e,\n            long_press=\u003cTrue\u003e,\n            sw_short_callback=\u003csw_short_callback\u003e,\n            sw_long_callback=\u003csw_long_callback\u003e\n            )\n    ```\n\n- start the listener\n    ```python\n    my_rotary.watch()\n    ```\n  Please note that calling .watch() this is only for demostration purposes. It is not neccessary for the encoder to operate it can even cause problems.\n\n\n___\n#### Basic example using default values\n\n```python\nfrom pigpio_encoder.rotary import Rotary\n\n\ndef rotary_callback(counter):\n  print(\"Counter value: \", counter)\n\n\ndef sw_short():\n  print(\"Switch pressed\")\n\n\ndef up_callback():\n  print(\"Up rotation\")\n\n\ndef down_callback():\n  print(\"Down rotation\")\n\n\nmy_rotary = Rotary(clk_gpio=27, dt_gpio=22, sw_gpio=17)\nmy_rotary.setup_rotary(\n  rotary_callback=rotary_callback,\n  up_callback=up_callback,\n  down_callback=down_callback,\n)\nmy_rotary.setup_switch(sw_short_callback=sw_short)\n\nmy_rotary.watch()\n```\n  Please note that calling .watch() this is only for demostration purposes. It is not neccessary for the encoder to operate it can even cause problems.\n\n\n___\n\n#### Example using all the Features\n\n```python\nfrom pigpio_encoder.rotary import Rotary\n\n\ndef rotary_callback(counter):\n  print(\"Counter value: \", counter)\n\n\ndef sw_short():\n  print(\"Switch short press\")\n\n\ndef sw_long():\n  print(\"Switch long press\")\n\n\nmy_rotary = Rotary(\n  clk_gpio=27,\n  dt_gpio=22,\n  sw_gpio=17\n)\nmy_rotary.setup_rotary(\n  min=10,\n  max=300,\n  scale=5,\n  debounce=200,\n  rotary_callback=rotary_callback\n)\nmy_rotary.setup_switch(\n  debounce=200,\n  long_press=True,\n  sw_short_callback=sw_short,\n  sw_long_callback=sw_long\n)\n\nmy_rotary.watch()\n\n```\n  Please note that calling .watch() this is only for demostration purposes. It is not neccessary for the encoder to operate it can even cause problems.\n\n___\n\n## Thanks to...\n- [joan2937](https://github.com/joan2937) for the awesome [pigpio library](https://github.com/joan2937/pigpio)\n- [Raphael Yancey](https://github.com/raphaelyancey) for inspiring me this library with his [similar project](https://github.com/raphaelyancey/pyKY040)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvash3d%2Fpigpio_encoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvash3d%2Fpigpio_encoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvash3d%2Fpigpio_encoder/lists"}