{"id":48736857,"url":"https://github.com/mmhfarooque/chipsailing-cs9711-fingerprint-linux","last_synced_at":"2026-04-12T05:01:20.886Z","repository":{"id":350781217,"uuid":"1208246090","full_name":"mmhfarooque/chipsailing-cs9711-fingerprint-linux","owner":"mmhfarooque","description":"Chipsailing CS9711 (USB 2541:0236) fingerprint scanner driver for Linux. One-command installer for Ubuntu, Debian, Fedora, Arch, openSUSE. Patched libfprint with 1500ms retry delay + PAM config. Includes .deb, RPM, and Arch packages.","archived":false,"fork":false,"pushed_at":"2026-04-12T03:53:59.000Z","size":379,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T04:23:13.418Z","etag":null,"topics":["biometric","chipsailing","cs9711","fingerprint","fingerprint-scanner","fprintd","libfprint","linux-driver","pam","ubuntu"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mmhfarooque.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T02:40:53.000Z","updated_at":"2026-04-12T03:53:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mmhfarooque/chipsailing-cs9711-fingerprint-linux","commit_stats":null,"previous_names":["mmhfarooque/chipsailing-cs9711-fingerprint-linux"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mmhfarooque/chipsailing-cs9711-fingerprint-linux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmhfarooque%2Fchipsailing-cs9711-fingerprint-linux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmhfarooque%2Fchipsailing-cs9711-fingerprint-linux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmhfarooque%2Fchipsailing-cs9711-fingerprint-linux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmhfarooque%2Fchipsailing-cs9711-fingerprint-linux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmhfarooque","download_url":"https://codeload.github.com/mmhfarooque/chipsailing-cs9711-fingerprint-linux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmhfarooque%2Fchipsailing-cs9711-fingerprint-linux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31704492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T21:17:31.016Z","status":"online","status_checked_at":"2026-04-12T02:00:06.763Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biometric","chipsailing","cs9711","fingerprint","fingerprint-scanner","fprintd","libfprint","linux-driver","pam","ubuntu"],"created_at":"2026-04-12T05:00:52.714Z","updated_at":"2026-04-12T05:01:20.866Z","avatar_url":"https://github.com/mmhfarooque.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chipsailing CS9711 Fingerprint Scanner — Linux Driver Installer\n\nOne-command installer for the **Chipsailing CS9711** USB fingerprint scanner on Linux.\n\nStock `libfprint` does **not** support this chip. This project automates the entire setup: detecting your distro, installing dependencies, cloning the community driver, applying patches, building, installing, and configuring PAM — so your fingerprint works for login, lock screen, and sudo.\n\n## Supported Hardware\n\n| Detail | Value |\n|--------|-------|\n| **Chip** | Chipsailing CS9711 |\n| **USB ID** | `2541:0236` |\n| **Form factor** | USB dongle / integrated sensor |\n| **Matching algorithm** | sigfm (optimised for small sensors) |\n| **Enrollment** | 15 touches per finger |\n\nTo check if you have this device:\n\n```bash\nlsusb | grep 2541:0236\n```\n\n## Supported Distros\n\n| Distro Family | Tested On | Package Manager |\n|---------------|-----------|-----------------|\n| **Ubuntu / Debian** | Ubuntu 24.04, 26.04, Debian 12+ | apt |\n| **Linux Mint / Pop!_OS** | Mint 21+, Pop 22.04+ | apt |\n| **Fedora / RHEL** | Fedora 39+, RHEL 9+ | dnf |\n| **Arch / Manjaro** | Arch, Manjaro, EndeavourOS | pacman |\n| **openSUSE** | Tumbleweed, Leap 15.5+ | zypper |\n\nThe installer auto-detects your distro and uses the right package manager.\n\n## Quick Start (All Distros)\n\n```bash\ngit clone https://github.com/mmhfarooque/chipsailing-cs9711-fingerprint-linux.git\ncd chipsailing-cs9711-fingerprint-linux\nchmod +x install.sh setup-gui.sh\n./install.sh\n```\n\nThe installer will:\n\n1. Detect your Linux distro and package manager\n2. Install all build dependencies\n3. Clone the [archeYR/libfprint-CS9711](https://github.com/archeYR/libfprint-CS9711) community driver\n4. Apply the **1500ms retry delay patch** (see below)\n5. Build and install the patched `libfprint`\n6. Configure PAM for fingerprint auth\n7. Verify the scanner is detected\n\nThen enroll your fingerprint:\n\n```bash\nfprintd-enroll          # 15 touches required\nfprintd-verify          # test it\n```\n\n## Complete Setup (Driver + GUI)\n\nFor the full experience — driver install, enrollment, and graphical manager:\n\n```bash\ngit clone https://github.com/mmhfarooque/chipsailing-cs9711-fingerprint-linux.git\ncd chipsailing-cs9711-fingerprint-linux\nchmod +x install.sh setup-gui.sh\n\n# Step 1: Install driver (builds from source, configures PAM)\n./install.sh\n\n# Step 2: Enroll your fingerprint (15 touches)\nfprintd-enroll\nfprintd-verify\n\n# Step 3: Install GUI manager (adds desktop shortcut)\n./setup-gui.sh\n\n# Step 4: Launch — or search \"CS9711\" in your app menu\npython3 cs9711-manager.py\n```\n\nAfter setup, you can manage everything from the GUI — enrollment, retry delay, PAM settings, and driver maintenance.\n\n## Install via .deb Package (Ubuntu / Debian / Mint / Pop!_OS)\n\nPre-built `.deb` packages are available in [Releases](https://github.com/mmhfarooque/chipsailing-cs9711-fingerprint-linux/releases), or build your own:\n\n```bash\n# Install build dependencies first\nsudo apt install -y git meson ninja-build libfprint-2-dev libglib2.0-dev \\\n  libgusb-dev libpixman-1-dev libcairo2-dev libssl-dev libopencv-dev \\\n  doctest-dev gobject-introspection libgirepository1.0-dev fprintd libpam-fprintd\n\n# Build the .deb\nchmod +x packaging/deb/build-deb.sh\n./packaging/deb/build-deb.sh\n\n# Install it\nsudo apt install ./cs9711-fingerprint_1.0.0_amd64.deb\n```\n\nRemove: `sudo apt remove cs9711-fingerprint`\n\n## Install via RPM (Fedora / RHEL / openSUSE)\n\n```bash\n# Build the RPM\nchmod +x packaging/rpm/build-rpm.sh\n./packaging/rpm/build-rpm.sh\n\n# Install (Fedora/RHEL)\nsudo dnf install ~/rpmbuild/RPMS/x86_64/cs9711-fingerprint-1.0.0-1.*.rpm\n\n# Install (openSUSE)\nsudo zypper install ~/rpmbuild/RPMS/x86_64/cs9711-fingerprint-1.0.0-1.*.rpm\n```\n\n## Install via PKGBUILD (Arch / Manjaro / EndeavourOS)\n\n```bash\ncd packaging/arch\nmakepkg -si\n```\n\nOr use the helper script:\n\n```bash\nchmod +x packaging/arch/build-arch.sh\n./packaging/arch/build-arch.sh\n```\n\n## After System Updates\n\nWhen your package manager updates `libfprint`, it may overwrite the patched library. Just run:\n\n```bash\n./reinstall.sh\n```\n\nThis rebuilds from the existing local source — no re-download needed.\n\n## The 1500ms Retry Delay Patch\n\nThe upstream driver uses a 250ms delay between scan retries. This is too fast — the scanner burns through all retry attempts before you can reposition your finger.\n\nThis project patches `CS9711_DEFAULT_RESET_SLEEP` from `250` to `1500` (milliseconds), giving you a comfortable pause between scans.\n\nThe patch is in `patches/cs9711-retry-delay-1500ms.patch`.\n\n## PAM Configuration\n\nThe installer configures PAM for fingerprint auth:\n\n**Debian/Ubuntu** (`/etc/pam.d/common-auth`):\n```\nauth sufficient pam_fprintd.so max-tries=7 timeout=30\n```\n\n**Fedora/RHEL** (via `authselect`):\n```bash\nsudo authselect enable-feature with-fingerprint\n```\n\n- **max-tries=7** — 7 fingerprint attempts before falling back to password (default is 1)\n- **timeout=30** — 30-second window for all attempts (default is 10)\n\n## What It Enables\n\n- Lock screen unlock via fingerprint\n- `sudo` authentication (fingerprint prompt before password)\n- Login screen fingerprint auth\n- All via `libpam-fprintd`\n\n## GUI Manager\n\nA GTK4 graphical manager is included for easy configuration:\n\n```bash\n./setup-gui.sh       # Install GUI dependencies + desktop shortcut\npython3 cs9711-manager.py   # Launch\n```\n\nOr search **\"CS9711\"** or **\"Fingerprint Manager\"** in your app launcher after setup.\n\nThe GUI lets you:\n- View scanner status and enrolled fingers\n- Enroll/delete/verify fingerprints with visual progress\n- Adjust retry delay (250ms–3000ms slider)\n- Set PAM max attempts and timeout\n- View which auth locations use fingerprint\n- Rebuild/install/uninstall the driver\n- Configure GNOME Keyring auto-unlock\n\n![CS9711 Fingerprint Manager](screenshot.png)\n\n## Optional: Auto-Unlock GNOME Keyring\n\nBy default, GNOME Keyring requires your password to unlock (fingerprint login skips it). To set an empty keyring password so it auto-unlocks:\n\n```bash\npython3 helpers/set-empty-keyring-password.py\n```\n\n## File Structure\n\n```\n.\n├── install.sh                   # Universal installer (auto-detects distro)\n├── reinstall.sh                 # Quick rebuild (after system updates)\n├── uninstall.sh                 # Remove driver, restore stock libfprint\n├── cs9711-manager.py            # GTK4 GUI manager\n├── setup-gui.sh                 # GUI dependency installer + desktop shortcut\n├── cs9711-manager.desktop       # Desktop entry template\n├── patches/\n│   └── cs9711-retry-delay-1500ms.patch\n├── helpers/\n│   └── set-empty-keyring-password.py\n├── packaging/\n│   ├── deb/\n│   │   └── build-deb.sh        # Build .deb package\n│   ├── rpm/\n│   │   ├── build-rpm.sh        # Build RPM package\n│   │   └── cs9711-fingerprint.spec\n│   └── arch/\n│       ├── build-arch.sh       # Build Arch package\n│       └── PKGBUILD\n├── VERSION                      # Current version number\n├── CHANGELOG.md                 # Version history and release notes\n├── LICENSE\n└── README.md\n```\n\n## Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| `No devices available` | Check USB connection. Run `sudo ldconfig`. Run `lsusb \\| grep 2541`. |\n| `verify-no-match` | Old enrollment data. Run `fprintd-delete $(whoami) \u0026\u0026 fprintd-enroll`. |\n| System update broke it | Run `./reinstall.sh` or reinstall the .deb/.rpm package. |\n| Scanner not detected | USB passthrough keyboards only work when wired (not Bluetooth). |\n| Burns through retries | Check patch: `grep CS9711_DEFAULT_RESET_SLEEP` in `cs9711.c` should show `1500`. |\n| Unsupported distro | Install dependencies manually (see source), then run `install.sh`. |\n\n## Useful Commands\n\n```bash\nfprintd-enroll                        # Enroll default finger (right index)\nfprintd-enroll -f left-index-finger   # Enroll specific finger\nfprintd-list $(whoami)                # List enrolled fingers\nfprintd-verify                        # Test fingerprint\nfprintd-delete $(whoami)              # Delete all enrolled fingerprints\nlsusb | grep 2541                     # Check if scanner is connected\n```\n\n## Credits\n\n- **Community driver:** [archeYR/libfprint-CS9711](https://github.com/archeYR/libfprint-CS9711) (maintained fork, originally by [ddlsmurf](https://github.com/ddlsmurf))\n- **Retry delay patch \u0026 Linux integration:** [mmhfarooque](https://github.com/mmhfarooque)\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for full version history and release notes.\n\n## License\n\nThe libfprint driver is licensed under LGPL-2.1 (same as upstream libfprint). The installer scripts in this repo are MIT licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmhfarooque%2Fchipsailing-cs9711-fingerprint-linux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmhfarooque%2Fchipsailing-cs9711-fingerprint-linux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmhfarooque%2Fchipsailing-cs9711-fingerprint-linux/lists"}