touchCalibration.hpp File Reference

Three-point touch-screen calibration for the RA8875's resistive panel. More...

#include "Adafruit_RA8875.h"

Go to the source code of this file.

Functions
bool	touchCalibrationCompute (const tsPoint_t *display, const tsPoint_t *screen, tsMatrix_t *matrix)
	Calculates the calibration matrix from three known display points and the raw touch readings taken at those points.
bool	touchCalibrationApply (const tsMatrix_t *matrix, const tsPoint_t *raw, tsPoint_t *display)
	Converts one raw touch reading into a display pixel position.
bool	touchCalibrationRun (Adafruit_RA8875 *display, UART_HandleTypeDef *uart, tsMatrix_t *matrix)
	Runs the interactive calibration: draws three targets one at a time, waits for the user to touch each, and computes the matrix.

Detailed Description

Three-point touch-screen calibration for the RA8875's resistive panel.

Project: F439_CPP_SPI_RA8875_TFT_LCD_04

Ported from the calibration code in the original RA8875 tutorial project, which is based on the public-domain touch-screen calibration code by Carlos E. Vidales (copyright (c) 2001) as used in Adafruit's RA8875 touch example (see AN2173 from Cypress Microsystems and "Calibration in touch-screen systems", Analog Applications Journal 3Q 2007). The matrix mathematics is unchanged; the Arduino, EEPROM and interrupt-pin pieces are not part of this port: touch is detected by polling the RA8875 over SPI, and storing the matrix is done separately.

Warning

Thread safety: touchCalibrationCompute() and touchCalibrationApply() keep no state of their own, so they may be called from several contexts as long as each call uses its own data. touchCalibrationRun() is NOT thread-safe and not ISR-safe: it draws on and reads from one shared Adafruit_RA8875 object, and every drawing or touch call is several separate SPI transactions on a bus other drivers also use, so an interleaving caller could corrupt them. It also blocks until the user has touched the three targets.

Created on: Oct 5, 2026 Author: johng

Definition in file touchCalibration.hpp.

Function Documentation

touchCalibrationApply()

bool touchCalibrationApply	(	const tsMatrix_t *	matrix,
		const tsPoint_t *	raw,
		tsPoint_t *	display )

Converts one raw touch reading into a display pixel position.

Parameters

matrix	Calibration matrix from touchCalibrationCompute().
raw	Raw touch reading (the 10-bit values from touchRead()).
display	Receives the display position in pixels (may fall outside the screen).

Returns

true on success; false if an argument is null or the matrix divider is zero.

Definition at line 207 of file touchCalibration.cpp.

References tsMatrix_t::An, tsMatrix_t::Bn, tsMatrix_t::Cn, tsMatrix_t::Divider, tsMatrix_t::Dn, tsMatrix_t::En, tsMatrix_t::Fn, Point::x, and Point::y.

Referenced by testTouch().

touchCalibrationCompute()

bool touchCalibrationCompute	(	const tsPoint_t *	display,
		const tsPoint_t *	screen,
		tsMatrix_t *	matrix )

Calculates the calibration matrix from three known display points and the raw touch readings taken at those points.

Parameters

display	Array of three points: where the targets were drawn on the display, in pixels.
screen	Array of three points: the raw touch readings for those targets.
matrix	Receives the calibration coefficients.

Returns

true on success; false if an argument is null or the three raw points lie on one line (the divider is zero), in which case the matrix is not usable.

Definition at line 172 of file touchCalibration.cpp.

References tsMatrix_t::An, tsMatrix_t::Bn, tsMatrix_t::Cn, tsMatrix_t::Divider, tsMatrix_t::Dn, tsMatrix_t::En, tsMatrix_t::Fn, Point::x, and Point::y.

Referenced by touchCalibrationRun().

touchCalibrationRun()

bool touchCalibrationRun	(	Adafruit_RA8875 *	display,
		UART_HandleTypeDef *	uart,
		tsMatrix_t *	matrix )

Runs the interactive calibration: draws three targets one at a time, waits for the user to touch each, and computes the matrix.

Parameters

display	The RA8875 display object, already started with begin() and with touch enabled.
uart	The UART handle of the serial terminal (USART1 here); the terminal must be open.
matrix	Receives the calibration coefficients.

Returns

true when a usable matrix was calculated; false if an argument is null or the three touches could not give a usable matrix after three attempts (for example because the targets were not touched where they were drawn).

After the first and the second target the terminal asks for the space bar and the next target appears only then, so an extra tap cannot be taken as the next touch. Pressing Esc there instead throws that touch away and shows the same target again. Each target counts only when the pen is held on it for about 0.3 seconds: a green ring then appears and the pen can be lifted. Short taps are ignored, and the readings taken during the hold are averaged. Each attempt waits for the user as long as it takes. Only a bad set of touches, which a new attempt can fix, is retried.

Definition at line 217 of file touchCalibration.cpp.

References Adafruit_RA8875::fillScreen(), Adafruit_RA8875::height(), RA8875_WHITE, touchCalibrationCompute(), and Adafruit_RA8875::width().

Referenced by testTouch().