Repository navigation
API 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
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 |
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 */ }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_bmpdoes) 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
staticor heap buffer; 73 KB is large for a small thread stack.
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.
openlru-lib - Open LRU Fingerprint Library · Home