compareeHub

A WIRELESS FINGERPRINT SCANNER, BUILT FROM SCRATCH

A keychain-sized wireless fingerprint key that unlocks your Mac, Windows or Linux desktop and approves sudo without typing a password.

by superdog (immurok)

FULL CAD BOM FIRMWARE DOCS

Open-hardwareAutomation

difficulty
●●●●○
time
a weekend-plus
license
BUSL-1.1
repo
repo ACTIVE23 stars

WHAT YOU’LL NEED

Videos
1
Jump to section

COMPAREE VERDICT

immurok is a keychain-sized wireless fingerprint key built around a WCH CH592F RISC-V Bluetooth LE microcontroller and an R559S capacitive fingerprint sensor. It advertises as a standard BLE HID keyboard so the computer keeps it connected, while the real traffic runs over an encrypted custom GATT service: ECDH P-256 pairing, then an HMAC-SHA256 signed message for every touch. Matching happens on the sensor itself, so no biometric data reaches the computer. Companion apps cover macOS (menu bar app plus PAM), Linux (Rust daemon and CLI plus PAM) and Windows (Credential Provider), and the device also works as a hardware SSH agent. Unlike most write-ups, this one is well documented: firmware source, OTA bootloader, a full schematic PDF, PCB renders, a pinout and a protocol and security spec are all on GitHub. What is missing for a from-scratch build is the PCB layout source, which the creator plans to release after the Kickstarter campaign, and a standalone parts list. Note the licence: firmware and hardware are BSL 1.1, fine for personal use but not for selling your own units until it converts to Apache 2.0 in 2030. If you just want one, the creator sells pre-orders on immurok.com.

GOOD TO KNOW

  • —Firmware source (C, Makefile) and OTA bootloader are public on GitHub.
  • —The hardware repository has a full schematic PDF (HW V7), PCB renders, pinout and component selection notes; PCB layout source is to be released after the Kickstarter campaign.
  • —No standalone parts list file; the key parts (CH592F, R559S, BQ21040 charger, XC6206 LDO, 110 mAh LiPo) are named in the hardware README and schematic.
  • —Companion apps for macOS, Linux and Windows are open source under Apache 2.0.
  • —Firmware and hardware are licensed BSL 1.1 (non-commercial use only), converting to Apache 2.0 on 2030-03-05.
  • —No enclosure CAD files are published.

Parts to buy

6 items

From our check of the build. Exact quantities and part numbers are in the creator’s BOM.

  • WCH CH592F microcontrollerFind
  • R559S capacitive fingerprint sensorFind
  • BQ21040 chargerFind
  • XC6206 3.3 V LDOFind
  • 110 mAh LiPo cellFind
  • USB-C power-only receptacle and passives per the schematicFind

Can I build this?

Printnothing required; no enclosure files are published
BuyWCH CH592F microcontroller, R559S capacitive fingerprint sensor, BQ21040 charger, XC6206 3.3 V LDO, 110 mAh LiPo cell, USB-C power-only receptacle and passives per the schematic
ToolsFine-pitch soldering setup (the CH592F is QFN28), PCB design software, a WCH-LinkE or USB-serial adapter for flashing, and a Bluetooth-capable computer
Skillsintermediate to advanced: PCB layout from a schematic, QFN soldering, building embedded firmware, and configuring PAM or system authentication
Timea weekend-plus, longer if you have to lay out the PCB yourself
Cost$$ for your own PCB and parts; a finished unit is offered as a pre-order on immurok.com
SafetySmall LiPo battery: keep the charger thermal protection and avoid shorting or puncturing the cell.

Build at your own risk. Projects involve tools, electronics and sometimes mains voltage — follow the creator’s safety notes.

Videos

immurok Linux app demostration: a Touch ID like wireless fingerprint auth key for all

Official demo of the Linux companion app from the immurok YouTube channel.

More builds like this

All projects
A do-it-yourself fingerprint unlock for a Mac, built to avoid Apple's 149 dollar Touch ID keyboardOpen-hardwareMake video calls with no internet over your own long-range meshAutomationA card in a spare PCIe slot presses your PC power button for you, from anywhereAutomation

Gallery

immurok, github.com/immurok/hardware
immurok, github.com/immurok/hardware
Immurok official, YouTube

Start here

