You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
ESP32S2: TouchIO default threshold is unsatisfactory #4311
import time
import board
import touchio
touch_IO1 = touchio.TouchIn(board.IO1)
touch_IO2 = touchio.TouchIn(board.IO2)
while True:
if touch_IO.value:
print("Touched IO1!")
if touch_IO.value:
print("Touched IO2!")
time.sleep(0.05)
will result in A1 constantly reading as touched. If additional pins are added (IO3, IO4, etc) then all pins before the last one created will constantly trigger.
@ladyada ping so this is on your radar. I'm investigating now.
@microdev1 interesting. I've edited the post to include the board (Saola Wrover). Your guess was correct, the pins only interfere when they're adjacent, putting them one or more pins away (IO1 and IO3) stops the issue. Should we consider tweaking the threshold value, or breaking it out on the board level? When a wire is connected to the pin, it's so sensitive that even just holding your hand within an inch the wire causes it to go off.
Nevermind, I see it's in the API. Sorry, haven't worked with TouchIO before. Still, I do wonder if it's worth adjusting the threshold from the board level since this could be a confusing issue for a new user.
Ya... while implementing TouchIO... I did all the testing on my microS2 which has very small traces + it is 4 layers thus having different electrical characteristics then most other boards. I think we can settle on a middle ground for threshold values which works for all of the boards... the api also offers some filtering features which might be helpful.
changed the title [-]ESP32S2: creating more than one TouchIO pin causes the previous ones to constantly trigger[/-][+]ESP32S2 Saola: TouchIO pins cause adjacent ones to constantly trigger[/+]on Mar 2, 2021
When the TouchIn object is created, an initial raw_value is read from the pin, and then threshold is set to be 100 + that value.
I doubt that all ports do exactly this, so the docs may need to be updated, but basically I think that for other platforms we've found that adding a constant to a value that is assumed to be the 'background value' was an effective but simple way to set the initial threshold.
changed the title [-]ESP32S2 Saola: TouchIO pins cause adjacent ones to constantly trigger[/-][+]ESP32S2: TouchIO default threshold is unsatisfactory[/+]on Mar 15, 2021
When the TouchIn object is created, an initial raw_value is read from the pin, and then threshold is set to be 100 + that value.
I doubt that all ports do exactly this, so the docs may need to be updated, but basically I think that for other platforms we've found that adding a constant to a value that is assumed to be the 'background value' was an effective but simple way to set the initial threshold.
The threshold is in shared-bindings, so it is indeed all ports. A long time ago we used a multiplicative threshold but that was less satisfactory and less sensitive.
I think this has a concrete cause on ESP32-S2, at least in current CircuitPython (10.3.1, Adafruit FunHouse): the default threshold isn't too low, it wraps around.
Cause. In common_hal_touchio_touchin_construct, peripherals_touch_init() stops, reconfigures and restarts continuous scanning, and then the threshold is set from an immediate raw_value + 100 (TouchIn.c#L22-L29). That first read can happen before the new channel has been measured, and it returns 65535 (the raw value is clipped to UINT16_MAX, touch.c#L133-L135). threshold is a uint16_t (TouchIn.h#L15), so 65535 + 100 wraps to 99. From then on .value (raw_value > threshold) is True for the life of the object.
Output after a reset, with the board on a plain USB charger:
10.3.1 on 2026-09-14
CAP6 first 65535 auto-thr 99
CAP7 first 65535 auto-thr 99
CAP8 first 65535 auto-thr 99
CAP9 first 65535 auto-thr 99
CAP10 first 65535 auto-thr 99
CAP11 first 65535 auto-thr 99
CAP12 first 65535 auto-thr 99
CAP13 first 65535 auto-thr 99
raw/100: 6 7 8 | 9 10 11 12 13
107 655 114|655 655 655 655 655
91 100 107|112 117 109 112 111
91 100 107|112 117 109 112 111
On another run, on a PC's USB, CAP6–CAP9 got a real first reading (thresholds 9227, 10165, 10848, 11227) while CAP10–CAP13 got 65535 and a threshold of 99. Which channels are hit varies from run to run, which fits a race on that first read.
About a second after construction, every channel reads normally: resting readings of 9100–11800, and a finger roughly triples a pad (CAP6: 9100 to 30700–35100). So the readings are fine; only the initial threshold is wrong.
Possible fix: in the constructor, wait for the channel's first real measurement before computing the default threshold (for example, poll briefly while the reading is still UINT16_MAX), and compute + 100 in a wider type clamped to UINT16_MAX. The clamp alone isn't enough: a pad whose threshold ends up at 65535 can never read as touched.
Workaround in user code: create all the TouchIn objects, wait until none reads 65535, then set each threshold yourself (we use 1.5 × the resting reading).
#11756 fixes the wrap-around that @caderoux described above. After a chip reset, an ESP32-S2 or ESP32-S3 touch channel read 65535 until it was first measured, and the default threshold (first reading + 100) wrapped to 99. The PR scans new channels once before using their readings, and it clamps the threshold to 65535.
That doesn't fix the original symptom of this issue, though. A pad's resting reading can rise as more channels are created after it. When it rises by more than 100, the pad reads as touched with nothing touching it.
Measurements
Metro ESP32-S3 running #11756, with nothing connected to the pads. Eight TouchIns were created in order (A0, A5, D2, D3, D4, D7, D8, D9), and the readings were taken 0.5 s after the last one. The results were the same in three runs.
Pad
First reading
After all 8 were created
Change
value
A5
~36700
~37190
+490
True
D3
~29820
~30220
+400
True
D7
~28790
~28905
+115
True in 2 of 3 runs
A0, D2, D4, D8, D9
under +70
False
The cause of the rise hasn't been investigated.
Possible fixes
Proportional margin. Set the default threshold to a percentage above the first reading, instead of a fixed +100. shared-module/touchio already uses raw * 1.05 + 100. The drifts above were at most about 1.3% of the reading. @caderoux measured a finger tripling a pad's reading on a FunHouse, so a margin of 5–10% would still leave plenty of room. The comment in TouchIn.c says touches through fruit and other objects change the reading much less than a finger does, so this needs checking with those too.
Re-baseline existing pads when a channel is added. After peripherals_touch_init() adds a channel and scans, recompute the default threshold of every existing TouchIn from its new reading. This would have to skip any TouchIn whose threshold was set by user code.
Take the baseline later. Set the default threshold on the first read of value, instead of in the constructor. By then the program has usually created all of its pads. A pad created later could still shift the earlier ones.
Use the ESP-IDF benchmark. On touch V2 and V3 (ESP32-S2, S3 and P4), the touch driver keeps a filtered baseline ("benchmark") for each channel and tracks slow drift. value could compare the reading with the benchmark instead of a fixed number. This is the most robust option, but the original ESP32 doesn't have a benchmark, and it changes what threshold means on Espressif compared with other ports.
The first option is the smallest change, and it keeps threshold meaning the same thing on every port.
Activity
microdev1 commentedon Mar 2, 2021
Unable to replicate this. Tested with :-
I suspect interference problems. Can you try with pins which are physically apart from each other.
hierophect commentedon Mar 2, 2021
@microdev1 interesting. I've edited the post to include the board (Saola Wrover). Your guess was correct, the pins only interfere when they're adjacent, putting them one or more pins away (IO1 and IO3) stops the issue. Should we consider tweaking the threshold value, or breaking it out on the board level? When a wire is connected to the pin, it's so sensitive that even just holding your hand within an inch the wire causes it to go off.
hierophect commentedon Mar 2, 2021
Nevermind, I see it's in the API. Sorry, haven't worked with TouchIO before. Still, I do wonder if it's worth adjusting the threshold from the board level since this could be a confusing issue for a new user.
microdev1 commentedon Mar 2, 2021
Ya... while implementing
TouchIO... I did all the testing on my microS2 which has very small traces + it is 4 layers thus having different electrical characteristics then most other boards. I think we can settle on a middle ground for threshold values which works for all of the boards... the api also offers some filtering features which might be helpful.[-]ESP32S2: creating more than one TouchIO pin causes the previous ones to constantly trigger[/-][+]ESP32S2 Saola: TouchIO pins cause adjacent ones to constantly trigger[/+]jepler commentedon Mar 15, 2021
I notice that the docs state
I doubt that all ports do exactly this, so the docs may need to be updated, but basically I think that for other platforms we've found that adding a constant to a value that is assumed to be the 'background value' was an effective but simple way to set the initial threshold.
[-]ESP32S2 Saola: TouchIO pins cause adjacent ones to constantly trigger[/-][+]ESP32S2: TouchIO default threshold is unsatisfactory[/+]dhalbert commentedon Mar 15, 2021
The threshold is in
shared-bindings, so it is indeed all ports. A long time ago we used a multiplicative threshold but that was less satisfactory and less sensitive.4 remaining items
caderoux commentedon Oct 4, 2026
I think this has a concrete cause on ESP32-S2, at least in current CircuitPython (10.3.1, Adafruit FunHouse): the default threshold isn't too low, it wraps around.
Cause. In
common_hal_touchio_touchin_construct,peripherals_touch_init()stops, reconfigures and restarts continuous scanning, and then the threshold is set from an immediateraw_value + 100(TouchIn.c#L22-L29). That first read can happen before the new channel has been measured, and it returns 65535 (the raw value is clipped toUINT16_MAX, touch.c#L133-L135).thresholdis auint16_t(TouchIn.h#L15), so 65535 + 100 wraps to 99. From then on.value(raw_value > threshold) isTruefor the life of the object.Repro (nothing else in
code.py):Output after a reset, with the board on a plain USB charger:
On another run, on a PC's USB, CAP6–CAP9 got a real first reading (thresholds 9227, 10165, 10848, 11227) while CAP10–CAP13 got 65535 and a threshold of 99. Which channels are hit varies from run to run, which fits a race on that first read.
About a second after construction, every channel reads normally: resting readings of 9100–11800, and a finger roughly triples a pad (CAP6: 9100 to 30700–35100). So the readings are fine; only the initial threshold is wrong.
Possible fix: in the constructor, wait for the channel's first real measurement before computing the default threshold (for example, poll briefly while the reading is still
UINT16_MAX), and compute+ 100in a wider type clamped toUINT16_MAX. The clamp alone isn't enough: a pad whose threshold ends up at 65535 can never read as touched.Workaround in user code: create all the
TouchInobjects, wait until none reads 65535, then set eachthresholdyourself (we use 1.5 × the resting reading).dhalbert commentedon Nov 5, 2026
Claude wrote this:
#11756 fixes the wrap-around that @caderoux described above. After a chip reset, an ESP32-S2 or ESP32-S3 touch channel read 65535 until it was first measured, and the default threshold (first reading + 100) wrapped to 99. The PR scans new channels once before using their readings, and it clamps the threshold to 65535.
That doesn't fix the original symptom of this issue, though. A pad's resting reading can rise as more channels are created after it. When it rises by more than 100, the pad reads as touched with nothing touching it.
Measurements
Metro ESP32-S3 running #11756, with nothing connected to the pads. Eight
TouchIns were created in order (A0, A5, D2, D3, D4, D7, D8, D9), and the readings were taken 0.5 s after the last one. The results were the same in three runs.valueTrueTrueTruein 2 of 3 runsFalseThe cause of the rise hasn't been investigated.
Possible fixes
shared-module/touchioalready usesraw * 1.05 + 100. The drifts above were at most about 1.3% of the reading. @caderoux measured a finger tripling a pad's reading on a FunHouse, so a margin of 5–10% would still leave plenty of room. The comment inTouchIn.csays touches through fruit and other objects change the reading much less than a finger does, so this needs checking with those too.peripherals_touch_init()adds a channel and scans, recompute the default threshold of every existingTouchInfrom its new reading. This would have to skip anyTouchInwhosethresholdwas set by user code.value, instead of in the constructor. By then the program has usually created all of its pads. A pad created later could still shift the earlier ones.valuecould compare the reading with the benchmark instead of a fixed number. This is the most robust option, but the original ESP32 doesn't have a benchmark, and it changes whatthresholdmeans on Espressif compared with other ports.The first option is the smallest change, and it keeps
thresholdmeaning the same thing on every port.