mpr121.h File Reference

NXP MPR121 12-channel capacitive-touch controller codec (DETWS_ENABLE_MPR121). More...

#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Macros
#define	MPR121_ELECTRODES   12
	Sense electrodes on the MPR121 (ELE0..ELE11).
#define	MPR121_INIT_MAX   82
	Largest init sequence in bytes: (17 fixed + 2*12 threshold) pairs * 2 bytes.

Functions
uint16_t	mpr121_touched (uint8_t status_lo, uint8_t status_hi)
	Decode the 12-electrode touch bitmask from the two status registers (0x00 low, 0x01 high). Bit i (0..11) is set when electrode i is touched; proximity (bit 12) and the over-current flag are masked out (see mpr121_proximity / mpr121_overcurrent).
bool	mpr121_is_touched (uint16_t mask, uint8_t e)
	True if electrode e (0..11) is touched in a mask from mpr121_touched.
bool	mpr121_proximity (uint8_t status_hi)
	True if the proximity electrode (status bit 12) is active.
bool	mpr121_overcurrent (uint8_t status_hi)
	True if the over-current flag (status bit 15) is set (wiring fault / short).
uint16_t	mpr121_word10 (uint8_t lsb, uint8_t msb)
	Combine a little-endian LSB/MSB register pair into a 10-bit value (filtered/baseline).
size_t	mpr121_build_init (uint8_t *buf, size_t cap, uint8_t n_electrodes, uint8_t touch_thr, uint8_t release_thr)
	Build the MPR121 bring-up sequence as consecutive (register, value) byte pairs.
bool	mpr121_begin (uint8_t addr)
	Reset + configure the MPR121 at addr over I2C.
uint16_t	mpr121_read_touched ()
	Read the current 12-electrode touch bitmask (0 if the device is absent).
uint16_t	mpr121_read_filtered (uint8_t e)
	Read electrode e's 10-bit filtered capacitance value.

Detailed Description

NXP MPR121 12-channel capacitive-touch controller codec (DETWS_ENABLE_MPR121).

The MPR121 reports a 16-bit touch-status word (registers 0x00/0x01): bits 0-11 are the twelve electrodes, bit 12 is the proximity electrode, and bit 15 is the over-current flag. It also exposes 10-bit filtered capacitance and 8-bit baseline per electrode. Bringing it up is a fixed sequence of register writes (soft reset, the NXP filter/AFE defaults, per-electrode touch/release thresholds, and the electrode-configuration register that starts it running).

This codec is pure and host-tested: mpr121_touched / mpr121_word10 decode the reported words, and mpr121_build_init emits the whole bring-up sequence as (register, value) byte pairs (so the exact bytes are verifiable off-target). On an ESP32 the binding replays that sequence over I2C (Wire) and reads the status; only that touches hardware.

A cheap solder-and-bench-test breakout for touch buttons / sliders: wire it up, touch a pad, watch the bit set.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file mpr121.h.

Macro Definition Documentation

MPR121_ELECTRODES

#define MPR121_ELECTRODES   12

Sense electrodes on the MPR121 (ELE0..ELE11).

Definition at line 33 of file mpr121.h.

MPR121_INIT_MAX

#define MPR121_INIT_MAX   82

Largest init sequence in bytes: (17 fixed + 2*12 threshold) pairs * 2 bytes.

Definition at line 36 of file mpr121.h.

Function Documentation

mpr121_touched()

uint16_t mpr121_touched	(	uint8_t	status_lo,
		uint8_t	status_hi
	)

Decode the 12-electrode touch bitmask from the two status registers (0x00 low, 0x01 high). Bit i (0..11) is set when electrode i is touched; proximity (bit 12) and the over-current flag are masked out (see mpr121_proximity / mpr121_overcurrent).

mpr121_is_touched()

bool mpr121_is_touched	(	uint16_t	mask,
		uint8_t	e
	)

True if electrode e (0..11) is touched in a mask from mpr121_touched.

mpr121_proximity()

bool mpr121_proximity

(

uint8_t

status_hi

)

True if the proximity electrode (status bit 12) is active.

mpr121_overcurrent()

bool mpr121_overcurrent

(

uint8_t

status_hi

)

True if the over-current flag (status bit 15) is set (wiring fault / short).

mpr121_word10()

uint16_t mpr121_word10	(	uint8_t	lsb,
		uint8_t	msb
	)

Combine a little-endian LSB/MSB register pair into a 10-bit value (filtered/baseline).

mpr121_build_init()

size_t mpr121_build_init	(	uint8_t *	buf,
		size_t	cap,
		uint8_t	n_electrodes,
		uint8_t	touch_thr,
		uint8_t	release_thr
	)

Build the MPR121 bring-up sequence as consecutive (register, value) byte pairs.

Emits: soft reset, ECR stop, the NXP rising/falling/touched filter defaults, per-electrode touch/release thresholds for n_electrodes, debounce, CONFIG1/CONFIG2, and finally the ECR that enables n_electrodes with baseline tracking. Replay each pair as an I2C register write, in order (the ECR-start pair must be written last).

Returns

the number of bytes written (pairs * 2), or 0 if cap is too small / args invalid.

mpr121_begin()

bool mpr121_begin

(

uint8_t

addr

)

Reset + configure the MPR121 at addr over I2C.

Returns

true if it acknowledged.

mpr121_read_touched()

uint16_t mpr121_read_touched

(

)

Read the current 12-electrode touch bitmask (0 if the device is absent).

mpr121_read_filtered()

uint16_t mpr121_read_filtered

(

uint8_t

e

)

Read electrode e's 10-bit filtered capacitance value.