Skip to content

About

Native Linux libfprint driver for the EgisTec EH576 (1c7a:0576) fingerprint sensor — reverse-engineered for interoperability

Topics

Resources

Stars

11 stars

Watchers

0 watching

Forks

Repository files navigation

libfprint driver for the EgisTec EH576 (1c7a:0576)

A native Linux libfprint driver for the EgisTec (LighTuning) EH576 fingerprint sensor — a match-on-host image sensor that ships in a number of laptops but has no vendor Linux driver.

With this driver the sensor works for real: fprintd enrollment, and fingerprint login / sudo / screen-unlock through PAM, on stock GNOME/KDE.

Heads-up before you rely on this: parts of this driver are reverse-engineered from Egis' proprietary Windows driver, including the fingerprint matcher. Please read PROVENANCE.md — it explains exactly what is original work, what is reverse-engineered, the licensing, and the (honest) legal grey area.

Status

Enroll / verify / identify ✅ works via fprintd
PAM login, sudo, unlock ✅ works (sufficient, password fallback intact)
Cross-reboot matching ✅ (per-boot flat-field)
Accuracy (shipped matcher) It admits false accepts on every dataset but one. Under the driver's own rule (two consecutive frames over the threshold): the reference unit's session of 2026-09-13 — the one every matcher constant was tuned on — 0 of 60 false rejects, 0 of 480 false accepts; the same unit, person and fingers five days later: 13 of 60 false rejects, 18 of 480 false accepts (right thumb taken for right index, where the vendor matcher on the same frames accepts none); enrolled on one of those sessions and tried with the other, 9 and 15 of 240 false accepts; sam-dant's unit 2 of 60 and 2 of 480. On irvingpop's unit 58 of 480 under the kit's looser press-maximum rule; on the second unit, under its owner's protocol, 6.9 % false rejects at 1.1 % false accepts. The cause is what the matcher measures (ridge flow and period, not identity), not any constant measured so far — see 2026-09-26: what prevents a universal 0/0. Until that date this row led with the 2026-09-13 0 / 0 as the reference unit's result. "Impostor" is always the same person's other fingers: no false-accept figure in this project comes from a second person, and physical artefacts were never tried.
Validated on five laptop models (AMD + Intel; Fedora, Arch and Ubuntu). See "Tested platforms" below for what each report covered and what it left untested.

The sensor, briefly

The EH576 is a small 70×57 px capacitive/optical image sensor speaking a simple EGIS/SIGE command protocol in the clear: the host pulls raw frames and does feature extraction + matching in software.

This driver implements the whole chain natively: sensor bring-up → frame capture → per-boot flat-field + preprocessing → Egis' extractor/matcher → libfprint enroll/verify. Design detail lives in the source comments and PROVENANCE.md.

The sensor also has a TLS-PSK session mode, reachable with class request 0x21/9 wValue=0. This driver deliberately does not use it, and neither does the vendor's own Windows driver for this device — verified against a USB capture of a working Windows session, which contains no vendor or class control transfers at all — only plaintext EGIS/SIGE bulk traffic. (The mode switch is a class request, so ruling out vendor requests alone would not have settled it.) Entering that mode is a one-way door: the sensor stays in it across USB autosuspend, a USB port reset and a reboot, and only a ForceResetDevice (wValue=0x00ff, which re-enumerates the device) brings it back. On a dual-boot machine that left Windows unable to start the sensor at all — Device Manager Code 10 — until the board was fully powered down. Driving the same command sequence in the clear also measures better: finger/no-finger frame variance 1069/140 = 7.6×, against 890/160 = 5.6× through the TLS path on the same unit.

Universality (does it work on other EH576 units?)

The driver is engineered to be device-independent, and every per-device dependency is handled at runtime rather than baked in:

  • Init / protocol — per-model constants, identical for every EH576.
  • Exposure — a per-device closed-loop calibration (binary search over register 0x0f to a fixed no-finger exposure target) is measured once per fprintd process and re-applied after every sensor bring-up (the vendor init sequence resets the register, and the sensor does not retain it), so each unit self-adjusts.
  • Fixed-pattern noise — removed by a per-boot host-side flat-field captured fresh on every unit.
  • On-chip background/vdm — neutralized to a model-level constant so no single unit's calibration data is embedded.

