STMPE610

This module provides a device-level API for STMPE610 resistive touch controllers over SPI (e.g. More...

Collaboration diagram for STMPE610:

Data Structures
struct	dev_stmpe610_config_t
	Optional STMPE610 initialization options. More...

Typedefs
typedef struct dev_stmpe610_t	dev_stmpe610_t
	Opaque STMPE610 handle.
typedef void(*	dev_stmpe610_callback_t) (dev_stmpe610_t *stmpe610, const hid_touch_t *touch, void *userdata)
	Touch event callback invoked from dev_stmpe610_poll(). More...

Lifecycle
void	dev_stmpe610_default_config (dev_stmpe610_config_t *config)
	Fill an STMPE610 config struct with safe defaults. More...
dev_stmpe610_t *	dev_stmpe610_init (hw_deviceio_t *device, const dev_stmpe610_config_t *config)
	Initialize an STMPE610 resistive touch controller over SPI. More...
void	dev_stmpe610_deinit (dev_stmpe610_t *stmpe610)
	Deinitialize an STMPE610 controller. More...
void	dev_stmpe610_set_callback (dev_stmpe610_t *stmpe610, dev_stmpe610_callback_t callback, void *userdata)
	Set (or replace) the callback invoked from dev_stmpe610_poll(). More...

Properties
bool	dev_stmpe610_irq_active (const dev_stmpe610_t *stmpe610)
	Report whether the STMPE610 interrupt line is currently asserted. More...

Methods
void	dev_stmpe610_poll (dev_stmpe610_t *stmpe610)
	Poll the controller, invoking the callback if the touch state changed. More...

HID
hid_device_t *	dev_stmpe610_register_hid (hid_t *instance, dev_stmpe610_t *stmpe610, uint32_t polling_interval_ms, void *userdata)
	Register an STMPE610 controller as a HID touchscreen source. More...

Detailed Description

This module provides a device-level API for STMPE610 resistive touch controllers over SPI (e.g.

Adafruit's 2.8" PiTFT resistive touch display, which pairs it with an ILI9341 display controller on the same SPI bus but a separate chip-select).

Typedef Documentation

dev_stmpe610_callback_t

typedef void(* dev_stmpe610_callback_t) (dev_stmpe610_t *stmpe610, const hid_touch_t *touch, void *userdata)

Touch event callback invoked from dev_stmpe610_poll().

Parameters

stmpe610	STMPE610 handle.
touch	The touch contact that changed - unlike a capacitive controller, STMPE610 is resistive and only ever reports one point at a time, always as hid_touch_t::slot 0. hid_touch_t::state is hid_state_on for a new contact, hid_state_repeat for an existing one that's still down but moved, and hid_state_off for a lifted one - see dev_ft6236_poll()'s own doc on the "repeat always follows on" guarantee this driver makes the same way. hid_touch_t::point and hid_touch_t::pressure are the controller's raw, uncalibrated 12-bit ADC readings (roughly 0-4095 for point, 8 bits for pressure) - not screen pixel coordinates or a real pressure unit. Each is a voltage-ratio measurement across the resistive panel along one axis (and, for pressure, a similar contact-resistance reading), so the exact range and scale is specific to the physical panel and its wiring. Turning point into pixel coordinates needs an application-level calibration step - typically touching each screen corner once to record the raw min/max seen there, then linearly mapping subsequent raw readings into the display's actual pixel range. This driver does not do that mapping itself.
userdata	User-defined data pointer passed to dev_stmpe610_set_callback().

Definition at line 64 of file stmpe610.h.

Function Documentation

dev_stmpe610_default_config()

void dev_stmpe610_default_config

(

dev_stmpe610_config_t *

config

)

Fill an STMPE610 config struct with safe defaults.

Parameters

config

Config structure to initialize.

dev_stmpe610_deinit()

void dev_stmpe610_deinit

(

dev_stmpe610_t *

stmpe610

)

Deinitialize an STMPE610 controller.

Parameters

stmpe610

STMPE610 handle.

Passing NULL is safe and is a no-op.

dev_stmpe610_init()

dev_stmpe610_t* dev_stmpe610_init	(	hw_deviceio_t *	device,
		const dev_stmpe610_config_t *	config
	)

Initialize an STMPE610 resistive touch controller over SPI.

Parameters

device	SPI device handle from hw_spi_init() / hw_spi_init_default() / hw_spi_init_device(), already opened on the controller's own chip-select (separate from any display sharing the same bus).
config	Optional pointer to initialization options - see dev_stmpe610_config_t's own doc for the interrupt pin. Pass NULL to use default values (no interrupt pin - always poll).

Returns

STMPE610 handle, or NULL on failure (including a chip ID mismatch - nothing responding correctly at the given chip-select).

No callback is attached here - use dev_stmpe610_set_callback afterward if dev_stmpe610_poll should report touches somewhere.

dev_stmpe610_irq_active()

bool dev_stmpe610_irq_active

(

const dev_stmpe610_t *

stmpe610

)

Report whether the STMPE610 interrupt line is currently asserted.

Parameters

stmpe610

STMPE610 handle.

Return values

true	The controller is signalling a pending update.
false	No pending update is signalled, or no interrupt pin exists.

dev_stmpe610_poll()

void dev_stmpe610_poll

(

dev_stmpe610_t *

stmpe610

)

Poll the controller, invoking the callback if the touch state changed.

Parameters

stmpe610

STMPE610 handle.

When an interrupt pin is configured, this function skips the SPI transaction entirely when no touch is pending and the previous sample was already idle. The callback set with dev_stmpe610_set_callback() (if any) is invoked only when a new contact, a moved contact, or a lifted contact is actually detected - never for an unchanged, still-idle, or still-touching-with-nothing-new poll. hid_state_repeat always follows an hid_state_on for the same slot (0, the only one this controller ever uses) - unlike dev_ft6236_poll(), which needs to synthesize that guarantee for a torn-read edge case (see its own doc), it holds here naturally: this driver's own had_touch tracking already decides on-vs-repeat the same way it decides when to stop reporting at all, so there's no path that reaches "repeat" without "on" already delivered.

dev_stmpe610_register_hid()

hid_device_t* dev_stmpe610_register_hid	(	hid_t *	instance,
		dev_stmpe610_t *	stmpe610,
		uint32_t	polling_interval_ms,
		void *	userdata
	)

Register an STMPE610 controller as a HID touchscreen source.

Parameters

instance	HID instance that owns the registration.
stmpe610	Already-initialized STMPE610 handle - HID observes it, it does not take ownership (dev_stmpe610_deinit() remains the caller's own responsibility, same as dev_stmpe610_init()'s own device/int_pin arguments).
polling_interval_ms	How often HID calls dev_stmpe610_poll() for this device, in milliseconds. Clamped up to a small minimum (STMPE610_HID_MIN_POLLING_INTERVAL_MS) purely to avoid needless SPI chatter - unlike FT6236 (see its own dev_ft6236_register_hid), this isn't a correctness requirement: the FIFO_STA/FIFO data registers this driver reads are hardware-arbitrated, so polling faster than the panel's own scan rate just finds FIFO_STA empty more often, not torn data.
userdata	Opaque user data retrievable via hid_device_userdata() on the returned device. To reach stmpe610 itself instead, use hid_device_handle().

Returns

Registered HID device descriptor, or NULL on failure.

Emits a hid_event_type_touch event (via hid_event_queue_touch()) for every touch dev_stmpe610_poll() reports as changed - see dev_stmpe610_callback_t's own doc for exactly what state/point/slot/ pressure mean here.

Replaces whatever callback stmpe610 already had attached via dev_stmpe610_set_callback(), the same way hid_register_wifi() replaces whatever callback its own hw_wifi_t already had - avoiding that collision is the caller's own responsibility, same as there.

hid_deregister() detaches the callback (equivalent to dev_stmpe610_set_callback(stmpe610, NULL, NULL)) but leaves stmpe610 itself initialized.

dev_stmpe610_set_callback()

void dev_stmpe610_set_callback	(	dev_stmpe610_t *	stmpe610,
		dev_stmpe610_callback_t	callback,
		void *	userdata
	)

Set (or replace) the callback invoked from dev_stmpe610_poll().

Parameters

stmpe610	STMPE610 handle.
callback	New callback, or NULL to stop invoking one.
userdata	User-defined data pointer passed to callback.

Replaces whatever callback a previous call to this set, if any - there is no way to have more than one observer. dev_stmpe610_register_hid() uses this to redirect touch events into HID, taking over from whatever the caller may have already set - see its own doc.