Light Sensor: Difference between revisions

From OLPC
Jump to navigation Jump to search
(Created page with '{{draft}} A light sensor is built into the XO-1.75. XO-1.75 B1 has a restricted form of the feature, in that the wireless activity indicator is affected by the sensor, and any …')
 
No edit summary
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<noinclude>[[Category:Hardware]][[Category:XO-1.75]][[Category:XO-4]]
{{draft}}
</noinclude>
A light sensor is built into the XO-4 and XO-1.75. It measures the amount of light reaching the laptop from outside.


The sensor is next to the [[Storage_Indicator|storage indicator]]. Any use of the wireless activity indicator or the panel backlight affects the readings. The storage indicator is turned off briefly during each sample capture.
A light sensor is built into the XO-1.75.


The sensor is managed by the embedded controller, and is averaged and updated at a rate that depends on the brightness of the light. Reading the averaged value can be done up to 213 times per second, but there is no great advantage to reading that quickly.
XO-1.75 B1 has a restricted form of the feature, in that the wireless activity indicator is affected by the sensor, and any future use of the storage indicator will affect the sensor.


== Testing ==
XO-1.75 A3 has a restricted form of the feature, in that the sensor is affected by the battery and power LED.


In Open Firmware at the [[Ok]] prompt, type
The sensor is managed by the embedded controller, and is averaged and updated roughly every two seconds.
ok als@ .d (cr d# 200 ms many
and press enter. The sensor readings will be displayed continuously, until you press a key.


A reading near 80 means the laptop is not outdoors, or it is a cloudy day.
== Testing ==


A reading near 40 means the laptop is in full sun.
In OpenFirmware at the [[Ok]] prompt, type ''als@ .d (cr d# 200 ms many'' and press enter.


== Programming ==
== Programming ==


* your program must read /sys/devices/platform/olpc-ols.0/power_state and parse the result as an integer,
The OLS kernel driver makes readings available two ways. All sysfs nodes mentioned here are under /sys/devices/platform/olpc-ols.0/.

* your program should avoid reading ''power_state'' at a rate more than the sample rate the sensor is configured for, because this consumes extra power by making the CPU and the EC more busy,
* Brightness/Darkness state can be reported to user programs via a virtual switch input device. The name of the device is "OLPC OLS notify". The "low_lim" and "high_lim" sysfs nodes determine the bright and dark hysteresis points for this "switch". When OLS readings go lower than "low_lim", the "switch" closes. When the light goes away, causing readings to go higher than "high_lim", the "switch" opens.

* The current OLS reading is reported by the "level" sysfs node. Polling this node will give a stream of integer values, with lower values for brighter light. The readings returned are the actual time taken, in milliseconds, for the reverse-biased diode to discharge (see below). Readings may take many seconds when there is very little light. Readings are rate limited to no more than two per second. It's advantageous to limit the amount of time spent reading the light sensor, because time spent reading is time during which the storage LED can't blink (since it interferes with the reading). To keep readings short normally, but allow for full use of the sensor on demand, the longest reading the sensor driver will take is the maximum of "high_lim" and "ceiling". "high_lim" is the high hysteresis limit, currently set by powerd to 80, and "ceiling" is set by default to 0. Therefore, by default the highest reading returned by "level" will be 80 (actually, 81). If you want longer readings, e.g., if TurtleArt wants to get the full range of readings possible, TA needs to write a value to "ceiling". The absolute maximum value that can be written is 10000. Dark room readings are something like 5000.

The "power_state" sysfs node is identical to "level", and is deprecated.


== Internals ==
== Internals ==


The sensor is a reverse biased LED. The EC charges the LED as if it is a capacitor, and then times how long it takes to discharge. The discharge time is mostly related to the ambient light, and slightly related to operating temperature of the embedded controller.
The sensor is a reverse biased LED. The EC charges the LED as if it is a capacitor, and then times how long it takes to discharge. The discharge time is mostly related to the ambient light, and slightly related to operating temperature of the embedded controller.

The LED can be forward biased in production line testing. For example;

ok 57 ec-cmd

The LED will glow red, and as it is next to a green LED the light may combine to form orange.

To turn off the LED;

ok 58 ec-cmd

To stop the test;

ok 5b ec-cmd

These commands may also be issued from Linux; here is a compound command to set the red LED flashing;

while true; do
echo 0x57:0 > /sys/kernel/debug/olpc-ec/generic
sleep 0.5
echo 0x58:0 > /sys/kernel/debug/olpc-ec/generic
sleep 0.5
done

== XO-4 and XO-1.75 C1 Restriction ==

The sensor is adjacent to the storage indicator. The EC disables the storage indicator while taking a sample. The wireless indicator, if it is used, and the screen backlight, will affect the sample.


== XO-1.75 B1 Restriction ==
== XO-1.75 B1 Restriction ==


The sensor is adjacent to the wireless indicator. The EC disables the wireless indicator while taking a sample. The storage indicator, if it is used, may affect the sample.
The sensor is adjacent to the wireless indicator. The EC disables the wireless indicator while taking a sample. The storage indicator, if it is used, and the screen backlight, may affect the sample.


== XO-1.75 A3 Restriction ==
== XO-1.75 A3 Restriction ==


The sensor is adjacent to the battery indicator, and as a result generates distorted samples when the laptop is connected to a DC power cable.
The sensor is adjacent to the battery indicator, and as a result generates distorted samples when the laptop is connected to a DC power cable.

== See also ==

* [[XO_1.75_HOST_to_EC_Protocol#1.75_Command.2FResponse_List|Command response list for host CPU to firmware]] has several commands associated with the sensor; search for OLS.


== References ==
== References ==


* (yet to be released) [http://dev.laptop.org/git/projects/runin/tree/runin-light-sensor runin-light-sensor] script for testing data stream from sensor,
* [http://dev.laptop.org/git/projects/runin/tree/runin-light-sensor runin-light-sensor] script for testing data stream from sensor,
* [http://dev.laptop.org/git/olpc-kernel/commit/?h=arm-3.0&id=389a4492d0e7ccbff0f66870a85b3723304721d6 kernel implementation],
* [http://dev.laptop.org/git/olpc-kernel/commit/?h=arm-3.0&id=389a4492d0e7ccbff0f66870a85b3723304721d6 kernel implementation] first included in os40,
* [http://dev.laptop.org/git/users/rsmith/ec-1.75/tree/ols.c embedded controller implementation]
* [http://dev.laptop.org/git/users/rsmith/ec-1.75/tree/ols.c embedded controller implementation],
* [http://tracker.coreboot.org/trac/openfirmware/browser/dev/olpc/kb3700/eccmds.fth#L79 OpenFirmware implementation]
* [http://tracker.coreboot.org/trac/openfirmware/browser/dev/olpc/kb3700/eccmds.fth#L79 Open Firmware implementation].

Latest revision as of 22:45, 5 May 2016


A light sensor is built into the XO-4 and XO-1.75. It measures the amount of light reaching the laptop from outside.

The sensor is next to the storage indicator. Any use of the wireless activity indicator or the panel backlight affects the readings. The storage indicator is turned off briefly during each sample capture.

The sensor is managed by the embedded controller, and is averaged and updated at a rate that depends on the brightness of the light. Reading the averaged value can be done up to 213 times per second, but there is no great advantage to reading that quickly.

Testing

In Open Firmware at the Ok prompt, type

ok als@ .d (cr  d# 200 ms  many

and press enter. The sensor readings will be displayed continuously, until you press a key.

A reading near 80 means the laptop is not outdoors, or it is a cloudy day.

A reading near 40 means the laptop is in full sun.

Programming

The OLS kernel driver makes readings available two ways. All sysfs nodes mentioned here are under /sys/devices/platform/olpc-ols.0/.

  • Brightness/Darkness state can be reported to user programs via a virtual switch input device. The name of the device is "OLPC OLS notify". The "low_lim" and "high_lim" sysfs nodes determine the bright and dark hysteresis points for this "switch". When OLS readings go lower than "low_lim", the "switch" closes. When the light goes away, causing readings to go higher than "high_lim", the "switch" opens.
  • The current OLS reading is reported by the "level" sysfs node. Polling this node will give a stream of integer values, with lower values for brighter light. The readings returned are the actual time taken, in milliseconds, for the reverse-biased diode to discharge (see below). Readings may take many seconds when there is very little light. Readings are rate limited to no more than two per second. It's advantageous to limit the amount of time spent reading the light sensor, because time spent reading is time during which the storage LED can't blink (since it interferes with the reading). To keep readings short normally, but allow for full use of the sensor on demand, the longest reading the sensor driver will take is the maximum of "high_lim" and "ceiling". "high_lim" is the high hysteresis limit, currently set by powerd to 80, and "ceiling" is set by default to 0. Therefore, by default the highest reading returned by "level" will be 80 (actually, 81). If you want longer readings, e.g., if TurtleArt wants to get the full range of readings possible, TA needs to write a value to "ceiling". The absolute maximum value that can be written is 10000. Dark room readings are something like 5000.

The "power_state" sysfs node is identical to "level", and is deprecated.

Internals

The sensor is a reverse biased LED. The EC charges the LED as if it is a capacitor, and then times how long it takes to discharge. The discharge time is mostly related to the ambient light, and slightly related to operating temperature of the embedded controller.

The LED can be forward biased in production line testing. For example;

ok 57 ec-cmd

The LED will glow red, and as it is next to a green LED the light may combine to form orange.

To turn off the LED;

ok 58 ec-cmd

To stop the test;

ok 5b ec-cmd

These commands may also be issued from Linux; here is a compound command to set the red LED flashing;

while true; do
   echo 0x57:0 > /sys/kernel/debug/olpc-ec/generic
   sleep 0.5
   echo 0x58:0 > /sys/kernel/debug/olpc-ec/generic
   sleep 0.5
done

XO-4 and XO-1.75 C1 Restriction

The sensor is adjacent to the storage indicator. The EC disables the storage indicator while taking a sample. The wireless indicator, if it is used, and the screen backlight, will affect the sample.

XO-1.75 B1 Restriction

The sensor is adjacent to the wireless indicator. The EC disables the wireless indicator while taking a sample. The storage indicator, if it is used, and the screen backlight, may affect the sample.

XO-1.75 A3 Restriction

The sensor is adjacent to the battery indicator, and as a result generates distorted samples when the laptop is connected to a DC power cable.

See also

References