0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ======================
0004 Kernel driver apds990x
0005 ======================
0006
0007 Supported chips:
0008 Avago APDS990X
0009
0010 Data sheet:
0011 Not freely available
0012
0013 Author:
0014 Samu Onkalo <samu.p.onkalo@nokia.com>
0015
0016 Description
0017 -----------
0018
0019 APDS990x is a combined ambient light and proximity sensor. ALS and proximity
0020 functionality are highly connected. ALS measurement path must be running
0021 while the proximity functionality is enabled.
0022
0023 ALS produces raw measurement values for two channels: Clear channel
0024 (infrared + visible light) and IR only. However, threshold comparisons happen
0025 using clear channel only. Lux value and the threshold level on the HW
0026 might vary quite much depending the spectrum of the light source.
0027
0028 Driver makes necessary conversions to both directions so that user handles
0029 only lux values. Lux value is calculated using information from the both
0030 channels. HW threshold level is calculated from the given lux value to match
0031 with current type of the lightning. Sometimes inaccuracy of the estimations
0032 lead to false interrupt, but that doesn't harm.
0033
0034 ALS contains 4 different gain steps. Driver automatically
0035 selects suitable gain step. After each measurement, reliability of the results
0036 is estimated and new measurement is triggered if necessary.
0037
0038 Platform data can provide tuned values to the conversion formulas if
0039 values are known. Otherwise plain sensor default values are used.
0040
0041 Proximity side is little bit simpler. There is no need for complex conversions.
0042 It produces directly usable values.
0043
0044 Driver controls chip operational state using pm_runtime framework.
0045 Voltage regulators are controlled based on chip operational state.
0046
0047 SYSFS
0048 -----
0049
0050
0051 chip_id
0052 RO - shows detected chip type and version
0053
0054 power_state
0055 RW - enable / disable chip. Uses counting logic
0056
0057 1 enables the chip
0058 0 disables the chip
0059 lux0_input
0060 RO - measured lux value
0061
0062 sysfs_notify called when threshold interrupt occurs
0063
0064 lux0_sensor_range
0065 RO - lux0_input max value.
0066
0067 Actually never reaches since sensor tends
0068 to saturate much before that. Real max value varies depending
0069 on the light spectrum etc.
0070
0071 lux0_rate
0072 RW - measurement rate in Hz
0073
0074 lux0_rate_avail
0075 RO - supported measurement rates
0076
0077 lux0_calibscale
0078 RW - calibration value.
0079
0080 Set to neutral value by default.
0081 Output results are multiplied with calibscale / calibscale_default
0082 value.
0083
0084 lux0_calibscale_default
0085 RO - neutral calibration value
0086
0087 lux0_thresh_above_value
0088 RW - HI level threshold value.
0089
0090 All results above the value
0091 trigs an interrupt. 65535 (i.e. sensor_range) disables the above
0092 interrupt.
0093
0094 lux0_thresh_below_value
0095 RW - LO level threshold value.
0096
0097 All results below the value
0098 trigs an interrupt. 0 disables the below interrupt.
0099
0100 prox0_raw
0101 RO - measured proximity value
0102
0103 sysfs_notify called when threshold interrupt occurs
0104
0105 prox0_sensor_range
0106 RO - prox0_raw max value (1023)
0107
0108 prox0_raw_en
0109 RW - enable / disable proximity - uses counting logic
0110
0111 - 1 enables the proximity
0112 - 0 disables the proximity
0113
0114 prox0_reporting_mode
0115 RW - trigger / periodic.
0116
0117 In "trigger" mode the driver tells two possible
0118 values: 0 or prox0_sensor_range value. 0 means no proximity,
0119 1023 means proximity. This causes minimal number of interrupts.
0120 In "periodic" mode the driver reports all values above
0121 prox0_thresh_above. This causes more interrupts, but it can give
0122 _rough_ estimate about the distance.
0123
0124 prox0_reporting_mode_avail
0125 RO - accepted values to prox0_reporting_mode (trigger, periodic)
0126
0127 prox0_thresh_above_value
0128 RW - threshold level which trigs proximity events.
