FocalTech fingerprint sensors TOD wrapper driver for upstream libfprint-tod

• Supports following sensors from the vendor properity libfprint package
  • 0x9338
  • 0xd979
  • 0xc652
  • 0xa959
  • 0x0579
  • 0x0752
• Support upstream libfprint-tod and tested on Ubuntu 25.10

This directory contains a standalone ftfp_proxy prototype for isolating the vendor libfprint.so in a separate process.

Build

apt install libfprint-2-tod-dev

meson setup build
meson compile -C build

If libfprint-2-tod-1 is available via pkg-config, Meson also builds:

• libdevice-focaltech-ftfp_proxy-tod-driver.so (TOD driver module)

Vendor libfprint.so

• You can grab the libfprint package here
• Extract the downloaded deb file and copy libfprint.so to /usr/share/ftfp_proxy/vendor/

Build deb

• Copy libfprint.so to vendor in project root.
• Execute ./scripts/build-deb.sh.
• Install deb in dist directory with dpkg.

Run (manual)

Terminal A:

./build/ftfp_proxy_daemon \
  --socket /run/ftfp_proxy-focaltech.sock \
  --vendor-lib /usr/share/ftfp_proxy/vendor/libfprint.so

Terminal B:

./build/ftfp_proxyctl --socket /run/ftfp_proxy-focaltech.sock ping
./build/ftfp_proxyctl --socket /run/ftfp_proxy-focaltech.sock info
./build/ftfp_proxyctl --socket /run/ftfp_proxy-focaltech.sock open
./build/ftfp_proxyctl --socket /run/ftfp_proxy-focaltech.sock close
./build/ftfp_proxyctl --socket /run/ftfp_proxy-focaltech.sock enroll --finger 1 --out /tmp/focal-template.bin
./build/ftfp_proxyctl --socket /run/ftfp_proxy-focaltech.sock verify --in /tmp/focal-template.bin

enroll now reports stage progress through IPC events, including retry hints from vendor messages (for example image quality low, move a little).

Run (systemd system socket activation)

sudo cp systemd/ftfp_proxy-focaltech.socket /etc/systemd/system/
sudo cp systemd/ftfp_proxy-focaltech.service /etc/systemd/system/

sudo systemctl daemon-reload
sudo systemctl enable --now ftfp_proxy-focaltech.socket
sudo systemctl status ftfp_proxy-focaltech.socket

With socket activation enabled, use:

./build/ftfp_proxyctl --socket /run/ftfp_proxy-focaltech.sock info

Security Notes

• Unix socket is created as 0600.
• Daemon enforces same-UID client connections via SO_PEERCRED.
• Payload sizes are checked for overflow and upper bound.
• The daemon keeps vendor libfprint.so isolated in a separate process.

Notes

• ENROLL/VERIFY use vendor fp_device_*_sync + fp_print_serialize/deserialize.
• NORMALIZE uses vendor internal symbol ft9362_histNormalize (offset-based binding).
• Template persistence is still handled by libfprint: the TOD driver stores vendor bytes in FpPrint.fpi-data (FPI_PRINT_RAW), then libfprint serializes/deserializes it.

TOD Driver Usage

Use a clean TOD drivers directory that only contains the driver .so:

mkdir -p build/tod-drivers
cp -f build/libdevice-focaltech-ftfp_proxy-tod-driver.so build/tod-drivers/

Recommended runtime environment:

export LD_LIBRARY_PATH=/path/to/libfprint-tod/lib/<multiarch>
export FP_TOD_DRIVERS_DIR="$(pwd)/build/tod-drivers"
export FTFP_PROXY_SOCKET=/run/ftfp_proxy-focaltech.sock

Optional timeout tuning (TOD side):

export FTFP_PROXY_ENROLL_TIMEOUT_MS=90000
export FTFP_PROXY_VERIFY_TIMEOUT_MS=30000

Backward compatibility is kept for legacy env names: FTPROXY_SOCKET, FTPROXY_ENROLL_TIMEOUT_MS, FTPROXY_VERIFY_TIMEOUT_MS.

Build DEB

./scripts/build-deb.sh

Output:

./dist/ftfp-proxy-focaltech-tod_<version>_<arch>.deb