Skip to content

PROTOCOL.md

Latest commit

 

History

History
200 lines (142 loc) · 5.36 KB

PROTOCOL.md

File metadata and controls

200 lines (142 loc) · 5.36 KB

Focaltech 2808:9e65 USB Protocol Notes

This document describes the protocol currently implemented in this repository for the Focaltech USB fingerprint sensor VID:PID 2808:9e65.

It is based on:

  • Reverse-engineering workflow and packet captures in captures/
  • Driver implementation in driver/focaltech.c
  • Standalone validator in test/focaltech_test.c

These notes represent observed/implemented behavior and should be treated as a working protocol specification.

1. Transport

  • Bus: USB bulk transfer
  • OUT endpoint (host -> device): 0x01
  • IN endpoint (device -> host): 0x82
  • Default command timeout: 2000 ms

The host performs request/response command transactions:

  1. Send one framed packet to EP_OUT
  2. Read one framed packet from EP_IN
  3. Validate frame checksum before parsing payload

2. Packet Format

All packets are framed as:

Byte Offset Field Size Notes
0 SOF 1 Always 0x02
1 Reserved 1 Always 0x00
2 Payload Length 1 Number of bytes in [CMD/RESP + ARGS/DATA]
3 Command or Response Code 1 Command in requests, response code in replies
4..N Args/Data variable Optional command args or response payload
Last Checksum 1 XOR checksum (see below)

2.1 Checksum Algorithm

Checksum is XOR over bytes starting at offset 2 through the end of payload bytes (excluding the checksum byte itself):

chk = 0
for i in [2 .. len-2]:
    chk ^= packet[i]
packet[len-1] = chk

For responses, checksum verification is equivalent to XOR over offsets 2..len-1 resulting in 0.

3. Response Codes

Known response codes (byte 3 in response frame):

  • 0x04: Success / OK
  • 0x09: No match (observed in verify path)

4. Command Set (Observed)

Command Code Direction Purpose
CMD_POWER 0x80 Host->Device Wake and polling sub-operations
CMD_INIT 0x37 Host->Device Device init sequence
CMD_STATUS 0xAD Host->Device Query status before enrollment
CMD_CAPTURE 0x3B Host->Device Trigger fingerprint capture
CMD_PROGRESS 0xA6 Host->Device Enrollment/progress query
CMD_SECURE 0x34 Host->Device Secure channel/state check
CMD_RESET 0x82 Host->Device Sensor reset between stages
CMD_ENROLL_KEY 0xA8 Host->Device Send 32-byte key/template blob
CMD_FINALIZE 0xA3 Host->Device Finalize enrollment using key
CMD_VERIFY 0xAA Host->Device Retrieve template/match operation

5. Important Command Argument Patterns

5.1 Power/Wake/Poll (CMD_POWER, 0x80)

  • Wake args: [0x01, 0x02]
  • Poll args: [0x02, 0x01]

Observed meanings:

  • Wake response payload often includes magic bytes A5 5A
  • Poll response payload indicates finger presence:
    • 0x01 => finger detected
    • non-0x01 => no finger yet

5.2 Init (CMD_INIT, 0x37)

  • Args: [0x01, 0x01, 0x00]

5.3 Capture (CMD_CAPTURE, 0x3B)

  • Args: [0x02, 0x00]

5.4 Reset (CMD_RESET, 0x82)

  • Args: [0x78]

5.5 Secure Check (CMD_SECURE, 0x34)

  • No args
  • Expected success payload includes magic bytes 55 AA

5.6 Enroll Key / Template Blob (CMD_ENROLL_KEY, 0xA8)

  • 32-byte payload
  • In current implementation, this carries:
    • Enrollment-time generated 32-byte key, or
    • Stored 32-byte template/blob during verification flow

5.7 Finalize (CMD_FINALIZE, 0xA3)

  • 32-byte payload (same key blob used in enrollment)

5.8 Verify (CMD_VERIFY, 0xAA)

  • No args
  • Used in two contexts:
    • Enrollment completion: retrieve 32-byte enrolled template blob
    • Verification: request match/verification result

6. High-Level Transaction Flows

The driver is implemented as asynchronous libfprint state machines (FpiSsm).

6.1 Device Open

  1. CMD_POWER([01 02])
  2. Receive/validate response
  3. CMD_INIT([01 01 00])
  4. Receive/validate response

6.2 Device Close

  1. CMD_RESET([78])
  2. Receive/validate response
  3. Release USB interface

6.3 Enrollment (Configured 10 stages)

Pre-check:

  1. CMD_STATUS
  2. CMD_SECURE
  3. CMD_ENROLL_KEY(32-byte key)

Per-stage loop (ENROLL_STAGES = 10):

  1. Wake: CMD_POWER([01 02])
  2. Poll until finger present: CMD_POWER([02 01])
  3. Capture: CMD_CAPTURE([02 00])
  4. Progress: CMD_PROGRESS
  5. Reset: CMD_RESET([78])
  6. Report stage progress to libfprint

Finalization:

  1. CMD_SECURE
  2. CMD_FINALIZE(32-byte key)
  3. Wake + poll + capture + progress + reset (final capture cycle)
  4. CMD_SECURE
  5. CMD_VERIFY -> extract 32-byte enrolled template/blob

Template handling in driver:

  • Stored as a 32-byte raw blob
  • Wrapped into libfprint print data variant format (@ay)

6.4 Verification

  1. Wake: CMD_POWER([01 02])
  2. Init: CMD_INIT([01 01 00])
  3. Send stored 32-byte template/blob via CMD_ENROLL_KEY
  4. Poll until finger present
  5. Capture
  6. Progress
  7. Reset
  8. Secure check
  9. Verify: CMD_VERIFY
  10. Match result from response code (0x04 success, otherwise fail/no match)

7. Example Frames

7.1 Wake Request Example

Request:

02 00 03 80 01 02 80

Explanation:

  • 03 payload length (CMD + 2 args)
  • 80 command (CMD_POWER)
  • args 01 02
  • checksum 0x80 (XOR of 03 ^ 80 ^ 01 ^ 02)

7.2 Typical Success Response Shape

Example shape (payload bytes vary by command):

02 00 <len> 04 <payload...> <chk>

Where 04 is success response code.