Skip to content

Commit 775be1d

Browse files
ruiseixasmruiseixasm
committed
Version 1.0.0
1 parent ee6e443 commit 775be1d

File tree

5 files changed

+213
-6
lines changed

5 files changed

+213
-6
lines changed

‎README.md

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
## **Versatile_RotaryEncoder Library V1.0.0** for Arduino
2+
**Written by:** _Rui Seixas Monteiro_.
3+
4+
## Installation
5+
Create a new folder called "Versatile_RotaryEncoder" under the folder named "libraries" in your Arduino sketchbook folder.
6+
Create the folder "libraries" in case it does not exist yet. Place all the files in the "Versatile_RotaryEncoder" folder.
7+
8+
## Import
9+
To use the library in your own sketch, select it from *Sketch > Import Library*.
10+
11+
## What is Versatile_RotaryEncoder
12+
The Versatile_RotaryEncoder library allows the callback of up to 9 different functions representing the same number of different encoder events. These different functions can bee associated with events like press rotate and long press among many others.
13+
14+
## Usage
15+
### **How to include**
16+
```Arduino
17+
#include <Versatile_RotaryEncoder.h>
18+
19+
void setup(){
20+
21+
}
22+
23+
void loop(){
24+
25+
}
26+
```
27+
28+
### **Library functions**
29+
#### **`Versatile_RotaryEncoder.setHandleRotate( void (*)(int8_t rotation) )`**
30+
This function sets the handle function for the rotation of the encoder.
31+
Its only parameter is the handle function as `void (*)(int8_t rotation)` that would be used to process the rotation value.
32+
33+
#### **`Versatile_RotaryEncoder.setHandlePressRotate( void (*)(int8_t rotation) )`**
34+
This function sets the handle function for the rotation of the encoder while being pressed.
35+
Its only parameter is the handle function as `void (*)(int8_t rotation)` that would be used to process the rotation value.
36+
37+
#### **`Versatile_RotaryEncoder.setHandleHeldRotate( void (*)(int8_t rotation) )`**
38+
This function sets the handle function for the rotation of the encoder after being long pressed while held.
39+
Its only parameter is the handle function as `void (*)(int8_t rotation)` that would be used to process the rotation value.
40+
41+
#### **`Versatile_RotaryEncoder.setHandlePress( void (*)() )`**
42+
This function sets the handle function for the button press of the encoder.
43+
Its only parameter is the handle function as `void (*)()` that would be used to process the pressed encoder switch.
44+
45+
#### **`Versatile_RotaryEncoder.setHandlePressRelease( void (*)() )`**
46+
This function sets the handle function for the button release of the encoder.
47+
Its only parameter is the handle function as `void (*)()` that would be used to process the released encoder switch.
48+
49+
#### **`Versatile_RotaryEncoder.setHandleLongPress( void (*)() )`**
50+
This function sets the handle function for the button long press of the encoder.
51+
Its only parameter is the handle function as `void (*)()` that would be used to process the long pressed encoder switch.
52+
53+
#### **`Versatile_RotaryEncoder.setHandleLongPressRelease( void (*)() )`**
54+
This function sets the handle function for the button long press released of the encoder.
55+
Its only parameter is the handle function as `void (*)()` that would be used to process the release of the long pressed encoder switch.
56+
57+
#### **`Versatile_RotaryEncoder.setHandlePressRotateRelease( void (*)() )`**
58+
This function sets the handle function for the button release of the encoder after being press rotated.
59+
Its only parameter is the handle function as `void (*)()` that would be used to process the release encoder switch after being press rotated.
60+
61+
#### **`Versatile_RotaryEncoder.setHandleHeldRotateRelease( void (*)() )`**
62+
This function sets the handle function for the button release of the encoder after being long press and then rotated.
63+
Its only parameter is the handle function as `void (*)()` that would be used to process the release encoder switch after being held rotated.
64+
65+
#### **`Versatile_RotaryEncoder.ReadEncoder()`**
66+
This functions reads the encoder and runs all Handle functions accordingly. It returns a `bool` with true whenever any handle function is called.
67+
68+
#### **`Versatile_RotaryEncoder.setReadIntervalDuration( byte )`**
69+
By default every 2 ms the encoder is readed, you can set a diffrent value with this function.
70+
71+
#### **`Versatile_RotaryEncoder.setShortPressDuration( byte )`**
72+
By default it's set 30 ms for the encoder switch debounce, you can set a diffrent value with this function.
73+
74+
#### **`Versatile_RotaryEncoder.setLongPressDuration( unsigned int )`**
75+
By default it's set 1000 ms for the press be considered a long press, you can set a diffrent value with this function.
76+
77+
#### **`Versatile_RotaryEncoder.getRotary()`**
78+
This functions returns a `short int` with a positive 1 or negative 1 accordingly to the rotation of the encoder.
79+
The purpose of this function is to allow a more specific use of the library.
80+
81+
#### **`Versatile_RotaryEncoder.getButton()`**
82+
This functions returns a `short unsigned int` with a value related to released, holdup, switchup, switchdown, pressed, holddown or held respectively.
83+
The purpose of this function is to allow a more specific use of the library.
84+
85+
#### **`Versatile_RotaryEncoder.getEncoder()`**
86+
This functions returns a `short unsigned int` with a value related to inactive, release, press, hold, rotate, pressrotate or heldrotate respectively.
87+
The purpose of this function is to allow a more specific use of the library.
88+
89+
#### **`Versatile_RotaryEncoder.getEncoderBits()`**
90+
This functions returns a `short unsigned int` representing the last rotary bits set by the encoder.
91+
The purpose of this function is to allow a more specific use of the library.
92+
93+
#### **`Versatile_RotaryEncoder.getButtonBits()`**
94+
This functions returns a `short unsigned int` representing the last button bits set by the encoder.
95+
The purpose of this function is to allow a more specific use of the library.
96+
97+
### **Examples**
98+
#### **Partial Dummy Memory Allocation (Testing Purposes)**
99+
```Arduino
100+
#include <Versatile_RotaryEncoder.h>
101+
102+
// Set here your encoder reading pins (Ex.: EC11 with breakout board)
103+
#define clk 17 // (A3)
104+
#define dt 18 // (A4)
105+
#define sw 19 // (A5)
106+
107+
// Functions prototyping to be handled on each Encoder Event
108+
void handleRotate(int8_t rotation);
109+
void handlePressRotate(int8_t rotation);
110+
void handleHeldRotate(int8_t rotation);
111+
void handlePress();
112+
void handlePressRelease();
113+
void handleLongPress();
114+
void handleLongPressRelease();
115+
void handlePressRotateRelease();
116+
void handleHeldRotateRelease();
117+
118+
// Create a global pointer for the encoder object
119+
Versatile_RotaryEncoder *versatile_encoder;
120+
121+
void setup() {
122+
123+
Serial.begin(9600);
124+
versatile_encoder = new Versatile_RotaryEncoder(clk, dt, sw);
125+
126+
// Load to the encoder all nedded handle functions here (up to 9 functions)
127+
versatile_encoder->setHandleRotate(handleRotate);
128+
versatile_encoder->setHandlePressRotate(handlePressRotate);
129+
versatile_encoder->setHandleHeldRotate(handleHeldRotate);
130+
versatile_encoder->setHandlePress(handlePress);
131+
versatile_encoder->setHandlePressRelease(handlePressRelease);
132+
versatile_encoder->setHandleLongPress(handleLongPress);
133+
versatile_encoder->setHandleLongPressRelease(handleLongPressRelease);
134+
versatile_encoder->setHandlePressRotateRelease(handlePressRotateRelease);
135+
versatile_encoder->setHandleHeldRotateRelease(handleHeldRotateRelease);
136+
137+
Serial.println("Ready!");
138+
139+
}
140+
141+
void loop() {
142+
143+
// Do the encoder reading and processing
144+
if (versatile_encoder->ReadEncoder()) {
145+
// Do something here whenever an encoder action is read
146+
}
147+
148+
}
149+
150+
// Implement your functions here accordingly to your needs
151+
152+
void handleRotate(int8_t rotation) {
153+
Serial.print("#1 Rotated: ");
154+
if (rotation > 0)
155+
Serial.println("Right");
156+
else
157+
Serial.println("Left");
158+
}
159+
160+
void handlePressRotate(int8_t rotation) {
161+
Serial.print("#2 Pressed and rotated: ");
162+
if (rotation > 0)
163+
Serial.println("Right");
164+
else
165+
Serial.println("Left");
166+
}
167+
168+
void handleHeldRotate(int8_t rotation) {
169+
Serial.print("#3 Held and rotated: ");
170+
if (rotation > 0)
171+
Serial.println("Right");
172+
else
173+
Serial.println("Left");
174+
}
175+
176+
void handlePress() {
177+
Serial.println("#4 Pressed");
178+
}
179+
180+
void handlePressRelease() {
181+
Serial.println("#5 Press released");
182+
}
183+
184+
void handleLongPress() {
185+
Serial.println("#6 Long pressed");
186+
}
187+
188+
void handleLongPressRelease() {
189+
Serial.println("#7 Long press released");
190+
}
191+
192+
void handlePressRotateRelease() {
193+
Serial.println("#8 Press rotate released");
194+
}
195+
196+
void handleHeldRotateRelease() {
197+
Serial.println("#9 Held rotate released");
198+
}
199+
```

‎examples/ExaustiveEncoder.ino

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
#include <Arduino.h>
21
#include <Versatile_RotaryEncoder.h>
32

4-
// Set here your encoder reading pins
3+
// Set here your encoder reading pins (Ex.: EC11 with breakout board)
54
#define clk 17 // (A3)
65
#define dt 18 // (A4)
76
#define sw 19 // (A5)
@@ -88,7 +87,7 @@ void handleLongPress() {
8887
}
8988

9089
void handleLongPressRelease() {
91-
Serial.println("#7 Long pressed released");
90+
Serial.println("#7 Long press released");
9291
}
9392

9493
void handlePressRotateRelease() {

‎library.properties

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name=Versatile_RotaryEncoder
2+
version=1.0.0
3+
author=ruiseixasm, Rui Seixas Monteiro
4+
maintainer=Rui Seixas Monteiro
5+
sentence=A rotary encoder library that allows the callback of up to 9 different functions representing the same number of different encoder events. These different functions can bee associated with events like press rotate and long press among many others.
6+
paragraph=A simple switch rotary encoder has multiple possibilities, namely press and rotating at the same time, this library takes advantage of all those possibilities allowing the set of handling functions for each of those 9 possibilites.
7+
category=Device Control
8+
url=https://github.com/ruiseixasm/Versatile_RotaryEncoder
9+
architectures=*

‎src/Versatile_RotaryEncoder.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ bool Versatile_RotaryEncoder::ReadEncoder() {
2828

2929
bool handled_functions = false;
3030

31-
if (millis() - last_encoder_read > (uint32_t)read_interval_duration || read_interval_duration == 0) {
31+
if (millis() - last_encoder_read >= (uint32_t)read_interval_duration) {
3232
last_encoder_read = millis();
3333
encoderBits = digitalRead(pin_sw) << 2 | digitalRead(pin_clk) << 1 | digitalRead(pin_dt);
3434

‎src/Versatile_RotaryEncoder.h

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ class Versatile_RotaryEncoder {
3131
uint8_t rotaryBits = 0b11; // 8 bits
3232
uint8_t buttonBits = 0b111; // 8 bits
3333

34-
uint8_t read_interval_duration = 1;
35-
uint8_t short_press_duration = 100;
34+
uint8_t read_interval_duration = 2; // by default reads the encoder each 2ms
35+
uint8_t short_press_duration = 30; // debounce duration to avoid noise triggering
3636
uint16_t long_press_duration = 1000;
3737
uint32_t lastTouch = 0;
3838
uint32_t last_encoder_read = 0;

0 commit comments

Comments
 (0)