Skip to main content

Open LRU Fingerprint Library

LRU sensors are small USB fingerprint modules developed by Shenzhen Lirox Information Technology Co., Ltd., designed for access-control and embedded security devices. Each module has its own onboard processor that captures the fingerprint image and extracts its features, communicating with the host computer solely over USB. Recently, I had the chance to work with the LRU1011, a thin, inexpensive capacitive fingerprint sensor.

LRU1011 Fingerprint sensor.

The vendor provides a closed-source Linux library for this sensor, which cannot be ported to architectures other than amd64.

To use the sensor on other architectures, I decided to build a lightweight C library for it. Because the vendor does not publish the protocol, I had to reverse-engineer it myself using two complementary methods:

- Hardware USB sniffing: I captured the USB traffic between the vendor's software and the sensor using an external hardware USB sniffer.

- Binary analysis: I studied the vendor's closed-source Linux library to identify commands, opcodes, and error codes, and to generalize the implementation.

Using both methods together worked especially well: the sniffed traffic confirmed what I found in the library, and the library explained what I observed on the wire.

From what I gathered, the protocol is split into two layers:

- Packets: The commands and replies themselves, which are consistent across models. 

- Transport: How a packet is framed and carried over USB, which varies on some models.

Every command and reply uses a single frame:

Offset Size Field
0 2 Header, always EF 01
2 4 Chip address, always FF FF FF FF
6 1 Packet id: 01 = command, 07 = reply
7 2 Length (payload size + 2), big endian
9 n Payload
9+n 2 Checksum (big endian)

The checksum is a simple 16-bit sum starting at the packet ID and ending at the last payload byte.

For example, here is the command to obtain the fingerprint image:

EF 01 FF FF FF FF 01 00 03 01 00 05

The first payload byte is the opcode. In a reply, the first byte is the confirmation code, where 00 means OK.

I mainly focused on the following commands:

Opcode Function
0x13 or 0x33 Check that the sensor answers
0x01 or 0x32 Capture an image. 00 = captured, 02 = no finger
0x0A Upload the raw image (73728 bytes)
0x02 Extract the feature template
0x08 Upload the template (512 bytes)

As I noticed, upload commands do not send an ACK packet; they send raw data directly.

The most interesting part of this sensor is its transport mechanism. I found that the same packets travel in two different ways:

- Bulk transport mode (models 0453:9005 and 0618:9018): Before every transfer, the host sends a vendor control request and then uses the bulk endpoints. The image is read in two halves of 36,864 bytes. The vendor library also resets the device after opening it and waits about 200ms.

- MSC mode (models 2009:7638 and 2109:7638): The device presents itself as a USB mass-storage device, even though it has no storage media, using the storage interface as a command pipe. Each transfer is wrapped in a mass-storage command: a 31-byte command block starting with USBC, a data stage, and a 13-byte status block starting with USBS. The image is read in 8 chunks of 9,216 bytes.

This is a clever trick by the vendor that lets the device work with basic drivers, though it requires care in the library since some ordinary USB drives share the same USB IDs.

Based on these findings, I built a generic C library for LRU sensors called openlru-lib. Written in C with zero external library dependencies, it doesn't even require libusb - it talks to the Linux usbfs interface directly.

The full source code, binary releases, and documentation are available in the project repository at https://github.com/dilshan/openlru-lib. The wiki covers the API, architecture, USB protocol, and troubleshooting in more detail.

This is an independent project and is not affiliated with or endorsed by the vendor. It is licensed under the BSD-3-Clause license.

Bug reports, test results on other models, and pull requests are all welcome.

Comments

Popular posts from this blog

Building the TD4 4-Bit CPU

The TD4 is a famous 4-bit CPU featured in the book How to Build a CPU by Kaoru Tonami . The book focuses on constructing a functional processor entirely from basic 74-series TTL logic ICs. While the book is unfortunately only available in Japanese, a friend from Japan sent me a copy along with a TD4 PCB. I believe the PCB is based on the open-source design files available on BG5DIW's GitHub repository . "How to Build CPU" book and the PCB. Recently, I finally found the time to build and experiment with it. The project took a few months, as I had to translate the book myself to grasp the core concepts. The overall design is simple and elegant, offering a set of 12 instructions and a 16-byte ROM (implemented via DIP switches) for programming. The board operates on 5V and can be powered via USB. Most components were sourced from local shops, though I had to order a few 74HC-series ICs online. Later, I tested the circuit by replacing some 74HC components with 74LS series...

CD2003 - yet another simple FM radio receiver

In the last few days, we are looking for some simple FM radio receiver to integrate into one of our ongoing projects. For that, we try several FM radio receiver ICs including TDA7000, CD2003/TA2003/TA8164, CXA1019, and KA22429. Out of all those chips we select CD2003 (or TA2003/TA8164) based receiver for our project because of its simplicity and outstanding performance. Except to CD2003, Sony CXA1019 also perform well but we drop it because of its higher component count. We design our receiver based on Toshiba TA2003 datasheet and later we try TA8164 and CD2003 with the same circuit. Either CD2003 or TA8164 can directly replace TA2003 IC, and as per our observations, TA8164 gives excellent results out of those 3 chips. A prototype version of CD2003 FM radio receiver The PCB design and schematic which we used in our prototype project are available to download at google drive (including pin-outs of crystal filters and inductors ). Except for CD2003 IC, this receiver consist...

AVR-HV: High voltage programmer for AVR microcontrollers

When it comes to AVR microcontrollers the most common programming option is In-System Programming ( ISP ). ISP interface is easy to use but in some scenarios it is totally unusable. The most common scenario is with some wrong fuse bit values. For example if we program SPIEN or RSTDISBL fuse bits, AVR microcontrollers may not respond to any in-system programmer(s). To overcome these problems the next available option is high voltage programming mode. In High voltage programming mode, 12V programming voltage is applied to RESET pin of target AVR microcontroller and user can change configuration fuses of AVR MCU with minimum amount of risk. The only drawback in this mode is that target microcontroller must need to be removed from the board to reprogram. Most of the AVR high voltage programmers are expensive and difficult to find in ordinary electronic shops. As a solution we implement USB base high voltage parallel programmer for AVR microcontrollers and it allows programming, readi...