Skip to content

API Reading Fingerprints

dilshan edited this page Nov 22, 2026 · 1 revision

Reading Fingerprints

Functions that read fingerprint data from an open sensor.

Typical sequence:

olru_capture_image / olru_wait_for_finger   <- sensor captures the image
        │
        ├── olru_read_image      <- download the 256×288 pixels
        └── olru_read_template   <- download the 256-byte feature template

olru_capture_image

int olru_capture_image(olru_device *dev);

Asks the sensor to capture an image once and returns immediately. It is the building block for polling, and is the right call for GUI programs that poll from a timer (see the GTK capture example).

Returns

Value Meaning
OLRU_OK a finger was present; the image is now held inside the sensor
OLRU_ERR_NO_FINGER nothing on the sensor yet - not a real failure, call again later
other negative transfer or sensor error, see Errors

olru_wait_for_finger

int olru_wait_for_finger(olru_device *dev, unsigned timeout_ms);

Calls olru_capture_image every 100 ms until a finger is detected. Blocks the calling thread.

Parameter Description
timeout_ms give up after this many milliseconds. 0 tries exactly once.

Returns OLRU_OK when a finger was captured, OLRU_ERR_TIMEOUT if none appeared in time, or any other error from olru_capture_image.

if (olru_wait_for_finger(dev, 5000) == OLRU_OK) { /* image captured */ }

olru_read_image

int olru_read_image(olru_device *dev, uint8_t *buf, size_t size);

Downloads the image captured by the last successful olru_capture_image / olru_wait_for_finger.

Parameter Description
buf receives OLRU_IMAGE_WIDTH × OLRU_IMAGE_HEIGHT bytes, 8 bit per pixel, row by row
size size of buf; must be at least OLRU_IMAGE_SIZE (73728)

Returns OLRU_OK, OLRU_ERR_ARG (bad pointer or size too small), or a transfer error (OLRU_ERR_IO, OLRU_ERR_TIMEOUT, OLRU_ERR_PROTOCOL).

Notes:

  • Pixel 0 = darkest, 255 = lightest. Ridges are dark.
  • The rows are in the same order as the vendor SDK's raw buffer. Writing them unchanged into a bottom-up BMP (what olru_image_to_bmp does) shows the image the way the SDK demo shows it. If you display the raw buffer top-down yourself, it appears vertically mirrored relative to that.
  • A transfer takes a fraction of a second.
  • Use a static or heap buffer; 73 KB is large for a small thread stack.

olru_read_template

int olru_read_template(olru_device *dev, uint8_t out[OLRU_TEMPLATE_SIZE]);

Has the sensor extract fingerprint features from the captured image and reads them back. The extraction is done by the sensor; the library only transports the result.

Call it after a successful capture. It may be called before or after olru_read_image.

Parameter Description
out receives OLRU_TEMPLATE_SIZE (256) bytes

Returns

Value Meaning
OLRU_OK template stored in out
OLRU_ERR_DEVICE the sensor refused - usually a poor image. Read the reason with olru_device_code
OLRU_ERR_ARG / transfer errors as usual

Common sensor codes after OLRU_ERR_DEVICE: 0x06 image too messy, 0x07 too few feature points, 0x15 no valid image in the sensor. Capture again with a cleaner, firmly placed finger.

uint8_t tpl[OLRU_TEMPLATE_SIZE];
int rc = olru_read_template(dev, tpl);
if (rc == OLRU_ERR_DEVICE)
    printf("sensor says: %s\n", olru_device_code_text(olru_device_code(dev)));

The template format is defined by the sensor firmware. The library does not interpret it, compare it, or convert it.

Clone this wiki locally