1# Virtual Fingerprint HAL 2 3This is a virtual HAL implementation that is backed by system properties instead 4of actual hardware. It's intended for testing and UI development on debuggable 5builds to allow devices to masquerade as alternative device types and for 6emulators. 7 8## Supported Devices 9 10This HAL can be used on emulators, like cuttlefish, or on real devices. Add the 11following to your device's `.mk` file to include it: 12 13``` 14PRODUCT_PACKAGES_DEBUG += com.android.hardware.biometrics.fingerprint.virtual 15``` 16 17The virtual HAL will be ignored if a real HAL is also installed on the target 18device. Set the `biometric_virtual_enabled` settings and reboot the device to 19switch to the virtual HAL. Unset it and reboot again to switch back. 20 21## Getting Started 22 23First, set the type of sensor the device should use, enable the virtual 24extensions in the framework, and reboot. 25 26```shell 27$ adb root 28$ adb shell settings put secure biometric_virtual_enabled 1 29$ adb shell setprop persist.vendor.fingerprint.virtual.type rear 30$ adb reboot 31``` 32 33### Enrollments 34 35Next, setup enrollments on the device. This can either be done through the UI, 36or via adb directly. 37 38#### Direct Enrollment 39 40To set enrollment directly without the UI: 41 42```shell 43$ adb root 44$ adb shell locksettings set-pin 0000 45$ adb shell setprop persist.vendor.fingerprint.virtual.enrollments 1 46$ adb shell cmd fingerprint sync 47``` 48 49#### UI Enrollment 50 511. Set pin 52 ```shell 53 $ adb shell locksettings set-pin 0000 54 ``` 552. Tee up the results of the enrollment before starting the process: 56 57 ```shell 58 $ adb shell setprop vendor.fingerprint.virtual.next_enrollment 1:100,100,100:true 59 ``` 60 613. Navigate to `Settings -> Security -> Fingerprint Unlock` and follow the 62 prompts. 634. Verify the enrollments in the UI: 64 65 ```shell 66 $ adb shell getprop persist.vendor.fingerprint.virtual.enrollments 67 ``` 68 69## Authenticate 70 71To authenticate successfully set the enrolled id that should succeed. Unset it 72or change the value to make authenticate operations fail: 73 74````shell 75$ adb shell setprop vendor.fingerprint.virtual.enrollment_hit 1 76```` 77 78## Acquired Info Insertion 79 80Fingerprint image acquisition states at HAL are reported to framework via onAcquired() callback. The valid acquired state info for AIDL HAL include 81 82{UNKNOWN(0), GOOD(1), PARTIAL(2), INSUFFICIENT(3), SENSOR_DIRTY(4), TOO_SLOW(5), TOO_FAST(6), VENDOR(7), START(8), TOO_DARK(9), TOO_BRIGHT(10), IMMOBILE(11), RETRYING_CAPTURE(12)} 83 84Refer to [AcquiredInfo.aidl](../android/hardware/biometrics/fingerprint/AcquiredInfo.aidl) for details 85 86 87The states can be specified in sequence for the HAL operations involving fingerprint image captures, namely authenticate, enrollment and detectInteraction 88 89```shell 90$ adb shell setprop vendor.fingerprint.virtual.operation_authenticate_acquired 6,9,1 91$ adb shell setprop vendor.fingerprint.virtual.operation_detect_interaction_acquired 6,1 92$ adb shell setprop vendor.fingerprint.virtual.next_enrollment 2:1000-[5,1],500:true 93 94#next_enrollment format example: 95.---------------------- enrollment id (2) 96| .------------------ the image capture 1 duration (1000ms) 97| | .-------------- acquired info first (TOO_SLOW) 98| | | .------------ acquired info second (GOOD) 99| | | | .-------- the image capture 2 duration (500ms) 100| | | | | .---- enrollment end status (success) 101| | | | | | 102| | | | | | 103| | | | | | 1042:1000-[5,1],500:true 105``` 106For vendor specific acquired info, acquiredInfo = 1000 + vendorAcquiredInfo 107 108## Error Insertion 109The valid error codes for AIDL HAL include 110 111{UNKNOWN(0), HW_UNAVAILABLE(1), UNABLE_TO_PROCESS(2), TIMEOUT(3), NO_SPACE(4), CANCELED(5), UNABLE_TO_REMOVE(6), VENDOR(7), BAD_CALIBRATION(8)} 112 113Refer to [Error.aidl](../android/hardware/biometrics/fingerprint/Error.aidl) for details 114 115 116There are many HAL operations which can result in errors, refer to [here](fingerprint.sysprop) file for details. 117 118```shell 119$ adb shell setprop vendor.fingerprint.virtual.operation_authenticate_error 8 120``` 121For vendor specific error, errorCode = 1000 + vendorErrorCode 122 123## Latency Insertion 124Three HAL operations (authenticate, enrollment and detect interaction) latency can be optionally specified in multiple ways 1251. default latency is fixed at 400 ms if not specified via sysprop 1262. specify authenticate operation latency to 900 ms 127 ```shell adb shell setprop vendor.fingerprint.virtual.operation_authenticate_latency 900``` 1283. specify authenticate operation latency between 600 to 1200 ms in unifrom distribution 129 ```shelladb shell setprop vendor.fingerprint.virtual.operation_authenticate_latency 600,1200``` 130 131## Lockout 132To force the device into lockout state 133```shell 134$ adb shell setprop persist.vendor.fingerprint.virtual.lockout true 135``` 136To test permanent lockout based on the failed authentication attempts (e.g. 7) 137```shell 138$ adb shell setprop persist.vendor.fingerprint.virtual.lockout_permanent_threshold 7 139$ adb shell setprop persist.vendor.fingerprint.virtual.lockout_enable true 140``` 141To test timed lockout based on the failed authentication attempts (e.g. 8 seconds on 5 attempts) 142```shell 143$ adb shell setprop persist.vendor.fingerprint.virtual.lockout_timed_duration 8000 144$ adb shell setprop persist.vendor.fingerprint.virtual.lockout_timed_threshold 5 145$ adb shell setprop persist.vendor.fingerprint.virtual.lockout_enable true 146``` 147 148## Reset all configurations to default 149The following command will reset virtual configurations (related system properties) to default value. 150```shell 151$ adb shell cmd android.hardware.biometrics.fingerprint.IFingerprint/virtual resetconfig 152$ adb reboot 153``` 154 155## View HAL State 156 157To view all the properties of the HAL (see `fingerprint.sysprop` file for the API): 158 159```shell 160$ adb shell getprop | grep vendor.fingerprint.virtual 161``` 162To dump virtual HAL internal data 163```shell 164adb shell dumpsys android.hardware.biometrics.fingerprint.IFingerprint/virtual 165``` 166