Install experimental driver for the goodix 55b4 fingerprint sensor on Ubuntu

archival_notice.md

🚧 This Document is archived.

I'm no longer using this exact setup, it is based on an old version of libfprint and further development is moving at a slow pace.

This document will still be available for further reference, but I don't plan to update it.

goodix_55b4.md

Install experimental driver for the goodix 55b4 fingerprint sensor on Ubuntu

---

🔧 This is not usable yet.

While the driver seems to work fine, the current fingerprint matching algorithm doesn't work with these devices and it may accept any finger or none. Don't use it to secure your device!

---

This will show you the steps to install an experimental driver for the goodix 55b4 fingerprint sensor on Ubuntu. You may have this sensor in your machine if the output of lsusb | grep fingerprint --ignore-case shows something like:

Bus 003 Device 004: ID 27c6:55b4 Shenzhen Goodix Technology Co.,Ltd. Fingerprint Reader

You can find more information on the related discord server.

These steps were tested on a Lenovo IdeaPad C340-14API using a live session of Ubuntu 21.04 (default gnome desktop) after setting a password and activating the universe repository.

⚠️ I'm not responsible for any damage to your device. Everything you do is at your own risk. You should check every code or command before running it. If you don't understand it, you shouldn't use it.

Flash custom firmware to the sensor

Goodix' fingerprint sensors use encrypted communication. We need to set a new encryption key by flashing a custom firmware to the sensor.

⚠️ If you dual-boot with windows, you should completely disable windows drivers for your fingerprint sensor, otherwise windows will reflash your sensor.

⛔ Don't run the flash script automatically on startup, flashing your sensor too often will break your sensor!

First, we need to install the dependencies (:information_source: this is somewhat untested, I might have forgotten something):

sudo apt install git python3-pip python3-crcmod
pip install pyusb

Then, we need to recursively clone the firmware repository:

git clone --recurse-submodules https://github.com/mpi3d/goodix-fp-dump.git

Now we can run a python script to flash the firmware.

sudo python3 goodix-fp-dump/run_55b4.py

You will see a warning message like this:

#######################################################
This program might break your device.
Consider that it may flash the device firmware.
Continue at your own risk.
But don't hold us responsible if your device is broken!
Don't run this program as part of a regular process.
#######################################################
Type 1855 to continue and confirm that you are not a bot:

After confirming that you read the warning, the script will flash the firmware to the sensor. It will wait for the detection of a finger on the sensor and exit. You should now be able to find a file called fingerprint.pgm in your folder which is an image of your finger. It should look a bit like this (no finger, but looks like it):

Build and install experimental driver

We need to install the dependencies to download, build and use the experimental version of libfprint:

sudo apt install fprintd meson libgusb-dev libcairo2-dev libgudev-1.0-dev libgirepository1.0-dev libnss3-dev libssl-dev gtk-doc-tools

Then, we clone the source repository of the driver:

git clone https://github.com/TheWeirdDev/libfprint.git --branch 55b4-experimental
cd libfprint/

Now, we can configure the build system, compile the program and install it.

meson builddir -Ddoc=false -Dprefix=/usr
ninja -C builddir
sudo ninja -C builddir install

You should now be able to enroll your fingerprint using gnome settings or fprintd-enroll and use it to log into your system.

Troubleshooting

ℹ️ The following tips were mostly suggested by others and I didn't test them.

Problem	Cause	Solution
I can't login using my fingerprint	the desktop manager may not be correctly configured	try running sudo apt install --reinstall gdm3 or sudo pam-auth-update --enable fprintd

not_a_finger.bmp

Hello, I have been looking al over the internet how to enable my goodix fingerprint sensor on my lenovo flex5. Apparently this is the only compatible driver i have found, however when I run the command: "sudo python3 goodix-fp-dump/run_55b4.py" I get the following error:

Traceback (most recent call last):
File "/home/martin/goodix-fp-dump/run_55b4.py", line 1, in
import driver_55x4
File "/home/martin/goodix-fp-dump/driver_55x4.py", line 11, in
import goodix
File "/home/martin/goodix-fp-dump/goodix.py", line 5, in
import protocol
File "/home/martin/goodix-fp-dump/protocol.py", line 5, in
import periphery
ModuleNotFoundError: No module named 'periphery'

I would really like your support on this issue, I am going crazy trying to figure out what to do.
Thank you in advance.

I think that the instructions in goodix-fp-dump's README aren't right, it should be sudo .venv/bin/python3 instead of sudo python3 (sudo ignores the activated venv).

However, I would strongly advise against using any of the above, unless you are interested in the low-level work needed to create these drivers.

Hello, on my side, installation workes. The thing thats keeps me away from using it, ist that the fingerprint recognizes a finger even not touching it. The moment i have my hinger on it thiks no finger present and waits. Is the Output a negertive bitmab?
If keepin finger iin sensor during isntallation, the pgm seems correct, so no erron on the sensorside...

Hi,
I have updated the driver and rebased it on a newer version of libfprint. The matching is also based on the new SIGFM algorithm and provides better results. Try it and let me know how it works. The AUR package is also updated.

Seen you post in discord. Aur does not seem to be patched. Building from repo did break my boot (only gray gnome background and try not responding). Removing fpind seems to have fixed it. Will provide any information if needed.