{"id":13580469,"url":"https://github.com/LennartHennigs/ESPRotary","last_synced_at":"2025-04-06T02:31:35.660Z","repository":{"id":28758201,"uuid":"110731893","full_name":"LennartHennigs/ESPRotary","owner":"LennartHennigs","description":"Arduino/ESP library to simplify reading rotary encoder data.","archived":false,"fork":false,"pushed_at":"2023-06-26T04:42:39.000Z","size":97,"stargazers_count":180,"open_issues_count":1,"forks_count":27,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-21T22:03:25.038Z","etag":null,"topics":["arduino","arduino-library","c-plus-plus","embedded","esp32","esp8266","hardware","mbed","rotary-encoder"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LennartHennigs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"lennart0815"}},"created_at":"2017-11-14T18:59:32.000Z","updated_at":"2025-03-10T16:11:58.000Z","dependencies_parsed_at":"2024-08-01T15:52:11.582Z","dependency_job_id":null,"html_url":"https://github.com/LennartHennigs/ESPRotary","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LennartHennigs%2FESPRotary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LennartHennigs%2FESPRotary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LennartHennigs%2FESPRotary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LennartHennigs%2FESPRotary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LennartHennigs","download_url":"https://codeload.github.com/LennartHennigs/ESPRotary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247426022,"owners_count":20937051,"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":["arduino","arduino-library","c-plus-plus","embedded","esp32","esp8266","hardware","mbed","rotary-encoder"],"created_at":"2024-08-01T15:01:51.969Z","updated_at":"2025-04-06T02:31:35.379Z","avatar_url":"https://github.com/LennartHennigs.png","language":"C++","funding_links":["https://ko-fi.com/lennart0815"],"categories":["C++"],"sub_categories":[],"readme":"# ESPRotary\n\nArduino/ESP library to simplify reading rotary encoder data.\n\n- Author: Lennart Hennigs (\u003chttps://www.lennarthennigs.de\u003e)\n- Copyright (C) 2017-2023 Lennart Hennigs.\n- Released under the MIT license.\n\n## Description\n\nThis library allows you read out interactions with a rotary encoder and act on them.\nIt uses callback functions to be notified when the rotary encoder changes.\n\nIt has been tested with Arduino, ESP8266 and ESP32 devices.\n\nTo see the latest changes to the library please take a look at the [Changelog](https://github.com/LennartHennigs/ESPRotary/blob/master/CHANGELOG.md).\n\nIf you find this library helpful please consider giving it a ⭐️ at [GitHub](https://github.com/LennartHennigs/ESPRotary) and/or [buy me a ☕️](https://ko-fi.com/lennart0815). Thanks!\n\nSome of the code based of this library is based on code from [PJRC](https://www.pjrc.com/teensy/td_libs_Encoder.html).\n\n## How to Use\n\n### Definition\n\n- Use the `begin()` or the parameterized constructor to create a new instance of the class\n- Encoder produce different numbers of \"click\" on a single turn.\n- You can specify the number of clicks in the constructor, or via a setter function\n  - `void setStepsPerClick(int steps)`\n  - `int getStepsPerClick() const`\n\n### Callback Handlers\n\n- The library provides several callback handlers to detect events\n  - `void setChangedHandler(CallbackFunction f)`\n  - `void setRightRotationHandler(CallbackFunction f)`\n  - `void setLeftRotationHandler(CallbackFunction f)`\n  - `void setUpperOverflowHandler(CallbackFunction f)`\n  - `void setLowerOverflowHandler(CallbackFunction f)`\n- The library does not detect button clicks. You have to use a separate library for this, e.g. my [Button2](https://github.com/LennartHennigs/Button2) library.\n\n### Ranges\n\n- In the constructor you can define an upper and a lower threshold. The encoder value will not be bypass these values.\n- There are also getter and setter functions the these values\n  - `void setUpperBound(int upper_bound)`\n  - `void setLowerBound(int lower_bound)`\n  - `int getUpperBound() const`\n  - `int getLowerBound() const`\n- See the [RangedCounter](https://github.com/LennartHennigs/ESPRotary/blob/master/examples/RangedCounter/RangedCounter.ino) example for details.\n\n### Retrigger (out of bound) events?\n\n- If you want that out of bound events are only triggered once a bound is reached, you can set:\n  - `retriggerEvent(false)`\n- Otherwise each (out of bounds) turn will re-trigger the event.\n- If you want to disable rotate events that would go beyond your defined boundary you can use:\n  - `void triggerOnBounds(false)`\n\n### Reading out information\n\n- The class allows you the get the position and the direction after a click using these function:\n  - `int getPosition() const`\n  - `byte getDirection() const`\n  - `String directionToString(byte direction) const`\n\n### Speed\n\n- You can define the speed, i.e. the increment the a single click in the constructor\n- There is also a getter and setter function for this\n  - `void setIncrement(int inc)`\n  - `int getIncrement() const`\n\n### Speedup Mode\n\n- You can also define, that the increment shall change when the encoder is turned fast.\n- Use these functions to define the interval (between clicks) and the increment:\n  - `void setSpeedupInterval(int time)`\n  - `void setSpeedupIncrement(int inc)`\n- Per default the interval is set to `75ms` and the increment is set to `5`.\n- There are also getter functions for both parameters:\n  - `int getSpeedupInterval() const`\n  - `int getSpeedupIncrement() const`\n- To enable the speedup mode use this member function:\n  - `void enableSpeedup(bool enable)`\n- ...and to check:\n  - `bool isSpeedupEnabled() const`\n- There are also event handlers that let you track if the speedup mode was entered or exited:\n  - `void setSpeedupStartedHandler(CallbackFunction f)`\n  - `void setSpeedupEndedHandler(CallbackFunction f)`\n- Alternatively, you can use this function to determine its state:\n  - `bool isInSpeedup() const`\n- If you have bound defined, the speedup mode will be automatically ended when you hit it.\n\n### The Loop\n\n- For the class to work, you need to call the `loop()` member function in your sketch's `loop()` function.\n- Alternatively, you can use a timer interrupt to call the member `loop()`function.\n- See the examples for more details.\n\n### Using it with a timer interrupt\n\n- Instead of using the main loop() of your sketch you can also use an interrupt timer function.\n- See [ESP32Interrupt](https://github.com/LennartHennigs/ESPRotary/blob/master/examples/ESP32Interrupt/ESP32Interrupt.ino) or [ESP8266Interrupt](https://github.com/LennartHennigs/ESPRotary/blob/master/examples/ESP8266Interrupt/ESP8266Interrupt.ino) to see how\n\n### IDs for Encoder Instances\n\n- Each encoder instance gets a unique (auto incremented) ID upon creation.\n- You can get a encoders' ID via `getID()`.\n- Alternatively, you can use `setID(int newID)` to set a new one. But then you need to make sure that they are unique.\n- You can also use the `==` operator to compare encoders\n\n## Notes\n\n- To see the latest changes to the library please take a look at the [Changelog](https://github.com/LennartHennigs/ESPRotary/blob/master/CHANGELOG.md).\n- And if you find this library helpful, please consider giving it a star at [GitHub](https://github.com/LennartHennigs/ESPRotary).  Thanks!\n\n## Examples\n\n- [SimpleCounter](https://github.com/LennartHennigs/ESPRotary/blob/master/examples/SimpleCounter/SimpleCounter.ino) - basic example\n- [SimpleCounterWithButton](https://github.com/LennartHennigs/ESPRotary/blob/master/examples/SimpleCounterWithButton/SimpleCounterWithButton.ino) - basic example with a button handler\n- [RangedCounter](https://github.com/LennartHennigs/ESPRotary/blob/master/examples/RangedCounter/RangedCounter.ino) - shows how to define ranges\n- [Speedup](https://github.com/LennartHennigs/ESPRotary/blob/master/examples/Speedup/Speedup.ino) - shows how to implement the speedup mode\n- [ESP8266Interrupt](https://github.com/LennartHennigs/ESPRotary/blob/master/examples/ESP8266Interrupt/ESP8266Interrupt.ino) - uses an ESP8266 interrupt instead of the main loop\n- [ESP32Interrupt](https://github.com/LennartHennigs/ESPRotary/blob/master/examples/ESP32Interrupt/ESP32Interrupt.ino) - uses an ESP32 interrupt instead of the main loop\n\n## Class Definition\n\nThese are the constructor and the member functions the library provides:\n\n``` c++\n  ESPRotary();\n  ESPRotary(byte pin1, byte pin2, byte steps_per_click = 1, int lower_bound = INT16_MIN, int upper_bound = INT16_MAX, int iniital_pos = 0, int increment = 1);\n\n  void begin(byte pin1, byte pin2, byte steps_per_click = 1, int lower_bound = INT16_MIN, int upper_bound = INT16_MAX, int initial_pos = 0, int increment = 1);\n\n  int getPosition() const;\n  void resetPosition(int p = 0, bool fireCallback = true);\n\n  rotary_direction getDirection() const;\n  String directionToString(rotary_direction dir) const;\n\n  void setIncrement(int inc);\n  int getIncrement() const;\n\n  void triggerOnBounds(bool triggerEvents = true);\n\n  void enableSpeedup(bool enable);\n  void setSpeedupInterval(int time);\n  void setSpeedupIncrement(int inc);\n\n  bool isSpeedupEnabled() const;\n  int getSpeedupInterval() const;\n  int getSpeedupIncrement() const;\n  bool isInSpeedup() const;\n\n  rotary_event getLastEvent() const;\n  void retriggerEvent(bool retrigger);\n\n  void setUpperBound(int upper_bound);\n  void setLowerBound(int lower_bound);\n  int getUpperBound() const;\n  int getLowerBound() const;\n\n  void setStepsPerClick(int steps);\n  int getStepsPerClick() const;\n\n  void setChangedHandler(CallbackFunction f);\n  void setRightRotationHandler(CallbackFunction f);\n  void setLeftRotationHandler(CallbackFunction f);\n  void setUpperOverflowHandler(CallbackFunction f);\n  void setLowerOverflowHandler(CallbackFunction f);\n  void setSpeedupStartedHandler(CallbackFunction f);\n  void setSpeedupEndedHandler(CallbackFunction f);\n\n  int getID() const;\n  void setID(int newID);\n\n  bool operator == (ESPRotary \u0026rhs);\n\n  void loop();\n```\n\n## Installation\n\nOpen the Arduino IDE choose \"Sketch \u003e Include Library\" and search for \"ESP Rotary\".\nOr download the ZIP archive (\u003chttps://github.com/lennarthennigs/ESPRotary/zipball/master\u003e), and choose \"Sketch \u003e Include Library \u003e Add .ZIP Library...\" and select the downloaded file.\n\n## License\n\nMIT License\n\nCopyright (c) 2017-2023 Lennart Hennigs\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLennartHennigs%2FESPRotary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLennartHennigs%2FESPRotary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLennartHennigs%2FESPRotary/lists"}