N-point affine touch-calibration demo + HIL gate (#262). More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_board_ek_ra8d2_touch.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_display_pal.h"
#include "ra8_display_pal_lcd.h"
#include "ra8_err.h"
#include "ra8_glcdc.h"
#include "ra8_isr.h"
#include "ra8_mstp.h"
#include "ra8_panel.h"
#include "ra8_panel_timing.h"
#include "ra8_time.h"
#include "ra8_touch.h"
#include "ra8_touch_cal.h"

Include dependency graph for main.c:

Data Structures
struct	tc_capture_t
	Per-run capture the calibration shims fill for the verify pass. More...

Enumerations
enum	tc_geom_t : uint16_t { k_tc_fb_w = 512U , k_tc_fb_h = 512U , k_tc_inset_px = 40U , k_tc_cross_half = 12U , k_tc_verify_tol = 2U }
	Framebuffer + calibration geometry (no magic numbers). More...
enum	tc_color_t : uint16_t { k_tc_color_bg = 0x0000U , k_tc_color_target = 0xFFFFU , k_tc_color_corrected = 0x07E0U }
	RGB565 palette for the calibration UI. More...
enum	tc_consts_t : uint32_t { k_tc_uart_baud = 115200U , k_tc_max_points = 5U , k_tc_poll_max = 20000U , k_tc_dec_ten = 10U , k_tc_blob_cap = 36U }
	Console / GT911 / poll knobs (no magic numbers). More...

Functions
static void	internal_tc_print (const uint8_t *msg, uint32_t len)
	Emit a byte run on the SCI8 console.
static void	internal_tc_panic_halt (const uint8_t *msg, uint32_t len)
	Print the fail banner and trap (ra8_emulator halts on the BKPT).
static void	internal_tc_print_uint (uint32_t value)
	Print a small unsigned integer in decimal.
static bool	internal_tc_pixel_in_bounds (int32_t v, int32_t dim)
	Report whether a framebuffer coordinate is inside the panel.
static void	internal_tc_put_px (int32_t x, int32_t y, uint16_t color)
	Write one RGB565 pixel, clipped to the framebuffer rectangle.
static void	internal_tc_fb_fill (uint16_t color)
	Fill the whole framebuffer with `color`.
static void	internal_tc_draw_cross (int32_t cx, int32_t cy, uint16_t color)
	Draw a plus-shaped cross-hair centred at (`cx`, `cy`).
static void	internal_tc_setup_or_halt (void)
	Bring up clocks/MSTP/time + the SCI8 console; halt on failure.
static bool	internal_tc_glcdc_bringup (display_handle_t **out_disp)
	Bring the GLCDC layer-1 path up and confirm it is programmed.
static bool	internal_tc_touch_bringup (void)
	Bring up IIC_B (I2C-compat) and open the GT911 touch driver.
static ra8_err_t	internal_tc_draw_target (void *ctx, ra8_touch_cal_point_t target)
	Draw shim: paint a target cross-hair and record it.
static bool	internal_tc_sample_usable (ra8_err_t rc, uint8_t got)
	Decide whether a touch read yielded a usable contact.
static ra8_err_t	internal_tc_read_raw (void ctx, ra8_touch_cal_point_t out_raw)
	Read shim: block (bounded) on one settled raw GT911 sample.
static int32_t	internal_tc_axis_err (int32_t a, int32_t b)
	Compute the absolute difference of two signed coordinates.
static bool	internal_tc_cal_pass (ra8_err_t run_rc, int32_t maxerr, int32_t tol, bool blob_ok)
	Verdict: did the whole calibration pipeline pass?
static bool	internal_tc_blob_roundtrip (const ra8_touch_cal_matrix_t *m)
	Round-trip the matrix through ra8_touch_cal_save / ra8_touch_cal_load and report stable reproduction.
static ra8_err_t	internal_tc_apply_and_measure (const ra8_touch_cal_matrix_t m, tc_capture_t cap, int32_t *out_max)
	Apply the solved matrix to every captured raw, paint the corrected cross-hairs, and return the largest residual.
static ra8_err_t	internal_tc_run_calibration (display_handle_t disp, ra8_touch_cal_matrix_t out_matrix)
	Reset the capture and run the five-point calibration collect+solve.
static void	internal_tc_report_ok (int32_t maxerr, bool verify_ok)
	Print the solved-and-verified result banner.
static void	internal_tc_report_skip (uint8_t got)
	Print the no-taps skip banner (bare automated bench).
static void	internal_tc_calibrate_and_report (display_handle_t *disp)
	Solve, verify, and report; degrade to SKIP if no taps arrived.
void	main (void)
	App entry: bring up panel + touch, run calibration, print the banner.

Variables
static uint16_t	s_framebuffer [(uint32_t) k_tc_fb_w *(uint32_t) k_tc_fb_h]
	Render target in internal SRAM, 64-byte AXI-burst aligned so the GLCDC's AXI fetches are clean.
static tc_capture_t	s_capture
	The single calibration capture the shims fill.
static const display_cfg_t	s_tc_display_cfg
	Display PAL config selecting the GLCDC LCD backend.
static const uint8_t	s_tc_msg_boot [] = "touchcal: boot\r\n"
	Startup banner emitted after the console becomes available.
static const uint8_t	s_tc_msg_fail_in [] = "touchcal: FAIL init\r\n"
	Fatal banner for clock, timebase, or console setup failure.
static const uint8_t	s_tc_msg_fail_gl [] = "touchcal: FAIL glcdc\r\n"
	Fatal banner for display-controller bring-up failure.
static const uint8_t	s_tc_msg_fail_op [] = "touchcal: FAIL open\r\n"
	Fatal banner for touch-controller open failure.
static const uint8_t	s_tc_msg_tgt [] = "touchcal: target "
	Prefix for a target-coordinate progress report.
static const uint8_t	s_tc_msg_cal_ok [] = "touchcal: cal=OK verify="
	Prefix for the solved calibration verification result.
static const uint8_t	s_tc_msg_ok [] = "OK"
	Success token used in the verification result banner.
static const uint8_t	s_tc_msg_bad [] = "FAIL"
	Failure token used in the verification result banner.
static const uint8_t	s_tc_msg_maxerr [] = " maxerr="
	Label introducing the maximum calibration residual.
static const uint8_t	s_tc_msg_skip [] = "touchcal: cal=SKIP got="
	Prefix for the no-contact calibration skip result.
static const uint8_t	s_tc_msg_ready [] = "touchcal: ready dim=512x512\r\n"
	Finger-independent HIL bring-up sentinel.
static const uint8_t	s_tc_msg_comma [] = ","
	Separator between target X and Y coordinates.
static const uint8_t	s_tc_msg_eol [] = "\r\n"
	CRLF terminator shared by composed console reports.

Detailed Description

N-point affine touch-calibration demo + HIL gate (#262).

Tag: [Ring 7 / App] {World: NS}

ra8_touch_cal (the weighted-least-squares affine solver from libs/ra8_touch_cal) had no standalone example. This app is that example and its CI gate: it wires the solver end-to-end over the REAL GoodIX GT911 touch driver (ra8_touch -> IIC_B) and the REAL GLCDC layer-1 display path (ra8_display_pal -> ra8_glcdc), and runs the full five-point calibration:

Bring up clocks / MSTP / time + the SCI8 J-Link OB console.
Bring up the GLCDC panel through the display PAL, scanning a 512x512 RGB565 SRAM framebuffer (the same size glcdc_render uses – the full 1024x600 panel buffer does not fit on-chip and SDRAM is a separate task).
Bring up the GT911 over IIC_B (I2C-compat), exactly as touch_demo.
Drive ra8_touch_cal_run: for each of the five built-in targets (four inset corners + centre) it paints a cross-hair on the panel and blocks on one settled raw GT911 sample. The two shims (internal_tc_draw_target, internal_tc_read_raw) are the SOLID-D seams ra8_touch_cal inverts onto: the draw shim renders into the framebuffer and the read shim polls the real ra8_touch_read. Each shim also records the target / raw pair so the verify pass can measure the residual.
On a successful solve: serialise the matrix with ra8_touch_cal_save, round-trip it back with ra8_touch_cal_load, re-apply the matrix to every captured raw sample with ra8_touch_cal_apply, and paint a corrected cross-hair at each mapped pixel (the "live cross-hair proving corrected coordinates" – it lands on its target). The largest target-to-corrected residual is the fit error.
Emit the outcome on the console:

touchcal: cal=OK verify=OK maxerr=<n> (all five taps collected) touchcal: cal=SKIP got=<k> (no operator / no taps)

then, unconditionally, the finger-free bring-up sentinel:

touchcal: ready dim=512x512

EIL==HIL discipline (the owner rule): the calibration solve is only reachable once five distinct raw samples arrive. On real silicon a human taps the five cross-hairs. ra8_emulator reproduces that by feeding five synthetic raw points through the modelled GT911 (--touch-seq, declared in this app's hil.conf as HIL_EMU_ARGS); those points return through the genuine ra8_touch_read decode, so the banner carries a real solved+verified result with no board attached. On a bare automated bench with no finger the read shim times out and the app reports cal=SKIP – so hil.conf asserts only the finger-free touchcal: ready line (which prints in every environment) and lists verify=FAIL / cal=FAIL in its negative set, so a solver regression trips the EIL gate. This mirrors touch_demo, which likewise gates the finger-free bring-up and lets the fake inject the touch.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file main.c.

Enumeration Type Documentation

◆ tc_color_t

enum tc_color_t : uint16_t

RGB565 palette for the calibration UI.

Enumerator
k_tc_color_bg	Black field.
k_tc_color_target	White target cross-hair.
k_tc_color_corrected	Green corrected-coordinate mark.

Definition at line 103 of file main.c.

◆ tc_consts_t

enum tc_consts_t : uint32_t

Console / GT911 / poll knobs (no magic numbers).

Enumerator
k_tc_uart_baud	Console baud.
k_tc_max_points	Read up to the GT911 capacity.
k_tc_poll_max	Bounded per-target poll (NASA R2).
k_tc_dec_ten	Decimal radix / small-buf cap.
k_tc_blob_cap	k_ra8_touch_cal_blob_size mirror.

Definition at line 113 of file main.c.

◆ tc_geom_t

enum tc_geom_t : uint16_t

Framebuffer + calibration geometry (no magic numbers).

The calibration screen space is the 512x512 SRAM framebuffer, so the affine transform maps GT911 raw units onto this 512x512 pixel grid. k_tc_inset_px is the corner-target margin passed to ra8_touch_cal_run (its four corner targets sit this far in from each edge; the fifth is the panel centre).

Enumerator
k_tc_fb_w	Framebuffer / screen width, pixels.
k_tc_fb_h	Framebuffer / screen height, pixels.
k_tc_inset_px	Corner-target inset from each panel edge.
k_tc_cross_half	Cross-hair arm half-length, pixels.
k_tc_verify_tol	Max allowed fit residual, pixels.

Definition at line 91 of file main.c.

Function Documentation

◆ internal_tc_apply_and_measure()

ra8_err_t internal_tc_apply_and_measure	(	const ra8_touch_cal_matrix_t *	m,
		tc_capture_t *	cap,
		int32_t *	out_max )

static

Apply the solved matrix to every captured raw, paint the corrected cross-hairs, and return the largest residual.

Maps each captured raw point through the solved affine transform, accumulates the worst per-axis error against its target, paints the corrected positions, and flushes the composed frame once.

Parameters

[in]	m	Solved calibration matrix.
[in]	cap	Capture holding the target / raw pairs.
[out]	out_max	Receives the largest target-to-corrected residual.

Returns: k_ra8_ok on success, k_ra8_err_* if an apply failed.

Return values

k_ra8_ok	Every captured sample was mapped and `out_max` was written.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_arg	The configured screen geometry is invalid.

Precondition: m, cap and out_max are non-NULL.; cap->n_read == cap->n_drawn == k_ra8_touch_cal_n_targets.

Postcondition: *out_max holds the max per-axis residual over all samples.; On a mapping error, later samples are not painted or measured.

Note: Earlier corrected marks can remain visible if a later apply fails.

Since: 0.1.0

Definition at line 753 of file main.c.

References tc_capture_t::disp, display_flush(), display_full_rect(), internal_tc_axis_err(), internal_tc_draw_cross(), k_display_refresh_fast, k_ra8_err_null_ptr, k_ra8_ok, k_tc_color_corrected, k_tc_fb_h, k_tc_fb_w, tc_capture_t::n_read, ra8_touch_cal_apply(), tc_capture_t::raws, tc_capture_t::targets, ra8_touch_cal_point_t::x, and ra8_touch_cal_point_t::y.

Referenced by internal_tc_calibrate_and_report().

◆ internal_tc_axis_err()

int32_t internal_tc_axis_err	(	int32_t	a,
		int32_t	b )

static

Compute the absolute difference of two signed coordinates.

Subtracts the target coordinate from the measured coordinate and folds a negative delta to its positive magnitude.

Parameters

[in]	a	First signed coordinate.
[in]	b	Second signed coordinate.

Returns: Nonnegative coordinate separation.

Return values

0	The coordinates are identical.

Precondition: The subtraction a - b is representable as an int32_t.; The resulting delta is not INT32_MIN.

Postcondition: The result equals the absolute value of a - b.; No global or caller-owned state is modified.

Note: Calibration coordinates are bounded by panel/controller geometry.

Since: 0.1.0

Definition at line 660 of file main.c.

References RA8_INTERNAL.

Referenced by internal_tc_apply_and_measure().

◆ internal_tc_blob_roundtrip()

bool internal_tc_blob_roundtrip ( const ra8_touch_cal_matrix_t * m )

static

Round-trip the matrix through ra8_touch_cal_save / ra8_touch_cal_load and report stable reproduction.

Serialises m, loads it back, and re-serialises the loaded matrix; a faithful round-trip yields a byte-identical second blob. Comparing the two byte blobs (not the float structs) both proves stability and sidesteps the ill-defined float object comparison.

Parameters

[in] m Matrix to serialise.

Returns: true iff the load-then-save reproduces the original blob byte-for-byte.

Return values

true	Both serialization calls and loading succeeded byte-exactly.
false	A codec operation failed or the re-serialized bytes differ.

Precondition: The six matrix coefficients are finite IEEE-754 floats.; m points to a readable calibration matrix.

Postcondition: No global state is mutated.; Temporary matrices and byte blobs do not escape the helper.

Note: A false result deliberately collapses codec and stability failures.

Since: 0.1.0

Definition at line 714 of file main.c.

References k_ra8_ok, k_tc_blob_cap, memcmp(), RA8_INTERNAL, ra8_touch_cal_load(), and ra8_touch_cal_save().

Referenced by internal_tc_calibrate_and_report().

◆ internal_tc_cal_pass()

bool internal_tc_cal_pass	(	ra8_err_t	run_rc,
		int32_t	maxerr,
		int32_t	tol,
		bool	blob_ok )

static

Verdict: did the whole calibration pipeline pass?

Requires solver success, an in-tolerance worst residual, and a byte-stable serialized matrix; no one condition can mask another.

Parameters

[in]	run_rc	Return code from ra8_touch_cal_run.
[in]	maxerr	Largest target-to-corrected residual, pixels.
[in]	tol	Allowed residual, pixels.
[in]	blob_ok	Whether the save/load round-trip reproduced the matrix.

Returns: true iff the solve succeeded, the residual is within tolerance, and the serialised matrix round-tripped bit-exactly.

Return values

true	All three independent acceptance conditions hold.
false	At least one acceptance condition failed.

Precondition: run_rc is a valid ra8_err_t.; tol is the nonnegative verification threshold in pixels.

Postcondition: No state is mutated.; The result is equivalent to the conjunction documented above.

Note: Pure; the compound decision is exercised for MC/DC by the host test.

Since: 0.1.0

Definition at line 687 of file main.c.

References k_ra8_ok.

Referenced by internal_tc_calibrate_and_report().

◆ internal_tc_calibrate_and_report()

void internal_tc_calibrate_and_report ( display_handle_t * disp )

static

Solve, verify, and report; degrade to SKIP if no taps arrived.

Runs collection and solving, maps every captured point to measure residual, round-trips the matrix blob, and selects the corresponding deterministic result banner.

Parameters

[in] disp Live display handle.

Precondition: disp is non-NULL (GLCDC up).; The touch driver is open.

Postcondition: Exactly one of the cal=OK / cal=SKIP banners is emitted.; A successful apply pass leaves corrected cross-hairs in the framebuffer.

Note: A solver/collection error follows the SKIP path; apply failure reports verification failure with the residual accumulated so far.

Since: 0.1.0

Definition at line 879 of file main.c.

References internal_tc_apply_and_measure(), internal_tc_blob_roundtrip(), internal_tc_cal_pass(), internal_tc_report_ok(), internal_tc_report_skip(), internal_tc_run_calibration(), k_ra8_ok, k_tc_verify_tol, RA8_INTERNAL, and s_capture.

Referenced by main().

◆ internal_tc_draw_cross()

void internal_tc_draw_cross	(	int32_t	cx,
		int32_t	cy,
		uint16_t	color )

static

Draw a plus-shaped cross-hair centred at (cx, cy).

Paints horizontal and vertical arms with clipped pixel writes, so a centre near an edge cannot address memory outside the framebuffer.

Parameters

[in]	cx	Horizontal cross-hair centre.
[in]	cy	Vertical cross-hair centre.
[in]	color	RGB565 color for both arms.

Precondition: s_framebuffer is available to the calibration UI.; k_tc_cross_half fits in an int32_t coordinate calculation.

Postcondition: Every in-bounds arm pixel contains color.; Pixels outside the two arms retain their prior values.

Note: The centre pixel is intentionally written by both arms.

Since: 0.1.0

Definition at line 428 of file main.c.

References internal_tc_put_px(), k_tc_cross_half, and RA8_INTERNAL.

Referenced by internal_tc_apply_and_measure(), and internal_tc_draw_target().

◆ internal_tc_draw_target()

ra8_err_t internal_tc_draw_target	(	void *	ctx,
		ra8_touch_cal_point_t	target )

static

Draw shim: paint a target cross-hair and record it.

Validates the injected context and capture capacity, records the solver-selected target, paints and flushes it, then emits the target coordinate for the operator.

Parameters

[in]	ctx	tc_capture_t (shared draw/read context).
[in]	target	Screen-space target centre in framebuffer pixels.

Returns: k_ra8_ok (rendering never fails for the SRAM framebuffer).

Return values

k_ra8_ok	The target was recorded, painted, and reported.
k_ra8_err_invalid_arg	The context is NULL or capture is full.

Precondition: ctx is non-NULL and holds a live display handle.; ctx->n_drawn < k_ra8_touch_cal_n_targets.

Postcondition: One target cross-hair is on the panel and target is recorded.; On invalid input the capture counters and framebuffer are unchanged.

Note: Reports the target over UART so a bench operator knows where to tap.

Since: 0.1.0

Definition at line 555 of file main.c.

References tc_capture_t::disp, display_flush(), display_full_rect(), internal_tc_draw_cross(), internal_tc_print(), internal_tc_print_uint(), k_display_refresh_fast, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_touch_cal_n_targets, k_tc_color_target, tc_capture_t::n_drawn, RA8_INTERNAL, s_tc_msg_comma, s_tc_msg_eol, s_tc_msg_tgt, tc_capture_t::targets, ra8_touch_cal_point_t::x, and ra8_touch_cal_point_t::y.

Referenced by internal_tc_run_calibration().

◆ internal_tc_fb_fill()

void internal_tc_fb_fill ( uint16_t color )

static

Fill the whole framebuffer with color.

Walks the compile-time framebuffer geometry once and assigns every RGB565 element without allocating a secondary surface.

Parameters

[in] color RGB565 value to write to every framebuffer pixel.

Precondition: s_framebuffer has exactly k_tc_fb_w times k_tc_fb_h elements.; The calibration UI exclusively owns framebuffer writes.

Postcondition: Every framebuffer element equals color.; No display handle or calibration sample is modified.

Note: The caller decides when the newly filled frame is flushed.

Since: 0.1.0

Definition at line 407 of file main.c.

References k_tc_fb_h, k_tc_fb_w, RA8_INTERNAL, and s_framebuffer.

Referenced by internal_tc_glcdc_bringup().

◆ internal_tc_glcdc_bringup()

bool internal_tc_glcdc_bringup ( display_handle_t ** out_disp )

static

Bring the GLCDC layer-1 path up and confirm it is programmed.

Clears the SRAM surface, initializes the display PAL with the fixed GLCDC descriptor, then verifies that the returned framebuffer is the application-owned surface before publishing the handle.

Parameters

[out] out_disp Receives the live display handle on success.

Returns: true when the panel is up and bound to s_framebuffer.

Return values

true	`out_disp` received a verified live display handle.
false	Initialization, handle validation, or framebuffer lookup failed.

Precondition: internal_tc_setup_or_halt has run (clocks, MSTP, console up).; out_disp is non-NULL.

Postcondition: On true *out_disp is a live handle scanning s_framebuffer.; On false the helper does not publish an unverified handle.

Note: Single-shot bring-up helper; not thread-safe.

Since: 0.1.0

Definition at line 487 of file main.c.

References display_get_framebuffer(), display_init(), internal_tc_fb_fill(), k_ra8_ok, k_tc_color_bg, display_fb_t::pixels, RA8_INTERNAL, s_framebuffer, and s_tc_display_cfg.

Referenced by main().

◆ internal_tc_panic_halt()

void internal_tc_panic_halt	(	const uint8_t *	msg,
		uint32_t	len )

static

Print the fail banner and trap (ra8_emulator halts on the BKPT).

Emits the supplied diagnostic once, executes a debugger-visible breakpoint, then enters a permanent low-power wait loop.

Parameters

[in]	msg	Start of the failure banner.
[in]	len	Number of banner bytes to transmit.

Precondition: msg addresses at least len readable bytes.; Console setup either succeeded or failed late enough to accept output.

Postcondition: The failure banner has been offered to the console.; Control never returns to the caller.

Note: The terminal loop preserves fixture state for debugger inspection.

Since: 0.1.0

Definition at line 307 of file main.c.

References internal_tc_print(), and RA8_INTERNAL.

Referenced by internal_tc_setup_or_halt(), and main().

◆ internal_tc_pixel_in_bounds()

bool internal_tc_pixel_in_bounds	(	int32_t	v,
		int32_t	dim )

static

Report whether a framebuffer coordinate is inside the panel.

Applies the inclusive lower and exclusive upper bounds used by the framebuffer index calculation.

Parameters

[in]	v	Coordinate under test (may be negative after a transform).
[in]	dim	Panel extent on that axis (width or height).

Returns: true iff 0 <= v < dim.

Return values

true	`v` can be used as an index on the tested axis.
false	`v` is negative or reaches/passes `dim`.

Precondition: dim is the framebuffer width or height (> 0).; v is representable as an int32_t coordinate.

Postcondition: No state is mutated.; The verdict reflects the supplied values without clamping them.

Note: Pure; safe from any context.

Since: 0.1.0

Definition at line 368 of file main.c.

References RA8_INTERNAL.

Referenced by internal_tc_put_px().

◆ internal_tc_print()

void internal_tc_print	(	const uint8_t *	msg,
		uint32_t	len )

static

Emit a byte run on the SCI8 console.

Passes the caller-owned bytes and explicit length directly to the board console; the demo intentionally ignores transport status.

Parameters

[in]	msg	Start of the byte run to transmit.
[in]	len	Number of bytes to transmit.

Precondition: msg addresses at least len readable bytes.; The board console has been initialized when len is nonzero.

Postcondition: The board console has been offered the complete byte run.; No application buffer or calibration state is modified.

Note: This helper neither allocates nor scans for a terminator.

Since: 0.1.0

Definition at line 289 of file main.c.

References ra8_board_uart_console_write(), and RA8_INTERNAL.

Referenced by internal_tc_draw_target(), internal_tc_panic_halt(), internal_tc_print_uint(), internal_tc_report_ok(), internal_tc_report_skip(), and main().

◆ internal_tc_print_uint()

void internal_tc_print_uint ( uint32_t value )

static

Print a small unsigned integer in decimal.

Builds digits in reverse in a fixed local buffer, then emits them most-significant first without using formatted I/O.

Parameters

[in] value Unsigned value to render in base ten.

Precondition: k_tc_dec_ten provides storage for every supported value's digits.; The board console is initialized.

Postcondition: The decimal representation has been offered to the console.; No global calibration or framebuffer state is modified.

Note: Output has no sign, prefix, padding, or line ending.

Since: 0.1.0

Definition at line 328 of file main.c.

References internal_tc_print(), k_tc_dec_ten, and RA8_INTERNAL.

Referenced by internal_tc_draw_target(), internal_tc_report_ok(), and internal_tc_report_skip().

◆ internal_tc_put_px()

void internal_tc_put_px	(	int32_t	x,
		int32_t	y,
		uint16_t	color )

static

Write one RGB565 pixel, clipped to the framebuffer rectangle.

Validates both signed coordinates before deriving the row-major framebuffer offset, so off-panel cross-hair arms are harmless.

Parameters

[in]	x	Horizontal framebuffer coordinate.
[in]	y	Vertical framebuffer coordinate.
[in]	color	RGB565 pixel value to store.

Precondition: s_framebuffer describes a k_tc_fb_w by k_tc_fb_h image.; x and y are representable int32_t coordinates.

Postcondition: An in-bounds coordinate contains color.; An out-of-bounds coordinate leaves the framebuffer unchanged.

Note: The write is not synchronized with the active GLCDC scan.

Since: 0.1.0

Definition at line 387 of file main.c.

References internal_tc_pixel_in_bounds(), k_tc_fb_h, k_tc_fb_w, RA8_INTERNAL, and s_framebuffer.

Referenced by internal_tc_draw_cross().

◆ internal_tc_read_raw()

ra8_err_t internal_tc_read_raw	(	void *	ctx,
		ra8_touch_cal_point_t *	out_raw )

static

Read shim: block (bounded) on one settled raw GT911 sample.

Polls the real touch driver at most k_tc_poll_max times, accepting the first successful contact and recording the first decoded point alongside the solver output.

Parameters

[in]	ctx	tc_capture_t (shared draw/read context).
[out]	out_raw	Receives the raw controller-space coordinate.

Returns: k_ra8_ok on a captured sample, k_ra8_err_hw_error on timeout.

Return values

k_ra8_ok	A raw point was returned and recorded.
k_ra8_err_invalid_arg	A pointer is NULL or capture storage is full.
k_ra8_err_hw_error	The bounded poll expired without a usable contact.

Precondition: ctx and out_raw are non-NULL.; The touch driver is open.

Postcondition: On ok *out_raw holds the raw sample and it is recorded in ctx.; On error no capture count is advanced.

Note: Bounded to k_tc_poll_max iterations (NASA P10 Rule 2). A bare automated bench with no finger exhausts the budget and returns an error, which ra8_touch_cal_run surfaces as k_ra8_err_hw_error.

Since: 0.1.0

Definition at line 618 of file main.c.

References internal_tc_sample_usable(), k_ra8_err_hw_error, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_touch_cal_n_targets, k_tc_max_points, k_tc_poll_max, tc_capture_t::n_read, RA8_INTERNAL, ra8_touch_read(), tc_capture_t::raws, ra8_touch_cal_point_t::x, and ra8_touch_cal_point_t::y.

Referenced by internal_tc_run_calibration().

◆ internal_tc_report_ok()

void internal_tc_report_ok	(	int32_t	maxerr,
		bool	verify_ok )

static

Print the solved-and-verified result banner.

Composes the fixed prefix, verification token, maximum-error label, decimal residual, and CRLF through bounded console writes.

Parameters

[in]	maxerr	Largest measured per-axis residual in pixels.
[in]	verify_ok	Whether the complete verification predicate passed.

Precondition: maxerr is nonnegative and representable as uint32_t.; The board console is initialized.

Postcondition: Exactly one verification token and one residual are emitted.; Calibration and framebuffer state are unchanged.

Note: This report labels solver success even when verification subsequently fails.

Since: 0.1.0

Definition at line 832 of file main.c.

References internal_tc_print(), internal_tc_print_uint(), RA8_INTERNAL, s_tc_msg_bad, s_tc_msg_cal_ok, s_tc_msg_eol, s_tc_msg_maxerr, and s_tc_msg_ok.

Referenced by internal_tc_calibrate_and_report().

◆ internal_tc_report_skip()

void internal_tc_report_skip ( uint8_t got )

static

Print the no-taps skip banner (bare automated bench).

Composes the skip prefix, collected-contact count, and CRLF without allocating or invoking formatted output.

Parameters

[in] got Number of raw calibration samples collected before failure.

Precondition: got does not exceed k_ra8_touch_cal_n_targets.; The board console is initialized.

Postcondition: The complete skip banner has been offered to the console.; Calibration and framebuffer state are unchanged.

Note: The banner distinguishes missing operator input from solver failure.

Since: 0.1.0

Definition at line 857 of file main.c.

References internal_tc_print(), internal_tc_print_uint(), RA8_INTERNAL, s_tc_msg_eol, and s_tc_msg_skip.

Referenced by internal_tc_calibrate_and_report().

◆ internal_tc_run_calibration()

ra8_err_t internal_tc_run_calibration	(	display_handle_t *	disp,
		ra8_touch_cal_matrix_t *	out_matrix )

static

Reset the capture and run the five-point calibration collect+solve.

Reinitializes the shared capture, binds its draw/read callbacks into a fixed five-point solver configuration, and delegates collection and affine fitting to ra8_touch_cal_run.

Parameters

[in]	disp	Live display handle used by the draw callback.
[out]	out_matrix	Destination for the solved affine matrix.

Returns: Calibration collection and solver status.

Return values

k_ra8_ok	All target/raw pairs were collected and a matrix was solved.
k_ra8_err_null_ptr	`disp` or `out_matrix` is NULL.
k_ra8_err_hw_error	A raw touch could not be collected in budget.

Precondition: The display and touch drivers are initialized.; out_matrix points to writable matrix storage.

Postcondition: s_capture contains every target/raw pair collected by the run.; On success out_matrix contains the fitted affine transform.

Note: This helper resets the sole file-scope capture and is not reentrant.

Since: 0.1.0

Definition at line 802 of file main.c.

References internal_tc_draw_target(), internal_tc_read_raw(), k_tc_fb_h, k_tc_fb_w, k_tc_inset_px, RA8_INTERNAL, ra8_touch_cal_run(), and s_capture.

Referenced by internal_tc_calibrate_and_report().

◆ internal_tc_sample_usable()

bool internal_tc_sample_usable	(	ra8_err_t	rc,
		uint8_t	got )

static

Decide whether a touch read yielded a usable contact.

Combines the driver status and decoded-contact count into the one predicate used by the bounded polling loop.

Parameters

[in]	rc	Return code from ra8_touch_read.
[in]	got	Reported contact count.

Returns: true iff the read succeeded AND at least one contact was decoded.

Return values

true	`rc` is success and `got` reports at least one contact.
false	The read failed or decoded no contacts.

Precondition: rc is a valid ra8_err_t.; got is the contact count returned with rc.

Postcondition: No state is mutated.; The result is true only when both usability conditions hold.

Note: Pure; safe from any context.

Since: 0.1.0

Definition at line 592 of file main.c.

References k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_tc_read_raw().

◆ internal_tc_setup_or_halt()

void internal_tc_setup_or_halt ( void )

static

Bring up clocks/MSTP/time + the SCI8 console; halt on failure.

Initializes each prerequisite in dependency order, derives the timebase from CPUCLK0, and treats any failure as terminal.

Precondition: Reset startup completed data and BSS initialization.; Board clock registers are in their reset-compatible state.

Postcondition: On return, clocks, module-stop control, time, and SCI8 are initialized.; Any failed prerequisite has emitted the init-failure banner and halted.

Note: This single-shot boot helper is not reentrant.

Since: 0.1.0

Definition at line 453 of file main.c.

References internal_tc_panic_halt(), k_ra8_clock_id_cpuclk0, k_ra8_ok, k_tc_uart_baud, ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), RA8_INTERNAL, ra8_mstp_init(), ra8_time_init(), and s_tc_msg_fail_in.

Referenced by main().

◆ internal_tc_touch_bringup()

bool internal_tc_touch_bringup ( void )

static

Bring up IIC_B (I2C-compat) and open the GT911 touch driver.

Configures channel zero for fast-mode I2C, binds it to the injected bus operations seam, and opens the touch controller with the board address and bounded contact capacity.

Returns: true when ra8_touch_open reported the GT911 alive.

Return values

true	The I2C seam is bound and the GT911 driver is open.
false	A bus initialization, bind, conversion, or open step failed.

Precondition: internal_tc_setup_or_halt has run.; IRQs are enabled (ra8_isr_globals_enable called).

Postcondition: On true the touch driver is open on IIC_B channel 0.; On false no success state is reported to the caller.

Note: Mirrors touch_demo: a future board revision that moves the GT911 onto a RIIC channel only swaps the bind call.

Since: 0.1.0

Definition at line 525 of file main.c.

References k_ra8_ok, k_ra8_touch_irq_pin_unset, k_tc_max_points, ra8_board_touch_open(), and RA8_INTERNAL.

Referenced by main().

◆ main()

void main ( void )

App entry: bring up panel + touch, run calibration, print the banner.

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: The cal=OK / cal=SKIP result and the finger-free touchcal: ready sentinel are emitted; the CPU then loops in WFI.

Since: 0.1.0

Definition at line 911 of file main.c.

References internal_tc_calibrate_and_report(), internal_tc_glcdc_bringup(), internal_tc_panic_halt(), internal_tc_print(), internal_tc_setup_or_halt(), internal_tc_touch_bringup(), ra8_isr_globals_enable(), s_tc_msg_boot, s_tc_msg_fail_gl, s_tc_msg_fail_op, and s_tc_msg_ready.

Variable Documentation

◆ s_capture

tc_capture_t s_capture

static

The single calibration capture the shims fill.

Note: File-scope because the shim ctx references it for the whole run.

Warning: Reset at the start of each calibration attempt.

Since: 0.1.0

Definition at line 160 of file main.c.

Referenced by c6_cam_camera_capture_jpeg(), internal_tc_calibrate_and_report(), and internal_tc_run_calibration().

◆ s_framebuffer

uint16_t s_framebuffer[(uint32_t) k_tc_fb_w *(uint32_t) k_tc_fb_h]

static

Render target in internal SRAM, 64-byte AXI-burst aligned so the GLCDC's AXI fetches are clean.

Note: Written by the calibration UI; scanned out continuously by GLCDC GR1.

Warning: Not thread-safe; single-shot calibration owns it.

Since: 0.1.0

Definition at line 151 of file main.c.

◆ s_tc_display_cfg

const display_cfg_t s_tc_display_cfg

static

Initial value:

                                            = {
  .iface             = &k_display_backend_lcd_ra8_glcdc,
  .framebuffer       = s_framebuffer,
  .framebuffer_bytes = sizeof(s_framebuffer),
  .width_px          = (uint16_t)k_tc_fb_w,
  .height_px         = (uint16_t)k_tc_fb_h,
  .pixfmt            = k_display_pixfmt_rgb565,
  .panel_timing      = &s_ra8_panel_ek_ra8d2_timing,
}

Display PAL config selecting the GLCDC LCD backend.

The panel timing is the board BSP's EK-RA8D2 descriptor; re-pointing iface at another backend is the only change to target it instead.

Since: 0.1.0

Definition at line 169 of file main.c.

Referenced by internal_tc_glcdc_bringup().

◆ s_tc_msg_bad

const uint8_t s_tc_msg_bad[] = "FAIL"

static

Failure token used in the verification result banner.

Note: The array excludes any separator or line ending.

Since: 0.1.0

Definition at line 234 of file main.c.

Referenced by internal_tc_report_ok().

◆ s_tc_msg_boot

const uint8_t s_tc_msg_boot[] = "touchcal: boot\r\n"

static

Startup banner emitted after the console becomes available.

Note: Immutable byte storage; the caller supplies its explicit length.

Since: 0.1.0

Definition at line 185 of file main.c.

Referenced by main().

◆ s_tc_msg_cal_ok

const uint8_t s_tc_msg_cal_ok[] = "touchcal: cal=OK verify="

static

Prefix for the solved calibration verification result.

Note: Followed by an OK/FAIL token and the maximum residual.

Since: 0.1.0

Definition at line 220 of file main.c.

Referenced by internal_tc_report_ok().

◆ s_tc_msg_comma

const uint8_t s_tc_msg_comma[] = ","

static

Separator between target X and Y coordinates.

Note: Kept as a byte array for the bounded console write seam.

Since: 0.1.0

Definition at line 262 of file main.c.

Referenced by internal_tc_draw_target().

◆ s_tc_msg_eol

const uint8_t s_tc_msg_eol[] = "\r\n"

static

CRLF terminator shared by composed console reports.

Note: Kept separate so reports can be emitted without formatting storage.

Since: 0.1.0

Definition at line 269 of file main.c.

Referenced by internal_tc_draw_target(), internal_tc_report_ok(), and internal_tc_report_skip().

◆ s_tc_msg_fail_gl

const uint8_t s_tc_msg_fail_gl[] = "touchcal: FAIL glcdc\r\n"

static

Fatal banner for display-controller bring-up failure.

Note: Consumed only by the terminal panic path.

Since: 0.1.0

Definition at line 199 of file main.c.

Referenced by main().

◆ s_tc_msg_fail_in

const uint8_t s_tc_msg_fail_in[] = "touchcal: FAIL init\r\n"

static

Fatal banner for clock, timebase, or console setup failure.

Note: Consumed only by the terminal panic path.

Since: 0.1.0

Definition at line 192 of file main.c.

Referenced by internal_tc_setup_or_halt().

◆ s_tc_msg_fail_op

const uint8_t s_tc_msg_fail_op[] = "touchcal: FAIL open\r\n"

static

Fatal banner for touch-controller open failure.

Note: Consumed only by the terminal panic path.

Since: 0.1.0

Definition at line 206 of file main.c.

Referenced by main().

◆ s_tc_msg_maxerr

const uint8_t s_tc_msg_maxerr[] = " maxerr="

static

Label introducing the maximum calibration residual.

Note: Followed by an unsigned decimal pixel count.

Since: 0.1.0

Definition at line 241 of file main.c.

Referenced by internal_tc_report_ok().

◆ s_tc_msg_ok

const uint8_t s_tc_msg_ok[] = "OK"

static

Success token used in the verification result banner.

Note: The array excludes any separator or line ending.

Since: 0.1.0

Definition at line 227 of file main.c.

Referenced by internal_tc_report_ok().

◆ s_tc_msg_ready

const uint8_t s_tc_msg_ready[] = "touchcal: ready dim=512x512\r\n"

static

Finger-independent HIL bring-up sentinel.

Note: Emitted after calibration handling in every successful bring-up.

Since: 0.1.0

Definition at line 255 of file main.c.

Referenced by main().

◆ s_tc_msg_skip

const uint8_t s_tc_msg_skip[] = "touchcal: cal=SKIP got="

static

Prefix for the no-contact calibration skip result.

Note: Followed by the number of raw contacts collected.

Since: 0.1.0

Definition at line 248 of file main.c.

Referenced by internal_tc_report_skip().

◆ s_tc_msg_tgt

const uint8_t s_tc_msg_tgt[] = "touchcal: target "

static

Prefix for a target-coordinate progress report.

Note: Followed by two decimal coordinates and a line ending.

Since: 0.1.0

Definition at line 213 of file main.c.

Referenced by internal_tc_draw_target().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ tc_color_t

◆ tc_consts_t

◆ tc_geom_t

Function Documentation

◆ internal_tc_apply_and_measure()

◆ internal_tc_axis_err()

◆ internal_tc_blob_roundtrip()

◆ internal_tc_cal_pass()

◆ internal_tc_calibrate_and_report()

◆ internal_tc_draw_cross()

◆ internal_tc_draw_target()

◆ internal_tc_fb_fill()

◆ internal_tc_glcdc_bringup()

◆ internal_tc_panic_halt()

◆ internal_tc_pixel_in_bounds()

◆ internal_tc_print()

◆ internal_tc_print_uint()

◆ internal_tc_put_px()

◆ internal_tc_read_raw()

◆ internal_tc_report_ok()

◆ internal_tc_report_skip()

◆ internal_tc_run_calibration()

◆ internal_tc_sample_usable()

◆ internal_tc_setup_or_halt()

◆ internal_tc_touch_bringup()

◆ main()

Variable Documentation

◆ s_capture

◆ s_framebuffer

◆ s_tc_display_cfg

◆ s_tc_msg_bad

◆ s_tc_msg_boot

◆ s_tc_msg_cal_ok

◆ s_tc_msg_comma

◆ s_tc_msg_eol

◆ s_tc_msg_fail_gl

◆ s_tc_msg_fail_in

◆ s_tc_msg_fail_op

◆ s_tc_msg_maxerr

◆ s_tc_msg_ok

◆ s_tc_msg_ready

◆ s_tc_msg_skip

◆ s_tc_msg_tgt