MojoScale Studio Docs
API Reference

touch

Capacitive touch sensor module.

All modules Open Studio
Studio Docs Sensors & I/O

import touch

The touch module reads ESP32-family capacitive touch pads. It is useful for simple touch buttons, metal pads, foil pads, proximity-style panels, and other GPIO-free human input surfaces. Use ``touch.Pad(...)`` to create an independent pad object when you want clean multi-pad code. Touch readings are calibrated into a baseline and a positive delta. A larger delta means the pad is more likely being touched. This keeps user code the same across ESP32 and ESP32-S3 even though the native hardware differs.

Quick example

import touch
import system

left = touch.Pad(1)
right = touch.Pad(2)

def check_buttons():
    if left.touched():
        print("left touched")
    if right.touched():
        print("right touched")

system.schedule("touch_check", 100, 100, -1, check_buttons)

reading = left.read()
print(reading["value"], reading["delta"])

importtouch

Capacitive touch sensor module.

The touch module reads ESP32-family capacitive touch pads. It is useful for simple touch buttons, metal pads, foil pads, proximity-style panels, and other GPIO-free human input surfaces. Use ``touch.Pad(...)`` to create an independent pad object when you want clean multi-pad code. Touch readings are calibrated into a baseline and a positive delta. A larger delta means the pad is more likely being touched. This keeps user code the same across ESP32 and ESP32-S3 even though the native hardware differs.

API 16 available

touch.Pad(pad: int, samples: int = None, threshold_ratio: float = None) -> touch_pad

Create an independent capacitive touch pad object.

Parameters
Name Type Pass as Required Description
pad int positional or keyword Yes Touch pad number to configure and calibrate.
samples int positional or keyword No Optional number of samples used for calibration. Defaults to 12.
threshold_ratio float positional or keyword No Optional fraction of the baseline used as the touch threshold. Defaults to 0.20.
Returns

touch_pad touch_pad object.

touch.Pad().calibrate(samples=12, threshold_ratio=0.20) -> dict

Recalibrate this pad.

Parameters
Name Type Pass as Required Description
samples int positional or keyword No Optional value. Defaults to 12.
threshold_ratio float positional or keyword No Optional value. Defaults to 0.20.

touch.Pad().read() -> dict

Read this pad's value, delta, threshold, and touched state.

touch.Pad().touched() -> bool

Return whether this pad is currently touched.

touch.Pad().threshold(value=None) -> int

Get or set this pad's raw threshold.

Parameters
Name Type Pass as Required Description
value any positional or keyword No Optional value. Defaults to None.

touch.Pad().info() -> dict

Return this pad's configuration and calibration state.

touch.Pad().close() -> bool

Mark this pad object closed.

touch.begin(pads: list = None, samples: int = None, threshold_ratio: float = None) -> bool

Initialize and optionally calibrate touch pads.

Parameters
Name Type Pass as Required Description
pads list positional or keyword No Optional touch pad number or list of touch pad numbers. If provided, each pad is configured and calibrated immediately.
samples int positional or keyword No Optional number of samples used for calibration. Defaults to 12.
threshold_ratio float positional or keyword No Optional fraction of the baseline used as the touch threshold. Defaults to 0.20.
Returns

bool True when the touch driver starts and all requested pads calibrate.

touch.calibrate(pad: int, samples: int = None, threshold_ratio: float = None) -> dict

Calibrate one touch pad.

Keep the pad untouched while calibrating. The module stores the average raw value as the baseline and computes a threshold from ``threshold_ratio``.

Parameters
Name Type Pass as Required Description
pad int positional or keyword Yes Touch pad number to calibrate.
samples int positional or keyword No Optional number of raw samples to average. Defaults to the configured module sample count.
threshold_ratio float positional or keyword No Optional fraction of baseline used to compute the raw touch threshold.
Returns

dict Dict with ``ok``, ``pad``, ``gpio``, ``baseline``, ``threshold``, ``samples``, and ``threshold_ratio``.

touch.read(pad: int) -> dict

Read one touch pad.

Parameters
Name Type Pass as Required Description
pad int positional or keyword Yes Touch pad number to read.
Returns

dict Dict with ``ok``, ``pad``, ``gpio``, raw ``value``, ``baseline``, positive ``delta``, ``threshold``, ``calibrated``, and ``touched``.

touch.touched(pad: int) -> bool

Return whether one touch pad is currently touched.

Parameters
Name Type Pass as Required Description
pad int positional or keyword Yes Touch pad number to read and compare against its calibrated threshold.
Returns

bool True when the current delta is greater than or equal to the calibrated threshold.

touch.read_all() -> list

Read all configured touch pads.

Returns

list List of reading dicts in the same shape as ``touch.read(pad)``.

touch.threshold(pad: int, value: int = None) -> int

Get or set a pad's raw touch threshold.

Parameters
Name Type Pass as Required Description
pad int positional or keyword Yes Touch pad number.
value int positional or keyword No Optional raw threshold value. If provided, it replaces the calibrated threshold for this pad.
Returns

int Current raw threshold value for the pad.

touch.pads() -> list

List touch pads available on the current board target.

Returns

list List of dicts with ``pad``, ``gpio``, ``configured``, and ``calibrated``.

touch.reset() -> bool

Stop the touch driver and clear calibration state.

Returns

bool True when internal module state is reset.

touch.info() -> dict

Return touch module state.

Returns

dict Dict with support status, initialization state, board target, pad counts, calibration count, sample count, and threshold ratio.