hdw-touch.h File Reference

Detailed Description

Design Philosophy

This component handles touch pads, which are touch-sensitive areas on the PCB.

The individual touch pads can be represented as a single circular analog touch pad which reports touches in polar coordinates with intensity or multiple linear touch strips which report 1D position and intensity. The hardware will dictate how touch pads are represented.

Touch Pad Design Philosophy

Touch hardware has changed between years, so differently shaped touch pads can be configured either with initTouchLinear() (multiple 1D touch strips) or initTouchJoystick() (single circular 2D touch pad). Swadge modes should not use readings from the physically discrete touch pads.

Touch pads are not polled. Events like touches are not queued to be processed later. The individual Swadge mode must poll the current touch state with getTouchJoystick() or getTouchLinear(). Both of those functions will report the position and intensity of the touch.

If touches are polled from a shape that was not initialized, no data will be returned.

Touch pad areas are set up and read with Touch Sensor.

Usage

You don't need to call initTouchPads() or deinitTouchPads(). The system does at the appropriate times. Likewise, initTouchLinear() or initTouchJoystick() will be called during system initialization depending on the hardware configuration.

If configured, you may call getTouchJoystick() to get the analog touch position. Three utility functions are provided in touchUtils.h to interpret touch data different ways.

• getTouchJoystickZones() is available to translate the analog touches into a four, five, eight, or nine-way virtual directional pad.
• getTouchSpins() is available to count the number of times the touch joystick was circled around.
• getTouchCartesian() is available to translate the polar coordinates of the touch into the Cartesian X-Y plane

If configured, you may call getTouchLinear() to get get the analog touch positions. There are no utilities for extra processing of 1D data.

Example

// Check if the circular touch area is touched, and print values if it is
int32_t phi, r, intensity;
if (getTouchJoystick(&phi, &r, &intensity))
{
    ESP_LOGI("TCH", "touch center: %" PRIu32 ", intensity: %" PRIu32 ", intensity %" PRIu32, phi, r, intensity);
}
else
{
    ESP_LOGI("TCH", "no touch");
}
 
linearTouch_t touches[2] = {0};
getTouchLinear(touches, ARRAY_SIZE(touches));
for (uint8_t tIdx = 0; tIdx < ARRAY_SIZE(touches); tIdx++)
{
    if (touches[tIdx].touched)
    {
        ESP_LOGI("TCH", "Touch %" PRIu8 " at %" PRId32 ", intensity %" PRId32, tIdx, touches[tIdx].position,
                 touches[tIdx].intensity);
    }
    else
    {
        ESP_LOGI("TCH", "No Touch on %" PRIu8, tIdx);
    }
}

Go to the source code of this file.

Data Structures
struct	touchLinearCfg_t
	The configuration for a linear set of touch pads. More...
struct	linearTouch_t
	The result of a linear touch. More...

Functions
void	initTouchPads (const touch_pad_t *touchPads, uint8_t numTouchPads, float touchPadSensitivity, bool denoiseEnable)
	Initialize touchPad sensors.
void	deinitTouchPads (void)
	Deinitialize the touch pads.
void	powerUpTouchPads (void)
	Power up the touchpad.
void	powerDownTouchPads (void)
	Power down the touchpad.
void	initTouchJoystick (uint8_t centerPadIdx, const uint8_t *ringPadIdxs)
	Initialize the touch pads as a virtual joystick. The arguments are indices into the array touchPads[] which should have been previously passed into initTouchPads().
bool	getTouchJoystick (int32_t *phi, int32_t *r, int32_t *intensity)
	Get high-level touch input, an analog input.
void	initTouchLinear (const touchLinearCfg_t *touchLinearCfgs, uint8_t numTouchLinearCfgs)
	Initialize the touch pads as a set of linear arrays.
uint8_t	getTouchLinear (linearTouch_t *touches, uint8_t numLinearTouches)
	Get a high level touch input from each configured linear array.

---

Data Structure Documentation

touchLinearCfg_t

struct touchLinearCfg_t

Data Fields
uint8_t	numTouchPads	The number of touch pads in the linear configuration.
const uint8_t *	touchPadIdxs	A list of touch pad indices into touchPads[] given to initTouchPads().

linearTouch_t

struct linearTouch_t

Data Fields
int32_t	position	The position of the touch, from 0 to 1023.
int32_t	intensity	How hard the touch is being pressed.
bool	touched	true if a touch is registered, false if it isn't

Function Documentation

initTouchPads()

void initTouchPads	(	const touch_pad_t *	touchPads,
		uint8_t	numTouchPads,
		float	touchPadSensitivity,
		bool	denoiseEnable )

Initialize touchPad sensors.

Parameters

touchPads	A list of touchPads to initialize
numTouchPads	The number of touchPads to initialize
touchPadSensitivity	The sensitivity to set for these touchPads
denoiseEnable	true to denoise the input, false to use it raw

deinitTouchPads()

void deinitTouchPads

(

void

)

Deinitialize the touch pads.

powerUpTouchPads()

void powerUpTouchPads

(

void

)

Power up the touchpad.

powerDownTouchPads()

void powerDownTouchPads

(

void

)

Power down the touchpad.

initTouchJoystick()

void initTouchJoystick	(	uint8_t	centerPadIdx,
		const uint8_t *	ringPadIdxs )

Initialize the touch pads as a virtual joystick. The arguments are indices into the array touchPads[] which should have been previously passed into initTouchPads().

Parameters

centerPadIdx	The touch pad index to use as the center of the joystick
ringPadIdxs	A list of touch pad indices to use as the ring of the joystick. Must be at least NUM_TZ_RING long.

getTouchJoystick()

bool getTouchJoystick	(	int32_t *	phi,
		int32_t *	r,
		int32_t *	intensity )

Get high-level touch input, an analog input.

Parameters

[out]	phi	the angle of the touch. Where 0 is right, 320 is up, 640 is left and 960 is down.
[out]	r	is how far from center you are. 511 is on the outside edge, 0 is on the inside.
[out]	intensity	is how hard the user is pressing.

Returns

true if touched (joystick), false if not touched (no centroid)

initTouchLinear()

void initTouchLinear	(	const touchLinearCfg_t *	touchLinearCfgs,
		uint8_t	numTouchLinearCfgs )

Initialize the touch pads as a set of linear arrays.

Parameters

touchLinearCfgs	A list of configurations for each linear touch pad array
numTouchLinearCfgs	The number of configurations of linear touch pad arrays. This memory is not copied, so it must be valid for the lifetime of the firmware.

getTouchLinear()

uint8_t getTouchLinear	(	linearTouch_t *	touches,
		uint8_t	numLinearTouches )

Get a high level touch input from each configured linear array.

Parameters

[out]	touches	The results of the touch, including if a touch was detected, intensity, and position
[in]	numLinearTouches	The number of linear arrays to try to read

Returns

The number of linear arrays successfully read