The low-level initialization, TLS session, finger detection and image capture paths work on the tested hardware. The project is not yet fully integrated into libfprint, and enrollment/verification is not production-ready.

The implementation has been tested on one GXFP5130 device with chip ID 0x2504 and the ChicagoHU profile.

Hardware-validated functionality

mailbox record I/O through /dev/gxfp
Goodix request and response framing
chip-ID and 64-byte OTP reads
OTP CRC validation and DAC calibration extraction
OTP-derived 224-byte ChicagoHU configuration generation
TLS 1.2 PSK session establishment with the sensor MCU
finger-down and finger-up detection
repeated image capture in one TLS session
7680-byte packed 12-bit image decoding into 5120 samples
CRC-32/MPEG-2 image validation
64x80 12-bit image output and deterministic 8-bit conversion
timeout, cancellation and session recovery regression paths

An experimental libfprint image-device skeleton is included under libfprint-driver/. It can capture images through libfprint, but the final enroll/verify pipeline and matching policy remain work in progress.

Requirements

Linux with the Goodix EC mailbox transport and /dev/gxfp
a C11 compiler and GNU Make
pkg-config
mbedTLS development libraries

The corresponding kernel transport patch is archived at:

https://lore.kernel.org/platform-driver-x86/20260803074454.49474-1-ertugtopcu0@gmail.com/

Build and test

make
sudo ./sensor-probe /dev/gxfp 10

Enable protocol/TLS debug output only when needed:

sudo env GXFP_DEBUG=1 ./sensor-probe /dev/gxfp 1

Run cancellation, timeout-recovery and normal-cycle regression tests:

sudo ./session-regression /dev/gxfp

Layout

include/gxfp/       protocol and session headers
src/                transport, configuration, TLS, capture and session code
examples/           hardware probes and session regression program
tools/              offline capture-analysis utilities
libfprint-driver/   experimental, incomplete libfprint integration
docs/               verified protocol documentation

See docs/protocol.md for the protocol and capture format.

Security and compatibility

The TLS material in src/tls.c was recovered for interoperability with the tested hardware and forms part of this experimental protocol implementation. It is not a user password or repository credential. Do not assume that the protocol, configuration, TLS material or image geometry applies to another Goodix model.

The prototype exposes raw biometric images. Captures, PGM files and enrollment templates are ignored by Git and should not be shared without the subject's consent.

Reverse-engineering notes

Protocol and configuration behavior was reconstructed primarily from the Windows implementation and verified against live hardware traces. Existing community GXFP5130 experiments were used for comparison. The capture-to-pgm utility is an offline diagnostic tool and is not used by the capture/session implementation.

License

The userspace library, examples and tools are GPL-2.0-only. The experimental libfprint integration file carries an LGPL-2.1-or-later SPDX identifier. Full license texts are available under LICENSES/.