Documentation/misc-devices/bh1770glc.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =======================
   4 Kernel driver bh1770glc
   5 =======================
   6
   7 Supported chips:
   8
   9 - ROHM BH1770GLC
  10 - OSRAM SFH7770
  11
  12 Data sheet:
  13 Not freely available
  14
  15 Author:
  16 Samu Onkalo <samu.p.onkalo@nokia.com>
  17
  18 Description
  19 -----------
  20 BH1770GLC and SFH7770 are combined ambient light and proximity sensors.
  21 ALS and proximity parts operates on their own, but they shares common I2C
  22 interface and interrupt logic. In principle they can run on their own,
  23 but ALS side results are used to estimate reliability of the proximity sensor.
  24
  25 ALS produces 16 bit lux values. The chip contains interrupt logic to produce
  26 low and high threshold interrupts.
  27
  28 Proximity part contains IR-led driver up to 3 IR leds. The chip measures
  29 amount of reflected IR light and produces proximity result. Resolution is
  30 8 bit. Driver supports only one channel. Driver uses ALS results to estimate
  31 reliability of the proximity results. Thus ALS is always running while
  32 proximity detection is needed.
  33
  34 Driver uses threshold interrupts to avoid need for polling the values.
  35 Proximity low interrupt doesn't exists in the chip. This is simulated
  36 by using a delayed work. As long as there is proximity threshold above
  37 interrupts the delayed work is pushed forward. So, when proximity level goes
  38 below the threshold value, there is no interrupt and the delayed work will
  39 finally run. This is handled as no proximity indication.
  40
  41 Chip state is controlled via runtime pm framework when enabled in config.
  42
  43 Calibscale factor is used to hide differences between the chips. By default
  44 value set to neutral state meaning factor of 1.00. To get proper values,
  45 calibrated source of light is needed as a reference. Calibscale factor is set
  46 so that measurement produces about the expected lux value.
  47
  48 SYSFS
  49 -----
  50
  51 chip_id
  52         RO - shows detected chip type and version
  53
  54 power_state
  55         RW - enable / disable chip
  56
  57         Uses counting logic
  58
  59              - 1 enables the chip
  60              - 0 disables the chip
  61
  62 lux0_input
  63         RO - measured lux value
  64
  65              sysfs_notify called when threshold interrupt occurs
  66
  67 lux0_sensor_range
  68         RO - lux0_input max value
  69
  70 lux0_rate
  71         RW - measurement rate in Hz
  72
  73 lux0_rate_avail
  74         RO - supported measurement rates
  75
  76 lux0_thresh_above_value
  77         RW - HI level threshold value
  78
  79              All results above the value
  80              trigs an interrupt. 65535 (i.e. sensor_range) disables the above
  81              interrupt.
  82
  83 lux0_thresh_below_value
  84         RW - LO level threshold value
  85
  86              All results below the value
  87              trigs an interrupt. 0 disables the below interrupt.
  88
  89 lux0_calibscale
  90         RW - calibration value
  91
  92              Set to neutral value by default.
  93              Output results are multiplied with calibscale / calibscale_default
  94              value.
  95
  96 lux0_calibscale_default
  97         RO - neutral calibration value
  98
  99 prox0_raw
 100         RO - measured proximity value
 101
 102              sysfs_notify called when threshold interrupt occurs
 103
 104 prox0_sensor_range
 105         RO - prox0_raw max value
 106
 107 prox0_raw_en
 108         RW - enable / disable proximity
 109
 110              Uses counting logic
 111
 112              - 1 enables the proximity
 113              - 0 disables the proximity
 114
 115 prox0_thresh_above_count
 116         RW - number of proximity interrupts needed before triggering the event
 117
 118 prox0_rate_above
 119         RW - Measurement rate (in Hz) when the level is above threshold
 120         i.e. when proximity on has been reported.
 121
 122 prox0_rate_below
 123         RW - Measurement rate (in Hz) when the level is below threshold
 124         i.e. when proximity off has been reported.
 125
 126 prox0_rate_avail
 127         RO - Supported proximity measurement rates in Hz
 128
 129 prox0_thresh_above0_value
 130         RW - threshold level which trigs proximity events.
 131
 132              Filtered by persistence filter (prox0_thresh_above_count)
 133
 134 prox0_thresh_above1_value
 135         RW - threshold level which trigs event immediately