[net-next-2.6.git] / Documentation / misc-devices / bh1770glc.txt

Kernel driver bh1770glc
=======================

Supported chips:
ROHM BH1770GLC
OSRAM SFH7770

Data sheet:
Not freely available

Author:
Samu Onkalo <samu.p.onkalo@nokia.com>

Description
-----------
BH1770GLC and SFH7770 are combined ambient light and proximity sensors.
ALS and proximity parts operates on their own, but they shares common I2C
interface and interrupt logic. In principle they can run on their own,
but ALS side results are used to estimate reliability of the proximity sensor.

ALS produces 16 bit lux values. The chip contains interrupt logic to produce
low and high threshold interrupts.

Proximity part contains IR-led driver up to 3 IR leds. The chip measures
amount of reflected IR light and produces proximity result. Resolution is
8 bit. Driver supports only one channel. Driver uses ALS results to estimate
reliability of the proximity results. Thus ALS is always running while
proximity detection is needed.

Driver uses threshold interrupts to avoid need for polling the values.
Proximity low interrupt doesn't exists in the chip. This is simulated
by using a delayed work. As long as there is proximity threshold above
interrupts the delayed work is pushed forward. So, when proximity level goes
below the threshold value, there is no interrupt and the delayed work will
finally run. This is handled as no proximity indication.

Chip state is controlled via runtime pm framework when enabled in config.

Calibscale factor is used to hide differences between the chips. By default
value set to neutral state meaning factor of 1.00. To get proper values,
calibrated source of light is needed as a reference. Calibscale factor is set
so that measurement produces about the expected lux value.

SYSFS
-----

chip_id
	RO - shows detected chip type and version

power_state
	RW - enable / disable chip. Uses counting logic
	     1 enables the chip
	     0 disables the chip

lux0_input
	RO - measured lux value
	     sysfs_notify called when threshold interrupt occurs

lux0_sensor_range
	RO - lux0_input max value

lux0_rate
	RW - measurement rate in Hz

lux0_rate_avail
	RO - supported measurement rates

lux0_thresh_above_value
	RW - HI level threshold value. All results above the value
	     trigs an interrupt. 65535 (i.e. sensor_range) disables the above
	     interrupt.

lux0_thresh_below_value
	RW - LO level threshold value. All results below the value
	     trigs an interrupt. 0 disables the below interrupt.

lux0_calibscale
	RW - calibration value. Set to neutral value by default.
	     Output results are multiplied with calibscale / calibscale_default
	     value.

lux0_calibscale_default
	RO - neutral calibration value

prox0_raw
	RO - measured proximity value
	     sysfs_notify called when threshold interrupt occurs

prox0_sensor_range
	RO - prox0_raw max value

prox0_raw_en
	RW - enable / disable proximity - uses counting logic
	     1 enables the proximity
	     0 disables the proximity

prox0_thresh_above_count
	RW - number of proximity interrupts needed before triggering the event

prox0_rate_above
	RW - Measurement rate (in Hz) when the level is above threshold
	     i.e. when proximity on has been reported.

prox0_rate_below
	RW - Measurement rate (in Hz) when the level is below threshold
	     i.e. when proximity off has been reported.

prox0_rate_avail
	RO - Supported proximity measurement rates in Hz

prox0_thresh_above0_value
	RW - threshold level which trigs proximity events.
	     Filtered by persistence filter (prox0_thresh_above_count)

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