Update — it works on other units. Originally all of this was validated on the author's single unit; for functional operation that caveat is retired. Independent testers have run the full stack on other EH576 units (different laptops, CPU vendors and USB host controllers; same sensor revision, bcdDevice 15.72): the first with a 17-point PASS (#2), the rest in the table above. More reports are still very welcome — success or failure.

Accuracy is a separate axis, and there the caveat stands. Three accuracy runs now exist — the author's plus sam-dant's and irvingpop's in #5 — and they disagree sharply: with the vendor matcher, 0, 2 and 37 of 60 genuine presses were rejected at the shipped threshold (on the worst run 33 of those 37 scored exactly 0). Those three vendor figures are from before kit_version 4 and flatter the vendor matcher: it adapts while it verifies, and the kit loaded each gallery once per fold where the driver reloads it for every action. Re-measured with kit v4, the reference unit's 0 of 60 holds; the other two have not been re-run and are lower bounds (kit v4, re-measurement). Each run is one person on one unit in one session, so person and unit change together and nothing in the data says which of the two the spread comes from. Exposure calibration and template size both order the runs the wrong way; the one measurement that does track the failure is how often the matcher found an enrolment frame already covered by the template — 19, 10 and none across the three runs — which is suggestive and nothing more. What this means practically: the driver working on your machine does not imply the accuracy figures from another machine, so if you are going to rely on fingerprint login, try it before you do — and please run the kit and post the result. Detail and all three tables: docs/matcher-comparison.md. Note that the worst of the three runs is on a unit whose functional report in the table below is a pass, though a qualified one (GDM login not tested there); the kit measures an offline protocol with thinner enrolment than the driver's, not the driver's own login success rate.

Tested platforms

Laptop Platform Sensor bcdDevice Distro Result Report
Lenovo Yoga 7 14ARB7 AMD Ryzen 7 6800U 15.72 Fedora 44 ✅ full stack (enroll, verify, GDM, sudo, unlock, suspend/resume) author
Lenovo Yoga 7 15ITL5 Intel Core i5-1135G7 15.72 Fedora 44 ✅ full stack, 17-point PASS incl. 3× suspend/resume #2
Lenovo IdeaPad Flex 5 16IRU8 Intel Core i7-1355U 15.72 Arch Linux (Omarchy 4.0.2) ✅ full stack (enroll, verify, sudo/PAM, polkit, lock screen, reboot, 3× suspend/resume); the long-lock stale-claim failure from the original report is gone on v0.4.5, re-tested over a 10 h 46 min locked screen and 1265 verification timeouts with zero refused claims #3
Lenovo Yoga 6 13ALC6 AMD Ryzen 7 5700U 15.72 Ubuntu 26.04 ✅ enroll, verify, sudo/PAM, polkit, unlock, suspend/resume (GDM login not tested) #4
Lenovo IdeaPad Flex 5 14ITL05 Intel (11th gen) 15.72 Ubuntu 26.04.1 (earlier Zorin OS 18.1) ✅ v0.5.1 Ubuntu TOD package, the vendor build: enroll, verify (the first verify right after enrolling did not match; a later run of five all matched), sudo, screen-lock unlock, unlock after suspend/resume from the menu and via the lid (2026-09-26), with the sleep hook and activation gate installed; login after a reboot and long-term use on v0.5.1 not yet tested. The gate is the reporter's design and ships since v0.4.5 (on v0.4.3, with the hook alone, unlock after suspend was not offered). Before that, v0.4.5 in daily use: stable on Zorin OS 18.1 (2026-09-20), no failure seen on Ubuntu 26.04.1 (2026-09-26) #3

Got a different machine with an EH576? Please open an issue with your results.

Install

Upgrading to v0.5.x from any earlier release? Re-enrol every finger. v0.5.0 changed how a print is stored (a versioned record instead of the bare template bytes every release up to v0.4.5 wrote) and changed the default matcher with it, so the driver refuses prints enrolled under an earlier release instead of scoring them, and verifying against one fails. This holds for every package, the Ubuntu TOD module included, although that one still builds the vendor matcher. Run fprintd-delete $USER, then enrol again.

