• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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