Skip to content

Architecture

dilshan edited this page Nov 22, 2026 · 1 revision

Architecture

Layers

 your application
        │   include/openlru.h
 ┌──────▼───────┐
 │  openlru.c   │  API: link check, capture, read image, read template
 ├──────────────┤
 │ olru_packet.c│  builds / parses the 0xEF01 command and reply packets
 ├──────────────┤
 │ olru_link.c  │  moves bytes over USB: BULK flavour or MSC flavour
 ├──────────────┤
 │ olru_usb.c   │  Linux usbfs backend: sysfs scan + control/bulk ioctls
 └──────┬───────┘
        │  /dev/bus/usb/BBB/DDD
     the sensor

olru_image.c sits beside this stack: it only converts a raw image to BMP.

Each layer talks only to the one below. The USB layer is reached through a small table of function pointers (struct olru_usb_ops), so another backend (libusb, a test double, a network bridge) can replace usbfs without touching anything above it. The unit tests use exactly that.

Source files

File Responsibility
include/openlru.h the entire public API
src/olru_internal.h private declarations, olru_usb_ops, struct olru_device, layering notes
src/openlru.c opcodes, command helpers, probe/open/close, capture, image and template reads, error text
src/olru_packet.c packet build (olru_packet_build) and reply check (olru_packet_parse_ack)
src/olru_link.c BULK and MSC transports: olru_link_write, olru_link_read, olru_link_read_block
src/olru_usb.c known-model table, sysfs scan, claim interface, control/bulk transfers
src/olru_image.c BMP headers, palette and file writer
examples/gtk_probe.c, examples/gtk_capture.c GTK 3 demonstrations
udev/99-openlru.rules non-root access rules
Makefile build, install, clean

The device handle

struct olru_device {
    const struct olru_usb_ops *ops;   /* USB backend in use          */
    void          *ctx;               /* backend private data (fd)   */
    olru_link_type link;              /* BULK or MSC framing         */
    uint8_t        alt_opcodes;       /* alternate opcode set?       */
    uint8_t        last_code;         /* last sensor confirmation    */
};

Life of one call: olru_capture_image

  1. openlru.c picks opcode 0x01 (or 0x32 for alt-opcode models).
  2. olru_packet_build wraps it into an EF 01 ... packet with checksum.
  3. olru_link_write sends it (BULK: control request + bulk out; MSC: CBW + data + CSW).
  4. olru_link_read reads the reply; olru_packet_parse_ack extracts the confirmation code.
  5. The code becomes an olru_status (0 → OLRU_OK, 2 → OLRU_ERR_NO_FINGER, else OLRU_ERR_DEVICE) and is stored in last_code.

Coding style

  • Small functions with one job; most are under 25 lines.
  • Every file starts with a comment explaining its role; every function that isn't obvious has one too.
  • Constants have names (OP_GET_IMAGE, MSC_CHUNKS, ...); no unexplained numbers.
  • Errors are returned as olru_status; the library never prints.
  • No global state, no dynamic allocation except the device handle.

Extending

To add... Touch
a new sensor model the known_models[] table in olru_usb.c (and the udev rule)
a new sensor command an opcode in openlru.c, using run_command() or send_command() + a raw read
a different USB backend implement struct olru_usb_ops, build a handle with olru_device_create()
another image format a function in olru_image.c + declaration in openlru.h

Clone this wiki locally