Upgrading from a release before v0.4.0? Those builds spoke a TLS-PSK transport and left the sensor in a mode it keeps until something resets it — so the first fingerprint attempt after the upgrade can fail once: the driver finds the sensor in that mode, issues ForceResetDevice and fails that open; the sensor stays on the bus until the next transfer to it, then drops off and re-enumerates (~0.4 s), after which attempts work normally. Details in docs/sensor-tuning.md §6. That step to v0.4.x needed no re-enrollment: existing prints kept matching, because the exposure target and register are unchanged. Going on to v0.5.x does need one, see the note above.

The same change fixes dual-boot: earlier releases left the sensor in a state where Windows' own driver failed to start it (Device Manager Code 10) until the machine was fully powered down. v0.4.0 never enters that mode.

Upgrading from any release before v0.4.3 (v0.1.0 – v0.4.2)? Those releases could hang: a fingerprint verify that never answers, and from then on every attempt refused with "Device was already claimed" until fprintd is restarted (the lock screen falls back to the password). The cause was a lost wakeup between the driver's capture thread and the fprintd main loop inside gusb's synchronous transfer helpers, narrow enough to survive months of use before it was caught on hardware. v0.4.3 fixes it — the capture thread no longer depends on the main loop at all (write-up in docs/worker-thread.md). That fix needed no re-enrollment, since capture and matching were unchanged; v0.5.x does, see the first note above.

