API Reference

touchpio

Capacitive touch sensing using Pico / Pico2 / RP2040 / RP2350 PIO.

  • Author(s): Tod Kurt

Hardware:

Each touch pad connects to a GPIO pin with a ~1MΩ resistor to ground (pull-down, the default) or to VCC (pull-up). Pads can be exposed copper, foil tape, conductive fabric, etc.

This library only works on RP2040- or RP2350-based boards like the Raspberry Pi Pico, QTPY RP2040, and similar.

Software and Dependencies:

References:

class touchpio.TouchIn(touch_pin, pull_type=digitalio.Pull.DOWN, max_count=10_000)

Read the state of a single capacitive touch sensor.

Parameters:

  • touch_pin (Pin) – the pin to read from

  • pull_type – digitalio.Pull.DOWN (default) for external pull-down resistors, or digitalio.Pull.UP for external pull-up resistors.

  • max_count (int) – the maximum possible pin value (a timeout effectively)

property raw_value

The raw touch measurement as an int. (read-only)

property value

Whether the touch pad is being touched or not. (read-only) True when raw_value > threshold.

class touchpio.TouchInMulti(first_pin, num_pins=8, pull_type=digitalio.Pull.DOWN, num_samples=50, sample_delay=3, touch_threshold=3)

Parallel capacitive touch reader for up to 16 channels on RP2040/RP2350.

Uses a single PIO state machine to read up to 16 capacitive touch pads simultaneously, streaming pin snapshots via autopush with a tunable inter-sample delay.

Hardware:

Each pad connects to a contiguous GPIO with a ~1MΩ resistor to ground (pull-down, the default) or to VCC (pull-up). Pads are exposed copper, foil tape, conductive fabric, etc.

Parameters:

  • first_pin – The first GPIO pin (a microcontroller.Pin or board pin). Channels use contiguous GPIOs starting here.

  • num_pins (int) – Number of touch channels (1–16).

  • pull_type – digitalio.Pull.DOWN (default) for external pull-down resistors, or digitalio.Pull.UP for external pull-up resistors.

  • num_samples (int) – Number of discharge snapshots per scan. Default 50.

  • sample_delay (int) – PIO inter-sample delay (0–31). Controls time between snapshots: (sample_delay + 1) × 256ns @ 125 MHz. Lower values → finer time resolution, but the measurement window (num_samples × time_per_sample) must cover your RC discharge curve. Default 5 → ~1.5µs per sample.

  • touch_threshold (int) – Raw count above baseline to register a touch. Scale this with num_samples. Default 5.

import board
import digitalio
from touchpio import TouchInMulti

touch = TouchInMulti(first_pin=board.GP0, num_pins=8)
touch.calibrate()

while True:
  values = touch.read()
  for i, v in enumerate(values):
    if v > 0:
      print(f"Pad {i}: {v}")
calibrate(num_samples=16)

Set baseline from the average of num_samples untouched scans.

deinit()

Release the PIO state machine.

read()

Read capacitance deltas above baseline.

Returns a list of ints (length num_pins). Zero means untouched; positive values indicate a touch.

property sample_delay

PIO delay loop count (0–31). Time per sample ≈ (value+1) × 256ns.

scan_raw()

Perform one charge-discharge scan.

Returns a list of ints (length num_pins). Each value is the number of snapshots where that pin was still in its charged state, proportional to pad capacitance.