Skip to content

Commit d14bc61

Browse files
IPdotSetAFIPdotSetAF
committed
modified readme
refactored some function and enum names
1 parent 74c02ef commit d14bc61

File tree

3 files changed

+132
-13
lines changed

3 files changed

+132
-13
lines changed

‎README.md‎

Lines changed: 122 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,123 @@
1+
<p align=left>
2+
<img src="https://img.shields.io/github/v/release/IPdotSetAF/EZButton"/>
3+
<img src="https://img.shields.io/github/release-date/IPdotSetAF/EZButton"/>
4+
<img src="https://img.shields.io/github/last-commit/IPdotSetAF/EZButton"/>
5+
<img src="https://img.shields.io/github/license/IPdotSetAF/EZButton"/>
6+
<!--<img src="https://img.shields.io/github/downloads/IPdotSetAF/EZButton/total"/>-->
7+
</p>
8+
19
# EZButton
2-
Arduino library for button event management
10+
Transform raw button/touch inputs into events easily.
11+
12+
Subscibe to Pressed/Released/Hold/HoldReleased events of as many buttons as you want. Customize time tresholds. Works with any button read method.
13+
14+
## Features
15+
- Flexibility
16+
- Works with:
17+
- Buttons
18+
- Touch
19+
- Any other signal
20+
- Also works with:
21+
- Pulling
22+
- Multiplexing
23+
- Interupts
24+
- AnalogReads
25+
- etc
26+
- Event Subscibtion : You can subscribe to any of the following events for any button:
27+
- Pressed
28+
- Released
29+
- Hold
30+
- Hold Released
31+
- Unlimited Buttons/Touches : You can config for as many buttons as you need.
32+
- Customizability: You can change any of the time tresholds to customize you user experience.
33+
- `HoldTreshHold` : The time it takes before the first `HOLD` event is executed after button is held down.
34+
- `HoldInterval` : The Time Interval that corresponds to `HOLD` event being executed repeatedly after the first `HOLD` event was registerd.
35+
- Debugging : Easily enable/disable debugging for all button states and events.
36+
- Blackout Time: Disable any event execution for any amount of time.
37+
38+
## How To
39+
### Installation
40+
This Library is available in `Arduino Library Repository` and `PIO` and you can install it from:
41+
- Arduino IDE Library Manager
42+
![arduino library manager]()
43+
- PlatformIO Libraries
44+
![pltformio library]()
45+
`ipdotsetaf/EZButton@^2.2.0`
46+
### Usage
47+
48+
1. Include the library
49+
``` C++
50+
#include <EZButton.h>
51+
```
52+
2. Create an object from `EZButton`
53+
``` C++
54+
#define BTN_1 0
55+
#define BTN_2 1
56+
#define BTN_3 2
57+
#define BTN_4 3
58+
//config for 4 buttons
59+
//Read button states from the 'ReadButtons' function
60+
//HoldTreshHold: 500ms
61+
//HoldInterval: 300ms
62+
EZButton _ezb(4, ReadButtons, 500, 300);
63+
```
64+
3. Initialize you buttons/touches however you want.
65+
4. Attach any Interrups if needed.
66+
5. Subscribe to any event you need
67+
``` C++
68+
//button index, function to execute, event type
69+
_ezb.Subscribe(BTN_1, Btn1HoldRelease, HOLD_RELEASED);
70+
_ezb.Subscribe(BTN_2, Btn2Release, RELEASED);
71+
_ezb.Subscribe(BTN_3, Btn3Hold, HOLD);
72+
_ezb.Subscribe(BTN_3, Btn3Release, RELEASED);
73+
_ezb.Subscribe(BTN_4, Btn4Hold, HOLD);
74+
_ezb.Subscribe(BTN_4, Btn4Release, RELEASED);
75+
```
76+
> [!IMPORTANT]
77+
> 'button index' stands for an array inside EZButton that hold you buttins states and IS NOT pin number of the button.
78+
79+
6. Define `ReadButtons` function
80+
``` C++
81+
void ReadButtons(bool *states, int num)
82+
{
83+
//Read all button states however you want
84+
states[BTN_1] = !digitalRead(2);
85+
states[BTN_2] = touchRead(3) <= 50;
86+
states[BTN_3] = touchRead(4) <= 50;
87+
states[BTN_4] = touchRead(5) <= 50;
88+
}
89+
```
90+
7. Call EZButtons `Loop()` function in your main loop.
91+
``` C++
92+
void loop()
93+
{
94+
//...
95+
96+
_ezb.Loop();
97+
}
98+
```
99+
100+
> [!TIP]
101+
> #### Debugging
102+
> In order to enable debugging, you need to add the `-DEZBUTTON_DEBUG` parameter to your `build_flags`.
103+
>
104+
> This will log event subscibtions and event executions to the serial.
105+
106+
> [!IMPORTANT]
107+
> Right now only one subscribtion is possible for each button event.
108+
>
109+
> e.g. You can only subscribe to the `PRESSED` event of `BTN_2` once and the second subscribtion to this event will override the last one.
110+
>
111+
> You can still subscribe to other events of the same button with no problem.
112+
113+
## TODO:
114+
- Rewrite in C
115+
- Add multiple subscribtions to a single event
116+
117+
## Contribution
118+
- You can open Issues for any bug report or feature request.
119+
- You are free to contribute to this project by following these steps:
120+
1. Fork this Repo.
121+
2. Create a new branch for your feature/bugfix in your forked Repo.
122+
3. Commit your changes to the new branch you just made.
123+
4. Create a pull request from your branch into the `main` branch of This Repo([https://github.com/IPdotSetAF/EZButton](https://github.com/IPdotSetAF/EZButton)).

‎src/EZButton.cpp‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ void EZButton::Blackout(unsigned long milis)
3939
_blackoutTime = millis() + milis;
4040
}
4141

42-
void EZButton::CheckButtons()
42+
void EZButton::Loop()
4343
{
4444
if (_blackoutTime > millis())
4545
return;
@@ -74,9 +74,9 @@ void EZButton::CheckButtons()
7474
_buttonLastState[i] = 0;
7575
_lastHoldInterval[i] = 0;
7676
if (millis() - _buttonDownMillis[i] > HoldTreshHold)
77-
CallEvent(i, EventTypes::HOLD_RELEASE);
77+
CallEvent(i, EventTypes::HOLD_RELEASED);
7878
else
79-
CallEvent(i, EventTypes::RELEASE);
79+
CallEvent(i, EventTypes::RELEASED);
8080
}
8181
}
8282
}
@@ -88,7 +88,7 @@ void EZButton::Subscribe(int index, void (*event)(), EventTypes type)
8888
{
8989
_events[EventIndex(index, type)] = event;
9090

91-
#ifdef DEBUG
91+
#ifdef EZBUTTON_DEBUG
9292
Serial.println("Subscribe:");
9393
DebugEvents(index, type);
9494
#endif
@@ -98,7 +98,7 @@ void EZButton::CallEvent(int index, EventTypes type)
9898
{
9999
int i = EventIndex(index, type);
100100

101-
#ifdef DEBUG
101+
#ifdef EZBUTTON_DEBUG
102102
Serial.println("Call:");
103103
DebugEvents(index, type);
104104
#endif
@@ -112,7 +112,7 @@ int EZButton::EventIndex(int index, EventTypes type)
112112
return index + type * _numButtons;
113113
}
114114

115-
#ifdef DEBUG
115+
#ifdef EZBUTTON_DEBUG
116116
void EZButton::DebugEvents(int index, EventTypes type)
117117
{
118118
Serial.println("index : " + (String)index);

‎src/EZButton.h‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,13 @@
33

44
#include <Arduino.h>
55

6-
// #define DEBUG
7-
86
#define EVENT_COUNT 4
97
enum EventTypes
108
{
119
PRESSED,
1210
HOLD,
13-
HOLD_RELEASE,
14-
RELEASE
11+
HOLD_RELEASED,
12+
RELEASED
1513
};
1614

1715
class EZButton
@@ -28,7 +26,7 @@ class EZButton
2826
~EZButton();
2927

3028
void Blackout(unsigned long milis);
31-
void CheckButtons();
29+
void Loop();
3230
void Subscribe(int index, void (*event)(), EventTypes type);
3331

3432
private:
@@ -46,7 +44,7 @@ class EZButton
4644
void CallEvent(int index, EventTypes type);
4745
int EventIndex(int index, EventTypes type);
4846

49-
#ifdef DEBUG
47+
#ifdef EZBUTTON_DEBUG
5048
void DebugEvents(int index, EventTypes type);
5149
#endif
5250
};

0 commit comments

Comments
 (0)