API Reference

ts20

Driver for TouchSemi TS20 I2C capacitive touch chip

The TS20 is a 20-channel capacitive touch sensor with automatic sensitivity calibration. Pads are numbered 0-19 in this library; the datasheet calls them channels CS1-CS20. Sensitivity is 0-15, where 0 is the most sensitive and 15 the least (it is really a touch threshold).

Usage:

import board
import ts20

touch = ts20.TS20(board.I2C(), sensitivity=3)  # all pads
touch[7].sensitivity = 8       # pad 7 only, less sensitive
touch.sensitivity = 5          # back to 5 for every pad
print(touch.touched_pads)      # tuple of 20 booleans
print(touch[7].value)          # single pad

  • Author(s): Tod Kurt

Implementation Notes

Hardware:

Software and Dependencies:

Some aspects of this library copy functions from Adafruit_CircuitPython_CAP1188 and Adafruit_CircuitPython_MPR121. Configuration information from yni2yni/TS20.

class ts20.TS20(i2c: I2C, address: int = _TS20_DEFAULT_ADDRESS, *, sensitivity: int | Sequence[int] = DEFAULT_SENSITIVITY, fine_steps: bool = False, fast_mode: bool = True, response_time: int = 2, first_touch_time: int = 1, high_impedance: bool = False, cal_ctrl: int = _DEFAULT_CAL_CTRL, err_ctrl: int = _DEFAULT_ERR_CTRL, reset_on_change: bool = True)

Driver for the TS20 connected over I2C.

Parameters:

  • i2c – the I2C bus the TS20 is on

  • address – I2C address, 0x6A (ADD=GND) or 0x7A (ADD=VDD)

All remaining options are keyword-only:

Parameters:

  • sensitivity – 0 (most sensitive) to 15 (least), either a single value for every pad or a 20-element list of per-pad values

  • fine_steps – sensitivity step size. False (default) gives normal steps of 0.2%, True gives fine steps of 0.1%

  • fast_mode – True (default) always sensing at the fast rate, False alternates between fast and slow to save power

  • response_time – how many sense periods a touch must persist before it is reported, 0-7

  • first_touch_time – length of the fast-calibration window after reset, 0-3 (13, 25, 50, 100 * 16 periods)

  • high_impedance – True for high sense impedance (more sensitive, noisier), False (default) for low

  • cal_ctrl – raw Cal_CTRL calibration-speed register value

  • err_ctrl – raw Err_CTRL noise-rejection register value

  • reset_on_change – bracket runtime sensitivity writes in a soft reset so the chip latches them. Set False if your board picks up the new values without it; a soft reset restarts calibration and so blanks touches for a moment.

is_touched(pad: int) → bool

True if ‘pad’ (0-19) is being touched.

property noise_detected: bool

True if the TS20 reports a noisy environment.

read_sensitivity_percent(pad: int) → float

Read back the sensitivity the TS20 currently measures on ‘pad’, in percent. This is a measurement, not the value set by set_sensitivity(), and is useful when tuning per-pad values. Blocks for ~150ms per call.

UNTESTED on hardware. Datasheet 8.2.11 literally says “Sensitivity(%) = SEN_DATA/2048”, but an 8-bit SEN_DATA cannot reach the 1.15% reset default that way, so SEN_DATA/2048 is read here as a fraction and scaled to a percent.

read_touches() → List[int]

Read back touches, as a list of 21 ints, one per pad plus the noise-detect flag last. Kept for compatibility; new code should use ‘touched_pads’.

reset() → None

Soft reset the TS20 and write the full configuration.

property sensitivity: List[int]

Sensitivity of every pad as a 20-element list. Set to a single value to change all pads at once, or to a 20-element list to set them individually. 0 is most sensitive, 15 is least.

sensitivity_percent(pad: int) → float

The sensitivity setting of ‘pad’ as the percent change in pad capacitance needed to register a touch (datasheet 8.2.1).

set_sensitivity(value: int | Sequence[int], pad: int | None = None) → None

Set the sensitivity of one pad, or of all pads.

Parameters:

  • value – 0 (most sensitive) to 15 (least). If ‘pad’ is None this may be a single value for every pad or a 20-element list of per-pad values.

  • pad – pad number 0-19, or None for all pads

touched() → int

Touch state of all pads as a 20-bit field, bit 0 is pad 0.

property touched_pads: Tuple[bool, ...]

Tuple of 20 booleans, one per pad, True if touched.

write_config(config_info: Sequence[Tuple[int, int]]) → None

Write an arbitrary set of registers to the TS20. ‘config_info’ is a list of (reg_addr, reg_val) tuples. Escape hatch for registers this driver does not expose.

class ts20.TS20_Pad(ts20: TS20, pad: int)

A single touch pad. Get one with ts20[pad_num].

property sensitivity: int

Sensitivity of this pad, 0 (most sensitive) to 15 (least).

property sensitivity_percent: float

Sensitivity setting of this pad as a capacitance-change percent.

property value: bool

True if this pad is being touched.