Skip to content

USB Protocol

dilshan edited this page Nov 22, 2026 · 1 revision

USB Protocol

Two layers

  1. Packets - the commands and replies (the same on every model).
  2. Transport - how a packet is carried over USB (differs by model).

Packet format

Every command and reply is one 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
  • Checksum = 16-bit sum of the bytes from the packet id (offset 6) through the last payload byte.
  • Command payload: the first byte is the opcode, the rest are its arguments.
  • Reply payload: the first byte is the confirmation code (00 = ok).

Example - GetImage command (opcode 01):

EF 01 FF FF FF FF 01 00 03 01 00 05
                  │  └──┘  │  └──┘
                  │  len=3 │  checksum = 01+00+03+01 = 5
                  pid=cmd  opcode

Like the vendor SDK, the library does not verify the checksum of replies; it checks the header, packet id and length only.

Commands used

Opcode Alt-opcode models Name Arguments Sensor replies with
0x13 0x33 Link 78 00 00 00 ack packet, code 00
0x01 0x32 GetImage - ack packet: 00 captured, 02 no finger
0x0A 0x0A UpImage - 73 728 raw bytes, no ack packet
0x02 0x02 GenChar buffer id (01) ack packet, 00 ok / error code
0x08 0x08 UpChar buffer id (01) 512 raw bytes, no ack packet

Notes:

  • The image is 256 × 288 pixels, 8 bit (73 728 bytes).
  • After GenChar + UpChar the library keeps the first 256 of the 512 bytes (the sensor's "matching template" size).
  • Reads of an ack use a 64-byte buffer; the ack itself is 12 bytes, so the transfer ends on a short packet.
  • The library has no commands for matching, searching, or storing templates in the sensor.

Confirmation codes

Code Meaning
00 OK
01 Communication error
02 No finger
03 Image capture failed
04 Image too light / finger too dry
05 Image too blurred / finger too wet
06 Image too messy
07 Too few feature points
15 No valid image in buffer

Transport A: BULK (OLRU_LINK_BULK)

Models: 0453:9005, 0618:9018.

Before every transfer the host sends a vendor control request and then uses the bulk endpoints:

Step Value
control request type 0xC0 (device-to-host, vendor)
request 0 = host will write, 1 = host will read
wValue transfer length (low 16 bits)
length of control data 10 bytes (reply ignored)
bulk OUT endpoint 0x02
bulk IN endpoint 0x81

The 73 728-byte image is announced once (wValue = 0x12000 & 0xFFFF = 0x2000) and read as two halves of 36 864 bytes.

The vendor SDK also resets these devices right after claiming them and waits about 200 ms; olru_open does the same.

Transport B: MSC (OLRU_LINK_MSC)

Models: 2009:7638, 2109:7638. The device presents a USB mass-storage style interface (class 08, subclass 06, protocol 50) but uses it as a command pipe.

Each transfer is wrapped like mass-storage Bulk-Only Transport:

Command block (31 bytes, sent on endpoint 0x01)

Offset Value
0-3 "USBC"
4-7 tag B0 FA 69 86
8-11 transfer length, little endian
12 80 for a read from the sensor, 00 for a write
13 00
14 0A (command length)
15 vendor opcode: 85 read, 86 write
16-30 00

Data stage - for a write, the packet goes out on 0x01; for a read, the data comes in on 0x81.

Status block (13 bytes, read from 0x81) - must start with "USBS", repeat the tag in bytes 4-7, and have status 00 in byte 12.

The image is read as 8 chunks of 9216 bytes, each with its own command/data/status exchange.

Sequences

Link check: Link command → ack (00).

Capture: GetImage → ack (00 = got a finger / 02 = none).

Read image: UpImage command → 73 728 raw bytes.

Read template: GenChar(1) → ack → UpChar(1) → 512 raw bytes (keep 256).

Not covered

The vendor SDK implements many more commands (storing templates in the sensor, on-device matching and search, passwords, baud rate, card reading, firmware update, other image sizes, ...). openlru-lib deliberately implements only what is needed to probe and read.

Clone this wiki locally