Documentation/misc-devices/apds990x.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======================
   4 Kernel driver apds990x
   5 ======================
   6
   7 Supported chips:
   8 Avago APDS990X
   9
  10 Data sheet:
  11 Not freely available
  12
  13 Author:
  14 Samu Onkalo <samu.p.onkalo@nokia.com>
  15
  16 Description
  17 -----------
  18
  19 APDS990x is a combined ambient light and proximity sensor. ALS and proximity
  20 functionality are highly connected. ALS measurement path must be running
  21 while the proximity functionality is enabled.
  22
  23 ALS produces raw measurement values for two channels: Clear channel
  24 (infrared + visible light) and IR only. However, threshold comparisons happen
  25 using clear channel only. Lux value and the threshold level on the HW
  26 might vary quite much depending the spectrum of the light source.
  27
  28 Driver makes necessary conversions to both directions so that user handles
  29 only lux values. Lux value is calculated using information from the both
  30 channels. HW threshold level is calculated from the given lux value to match
  31 with current type of the lightning. Sometimes inaccuracy of the estimations
  32 lead to false interrupt, but that doesn't harm.
  33
  34 ALS contains 4 different gain steps. Driver automatically
  35 selects suitable gain step. After each measurement, reliability of the results
  36 is estimated and new measurement is triggered if necessary.
  37
  38 Platform data can provide tuned values to the conversion formulas if
  39 values are known. Otherwise plain sensor default values are used.
  40
  41 Proximity side is little bit simpler. There is no need for complex conversions.
  42 It produces directly usable values.
  43
  44 Driver controls chip operational state using pm_runtime framework.
  45 Voltage regulators are controlled based on chip operational state.
  46
  47 SYSFS
  48 -----
  49
  50
  51 chip_id
  52         RO - shows detected chip type and version
  53
  54 power_state
  55         RW - enable / disable chip. Uses counting logic
  56
  57              1 enables the chip
  58              0 disables the chip
  59 lux0_input
  60         RO - measured lux value
  61
  62              sysfs_notify called when threshold interrupt occurs
  63
  64 lux0_sensor_range
  65         RO - lux0_input max value.
  66
  67              Actually never reaches since sensor tends
  68              to saturate much before that. Real max value varies depending
  69              on the light spectrum etc.
  70
  71 lux0_rate
  72         RW - measurement rate in Hz
  73
  74 lux0_rate_avail
  75         RO - supported measurement rates
  76
  77 lux0_calibscale
  78         RW - calibration value.
  79
  80              Set to neutral value by default.
  81              Output results are multiplied with calibscale / calibscale_default
  82              value.
  83
  84 lux0_calibscale_default
  85         RO - neutral calibration value
  86
  87 lux0_thresh_above_value
  88         RW - HI level threshold value.
  89
  90              All results above the value
  91              trigs an interrupt. 65535 (i.e. sensor_range) disables the above
  92              interrupt.
  93
  94 lux0_thresh_below_value
  95         RW - LO level threshold value.
  96
  97              All results below the value
  98              trigs an interrupt. 0 disables the below interrupt.
  99
 100 prox0_raw
 101         RO - measured proximity value
 102
 103              sysfs_notify called when threshold interrupt occurs
 104
 105 prox0_sensor_range
 106         RO - prox0_raw max value (1023)
 107
 108 prox0_raw_en
 109         RW - enable / disable proximity - uses counting logic
 110
 111              - 1 enables the proximity
 112              - 0 disables the proximity
 113
 114 prox0_reporting_mode
 115         RW - trigger / periodic.
 116
 117              In "trigger" mode the driver tells two possible
 118              values: 0 or prox0_sensor_range value. 0 means no proximity,
 119              1023 means proximity. This causes minimal number of interrupts.
 120              In "periodic" mode the driver reports all values above
 121              prox0_thresh_above. This causes more interrupts, but it can give
 122              _rough_ estimate about the distance.
 123
 124 prox0_reporting_mode_avail
 125         RO - accepted values to prox0_reporting_mode (trigger, periodic)
 126
 127 prox0_thresh_above_value
 128         RW - threshold level which trigs proximity events.