I’m Building an Open-Source Linux Driver for Goodix SPI Fingerprint Sensors — We Need Help

I’m Building an Open-Source Linux Driver for Goodix SPI Fingerprint Sensors — We Need Help

Fingerprint readers on laptops are one of those things that can feel completely invisible until you install Linux.

Your laptop has a fingerprint sensor.
Windows supports it.
The hardware works.
But Linux may have no usable driver at all.

That's the problem I'm trying to solve with OpenGoodixSPI.

What is OpenGoodixSPI?

OpenGoodixSPI is an experimental open-source Linux kernel driver project focused on Goodix fingerprint sensors that communicate over SPI.

The long-term goal is not just to make one laptop work. I want to build a clean driver architecture that can eventually provide a path toward proper Linux and "libfprint" support for compatible Goodix SPI sensors.

The project currently focuses on sensors such as:

• GXFP5187
• GXFP3287
• GXFP51A0

There are other Goodix fingerprint devices that look similar but use completely different hardware architectures, so an important part of this project is identifying exactly which devices are actually SPI-based.

Why is this difficult?

The hardware is not particularly mysterious.

The problem is the protocol.

Goodix does not appear to publicly document everything required to initialize and operate these sensors on Linux. The Windows driver already knows how to communicate with the hardware, but reproducing that communication from an open Linux driver requires reverse engineering.

So far I've been able to establish parts of the communication path, including:

• SPI communication
• device detection
• interrupt handling
• reset handling
• debug logging
• a character-device interface for experimentation
• parts of the sensor command/state handling
• initial protocol observations

But getting from "the Linux kernel can talk to the sensor" to "Linux can actually capture and use a fingerprint" is a much bigger problem.

The current blocker: initialization

My current hardware investigation around the GXFP51A0 has produced some interesting results.

The ACPI resources indicate that the reset GPIO is separate from the SPI interface, and experiments indicate that the sensor needs a reset sequence before communication becomes meaningful.

The current findings point toward a reset sequence approximately like:

RESET LOW
↓
10 ms
↓
RESET HIGH
↓
100 ms
↓
SPI initialization

But this is only one piece of the puzzle.

After reset, I'm still hitting an important problem where the sensor can return:

FF FF FF FF ...

That doesn't tell us enough by itself.

It could be a protocol/framing problem, an initialization problem, a device state problem, or something else entirely.

I don't want to simply assume that "0xFF" means "firmware missing" and build the driver around an unverified theory.

Firmware is another major unknown

The Windows driver appears to contain or reference firmware-related data, and there are indications that firmware handling is part of the initialization process on some devices.

The Linux project currently has the beginnings of a firmware-loading path, but the actual transfer protocol is not sufficiently confirmed.

For example, we need to determine things such as:

• firmware packet format
• commands used for firmware transfer
• chunk size
• addresses
• checksums
• acknowledgements
• bootloader state transitions
• firmware version queries
• when firmware actually needs to be uploaded
• whether firmware is already persistent on the sensor

I don't want to implement a guessed protocol and call it finished.

What we really need

This project has reached the point where information from people with experience in Linux kernel development, embedded reverse engineering, SPI devices, or Goodix hardware could make a huge difference.

1. Windows SPI captures

This is probably the most valuable missing piece.

A logic-analyzer capture of a compatible Goodix SPI fingerprint sensor while Windows initializes it would allow us to compare:

RESET
↓
SPI initialization
↓
Wake
↓
Device identification
↓
Firmware / configuration
↓
Sensor initialization
↓
Ready

against what the Linux driver currently does.

Even a partial capture could be extremely useful.

1. Goodix documentation

If anyone has access to legitimate documentation for Goodix SPI fingerprint controllers, especially the GXFP51xx/GXFP32xx families, I'm interested in information such as:

• SPI protocol documentation
• register maps
• initialization sequences
• command specifications
• firmware protocol documentation
• GPIO/IRQ requirements
• sensor geometry information
• image acquisition protocol
• enrollment/matching interfaces
• Linux driver references
• SDK documentation
• datasheets or application notes

I am not looking for leaked credentials, proprietary source code, or anything that someone isn't allowed to share.

Public documentation, legitimately obtained developer documentation, or guidance on how to obtain the appropriate documentation would already be extremely helpful.

1. Compatible hardware owners

If you have a laptop containing a Goodix SPI fingerprint sensor, especially one of these:

GXFP5187
GXFP3287
GXFP51A0

I'd love to hear from you.

Useful information includes:

Laptop model:
Sensor model:
Linux distribution:
Kernel version:
ACPI information:
SPI information:
dmesg output:

Different laptop implementations may expose important differences that aren't obvious from a single machine.

1. Linux kernel / libfprint developers

Eventually, the goal is to move beyond an experimental kernel driver and toward something that can integrate cleanly with the Linux fingerprint ecosystem.

If you have experience with:

• Linux kernel drivers
• SPI kernel APIs
• ACPI
• GPIO/IRQ handling
• libfprint
• embedded reverse engineering
• fingerprint sensor protocols

your experience would be extremely valuable.

I have also contacted Goodix

I've recently contacted Goodix directly to ask whether developer documentation or technical information can be made available for these sensors.

I'm hoping they can point the project toward legitimate documentation or the appropriate engineering/developer contact.

Until then, the project continues through hardware investigation and reverse engineering.

What I don't want this project to become

I don't want OpenGoodixSPI to become a collection of random register writes that happens to work on one laptop.

The goal is a maintainable Linux driver with:

ACPI
↓
SPI
↓
Goodix protocol
↓
Sensor initialization
↓
Image acquisition
↓
libfprint integration

with the protocol documented and understood well enough that other developers can work on it.

Current status

The project is definitely not finished.

That's actually why I'm writing this.

The basic driver infrastructure exists, but the critical protocol work is still incomplete.

The biggest missing pieces are currently:

• [ ] Fully understand GXFP51A0 initialization
• [ ] Confirm the SPI command framing
• [ ] Determine the exact meaning of the current "0xFF" responses
• [ ] Reproduce the Windows initialization sequence
• [ ] Understand firmware loading/update behavior
• [ ] Implement reliable firmware communication if required
• [ ] Capture fingerprint images
• [ ] Understand enrollment/matching
• [ ] Build the userspace/libfprint integration
• [ ] Test across multiple Goodix SPI devices
• [ ] Eventually work toward upstream-quality Linux support

If you can help

You don't need to become a project contributor immediately.

Even one useful piece of information can help:

«"I have a GXFP51A0 and can capture SPI traffic."»

or:

«"I have documentation for this controller."»

or:

«"I've worked with Goodix SPI protocols before."»

or:

«"I know how this should integrate with libfprint."»

That could potentially unblock weeks of reverse engineering.

The project is open source, and I'm documenting the findings as I go.

Project: "PeshalaDilshan/OpenGoodixSPI"

OpenGoodixSPI

If you have relevant experience, hardware, documentation, or protocol knowledge, I'd genuinely appreciate hearing from you in the comments or through the project.

Let's see if we can get these fingerprint sensors working properly on Linux. 🐧

Disclosure: This article was prepared with assistance from AI for drafting and editing. The technical information and project status are based on my own work, experiments, and project research, and I have reviewed the content before publishing.