Navigation into the creator’s own docs — we don’t rewrite the guide, we route you to the source.

  1. 1.Read the main repository to understand the architecture (Overview, repository map, BLE protocol and security docs)
  2. 2.Study the hardware design and source the CH592F and R559S (Schematic PDF, PCB renders, pinout and why each part was chosen)
  3. 3.Build and flash the firmware (Needs the WCH RISC-V GCC toolchain, CH592 EVT SDK and your own OTA keys)
  4. 4.Install the companion app and set up PAM or the Windows Credential Provider (Or app-macos / app-win for the other platforms)

Resources

Documentation, files and community threads for this build — we link straight to the original sources and never rehost the creator’s files.

KNOWN ISSUES

  • The PCB layout source files are not released yet, only renders and the schematic PDF, so you would have to lay out the board yourself from the schematic.
  • The firmware needs the WCH RISC-V GCC toolchain and the CH592 EVT SDK, plus wchisp or a WCH-LinkE for flashing. That is less familiar than Arduino or PlatformIO.
  • You must generate your own OTA keys before the first build. Firmware signed with self-generated keys will not update a retail device running official firmware.
  • The device runs on a small LiPo cell. Use the charger design from the schematic (BQ21040 with an NTC thermistor) and do not skip the thermal protection.
  • The BLE stack is a closed binary library from WCH; only the application layer is open source.
  • BSL 1.1 forbids commercial use of the firmware and hardware design, so building units to sell is not allowed until 2030.

Is there a repository with the code and schematics?

Yes. The immurok GitHub organization has separate repositories for the firmware, the OTA bootloader, the hardware (a schematic PDF, PCB renders and a component write-up), and the macOS, Linux and Windows companion apps. The PCB layout source files are not released yet; the hardware README says they will follow after the Kickstarter campaign.

What licence is it under?

The firmware, hardware and core project are under the Business Source License 1.1. Personal, educational and non-commercial research use is allowed, commercial use is not, and the licence converts to Apache 2.0 on 2030-03-05. The macOS, Linux (Rust) and Windows companion apps are Apache 2.0.

Does this work with Windows?

Yes. Besides the macOS and Linux apps there is a Windows companion app with a native Credential Provider for Windows login. sudo and PAM integration applies to macOS and Linux.

How does the computer know to trust the fingerprint device?

The device and the companion app pair with an ECDH P-256 key exchange. Each touch produces an HMAC-SHA256 signed notification over a custom BLE GATT service, which the app verifies before typing the password, answering the PAM challenge or signing an SSH request. The fingerprint template stays inside the R559S sensor. The full protocol and security model are documented in the main repository.

Can I use a different fingerprint sensor?

The firmware is written for the R559S, which talks UART and does enrollment and matching on the module itself. Swapping it would mean porting the sensor driver, and you should pick a module that also matches on-device so no biometric data reaches the MCU.

Community builds

No community builds yet — be the first, we feature the best ones.

Discussion1

FROM THE COMPAREE TEAM

immurok matches the fingerprint on the sensor and only sends a signed approval over Bluetooth. Would you trust a device like this for sudo and screen unlock, or stick with typing the password?

CompareeTEAM1d ago

Practical notes from our verification: this project is far better documented than the Hackaday article suggests. The GitHub organization has the firmware, the OTA bootloader, the schematic and companion apps for all three desktop systems. The one real gap is the PCB layout source, which is promised after the Kickstarter. Check the licence before you build: BSL 1.1 means personal use is fine, selling units is not.

superdog (immurok)

superdog, posting on Hackaday.io, built immurok as a wireless fingerprint key for people who use external keyboards, Mac desktops, Linux machines and terminal-heavy workflows, where repeated password prompts for sudo and login break the flow. The project is published under the immurok GitHub organization and is also being prepared as a commercial product.

GitHub Web

Star the project on GitHub

DISCLAIMER

  • Comparee is not the author of the projects featured here. All rights to each project belong to its creator — every page links to the original source, and we never host creators’ files.
  • Information is provided without warranty and may become outdated as projects evolve. Prices are indicative bands only — always check the creator’s parts list for current costs.
  • Building and operating any project is at your own responsibility. Protective equipment, safe workshop practice and compliance with local regulations are the builder’s responsibility.
GitHub repo