How the driver reaches fprintd depends on the distribution. On Fedora, Arch and Debian it is compiled into libfprint-2.so, so installing it means installing a libfprint that includes it, replacing the distro's; the stock fprintd then loads it through the unchanged ABI (no fprintd rebuild). On Ubuntu nothing is replaced: every Ubuntu series ships libfprint-2-tod1, and the package in packaging/ubuntu-tod/ builds the driver as a loadable TOD module that the distro's own libfprint picks up (#9, contributed by irvingpop).

One command (packaged)

Fedora (COPR):

sudo dnf copr enable philippdev5396/libfprint-egis0576
sudo dnf upgrade 'libfprint*'
sudo systemctl restart fprintd

The COPR owner name is lower-case; dnf copr enable PHILIPPDEV5396/… fails with a 404. As of October 2026 COPR serves v0.4.5, not v0.5.1: its newest build is libfprint-1.94.100-99.fcNN.egis10 from 2026-09-14 (the vendor matcher and the v0.4 template format); v0.5.0 and v0.5.1 have not been built there. v0.5.1's Fedora package is on the release page, built for Fedora 43 only, and because the spec's Release: was not bumped after v0.4.5 it carries the same name, version and release as COPR's Fedora 43 build, so dnf install of it over that build does nothing. On Fedora 43:

curl -LO https://github.com/PHILIPPDEV5396/libfprint-egis0576/releases/download/v0.5.1/libfprint-1.94.100-99.fc43.egis10.x86_64.rpm
sudo dnf reinstall ./libfprint-1.94.100-99.fc43.egis10.x86_64.rpm   # over the COPR build
# sudo dnf install ./libfprint-1.94.100-99.fc43.egis10.x86_64.rpm   # over Fedora's own libfprint
sudo systemctl restart fprintd

then re-enrol (first note above). For Fedora 44 and later there is no v0.5.1 package; build from source below.

Debian 13 (trixie), Ubuntu 24.04 (noble) and 26.04 (resolute): download the .deb for your system from the release page (check it against SHA256SUMS there) and install it with apt:

# Ubuntu: a TOD module next to the stock libfprint, nothing replaced
sudo apt install ./ubuntu-resolute-libfprint-2-tod1-egis0576_0.5.1.26.04_amd64.deb   # 26.04
sudo apt install ./ubuntu-noble-libfprint-2-tod1-egis0576_0.5.1.24.04_amd64.deb      # 24.04
# Debian trixie: replaces libfprint-2-2 (never install these on Ubuntu)
sudo apt install ./debian-trixie-libfprint-2-2_1.94.100-99egis0.5.1_amd64.deb \
                 ./debian-trixie-libfprint-2-dev_1.94.100-99egis0.5.1_amd64.deb \
                 ./debian-trixie-gir1.2-fprint-2.0_1.94.100-99egis0.5.1_amd64.deb
sudo systemctl restart fprintd

They are files, not a repository, so apt upgrade will not update them; install the next release's .deb the same way. The Ubuntu and the Debian packages both install the suspend/resume hook and its gate. The Ubuntu module builds the vendor matcher, the Debian package the clean-room default. A real finger has been reported on the 26.04 module only; on 24.04 only the sensor bring-up was tried on hardware (packaging/).

Arch (PKGBUILD, not on AUR yet):

git clone https://github.com/PHILIPPDEV5396/libfprint-egis0576.git
cd libfprint-egis0576/packaging/aur
makepkg -si
sudo systemctl restart fprintd

Unlike the Fedora package, the PKGBUILD does not install the suspend/resume sleep hook and its fprintd gate — install them by hand, see integration/.

Packaging sources and how they're published live in packaging/. The Fedora, Arch and Debian packages replace the stock libfprint (same soname); your other fingerprint hardware keeps working because the build includes the full upstream default driver set. Since libfprint 1.94.100 that set includes the egis_etu905 driver (1c7a:05ae / 1c7a:9201) Fedora used to carry as a downstream patch, so the Fedora build no longer drops it.

No package for your distribution? Build from source below.

Building from source (any distro / development)

As noted under Install, the driver is compiled into libfprint-2.so, so this builds a full libfprint that includes it; fprintd is not rebuilt.

1. Install build dependencies

You need the usual libfprint build stack, which includes OpenSSL ≥ 3.0 — upstream's own uru4000 driver requires it (meson.build: 'uru4000' : [ 'openssl' ]). The egis0576 driver itself links no crypto at all; it speaks the sensor's plaintext protocol over gusb.

  • Fedora: sudo dnf install git meson ninja-build gcc pkgconf-pkg-config glib2-devel libgusb-devel openssl-devel gobject-introspection-devel nss-devel systemd-devel libgudev-devel pixman-devel cairo-gobject-devel gtk-doc
  • Arch: sudo pacman -S --needed git meson ninja gcc pkgconf glib2 libgusb openssl gobject-introspection nss systemd-libs libgudev pixman cairo gtk-doc
  • Debian/Ubuntu: sudo apt install git meson ninja-build build-essential pkg-config libglib2.0-dev libgusb-dev libssl-dev libgirepository1.0-dev libnss3-dev libsystemd-dev systemd-dev libgudev-1.0-dev libpixman-1-dev libcairo2-dev gtk-doc-tools
  • openSUSE: sudo zypper install git meson ninja gcc pkgconf glib2-devel libgusb-devel libopenssl-devel gobject-introspection-devel mozilla-nss-devel systemd-devel libgudev-1_0-devel pixman-devel cairo-devel gtk-doc

2. Build + install

./install.sh

This clones libfprint 1.94.100, applies the driver, builds the full default driver set (so any other fingerprint hardware you have keeps working), and installs to /usr/local (override with PREFIX=/usr ./install.sh).

Make sure fprintd loads this libfprint, not the distro's:

ldconfig -p | grep libfprint-2      # should point at your PREFIX
sudo systemctl restart fprintd

If it still points at the distro copy, add PREFIX/lib (or lib64) to /etc/ld.so.conf.d/, run sudo ldconfig, and restart fprintd. (Installing with PREFIX=/usr replaces the distro library outright — simplest, but a distro update can overwrite it, so you'd re-run install.sh after libfprint updates.)

The matcher, and the two other flavours. Since v0.5.0 the driver ships the clean-room matcher by default: own LGPL code — an orientation-selective Gabor front-end, a per-pixel coherence mask, a rotation search and a ridge-period consistency check (driver/egis0576/gabor/) behind Thaddeus Stepanovich's adapter interface — with no vendor code in the matching path at all. It is the flavour prepared for libfprint (that submission is on hold, see below), and the one the numbers below are measured on: on one session of the reference unit (2026-09-13, the session all its constants were tuned on) its genuine and impostor populations do not overlap (0 % / 0 % at its threshold, cross-fold checked — "impostor" means the same person's other fingers; no false-accept figure in this project comes from a second person yet); on no other dataset do they. On a second unit, Thaddeus Stepanovich's, it takes his matcher from 51.7 % to 6.9 % false rejects held-out, without reaching a clean gap there.

That clean gap is a property of one session — not of the reference unit, and not of the matcher (2026-09-26). From 2026-09-22 until then this paragraph called it a property of the reference unit; before that the README presented it as the matcher's result. The same unit, person and fingers five days later give 18 false accepts of 480 under the driver's own rule (two consecutive frames over the threshold, the second corroborated on the un-flat-fielded bytes), at a same-person impostor score of 0.896 against the accept point of 0.78, where the vendor matcher on the identical frames accepts none. Every foreign unit reported so far also scores a same-person impostor above 0.78: 0.815 on Stepanovich's, 0.845 on sam-dant's (2 of 480 under the driver's rule), 0.903 on irvingpop's (12.1 % false accepts under the kit's press-maximum rule, 60 % false rejects — a second failure mode, not yet explained, in which the vendor matcher loses genuine presses too). The reason, shown on the reference unit's own frames, is what the matcher measures: whether two patches agree in ridge flow and ridge period, which two different fingers can do when they land at the same angle — not whose finger it is. None of the constants measured fixes that: threshold, overlap floor and search width each only trade false rejects for false accepts (the front-end's filter constants were not swept; the mechanism argues against them, which is an argument, not a measurement). The project's target is now an own matcher that is at least as good as the vendor one — no false accept under the driver's rule on both reference-unit sessions, across them, on sam-dant's and on tsteppy's data; no more false rejects than vendor on the same data; tuned on one dataset and certified on the others, never on the same session — and the upstream submission is on hold until one exists. Measurements and root cause: docs/matcher-comparison.md. Treat the 0 % / 0 % above as what one favourable session can tell you, and no more.

Two other flavours build from the same tree, for comparison rather than use:

EGIS0576_MESON_ARGS="-Degis0576_matcher=vendor" ./install.sh     # Egis' own matcher
EGIS0576_MESON_ARGS="-Degis0576_matcher=cleanroom" ./install.sh  # his original front-end

vendor is Egis' extractor and matcher, machine-translated from the Windows driver — what this driver used until v0.4.x, and what keeps it out of upstream libfprint. On the three accuracy-tested units it rejected 0 %, 3.33 % and 61.7 % of genuine presses and scored 0 on all 480 impostor comparisons of each run. Those false-reject rates predate kit_version 4 and are too favourable to vendor (see "Accuracy is a separate axis" above): re-measured, the reference unit's 0 % holds, the other two have not been re-run and are lower bounds, and on the reference unit's second session (2026-09-18) kit v4 gives 4 of 60 under the driver's rule where the earlier kit gave 2. cleanroom is his original front-end behind the same adapter: at its published threshold it rejects 35 %, 73.3 % and 93.3 % of genuine presses on those same captures (5 false accepts of 480 on one unit). It is not the only flavour with measured false accepts: the default produced 58 of 480 on the third unit under the same press-maximum rule, and 18 of 480 on the reference unit's own second session under the driver's rule. vendor is the only one that has never accepted an impostor press on any unit measured so far — at the cost of the 61.7 % (or more) above. All three are measured on identical captures in docs/matcher-comparison.md; reproduce on your own unit with tools/accuracy/.

Templates do not survive a flavour switch (nor the v0.4 → v0.5 upgrade): re-enrol after either. Fedora: the spec in packaging/fedora/ builds the default; rpmbuild --with vendor builds the vendor flavour.

Enrolling

fprintd-enroll                 # or: Settings → Users → Fingerprint Login
fprintd-verify                 # test it

Enroll with coverage: press the same finger at deliberately varied positions (centre, up/down, left/right, slight rotations) across the enrollment stages. On a sensor this small, a template built from one position matches poorly.

Enabling fingerprint auth

These steps assume libfprint + fprintd are installed and your fingerprint is already enrolled.

How PAM fingerprint auth works (read first)

Enabling fingerprint login means adding one line to the PAM auth stack:

auth    sufficient    pam_fprintd.so
  • It must sit above pam_unix.so (the password module). PAM evaluates auth modules top-to-bottom.
  • sufficient = if the fingerprint matches, auth succeeds immediately; if it fails, times out, or nothing is enrolled, PAM falls through to the password. This keeps your password as a working fallback.
  • Do not use required for pam_fprintd unless you want fingerprint-AND- password (2-factor) and accept that a missing/broken reader can lock you out. For normal "fingerprint OR password", use sufficient and keep the pam_unix line.
  • fprintd is D-Bus/systemd-activated on all distros — it starts on demand, so systemctl enable --now fprintd is normally unnecessary.
  • Keyrings still need your password. GNOME Keyring / KWallet are unlocked by the login password, so a fingerprint-only login still prompts for the keyring once.

Fedora

sudo authselect enable-feature with-fingerprint

(fprintd-pam provides the module.) Wires pam_fprintd.so into the system-auth / password-auth stacks for login, sudo, and the display manager.

Arch Linux (and Manjaro, EndeavourOS, …)

  • Packages: fprintd (provides the daemon and pam_fprintd.so) + libfprint.
  • Arch has no PAM helper — edit by hand. Add to the top of the auth section of /etc/pam.d/system-local-login:
    auth      sufficient pam_fprintd.so
    auth      include    system-login
    
    For sudo, add the same auth sufficient pam_fprintd.so at the top of the auth section of /etc/pam.d/sudo.
  • GDM and KDE/Plasma have built-in fingerprint handling (don't edit kde-fingerprint).
  • Keep an open root shell while editing PAM so a mistake can't lock you out.
  • Ref: ArchWiki – fprint

Debian / Ubuntu (and Mint, Pop!_OS, …)

sudo apt install fprintd libpam-fprintd
sudo pam-auth-update --enable fprintd      # or run `sudo pam-auth-update` and tick the box

Installing libpam-fprintd registers the profile but does not enable it — the command above inserts auth sufficient pam_fprintd.so into /etc/pam.d/common-auth (included by login, sudo, the DM). Add --force if it refuses due to local PAM edits; disable later with --remove fprintd. Ref: Debian Wiki – fingerprint authentication

openSUSE (Tumbleweed / Leap)

sudo zypper install fprintd fprintd-pam
sudo pam-config -a --fprintd               # disable later: pam-config -d --fprintd

Adds auth sufficient pam_fprintd.so to the pam-config-managed common auth stack. Prefer pam-config over hand-editing (it regenerates those files). Ref: openSUSE SDB – Using fingerprint authentication

Suspend / resume

The sensor is brought up at device-open. Across a system suspend — especially s2idle, where the USB device stays powered and is not re-enumerated — it comes back with its capture pipeline unusable. On resume the next fingerprint attempt (typically the lock screen after wake) can then block on it and, on some systems (observed on AMD Rembrandt laptops that only offer mem_sleep=s2idle), hang the unlock screen hard.

Two separate things are at play, and it took a long investigation to tell them apart (written up in full in docs/suspend-resume.md):

  • The hard freeze is prevented in the driver: every bulk read is bounded by a timeout, so talking to an unresponsive sensor fails fast to a clean error instead of spinning forever.
  • "No fingerprint offered after resume" (the lock screen drops to password) is not this driver's bug at all. It is a well-known, still-unfixed gnome-shell/fprintd issue: fprintd keeps a stale device claim across suspend ("Device was already claimed"), so the post-resume claim is refused — libfprint is never even reached. See gnome-shell #7791 and Ubuntu #2067135 (it hits ThinkPads, Framework laptops, etc., on unrelated readers).

The community-standard fix — restart fprintd around suspend — is what the helpers in integration/ do (a systemd-sleep hook that stops fprintd before sleep and re-enumerates the sensor on resume, plus a gate that holds fprintd's start until the sensor is back). install.sh installs them and you should keep them installed; they are the correct fix for the upstream bug, not a workaround for a driver shortcoming. Details and the full investigation: integration/README.md and docs/suspend-resume.md.

Usability & security notes

  • The wire is plaintext, by design. Traffic to the sensor is the vendor's own EGIS/SIGE protocol, exactly as the shipped Windows driver sends it, and the driver links no crypto. The sensor does have a TLS-PSK session mode; using it would not have bought a security property here — the key is a fixed per-model constant, the channel would terminate in the same userspace process that then handles the decrypted image anyway, and matching is host-side, so the template is on disk regardless. On Linux the meaningful boundary is match-on-chip, which this sensor does not offer. The variance figures quoted above, and what else was measured and found to be at its limit, are in docs/sensor-tuning.md.

  • Nothing blocks the fprintd main loop. The transport is a set of FpiSsm machines over FpiUsbTransfer — the in-tree libfprint model — and only the matcher runs on another thread (a GTask, as secugen does). open() completes asynchronously too. Cancellation is honoured between transfer sequences and never handed to gusb: aborting an in-flight URB wedges this sensor until board power is cut (measured). The worker thread of v0.4.x and the lost-wakeup hang it once had are history, kept in docs/worker-thread.md.

  • Press firmly, flat, centred, and hold ~2 s. Verification scores every frame while the finger is down and takes the best; light or brief taps on a 70×57 sensor can score zero. How much this matters clearly differs between people and units: in one of the three accuracy runs 33 of 60 genuine presses scored exactly 0 (docs/matcher-comparison.md).

  • The match threshold is strict and not user-tunable by design — the priority is rejecting impostors (including adjacent same-hand fingers), not maximum convenience. Lowering it would not have rescued that run either: 33 of its 37 failing presses scored 0, which no threshold recovers.

  • Templates are stored by fprintd under /var/lib/fprint/, protected by filesystem permissions (as with every libfprint driver).

  • Re-enroll after anything that changes capture conditions materially (the exposure calibration converges to the same fixed target every boot, so normal reboots are fine).

Troubleshooting

  • The first verify (or two) after upgrading fails, then it works. Expected, once: the driver found the sensor in the session mode an older release left behind and issued a reset; the sensor re-enumerates on the next access (docs/sensor-tuning.md §6). See the note under Install.

  • Every verify fails right after upgrading to v0.5.x: prints enrolled under v0.4.x or earlier are refused, not scored. Re-enrol; see the first note under Install.

  • fprintd still uses the old driver / device not found: confirm ldconfig -p | grep libfprint-2 points at your PREFIX, then sudo systemctl restart fprintd.

  • Enrollment "fails to capture": press more firmly and hold; ensure no finger is on the sensor during the first ~2 s (baseline + exposure calibration run then).

  • Verify always fails after it worked: re-enroll with coverage (see "Enrolling").

  • Debug logging: sudo G_MESSAGES_DEBUG=all fprintd (stop the service first) or journalctl -u fprintd -f.

Contributing

Most wanted, in order:

  1. A clean-room fingerprint matcher good enough to distinguish adjacent same-hand fingers at 70×57 — this is what blocks clean libfprint upstreaming. The shipped Gabor matcher does not (it compares ridge flow and period, not identity); the bar a replacement has to clear, and why, is in docs/matcher-comparison.md. See the "Why the reverse-engineered matcher (and not a clean-room one)?" in PROVENANCE.md.
  2. Test reports from other physical EH576 units (see "Universality").
  3. Accuracy reports from your own fingers — especially if the result is poor; the three runs collected so far disagree sharply and more points are the only way to understand that. Run the tools/accuracy/ kit (about 15 minutes; only the results.json summary is shared, never frames) and open an issue titled accuracy: <laptop model> as its README asks — collected under #5.
  4. Packaging. The release CI and the Debian/Ubuntu .deb packages landed through #6 (closed 2026-09-21): the release workflow builds, and v0.5.1 carries, a Fedora 43 RPM, an Arch package, Debian trixie .debs and Ubuntu noble/resolute TOD .debs. Still wanted: the PKGBUILD published on the AUR (it is not there); an apt repository or PPA for the .debs (today they are release-page files that apt upgrade never updates, and the PPA named in packaging/ does not exist yet); COPR rebuilt on every release tag, since it is the only source of Fedora 44 and later packages and is still at v0.4.5 (the release workflow never pushes there); a way to rebuild automatically when a distro updates libfprint; recipes for other distributions.

License & legal

Original driver code: LGPL-2.1-or-later (see LICENSE), matching libfprint. Reverse-engineered portions and the full legal picture: PROVENANCE.md. The original Egis Windows driver and its decompilation are not included and must not be committed here.

Credits

Reverse-engineered and ported to libfprint by the repository author, with the goal of making already-owned hardware usable on Linux. The optional clean-room correlation matcher (driver/egis0576/tsteppy/, LGPL-2.1-or-later) is the work of Thaddeus Stepanovich. The suspend/resume activation gate in integration/ implements a design diagnosed, built and tested by sam-dant. The Debian and Ubuntu packaging, the Ubuntu TOD module and the release CI's version checks were contributed by irvingpop, who maintains that part of the packaging stack. Prior art this project started from is listed in PROVENANCE.md §3; the people who tested the driver on their hardware are named in the "Tested platforms" table above. Built on the excellent libfprint and fprintd.

About

Native Linux libfprint driver for the EgisTec EH576 (1c7a:0576) fingerprint sensor — reverse-engineered for interoperability

Topics

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages