Skip to content

Commit 03e28b7

Browse files
fbiegofbiego
authored
Merge pull request #12 from georgemclaughlin/1.3.0
Updated auto sleep functionality and added user interrupt
2 parents 4238b84 + be41d45 commit 03e28b7

9 files changed

Lines changed: 253 additions & 48 deletions

File tree

‎CST816S.cpp‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,10 @@ void CST816S::read_touch() {
6868
void IRAM_ATTR CST816S::handleISR(void) {
6969
_event_available = true;
7070

71+
// Call user callback if it has been set
72+
if (userISR != nullptr) {
73+
userISR();
74+
}
7175
}
7276

7377
/*!
@@ -79,13 +83,40 @@ void CST816S::enable_double_click(void) {
7983
}
8084

8185
/*!
82-
@brief Enable auto standby mode with a specified delay.
83-
@param milliseconds
84-
Time in milliseconds before entering standby mode.
86+
@brief Disable auto sleep mode
87+
*/
88+
void CST816S::disable_auto_sleep(void)
89+
{
90+
byte disableAutoSleep = 0xFE; // Non-zero value disables auto sleep
91+
i2c_write(CST816S_ADDRESS, 0xFE, &disableAutoSleep, 1);
92+
}
93+
94+
/*!
95+
@brief Enable auto sleep mode
96+
*/
97+
void CST816S::enable_auto_sleep(void)
98+
{
99+
byte enableAutoSleep = 0x00; // 0 value enables auto sleep
100+
i2c_write(CST816S_ADDRESS, 0xFE, &enableAutoSleep, 1);
101+
}
102+
103+
/*!
104+
@brief Set the auto sleep time
105+
@param seconds Time in seconds (1-255) before entering standby mode after inactivity
85106
*/
86-
void CST816S::enable_auto_standby(uint16_t milliseconds) {
87-
byte standbyTime = min(milliseconds / 1000, 255); // Convert milliseconds to seconds, max value 255
88-
i2c_write(CST816S_ADDRESS, 0xF9, &standbyTime, 1);
107+
void CST816S::set_auto_sleep_time(int seconds)
108+
{
109+
if (seconds < 1)
110+
{
111+
seconds = 1; // Enforce minimum value of 1 second
112+
}
113+
else if (seconds > 255)
114+
{
115+
seconds = 255; // Enforce maximum value of 255 seconds
116+
}
117+
118+
byte sleepTime = static_cast<byte>(seconds); // Convert int to byte
119+
i2c_write(CST816S_ADDRESS, 0xF9, &sleepTime, 1);
89120
}
90121

91122
/*!
@@ -113,6 +144,15 @@ void CST816S::begin(int interrupt) {
113144
attachInterrupt(_irq, std::bind(&CST816S::handleISR, this), interrupt);
114145
}
115146

147+
/*!
148+
@brief Attaches a user-defined callback function to be triggered on an interrupt event from the CST816S touch controller.
149+
@param callback A function to be called when an interrupt event occurs, must have no parameters and return void.
150+
*/
151+
void CST816S::attachUserInterrupt(std::function<void(void)> callback)
152+
{
153+
userISR = callback;
154+
}
155+
116156
/*!
117157
@brief check for a touch event
118158
*/

‎CST816S.h‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,10 @@ class CST816S {
5959
CST816S(int sda, int scl, int rst, int irq);
6060
void begin(int interrupt = RISING);
6161
void enable_double_click();
62-
void enable_auto_standby(uint16_t milliseconds);
62+
void disable_auto_sleep();
63+
void enable_auto_sleep();
64+
void set_auto_sleep_time(int seconds);
65+
void attachUserInterrupt(std::function<void(void)> callback);
6366
void sleep();
6467
bool available();
6568
data_struct data;
@@ -72,6 +75,8 @@ class CST816S {
7275
int _rst;
7376
int _irq;
7477
bool _event_available;
78+
std::function<void(void)> userISR;
79+
7580

7681
void IRAM_ATTR handleISR();
7782
void read_touch();

‎README.md‎

Lines changed: 46 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,41 @@
33

44
[![arduino-library-badge](https://www.ardu-badge.com/badge/CST816S.svg?)](https://www.arduinolibraries.info/libraries/cst816-s)
55

6+
## Auto Sleep Control
7+
8+
Auto Sleep is referred to as Standby Mode in this [Waveshare document](https://www.waveshare.com/w/upload/5/51/CST816S_Datasheet_EN.pdf). Disabling of auto sleep or auto standby will keep the touch display in Dynamic mode. This will improve responsiveness, at the cost of about ~1.6mA.
9+
10+
By default, auto sleep is **enabled** with a timeout of 2 seconds. The following functions allow you to manage auto sleep behavior:
11+
12+
- **`void disable_auto_sleep();`**
13+
Disables auto sleep, keeping the device active indefinitely.
14+
15+
- **`void enable_auto_sleep();`**
16+
Re-enables auto sleep with the current timeout (default is 2 seconds).
17+
18+
- **`void set_auto_sleep_time(int seconds);`**
19+
Sets the auto sleep timeout in seconds (1-255).
20+
Example: `set_auto_sleep_time(10);` sets a 10-second timeout.
21+
22+
## User-Provided Interrupt
23+
24+
The CST816S library allows you to attach a custom interrupt function to handle touch events according to your application's needs. By providing a user-defined interrupt, you can trigger specific actions upon touch events, such as waking the device from a low-power state, checking gestures, or executing custom logic without constantly polling the device.
25+
26+
**Feature Highlights:**
27+
- **Custom Event Handling**: Define and attach a user function that executes on each touch interrupt, allowing immediate responses to touch events.
28+
- **Power Management**: Ideal for applications needing to manage power, such as waking from sleep modes, as the interrupt triggers only on touch.
29+
- **Gesture-Based Logic**: Use the interrupt to wake, then analyze gestures to decide on further actions, enabling efficient and gesture-responsive behavior.
30+
31+
32+
633
## Register Information
734

835
The following information was extracted from [this document](https://www.waveshare.com/w/upload/c/c2/CST816S_register_declaration.pdf) provided by Waveshare.
936

1037
| Register Name | Address | Bit Description | Default Value | Configuration Options |
1138
|-------------------|---------|-------------------------------------------------------|---------------|----------------------------------------------------------------|
12-
| GestureID | 0x01 | Gesture code for detected gestures | N/A | 0x00: None, 0x01: Slide Up, 0x02: Slide Down, 0x0B: Double Click |
13-
| FingerNum | 0x02 | Number of fingers detected | N/A | 0: No finger, 1: One finger |
39+
| GestureID | 0x01 | Gesture code for detected gestures | N/A | - 0x00: None <br> - 0x01: Slide Up <br> - 0x02: Slide Down <br> - 0x03: Slide Left <br> - 0x04: Slide Right <br> - 0x05: Single Click <br> - 0x0B: Double Click <br> - 0x0C: Long Press |
40+
| FingerNum | 0x02 | Number of fingers detected | N/A | - 0: No finger <br> - 1: One finger |
1441
| XposH | 0x03 | High 4 bits of X coordinate | N/A | - |
1542
| XposL | 0x04 | Low 8 bits of X coordinate | N/A | - |
1643
| YposH | 0x05 | High 4 bits of Y coordinate | N/A | - |
@@ -22,22 +49,22 @@
2249
| ChipID | 0xA7 | Chip model identifier | N/A | - |
2350
| ProjID | 0xA8 | Project number | N/A | - |
2451
| FwVersion | 0xA9 | Firmware version number | N/A | - |
25-
| MotionMask | 0xEC | Enable gesture actions like double-click | 0x00 | Bit 0: EnDClick (enable double-click), Bit 1: EnConUD |
52+
| MotionMask | 0xEC | Enable continuous gesture actions and double-click | 0x00 | - Bit 0: EnDClick (enable double-click) <br> - Bit 1: EnConUD (enable continuous up/down swipe) <br> - Bit 2: EnConLR (enable continuous left/right swipe) |
2653
| IrqPluseWidth | 0xED | Interrupt pulse width (0.1 ms units) | 10 | 1-200 |
2754
| NorScanPer | 0xEE | Normal scan period (10 ms units) | 1 | 1-30 |
28-
| MotionSlAngle | 0xEF | Gesture detection sliding angle control | N/A | - |
29-
| LpScanRaw1H | 0xF0 | High 8 bits of low-power scan channel 1 reference | N/A | - |
30-
| LpScanRaw1L | 0xF1 | Low 8 bits of low-power scan channel 1 reference | N/A | - |
31-
| LpScanRaw2H | 0xF2 | High 8 bits of low-power scan channel 2 reference | N/A | - |
32-
| LpScanRaw2L | 0xF3 | Low 8 bits of low-power scan channel 2 reference | N/A | - |
33-
| LpAutoWakeTime | 0xF4 | Auto recalibration time in low-power mode | 5 minutes | 1-5 minutes |
34-
| LpScanTH | 0xF5 | Low-power scan wake threshold | 48 | 1-255 |
35-
| LpScanWin | 0xF6 | Low-power scan range | 3 | 0-3 |
36-
| LpScanFreq | 0xF7 | Low-power scan frequency | 7 | 1-255 |
37-
| LpScanIdac | 0xF8 | Low-power scan current | N/A | 1-255 |
38-
| AutoSleepTime | 0xF9 | Time in seconds before entering standby mode | 2 seconds | 1-255 seconds |
39-
| IrqCtl | 0xFA | Control of interrupt behavior | N/A | EnTest, EnTouch, EnChange, EnMotion |
40-
| AutoReset | 0xFB | Auto-reset time with no valid gesture detected | 5 seconds | 0-5 seconds (0 to disable) |
41-
| LongPressTime | 0xFC | Time for long press to trigger reset | 10 seconds | 0-10 seconds (0 to disable) |
42-
| IOCtl | 0xFD | IO control settings including soft reset | N/A | SOFT_RST, IIC_OD, En1v8 |
43-
| DisAutoSleep | 0xFE | Disable auto sleep mode | 0 | Non-zero value disables auto sleep mode |
55+
| MotionSlAngle | 0xEF | Gesture detection sliding angle control (Angle = tan(c) * 10, where c is the angle relative to the positive X-axis) | N/A | - |
56+
| LpScanRaw1H | 0xF0 | High 8 bits of low-power scan channel 1 reference | N/A | - |
57+
| LpScanRaw1L | 0xF1 | Low 8 bits of low-power scan channel 1 reference | N/A | - |
58+
| LpScanRaw2H | 0xF2 | High 8 bits of low-power scan channel 2 reference | N/A | - |
59+
| LpScanRaw2L | 0xF3 | Low 8 bits of low-power scan channel 2 reference | N/A | - |
60+
| LpAutoWakeTime | 0xF4 | Low-power mode auto recalibration interval (in minutes) | 5 minutes | 1-5 minutes |
61+
| LpScanTH | 0xF5 | Low-power scan wake threshold. The smaller the value, the more sensitive it is. | 48 | 1-255 |
62+
| LpScanWin | 0xF6 | Low-power scan range. The larger the value, the more sensitive it is, but power consumption increases. | 3 | 0-3 |
63+
| LpScanFreq | 0xF7 | Low-power scan frequency. The smaller the value, the more sensitive it is. | 7 | 1-255 |
64+
| LpScanIdac | 0xF8 | Low-power scan current. The smaller the value, the more sensitive it is. | N/A | 1-255 |
65+
| AutoSleepTime | 0xF9 | Time in seconds before entering standby mode after inactivity | 2 seconds | 1-255 seconds |
66+
| IrqCtl | 0xFA | Control of interrupt behavior | N/A | - Bit 7: EnTest (Enable test, periodically sends low pulses) <br> - Bit 6: EnTouch (Sends low pulse on touch detection) <br> - Bit 5: EnChange (Sends low pulse on touch state change) <br> - Bit 4: EnMotion (Sends low pulse on gesture detection) <br> - Bit 0: OnceWLP (Sends one low pulse on long press) |
67+
| AutoReset | 0xFB | Auto-reset time after detecting touch with no valid gesture | 5 seconds | - 0: Disable <br> - 1-5: Time in seconds before auto-reset |
68+
| LongPressTime | 0xFC | Time (in seconds) for a long press to trigger reset | 10 seconds | - 0: Disable <br> - 1-10: Long press duration in seconds |
69+
| IOCtl | 0xFD | IO control settings including soft reset and power options | N/A | - Bit 2: SOFT_RST (0: Disable soft reset, 1: Enable soft reset) <br> - Bit 1: IIC_OD (0: Pull-up resistor, 1: Open-drain) <br> - Bit 0: En1v8 (0: VDD, 1: 1.8V) |
70+
| DisAutoSleep | 0xFE | Disable automatic entry into low-power mode | 0 (enabled) | - 0: Enable auto sleep <br> - Non-zero: Disable auto sleep |

‎examples/auto_sleep/auto_sleep.ino‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
/*
2+
MIT License
3+
4+
Copyright (c) 2021 Felix Biego
5+
6+
Permission is hereby granted, free of charge, to any person obtaining a copy
7+
of this software and associated documentation files (the "Software"), to deal
8+
in the Software without restriction, including without limitation the rights
9+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10+
copies of the Software, and to permit persons to whom the Software is
11+
furnished to do so, subject to the following conditions:
12+
13+
The above copyright notice and this permission notice shall be included in all
14+
copies or substantial portions of the Software.
15+
16+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22+
SOFTWARE.
23+
*/
24+
25+
#include <CST816S.h>
26+
27+
CST816S touch(21, 22, 5, 4); // sda, scl, rst, irq
28+
29+
void setup() {
30+
Serial.begin(115200);
31+
32+
touch.begin();
33+
34+
// Print version information
35+
Serial.print("Touch Firmware Version: ");
36+
Serial.print(touch.data.version);
37+
Serial.print("\t");
38+
Serial.print(touch.data.versionInfo[0]);
39+
Serial.print("-");
40+
Serial.print(touch.data.versionInfo[1]);
41+
Serial.print("-");
42+
Serial.println(touch.data.versionInfo[2]);
43+
44+
// Disable auto sleep to keep the device active (useful during debugging or testing)
45+
touch.disable_auto_sleep();
46+
Serial.println("Auto sleep disabled");
47+
48+
// Optionally, set a custom auto sleep time (e.g., 10 seconds)
49+
touch.set_auto_sleep_time(10);
50+
Serial.println("Auto sleep timeout set to 10 seconds");
51+
52+
// Setting the auto sleep time does not automatically reenable auto sleep
53+
touch.enable_auto_sleep();
54+
}
55+
56+
void loop() {
57+
if (touch.available()) {
58+
Serial.print("Gesture: ");
59+
Serial.print(touch.gesture());
60+
Serial.print("\tPoints: ");
61+
Serial.print(touch.data.points);
62+
Serial.print("\tEvent: ");
63+
Serial.print(touch.data.event);
64+
Serial.print("\tX: ");
65+
Serial.print(touch.data.x);
66+
Serial.print("\tY: ");
67+
Serial.println(touch.data.y);
68+
}
69+
}

‎examples/auto_standby/auto_standby.ino‎

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎examples/double_click/double_click.ino‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,27 @@
1+
/*
2+
MIT License
3+
4+
Copyright (c) 2021 Felix Biego
5+
6+
Permission is hereby granted, free of charge, to any person obtaining a copy
7+
of this software and associated documentation files (the "Software"), to deal
8+
in the Software without restriction, including without limitation the rights
9+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10+
copies of the Software, and to permit persons to whom the Software is
11+
furnished to do so, subject to the following conditions:
12+
13+
The above copyright notice and this permission notice shall be included in all
14+
copies or substantial portions of the Software.
15+
16+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22+
SOFTWARE.
23+
*/
24+
125
#include <CST816S.h>
226

327
CST816S touch(21, 22, 5, 4); // sda, scl, rst, irq
@@ -17,4 +41,4 @@ void loop() {
1741
Serial.println(doubleClickCount);
1842
}
1943
}
20-
}
44+
}

‎examples/user_interrupt/user_interrupt.ino‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
/*
2+
MIT License
3+
4+
Copyright (c) 2021 Felix Biego
5+
6+
Permission is hereby granted, free of charge, to any person obtaining a copy
7+
of this software and associated documentation files (the "Software"), to deal
8+
in the Software without restriction, including without limitation the rights
9+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10+
copies of the Software, and to permit persons to whom the Software is
11+
furnished to do so, subject to the following conditions:
12+
13+
The above copyright notice and this permission notice shall be included in all
14+
copies or substantial portions of the Software.
15+
16+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22+
SOFTWARE.
23+
*/
24+
25+
#include <CST816S.h>
26+
27+
CST816S touch(21, 22, 5, 4); // sda, scl, rst, irq
28+
29+
// Flag to indicate a touch interrupt has occurred
30+
volatile bool touchEventFlag = false;
31+
32+
// Interrupt function to set the flag
33+
void IRAM_ATTR onTouchInterrupt() {
34+
touchEventFlag = true;
35+
}
36+
37+
void setup() {
38+
Serial.begin(9600);
39+
touch.begin();
40+
touch.attachUserInterrupt(onTouchInterrupt);
41+
touch.enable_double_click(); // Enable double-click detection
42+
}
43+
44+
void loop() {
45+
// Check if the interrupt flag has been set by the interrupt handler
46+
if (touchEventFlag) {
47+
touchEventFlag = false; // Clear the flag
48+
49+
// Check if there’s touch data available
50+
if (touch.available()) {
51+
// Check if the gesture is a double touch
52+
if (touch.gesture() == "DOUBLE CLICK") {
53+
Serial.println("Double touch detected!");
54+
} else {
55+
Serial.println("Touch event detected, but not a double touch.");
56+
}
57+
}
58+
}
59+
}

0 commit comments

Comments
 (0)