{"id":18869108,"url":"https://github.com/myles-parfeniuk/button_driver","last_synced_at":"2026-04-27T08:32:01.300Z","repository":{"id":178525847,"uuid":"661975898","full_name":"myles-parfeniuk/button_driver","owner":"myles-parfeniuk","description":"Driving push-buttons \u0026 tactile switches in C++, with esp-idf v5.0+. ","archived":false,"fork":false,"pushed_at":"2023-11-14T22:28:48.000Z","size":1027,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-30T16:48:32.752Z","etag":null,"topics":["button","button-control","button-driver","esp-32","esp-idf","esp32","tactile-switch"],"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/myles-parfeniuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2023-07-04T05:13:51.000Z","updated_at":"2024-12-21T23:10:24.000Z","dependencies_parsed_at":"2024-12-30T23:31:50.410Z","dependency_job_id":"f5971fee-aa84-4ce4-a3f7-902b9b2d3d06","html_url":"https://github.com/myles-parfeniuk/button_driver","commit_stats":null,"previous_names":["myles-parfeniuk/button_driver"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/myles-parfeniuk/button_driver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/myles-parfeniuk%2Fbutton_driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/myles-parfeniuk%2Fbutton_driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/myles-parfeniuk%2Fbutton_driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/myles-parfeniuk%2Fbutton_driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/myles-parfeniuk","download_url":"https://codeload.github.com/myles-parfeniuk/button_driver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/myles-parfeniuk%2Fbutton_driver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32329463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["button","button-control","button-driver","esp-32","esp-idf","esp32","tactile-switch"],"created_at":"2024-11-08T05:15:45.579Z","updated_at":"2026-04-27T08:32:01.264Z","avatar_url":"https://github.com/myles-parfeniuk.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n![image](./documentation/readme_images/ButtonDriver_banner.png)\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003csummary\u003eTable of Contents\u003c/summary\u003e\n\u003col\u003e\n  \u003cli\u003e\n    \u003ca href=\"#about\"\u003eAbout\u003c/a\u003e\n  \u003c/li\u003e\n  \u003cli\u003e\n    \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n    \u003cul\u003e\n      \u003cli\u003e\u003ca href=\"#adding-to-project\"\u003eAdding to Project\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n  \u003c/li\u003e\n  \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n  \u003cul\u003e\n    \u003cli\u003e\u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e\u003c/li\u003e\n    \u003cul\u003e\n      \u003cli\u003e\u003ca href=\"#initializing-button-object\"\u003eInitializing Button Object\u003c/a\u003e\u003c/li\u003e\n      \u003cli\u003e\u003ca href=\"#button-events\"\u003eButton Events\u003c/a\u003e\u003c/li\u003e\n      \u003cli\u003e\u003ca href=\"#handling-button-events\"\u003eHandling Button Events\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n    \u003cli\u003e\u003ca href=\"#examples\"\u003eExamples\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#program-flowchart\"\u003eProgram Flowchart\u003c/a\u003e\u003c/li\u003e\n  \u003c/ul\u003e\n  \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n  \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n\u003c/ol\u003e\n\n\n\u003c!-- ABOUT --\u003e\n## About\n\nButtonDriver is a C++ based component written for esp-idf version 5.0+, intended to simplify the use of push-buttons and tactile switches.\n\nIt allows for the creation of Button objects which automatically detect user input from externally connected tactile switches or push-buttons.  \nCall-back functions can be registered to button objects to handle detected user input.   \n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Getting Started\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n### Adding to Project\n\n1. Create a \"components\" directory in the root workspace directory of your esp-idf project if it does not exist already.\n\n   In workspace directory:     \n   ```sh\n   mkdir components\n   ```\n\n\n2. Cd into the components directory and clone both the ButtonDriver, and DataControl repos.   \n\n   ```sh\n   cd components\n   git clone https://github.com/myles-parfeniuk/data_control.git\n   git clone https://github.com/myles-parfeniuk/button_driver.git\n   ```\n   The ButtonDriver is dependent on DataControl and will not build without it.  \n\n3. Ensure you clean your esp-idf project before rebuilding.  \n   Within esp-idf enabled terminal:\n   ```sh\n    idf.py fullclean\n   ```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n### Quick Start\nThis is intended to be a quick-guide, api documentation generated with doxygen can be found in the documentation directory of the master branch. \n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n#### Initializing Button Object\nTo initialize a button object, first initialize and configure a button_conf_t struct with the desired settings, then pass it into the Button constructor.  \n\nThe settings available within a button_conf_t struct:  \n* **gpio_num** — The GPIO number associated with the button, must not be initialized as GPIO_NUM_NC  \n* **active_lo** — Set to true if the button is active low (falling edge trigger), cannot be true if active_hi is also true   \n* **active_hi** — Set to true if the button is active high (rising edge trigger), cannot be true if active_lo is also true   \n* **pull_en** — Set to true if internal pullup/pulldown resistor is enabled for button gpio pin, set to false if external resistors are used  \n* **long_press_evt_time** — long-press event generation time in microseconds (us) if the button is held for longer than (long_press_evt_time+25ms) \n                        a long-press event is generated, if it is released before (long_press_evt_time+25ms) elapses, a quick-press event is generated instead\n                        suggested time of 300000us, must be between 10000us and 5000000us   \n* **held_event_evt_time** — held event generation time in microseconds (us), if a long press event has already occurred and the button is still being held, \n                       held events will be generated every held_evt_time elapses, suggested time of 200000us, must be between 10000us and 5000000us \n\n\nIf the button_conf_t struct is not initialized correctly the Button constructor will output an error related to the issue in the terminal and dump a stack trace.   \n\nExample Initializations:  \n\n1. Active-Low w/ external pullup  \n\n![image](./documentation/readme_images/ButtonDriver_active_low_external_pullup.png)\n\n```cpp\n    //initialize button_config_t struct\n    Button::button_config_t button_conf =\n    {\n        .gpio_num = GPIO_NUM_25, //gpio number connected to button, for ex.25\n        .active_lo = true, //active low\n        .active_hi = false, //not active high\n        .pull_en = false, //internal pullup disabled\n        .long_press_evt_time = 300000, //300ms long-press event generation time\n        .held_evt_time = 200000, //200ms held event generation time\n    };\n\n    //declare \u0026 initialize Button object\n    Button my_button(button_conf);\n```\n\n2. Active-Low w/ no external pullup\n\n![image](./documentation/readme_images/ButtonDriver_active_low_no_external_pullup.png)\n\n```cpp\n    //initialize button_config_t struct\n    Button::button_config_t button_conf =\n    {\n        .gpio_num = GPIO_NUM_25, //gpio number connected to button, for ex.25\n        .active_lo = true, //active low\n        .active_hi = false, //not active high\n        .pull_en = true, //internal pullup enabled\n        .long_press_evt_time = 300000, //300ms long-press event generation time\n        .held_evt_time = 200000, //200ms held event generation time\n    };\n\n    //declare \u0026 initialize Button object\n    Button my_button(button_conf);\n```\n\n3. Active-High w/ external pulldown\n\n![image](./documentation/readme_images/ButtonDriver_active_high_external_pulldown.png)\n\n```cpp\n    //initialize button_config_t struct\n    Button::button_config_t button_conf =\n    {\n        .gpio_num = GPIO_NUM_25, //gpio number connected to button, for ex.25\n        .active_lo = false, //not active low\n        .active_hi = true, //active high\n        .pull_en = false, //internal pulldown disabled\n        .long_press_evt_time = 300000, //300ms long-press event generation time\n        .held_evt_time = 200000, //200ms held event generation time\n    };\n\n    //declare \u0026 initialize Button object\n    Button my_button(button_conf);\n```\n\n4. Active-High w/ no external pulldown\n\n![image](./documentation/readme_images/ButtonDriver_active_high_no_external_pulldown.png)\n\n```cpp\n    //initialize button_config_t struct\n    Button::button_config_t button_conf =\n    {\n        .gpio_num = GPIO_NUM_25, //gpio number connected to button, for ex.25\n        .active_lo = false, //not active low\n        .active_hi = true, //active high\n        .pull_en = true, //internal pulldown enabled\n        .long_press_evt_time = 300000, //300ms long-press event generation time\n        .held_evt_time = 200000, //200ms held event generation time\n    };\n\n    //declare \u0026 initialize Button object\n    Button my_button(button_conf);\n```\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n#### Button Events\nAfter being initialized, a Button object will automatically detect any user input and generate an event. \n\nThese events come in 4 flavors:\n\n1. **quick-press:**  \n   This event indicates the button was momentarily pressed.\n   This event is generated when the push-button is pressed \u0026 then released before (25ms + long_press_evt_time) has elapsed. \n\n2. **long-press:**   \n   This event indicates the button was pressed and held.\n   This event is generated when the push-button is pressed \u0026 not released after (25ms + long_press_evt_time) has elapsed. \n\n3. **held:**   \n   This event indicates a long-press event has already occurred, and the button is still being held. \n   This event is generated every time held_evt_time elapses, after a long-press event, until the button is released.\n\n4. **released:**   \n   This event indicates the button has been released.\n   This event is generated if the button is released any time after a long_press event has occurred. \n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n#### Handling Button Events\nIn order to be notified when a button-event has occurred, a call-back function (or multiple) can be registered with the button by calling the follow() method on its event member.  \n\nAs many call-backs as desired can be registered to a button using follow(). When a button event occurs, any call-backs registered to the respective button will be called in the order they were registered— this means whichever call-back was registered first has highest priority.  \n\nIt is recommended to initialize the call-back functions as lambda-functions for easy readability.  \nAny call-back function registered with follow() must take the form:   \n```cpp\n  void call_back_example(Button::ButtonEvent event);\n```\n\nExample call-back functions \u0026 registrations:\n\n1. Using a lambda call-back function:\n\n```cpp\n//call the follow() method on a button event member to register a callback with a button\nmy_button.event.follow(\n        //lambda call-back function— called automatically when button input is detected\n        [](Button::ButtonEvent event)\n        {\n            //button event handler\n            switch(event){\n                case Button::ButtonEvent::quick_press:\n                  //place code that should be run on quick-press here\n                break;\n\n                case Button::ButtonEvent::long_press:\n                  //place code that should be run on long-press here\n                break;\n\n                case Button::ButtonEvent::held:\n                  //place code that should be run when button is held here\n                break;\n\n                case Button::ButtonEvent::released:\n                  //place code that should be run when button is released here\n                break;\n            }\n        });\n```\n\n2. Using call-back function pointer:\n\n```cpp\n//call-back prototype\nvoid my_callback(Button::ButtonEvent event);\n\n//call the follow() method on a button event member to register a callback with a button\nmy_button.event.follow(my_callback);\n\n//call-back function— called automatically when button input is detected\nvoid my_callback(Button::ButtonEvent event)\n{\n  \n  //button event handler\n  switch(event)\n  {\n    case Button::ButtonEvent::quick_press:\n      //place code that should be run on quick-press here\n    break;\n\n    case Button::ButtonEvent::long_press:\n      //place code that should be run on long-press here\n    break;\n\n    case Button::ButtonEvent::held:\n      //place code that should be run when button is held here\n    break;\n\n    case Button::ButtonEvent::released:\n      //place code that should be run when button is released here\n    break;\n  }\n}\n```\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\n### Examples\nExamples are available in the ButtonDriver directory of my esp_idf_cpp_examples repo:    \n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n[https://github.com/myles-parfeniuk/esp_idf_cpp_examples](https://github.com/myles-parfeniuk/esp_idf_cpp_examples)\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n### Program Flowchart\n![image](./documentation/readme_images/ButtonDriver_flow_chart.png)\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## License\nDistributed under the MIT License. See `LICENSE.md` for more information.\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Contact\nMyles Parfeniuk - myles.parfenyuk@gmail.com  \nProject Link: [https://github.com/myles-parfeniuk/button_driver](https://github.com/myles-parfeniuk/button_driver)  \n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmyles-parfeniuk%2Fbutton_driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmyles-parfeniuk%2Fbutton_driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmyles-parfeniuk%2Fbutton_driver/lists"}