apds990x.rst 3.6 KB

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