Maemo Wiki Mirror - User contributions [en]

N900 Hardware LED

2014-01-07T09:43:14Z

90.180.214.199: /* Hardware */

==Hardware==

The [[Nokia N900|N900]] has LP5523 <ref name="lp5523-spec">http://www.national.com/pf/LP/LP5523.html</ref> <ref name="leds-lp5523-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/leds/leds-lp5523.c</ref>, which has 3 engines like LP5521 (compatible though augmented instruction set) but can drive 9 LEDs via a multiplexer which maps each LED to one of the 3 engines. A LED also can be unassigned to any engine, in which case you can control it by writing to the corresponding brightness sysnode) which handles the keyboard and notification LED. (not the [[N900 Hardware Flash Torch|flash LEDs]] and red indicator light next to those, and also not the Infrared-LED used for CIR)

The controller can be programmed via "/sys/class/i2c-adapter/i2c-2/2-0032". In that directory there are three files corresponding to the three channels: <code>engine1_mode</code>, <code>engine2_mode</code> and <code>engine3_mode</code>. Each file "stores" one of <code>run</code>, <code>load</code>, <code>disabled</code> (it seems that there is another mode "direct" but it doesn't work)(direct mode requires explicit writes to PWM, current and multiplexing registers, which may not be supported in the code...):
* <code>run</code>: The program runs
* <code>disabled</code>: The channel is disabled - not running
* <code>load</code>: In that state, there are two more files in that directory:
** engine1_LEDs is in the form "0000bgr00" (9 digits, "1" or "0"), where rgb control which LEDs should participate. The 6 "0" in the above pattern correspond to the 6 kbd white LEDs controlled by MCE via engine3, so readout of engine3_leds gives 111100011 ;-)
** engine1_load accepts a string as specified above (e.g. 9d804000427f0d7f7f007f0042000000). LP5523 has an absolute storage of 96 steps a 16bits, which can dynamically partitioned between the three engines. (Supports 32-96 steps per engine, dynamically-assigned, alas the lp5523.ko driver is braindamaged and doesn't support more than 16 instructions per engine)
After that, when the state is changed to "run", the program will be ran by the controller.

In order for the LEDs to work, the led_current of the appropriate LEDs need to be set to non-zero values. This is accomplished by writing to files LEDs:lp5523:[bgr]/led_current under the same directory. Default values from kernel module init are suitable.

Despite the line
<source lang="c">
#define LP5523_DEFAULT_CURRENT 50 /* microAmps */
</source>
suggesting different, the units in there are 0.1 mA (100 µA per step is correct). So the driver init default "50" for all LEDs is 5 mA, and mce seems to set current to 0.2 mA (value 2 in the led_current sysnode) for B and G, and either to 0.2 mA or 0.8 mA for R. Probably settings as high as 100 for 10 mA are safe for the RGB LED, higher values might destroy the LED. (yes, correct, the RGB could be damaged from heat if set to more than 10 mA on all 3 LEDs)

''BEWARE!
register addr 0x3B: GPO
LP5523 has one General Purpose Output pin (GPO).
Status of the pin can be controlled with this register. Also,
'''INT pin can be configured to function as a GPO''' by setting
the bit INT_CONF. When INT is configured to function as
a GPO, '''output level is defined by the VDD voltage'''.
3B — Bit [2] INT_CONF
0 = INT pin is set to function as an interrupt pin (default).
1 = INT pin is configured to function as a GPO.

INT is routed directly to a SOC GPIO that is not designed to take voltages >1.8V ! So setting 0x3B:2 to 1 may fry your CPU
''

==Software==

== References ==

also see [[LED_patterns]] of which this page is a "fork" without cleaning the original page, so now there are two versions with almost identical but slightly complementary info

Since beginning of 2012 a datasheet for LP5523 is available from TI: http://www.ti.com/product/lp5523 Direct link: http://www.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=snvs550d&fileType=pdf

<references />

[[Category:N900 Hardware]]

LED patterns

2014-01-07T08:58:06Z

90.180.214.199: /* Low Level */

== N800 ==

The [[Nokia N800|N800]] has a single-colour (blue) LED behind the dpad.

== N810 ==

The [[Nokia N810|N810]] has an RGB LED.

== N900 ==

=== File Location ===

The software on the device that controls the LED colors is [[N900 Software MCE|MCE]].

The file defining patterns can be found in
/etc/mce/mce.ini

An application ([http://talk.maemo.org/showthread.php?t=27818 mcedit]) for modifying LED patterns was written for the N8x0, but this will not work with the [[Nokia N900|N900]] due to the new <code>mce.ini</code> format.

An app to edit LED patterns on the N900 is available in the [[extras]] repository ([http://maemo.org/downloads/product/Maemo5/led-pattern-editor Downloads Page]), [[LED Pattern Editor]]. This adds a way to edit LED patterns in the settings application.

=== Pattern Format ===

The patterns are broken down as follows:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern</tt>

(Though the LP5523 chip has 3 engines meant to control R, G, and B, the mce program exlusively uses engine3 for kbd backlight and so doesn't support pattern
definitions for engine3. mce is closed source and thus this can't be fixed in any reasonable way. If mce were open, an alternative compatible format was possible:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern;Engine3Pattern</tt>

where LEDsToMap was something like "000012300" to map the particular LED to either none, or Engine1..3 respectively.

We could also fix mce to allow pattern definitions of arbitrary length up to the max RAM available, which is 96 commands with all RAM allocated to one engine - this would need a patch to support doing this in lp5523.ko driver as well.
)

==== Priority ====

0-255, 0 is highest, 255 is lowest.

Since currently only a single pattern at a time can be displayed, this is used to assign importance to the LED patterns. Although only a single LED pattern can be displayed at any time, multiple patterns may be active, the pattern with the highest priority being displayed.

A common example of this is where the N900 is on charge, the battery is full (starting PatternBatteryFull with a priority of 40), and an SMS message is received (PatternCommunicationSMS with a priority of 30). On receipt of the SMS, the LED begins to display the flashing blue led of an SMS. Once that SMS has been dismissed, the green LED of the full battery notification is again displayed.

==== ScreenOn ====

* 0: only show pattern when the display is off
* 1: show pattern even when the display is on
* 2: only show pattern when the display is off, including acting dead
* 3: show pattern even when the display is on, including acting dead
* 4: only show pattern if the display is off, or if in acting dead
* 5: always show pattern, even if LED disabled

==== TimeOut ====

This is the time-out of the LED pattern in seconds. 0 for infinite, i.e. until the notification is dismissed.

If this is set to 20, the pattern will display for 20 seconds, and then stop.

==== LEDsToMap ====

There are two engines that can be used to make custom LED patterns.<ref name="engines">Actually there are three, but the third engine is used exclusively for the keyboard LED.</ref>

r, g, or b maps the corresponding colour channel to Engine 1.

R, G, or B maps the corresponding colour channel to Engine 2.

For example, "rG" maps the red channel to Engine 1, and the green channel to Engine 2.

You should avoid mapping the same channel to both engines, for example "rR", "gG" or "bB" - it's not supported by the hardware, makes no sense anyway, and therefore probably never has been tested.

==== Engine Pattern ====

This is a series of text that describes the speed and intensity of changes in the LED(s) being managed by that particular engine. See below for a breakdown of the patterns. Each can be at most 16 commands long.

=== Lysti Format Engine Patterns and Commands ===

The LED patterns are of the form
:<tt>9d8040007f007f0040ff7f007f000000</tt>

Breaking this down for ease of reading we get a list of 8 commands, each of which is four characters long. There may be up to 16 commands for a pattern (kernel driver limitation, the hardware could manage up to 96)
:<tt>9d80 4000 7f00 7f00 40ff 7f00 7f00 0000</tt>

==== 9d80 - Refresh Engine Multiplexer ====

This is to be used as the first command of every pattern. If this is excluded from the pattern, the led won't flash. (actually this command loads the first [and only] entry of a predefined [by kernel driver] multiplexer table in chip's RAM to the multiplexer register)

==== 40xx - Set channel brightness ====

Where xx are two hexadecimal digits, e.g. 00 (for a brightness of 0) or ff (for a brightness of 255).

==== xxyy - Adjust channel brightness ====

Increment or decrement the channel brightness over a period of time (xx) and a number of steps (yy).

Where xx and yy are hexadecimal digits

xx - Time (per step?)

yy - Number of steps

The following rules apply to these:
* If xx is even, the steps are increment steps and brightness will increase.
* If xx is odd, the steps are decrement steps and brightness will decrease.
* If xx is between 02 and 3f, a short step time is used (granularity 0.49ms)
* If xx is between 42 and 7f, a long step time is used (granularity 15.6ms)
* yy can be any value between 00 and ff (0 to 255)
* Pauses can be achieved by using 00 steps, e.g. 7f00 where, where the 7f is how long each step takes and 00 is how many increment steps to take.

The mce.ini instructions (/etc/mce/mce.ini) also state that
:Two consecutive increment/decrement sequences are needed to cover the entire range from 0-255
However I believe this is a throwback to the older patterns, and the full range of 00 to ff is available in a single step for the number of steps, since whether these are increment or decrement steps are now handled through use of even or odd xx values.

==== 0000 - Jump to start ====

Jump to the start of the pattern for this channel. You will see this at the end of most repeating patterns.

This command may not actually be needed to make the pattern repeat. If this is removed, the pattern will repeat anyway, although it's useful to have it there as an explicit command to repeat for clarity. If you wanted a pattern to run once and then terminate you would use the c000 command.

==== A000 .. BFFF - Branch (decrement and branch if non zero) ====

101<llllll><sssssss> : 16bit

llllll : 6bit; Loop count, 0=infinite loop, or max 63 loops

sssssss : 7 bit; Step number; Value to store to PC (0-95 actual progspace of LP5523 of 96 16bit commands. [Unclear if that's absolute address, or probably offset relative to start of program space assigned to the particular engine])

You can build MUCH SMARTER loops with this! ;-D

==== c000 - End pattern execution ====

(also d000 = with hw INT; c800/d800 = with PC reset. INT might serve to signal end-of-pattern to main CPU ->*)

The pattern is terminated without repeating.

''the following is about mce, not about how LP5523 chip works''

It is important to note here that although that pattern has stopped, it is still active *) until the Timeout time has passed. As a consequence of this any higher priority patterns (patterns with a lower priority value, since 0 is the highest and 255 is the lowest) will not be displayed until the pattern has fully expired. In the case that the timeout is 0, it will not display until the notification is dismissed.

==== Sending and receiving engine triggers ====

Further complexity in patterns can be added through use of triggers. This is especially useful if we want to synchronise the two engines in time, for example to wait until the LED has turned red before turning it immediately to green. Rather than waste time with steps doing nothing, we can simply wait for a trigger to be received from the other engine.

The following pattern does exactly that:
:<tt>PatternTest=29;1;0;rG;9d80''4000''08ff''e004''4000''c000'';9d80''e080''40ff''c000''</tt>

===== e002, e004, e008 - Send engine trigger =====

e002 - Send trigger to engine 1

e004 - Send trigger to engine 2

e008 - Send trigger to engine 3 (used by keyboard backlight)

A signal is sent from the current engine to signal another engine.

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function (unless you stop mce, so it doesn't mess with LP5523 anymore - see below).

===== e080, e100, e200 - Wait for engine trigger =====

e080 - Wait for trigger from engine 1

e100 - Wait for trigger from engine 2

e200 - Wait for trigger from engine 3 (used by keyboard backlight)

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function.

...and there's more. Engine can actually do sub/add arithmetics, branches, and select which leds it controls.

Pavel Machek created a simple compiler, it is at https://gitorious.org/tui/tui/source/5b3f5cacf8e208d3ea50d6066e549940d85e55be:maemo/notcc.py , and it can use more features of the chip than described here.

=== Default LED Patterns for Nokia N900 ===

PatternError=0;5;0;r;9d8040007f007f0040ff7f007f000000;9d800000
PatternDeviceOn=254;0;0;rgb;9d804000422043207f100000;9d800000
PatternDeviceSoftOff=253;0;0;rg;9d804000423f433f7f100000;9d800000
PatternPowerOn=9;3;0;rgb;9d80400042ff02ffc000;9d800000
PatternPowerOff=10;3;0;rgb;9d80400001ff43ff7f007f00c000;9d800000
PatternCommunicationCall=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationIM=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationSMS=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationEmail=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommonNotification=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternWebcamActive=20;1;0;r;9d80400004ffc0000000;9d800000
PatternBatteryCharging=50;4;0;rg;9d804000427f0d7f7f007f0042000000;9d800000
PatternBatteryFull=40;4;0;g;9d80407f0000;9d800000

=== Community-Made Patterns ===
''Please note that these patterns should each be on one line.''
''They can also be used for any notification by choosing the appropriately named "Pattern... for the start of the line.''

A traffic-light battery charging pattern, courtesy of [http://talk.maemo.org/showthread.php?p=512430#post512430 blue_led]
PatternBatteryCharging=50;4;0;Rg;9d80407f7f00e0047f0040007f007f007f00407f7f00e0047f007f000000;9d804000e080407fe0800000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=499305#post499305 mihapodb]. This pattern cuts quickly between blue and red.
PatternCommunicationEmail=30;1;0;rB;9d8040ff7f00e00440007f000000;9d80e08040ff7f0040000000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=540959#post540959 villo]. This pattern fades between red and blue.
PatternCommunicationEmail=30;1;0;rB;9d8004ff05ffe004e1000000;9d80e08004ff05ffe0020000

Cehteh's patterns with some comments

Slow dark glowing in cyan, never goes fully off, so you can locate the device in the dark:
PatternDeviceOn=254;0;0;gb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

Slow dark glowing in yellow, never goes fully off, so you can locate the device in the dark:
PatternBatteryCharging=50;3;0;rg;9d804001427f0d7f7f007f0042000000;9d800000

Slow dark glowing in white, never goes fully off, so you can locate the device in the dark:
PatternBatteryFull=40;3;0;rgb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

White, bright flashing (must be enabled in 'LEDPatterns=' ?):
PatternExample=42;1;30;rgb;9d8040007f007f0040ff42000000;9d800000

=== Step by step instructions ===
{{ambox
|type=notice
|text=There's a command
IroN900:~# /usr/bin/mceledpattern --help
Usage:
mceledpattern add[_vibra] <pattern_name> <pattern>
mceledpattern remove[_vibra] <pattern_name>

To replace existing pattern use add, to restore replaced pattern back to previous value use remove
Please check if it's default or came with one of my additional packages}}
* Open terminal
* Gain [[root access]]
* Make a backup (for your own convenience) from original mce.ini -file, for example:<pre>cp /etc/mce/mce.ini /etc/mce/mce.ini_old</pre>
* Open <code>/etc/mce/mce.ini</code> with a text editor (nano, vim, leafpad...)
* Search for a line:<pre>[LEDPatternLystiRX51]</pre>
* Make your changes to the lines below
* Save
* Restart mce -process. Either reboot or type in terminal:<pre>initctl stop mce; sleep 2; initctl start mce</pre>

Please note: restarting mce several times in 2 minutes will cause the system to think there is a problem with mce, and so won't start it. The initctl program will inform you of this. When it does, simply wait a while before trying again.

Alternatively, mce is started using [[dsmetool]] which monitors and reboots the device on failure.
This monitoring can be adjusted for more convenient hacking.

/etc/event.d/mce

* /usr/sbin/dsmetool -n -1 -t "/sbin/mce --force-syslog"

Replacing -t (start and restart) with -o (start once) eliminates this monitoring.

Please be aware that errors in editing these files could cause a reboot loop, which could require a reflash to stop.

=== Low Level ===
'''see also [[N900_Hardware_LED]] !'''

Alas the LP5523 driver doesn't support any of those advanced features of LP5523, and uses one of those engines for a kbd backlight ramp-up/down. 
''This could as well get done in mce by a 25ms timer that writes 40 new brightness values to the master control of kbd LEDs during 1 second.''

See [[N900_Hardware_LED]] for hardware programming details.

== References ==
Also see [[N900_Hardware_LED]]!

<references />

[[Category:N900 Hardware]]
[[Category:Power users]]

LED patterns

2014-01-07T08:56:45Z

90.180.214.199: /* Low Level */

== N800 ==

The [[Nokia N800|N800]] has a single-colour (blue) LED behind the dpad.

== N810 ==

The [[Nokia N810|N810]] has an RGB LED.

== N900 ==

=== File Location ===

The software on the device that controls the LED colors is [[N900 Software MCE|MCE]].

The file defining patterns can be found in
/etc/mce/mce.ini

An application ([http://talk.maemo.org/showthread.php?t=27818 mcedit]) for modifying LED patterns was written for the N8x0, but this will not work with the [[Nokia N900|N900]] due to the new <code>mce.ini</code> format.

An app to edit LED patterns on the N900 is available in the [[extras]] repository ([http://maemo.org/downloads/product/Maemo5/led-pattern-editor Downloads Page]), [[LED Pattern Editor]]. This adds a way to edit LED patterns in the settings application.

=== Pattern Format ===

The patterns are broken down as follows:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern</tt>

(Though the LP5523 chip has 3 engines meant to control R, G, and B, the mce program exlusively uses engine3 for kbd backlight and so doesn't support pattern
definitions for engine3. mce is closed source and thus this can't be fixed in any reasonable way. If mce were open, an alternative compatible format was possible:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern;Engine3Pattern</tt>

where LEDsToMap was something like "000012300" to map the particular LED to either none, or Engine1..3 respectively.

We could also fix mce to allow pattern definitions of arbitrary length up to the max RAM available, which is 96 commands with all RAM allocated to one engine - this would need a patch to support doing this in lp5523.ko driver as well.
)

==== Priority ====

0-255, 0 is highest, 255 is lowest.

Since currently only a single pattern at a time can be displayed, this is used to assign importance to the LED patterns. Although only a single LED pattern can be displayed at any time, multiple patterns may be active, the pattern with the highest priority being displayed.

A common example of this is where the N900 is on charge, the battery is full (starting PatternBatteryFull with a priority of 40), and an SMS message is received (PatternCommunicationSMS with a priority of 30). On receipt of the SMS, the LED begins to display the flashing blue led of an SMS. Once that SMS has been dismissed, the green LED of the full battery notification is again displayed.

==== ScreenOn ====

* 0: only show pattern when the display is off
* 1: show pattern even when the display is on
* 2: only show pattern when the display is off, including acting dead
* 3: show pattern even when the display is on, including acting dead
* 4: only show pattern if the display is off, or if in acting dead
* 5: always show pattern, even if LED disabled

==== TimeOut ====

This is the time-out of the LED pattern in seconds. 0 for infinite, i.e. until the notification is dismissed.

If this is set to 20, the pattern will display for 20 seconds, and then stop.

==== LEDsToMap ====

There are two engines that can be used to make custom LED patterns.<ref name="engines">Actually there are three, but the third engine is used exclusively for the keyboard LED.</ref>

r, g, or b maps the corresponding colour channel to Engine 1.

R, G, or B maps the corresponding colour channel to Engine 2.

For example, "rG" maps the red channel to Engine 1, and the green channel to Engine 2.

You should avoid mapping the same channel to both engines, for example "rR", "gG" or "bB" - it's not supported by the hardware, makes no sense anyway, and therefore probably never has been tested.

==== Engine Pattern ====

This is a series of text that describes the speed and intensity of changes in the LED(s) being managed by that particular engine. See below for a breakdown of the patterns. Each can be at most 16 commands long.

=== Lysti Format Engine Patterns and Commands ===

The LED patterns are of the form
:<tt>9d8040007f007f0040ff7f007f000000</tt>

Breaking this down for ease of reading we get a list of 8 commands, each of which is four characters long. There may be up to 16 commands for a pattern (kernel driver limitation, the hardware could manage up to 96)
:<tt>9d80 4000 7f00 7f00 40ff 7f00 7f00 0000</tt>

==== 9d80 - Refresh Engine Multiplexer ====

This is to be used as the first command of every pattern. If this is excluded from the pattern, the led won't flash. (actually this command loads the first [and only] entry of a predefined [by kernel driver] multiplexer table in chip's RAM to the multiplexer register)

==== 40xx - Set channel brightness ====

Where xx are two hexadecimal digits, e.g. 00 (for a brightness of 0) or ff (for a brightness of 255).

==== xxyy - Adjust channel brightness ====

Increment or decrement the channel brightness over a period of time (xx) and a number of steps (yy).

Where xx and yy are hexadecimal digits

xx - Time (per step?)

yy - Number of steps

The following rules apply to these:
* If xx is even, the steps are increment steps and brightness will increase.
* If xx is odd, the steps are decrement steps and brightness will decrease.
* If xx is between 02 and 3f, a short step time is used (granularity 0.49ms)
* If xx is between 42 and 7f, a long step time is used (granularity 15.6ms)
* yy can be any value between 00 and ff (0 to 255)
* Pauses can be achieved by using 00 steps, e.g. 7f00 where, where the 7f is how long each step takes and 00 is how many increment steps to take.

The mce.ini instructions (/etc/mce/mce.ini) also state that
:Two consecutive increment/decrement sequences are needed to cover the entire range from 0-255
However I believe this is a throwback to the older patterns, and the full range of 00 to ff is available in a single step for the number of steps, since whether these are increment or decrement steps are now handled through use of even or odd xx values.

==== 0000 - Jump to start ====

Jump to the start of the pattern for this channel. You will see this at the end of most repeating patterns.

This command may not actually be needed to make the pattern repeat. If this is removed, the pattern will repeat anyway, although it's useful to have it there as an explicit command to repeat for clarity. If you wanted a pattern to run once and then terminate you would use the c000 command.

==== A000 .. BFFF - Branch (decrement and branch if non zero) ====

101<llllll><sssssss> : 16bit

llllll : 6bit; Loop count, 0=infinite loop, or max 63 loops

sssssss : 7 bit; Step number; Value to store to PC (0-95 actual progspace of LP5523 of 96 16bit commands. [Unclear if that's absolute address, or probably offset relative to start of program space assigned to the particular engine])

You can build MUCH SMARTER loops with this! ;-D

==== c000 - End pattern execution ====

(also d000 = with hw INT; c800/d800 = with PC reset. INT might serve to signal end-of-pattern to main CPU ->*)

The pattern is terminated without repeating.

''the following is about mce, not about how LP5523 chip works''

It is important to note here that although that pattern has stopped, it is still active *) until the Timeout time has passed. As a consequence of this any higher priority patterns (patterns with a lower priority value, since 0 is the highest and 255 is the lowest) will not be displayed until the pattern has fully expired. In the case that the timeout is 0, it will not display until the notification is dismissed.

==== Sending and receiving engine triggers ====

Further complexity in patterns can be added through use of triggers. This is especially useful if we want to synchronise the two engines in time, for example to wait until the LED has turned red before turning it immediately to green. Rather than waste time with steps doing nothing, we can simply wait for a trigger to be received from the other engine.

The following pattern does exactly that:
:<tt>PatternTest=29;1;0;rG;9d80''4000''08ff''e004''4000''c000'';9d80''e080''40ff''c000''</tt>

===== e002, e004, e008 - Send engine trigger =====

e002 - Send trigger to engine 1

e004 - Send trigger to engine 2

e008 - Send trigger to engine 3 (used by keyboard backlight)

A signal is sent from the current engine to signal another engine.

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function (unless you stop mce, so it doesn't mess with LP5523 anymore - see below).

===== e080, e100, e200 - Wait for engine trigger =====

e080 - Wait for trigger from engine 1

e100 - Wait for trigger from engine 2

e200 - Wait for trigger from engine 3 (used by keyboard backlight)

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function.

...and there's more. Engine can actually do sub/add arithmetics, branches, and select which leds it controls.

Pavel Machek created a simple compiler, it is at https://gitorious.org/tui/tui/source/5b3f5cacf8e208d3ea50d6066e549940d85e55be:maemo/notcc.py , and it can use more features of the chip than described here.

=== Default LED Patterns for Nokia N900 ===

PatternError=0;5;0;r;9d8040007f007f0040ff7f007f000000;9d800000
PatternDeviceOn=254;0;0;rgb;9d804000422043207f100000;9d800000
PatternDeviceSoftOff=253;0;0;rg;9d804000423f433f7f100000;9d800000
PatternPowerOn=9;3;0;rgb;9d80400042ff02ffc000;9d800000
PatternPowerOff=10;3;0;rgb;9d80400001ff43ff7f007f00c000;9d800000
PatternCommunicationCall=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationIM=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationSMS=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationEmail=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommonNotification=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternWebcamActive=20;1;0;r;9d80400004ffc0000000;9d800000
PatternBatteryCharging=50;4;0;rg;9d804000427f0d7f7f007f0042000000;9d800000
PatternBatteryFull=40;4;0;g;9d80407f0000;9d800000

=== Community-Made Patterns ===
''Please note that these patterns should each be on one line.''
''They can also be used for any notification by choosing the appropriately named "Pattern... for the start of the line.''

A traffic-light battery charging pattern, courtesy of [http://talk.maemo.org/showthread.php?p=512430#post512430 blue_led]
PatternBatteryCharging=50;4;0;Rg;9d80407f7f00e0047f0040007f007f007f00407f7f00e0047f007f000000;9d804000e080407fe0800000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=499305#post499305 mihapodb]. This pattern cuts quickly between blue and red.
PatternCommunicationEmail=30;1;0;rB;9d8040ff7f00e00440007f000000;9d80e08040ff7f0040000000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=540959#post540959 villo]. This pattern fades between red and blue.
PatternCommunicationEmail=30;1;0;rB;9d8004ff05ffe004e1000000;9d80e08004ff05ffe0020000

Cehteh's patterns with some comments

Slow dark glowing in cyan, never goes fully off, so you can locate the device in the dark:
PatternDeviceOn=254;0;0;gb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

Slow dark glowing in yellow, never goes fully off, so you can locate the device in the dark:
PatternBatteryCharging=50;3;0;rg;9d804001427f0d7f7f007f0042000000;9d800000

Slow dark glowing in white, never goes fully off, so you can locate the device in the dark:
PatternBatteryFull=40;3;0;rgb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

White, bright flashing (must be enabled in 'LEDPatterns=' ?):
PatternExample=42;1;30;rgb;9d8040007f007f0040ff42000000;9d800000

=== Step by step instructions ===
{{ambox
|type=notice
|text=There's a command
IroN900:~# /usr/bin/mceledpattern --help
Usage:
mceledpattern add[_vibra] <pattern_name> <pattern>
mceledpattern remove[_vibra] <pattern_name>

To replace existing pattern use add, to restore replaced pattern back to previous value use remove
Please check if it's default or came with one of my additional packages}}
* Open terminal
* Gain [[root access]]
* Make a backup (for your own convenience) from original mce.ini -file, for example:<pre>cp /etc/mce/mce.ini /etc/mce/mce.ini_old</pre>
* Open <code>/etc/mce/mce.ini</code> with a text editor (nano, vim, leafpad...)
* Search for a line:<pre>[LEDPatternLystiRX51]</pre>
* Make your changes to the lines below
* Save
* Restart mce -process. Either reboot or type in terminal:<pre>initctl stop mce; sleep 2; initctl start mce</pre>

Please note: restarting mce several times in 2 minutes will cause the system to think there is a problem with mce, and so won't start it. The initctl program will inform you of this. When it does, simply wait a while before trying again.

Alternatively, mce is started using [[dsmetool]] which monitors and reboots the device on failure.
This monitoring can be adjusted for more convenient hacking.

/etc/event.d/mce

* /usr/sbin/dsmetool -n -1 -t "/sbin/mce --force-syslog"

Replacing -t (start and restart) with -o (start once) eliminates this monitoring.

Please be aware that errors in editing these files could cause a reboot loop, which could require a reflash to stop.

=== Low Level ===
'''see also [[N900_Hardware_LED]] !'''

Alas the LP5523 driver doesn't support any of those advanced features of LP5523, and uses one of those engines for a kbd backlight ramp-up/down. 
''This could as well get done in mce by a 25ms timer that writes 40 new brightness values to the master control of kbd LEDs during 1 second.''

See [[N900_Hardware_LED]] for hardware programming details.

** engine1_leds is in the form "0000rgb00" (9 digits, "1" or "0"), where rgb control which leds should participate. The 6 "0" in the above pattern correspond to the 6 kbd white leds controlled by mce via engine3, so readout of engine3_leds gives 111100011 ;-)
** engine1_load accepts a string as specified above (e.g. 9d804000427f0d7f7f007f0042000000). Though LP5523 has an absolute storage of 96 steps a 16bits, which can dynamically partitioned between the three engines, the driver limits this to a fixed 16 words a 16bit per engine

After that, when the state is changed to "run", the program will be run by the controller.

In order for the leds to work, the led_current of the appropriate leds need to be set to non-zero values. This is accomplished by writing to files leds:lp5523:[bgr]/'''led_current''' under the same directory. '''Don't mess with''' the default settings here that come with driver init, they are suitable and changing to higher values may and for certain values '''will kill your LEDS'''!.

== References ==
Also see [[N900_Hardware_LED]]!

<references />

[[Category:N900 Hardware]]
[[Category:Power users]]

LED patterns

2014-01-06T13:40:13Z

90.180.214.199: /* e080, e100, e200 - Wait for engine trigger */

== N800 ==

The [[Nokia N800|N800]] has a single-colour (blue) LED behind the dpad.

== N810 ==

The [[Nokia N810|N810]] has an RGB LED.

== N900 ==

=== File Location ===

The software on the device that controls the LED colors is [[N900 Software MCE|MCE]].

The file defining patterns can be found in
/etc/mce/mce.ini

An application ([http://talk.maemo.org/showthread.php?t=27818 mcedit]) for modifying LED patterns was written for the N8x0, but this will not work with the [[Nokia N900|N900]] due to the new <code>mce.ini</code> format.

An app to edit LED patterns on the N900 is available in the [[extras]] repository ([http://maemo.org/downloads/product/Maemo5/led-pattern-editor Downloads Page]), [[LED Pattern Editor]]. This adds a way to edit LED patterns in the settings application.

=== Pattern Format ===

The patterns are broken down as follows:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern</tt>

(Though the LP5523 chip has 3 engines meant to control R, G, and B, the mce program exlusively uses engine3 for kbd backlight and so doesn't support pattern
definitions for engine3. mce is closed source and thus this can't be fixed in any reasonable way. If mce were open, an alternative compatible format was possible:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern;Engine3Pattern</tt>

where LEDsToMap was something like "000012300" to map the particular LED to either none, or Engine1..3 respectively.

We could also fix mce to allow pattern definitions of arbitrary length up to the max RAM available, which is 96 commands with all RAM allocated to one engine - this would need a patch to support doing this in lp5523.ko driver as well.
)

==== Priority ====

0-255, 0 is highest, 255 is lowest.

Since currently only a single pattern at a time can be displayed, this is used to assign importance to the LED patterns. Although only a single LED pattern can be displayed at any time, multiple patterns may be active, the pattern with the highest priority being displayed.

A common example of this is where the N900 is on charge, the battery is full (starting PatternBatteryFull with a priority of 40), and an SMS message is received (PatternCommunicationSMS with a priority of 30). On receipt of the SMS, the LED begins to display the flashing blue led of an SMS. Once that SMS has been dismissed, the green LED of the full battery notification is again displayed.

==== ScreenOn ====

* 0: only show pattern when the display is off
* 1: show pattern even when the display is on
* 2: only show pattern when the display is off, including acting dead
* 3: show pattern even when the display is on, including acting dead
* 4: only show pattern if the display is off, or if in acting dead
* 5: always show pattern, even if LED disabled

==== TimeOut ====

This is the time-out of the LED pattern in seconds. 0 for infinite, i.e. until the notification is dismissed.

If this is set to 20, the pattern will display for 20 seconds, and then stop.

==== LEDsToMap ====

There are two engines that can be used to make custom LED patterns.<ref name="engines">Actually there are three, but the third engine is used exclusively for the keyboard LED.</ref>

r, g, or b maps the corresponding colour channel to Engine 1.

R, G, or B maps the corresponding colour channel to Engine 2.

For example, "rG" maps the red channel to Engine 1, and the green channel to Engine 2.

You should avoid mapping the same channel to both engines, for example "rR", "gG" or "bB" - it's not supported by the hardware, makes no sense anyway, and therefore probably never has been tested.

==== Engine Pattern ====

This is a series of text that describes the speed and intensity of changes in the LED(s) being managed by that particular engine. See below for a breakdown of the patterns. Each can be at most 16 commands long.

=== Lysti Format Engine Patterns and Commands ===

The LED patterns are of the form
:<tt>9d8040007f007f0040ff7f007f000000</tt>

Breaking this down for ease of reading we get a list of 8 commands, each of which is four characters long. There may be up to 16 commands for a pattern (kernel driver limitation, the hardware could manage up to 96)
:<tt>9d80 4000 7f00 7f00 40ff 7f00 7f00 0000</tt>

==== 9d80 - Refresh Engine Multiplexer ====

This is to be used as the first command of every pattern. If this is excluded from the pattern, the led won't flash. (actually this command loads the first [and only] entry of a predefined [by kernel driver] multiplexer table in chip's RAM to the multiplexer register)

==== 40xx - Set channel brightness ====

Where xx are two hexadecimal digits, e.g. 00 (for a brightness of 0) or ff (for a brightness of 255).

==== xxyy - Adjust channel brightness ====

Increment or decrement the channel brightness over a period of time (xx) and a number of steps (yy).

Where xx and yy are hexadecimal digits

xx - Time (per step?)

yy - Number of steps

The following rules apply to these:
* If xx is even, the steps are increment steps and brightness will increase.
* If xx is odd, the steps are decrement steps and brightness will decrease.
* If xx is between 02 and 3f, a short step time is used (granularity 0.49ms)
* If xx is between 42 and 7f, a long step time is used (granularity 15.6ms)
* yy can be any value between 00 and ff (0 to 255)
* Pauses can be achieved by using 00 steps, e.g. 7f00 where, where the 7f is how long each step takes and 00 is how many increment steps to take.

The mce.ini instructions (/etc/mce/mce.ini) also state that
:Two consecutive increment/decrement sequences are needed to cover the entire range from 0-255
However I believe this is a throwback to the older patterns, and the full range of 00 to ff is available in a single step for the number of steps, since whether these are increment or decrement steps are now handled through use of even or odd xx values.

==== 0000 - Jump to start ====

Jump to the start of the pattern for this channel. You will see this at the end of most repeating patterns.

This command may not actually be needed to make the pattern repeat. If this is removed, the pattern will repeat anyway, although it's useful to have it there as an explicit command to repeat for clarity. If you wanted a pattern to run once and then terminate you would use the c000 command.

==== A000 .. BFFF - Branch (decrement and branch if non zero) ====

101<llllll><sssssss> : 16bit

llllll : 6bit; Loop count, 0=infinite loop, or max 63 loops

sssssss : 7 bit; Step number; Value to store to PC (0-95 actual progspace of LP5523 of 96 16bit commands. [Unclear if that's absolute address, or probably offset relative to start of program space assigned to the particular engine])

You can build MUCH SMARTER loops with this! ;-D

==== c000 - End pattern execution ====

(also d000 = with hw INT; c800/d800 = with PC reset. INT might serve to signal end-of-pattern to main CPU ->*)

The pattern is terminated without repeating.

''the following is about mce, not about how LP5523 chip works''

It is important to note here that although that pattern has stopped, it is still active *) until the Timeout time has passed. As a consequence of this any higher priority patterns (patterns with a lower priority value, since 0 is the highest and 255 is the lowest) will not be displayed until the pattern has fully expired. In the case that the timeout is 0, it will not display until the notification is dismissed.

==== Sending and receiving engine triggers ====

Further complexity in patterns can be added through use of triggers. This is especially useful if we want to synchronise the two engines in time, for example to wait until the LED has turned red before turning it immediately to green. Rather than waste time with steps doing nothing, we can simply wait for a trigger to be received from the other engine.

The following pattern does exactly that:
:<tt>PatternTest=29;1;0;rG;9d80''4000''08ff''e004''4000''c000'';9d80''e080''40ff''c000''</tt>

===== e002, e004, e008 - Send engine trigger =====

e002 - Send trigger to engine 1

e004 - Send trigger to engine 2

e008 - Send trigger to engine 3 (used by keyboard backlight)

A signal is sent from the current engine to signal another engine.

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function (unless you stop mce, so it doesn't mess with LP5523 anymore - see below).

===== e080, e100, e200 - Wait for engine trigger =====

e080 - Wait for trigger from engine 1

e100 - Wait for trigger from engine 2

e200 - Wait for trigger from engine 3 (used by keyboard backlight)

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function.

...and there's more. Engine can actually do sub/add arithmetics, branches, and select which leds it controls.

Pavel Machek created a simple compiler, it is at https://gitorious.org/tui/tui/source/5b3f5cacf8e208d3ea50d6066e549940d85e55be:maemo/notcc.py , and it can use more features of the chip than described here.

=== Default LED Patterns for Nokia N900 ===

PatternError=0;5;0;r;9d8040007f007f0040ff7f007f000000;9d800000
PatternDeviceOn=254;0;0;rgb;9d804000422043207f100000;9d800000
PatternDeviceSoftOff=253;0;0;rg;9d804000423f433f7f100000;9d800000
PatternPowerOn=9;3;0;rgb;9d80400042ff02ffc000;9d800000
PatternPowerOff=10;3;0;rgb;9d80400001ff43ff7f007f00c000;9d800000
PatternCommunicationCall=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationIM=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationSMS=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationEmail=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommonNotification=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternWebcamActive=20;1;0;r;9d80400004ffc0000000;9d800000
PatternBatteryCharging=50;4;0;rg;9d804000427f0d7f7f007f0042000000;9d800000
PatternBatteryFull=40;4;0;g;9d80407f0000;9d800000

=== Community-Made Patterns ===
''Please note that these patterns should each be on one line.''
''They can also be used for any notification by choosing the appropriately named "Pattern... for the start of the line.''

A traffic-light battery charging pattern, courtesy of [http://talk.maemo.org/showthread.php?p=512430#post512430 blue_led]
PatternBatteryCharging=50;4;0;Rg;9d80407f7f00e0047f0040007f007f007f00407f7f00e0047f007f000000;9d804000e080407fe0800000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=499305#post499305 mihapodb]. This pattern cuts quickly between blue and red.
PatternCommunicationEmail=30;1;0;rB;9d8040ff7f00e00440007f000000;9d80e08040ff7f0040000000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=540959#post540959 villo]. This pattern fades between red and blue.
PatternCommunicationEmail=30;1;0;rB;9d8004ff05ffe004e1000000;9d80e08004ff05ffe0020000

Cehteh's patterns with some comments

Slow dark glowing in cyan, never goes fully off, so you can locate the device in the dark:
PatternDeviceOn=254;0;0;gb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

Slow dark glowing in yellow, never goes fully off, so you can locate the device in the dark:
PatternBatteryCharging=50;3;0;rg;9d804001427f0d7f7f007f0042000000;9d800000

Slow dark glowing in white, never goes fully off, so you can locate the device in the dark:
PatternBatteryFull=40;3;0;rgb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

White, bright flashing (must be enabled in 'LEDPatterns=' ?):
PatternExample=42;1;30;rgb;9d8040007f007f0040ff42000000;9d800000

=== Step by step instructions ===
{{ambox
|type=notice
|text=There's a command
IroN900:~# /usr/bin/mceledpattern --help
Usage:
mceledpattern add[_vibra] <pattern_name> <pattern>
mceledpattern remove[_vibra] <pattern_name>

To replace existing pattern use add, to restore replaced pattern back to previous value use remove
Please check if it's default or came with one of my additional packages}}
* Open terminal
* Gain [[root access]]
* Make a backup (for your own convenience) from original mce.ini -file, for example:<pre>cp /etc/mce/mce.ini /etc/mce/mce.ini_old</pre>
* Open <code>/etc/mce/mce.ini</code> with a text editor (nano, vim, leafpad...)
* Search for a line:<pre>[LEDPatternLystiRX51]</pre>
* Make your changes to the lines below
* Save
* Restart mce -process. Either reboot or type in terminal:<pre>initctl stop mce; sleep 2; initctl start mce</pre>

Please note: restarting mce several times in 2 minutes will cause the system to think there is a problem with mce, and so won't start it. The initctl program will inform you of this. When it does, simply wait a while before trying again.

Alternatively, mce is started using [[dsmetool]] which monitors and reboots the device on failure.
This monitoring can be adjusted for more convenient hacking.

/etc/event.d/mce

* /usr/sbin/dsmetool -n -1 -t "/sbin/mce --force-syslog"

Replacing -t (start and restart) with -o (start once) eliminates this monitoring.

Please be aware that errors in editing these files could cause a reboot loop, which could require a reflash to stop.

=== Low Level ===
'''this section should get merged with [[N900_Hardware_LED]] !'''

The N8x0 had a LP5521<ref name="lp5521-spec">http://www.national.com/pf/LP/LP5521.html</ref> <ref name="lp5521-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/i2c/chips/lp5521.c</ref> programmable three channel controller LED Driver which handles the leds.
The N900 has a LP5523 <ref name="lp5523-spec">http://www.national.com/pf/LP/LP5523.html</ref> <ref name="leds-lp5523-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/leds/leds-lp5523.c</ref>, which has 3 engines like LP5521 but can drive 9 LEDs via a multiplexer. Actually the multiplexer is between the engine (CPU) and the 9 PWM blocks for the 9 LED outputs - each of those 9 PWM blocks has its own accessable registers for current and brightness, and they are exposed to sysfs. This chip also has double the RAM size for 'programs', plus 2 per-machine and one global register variable and a true set of conditional branch and arithmetic commands.

Alas the LP5523 driver doesn't support any of those advanced features of LP5523, and uses one of those engines for a kbd backlight ramp-up/down. 
''This could as well get done in mce by a 25ms timer that writes 40 new brightness values to the master control of kbd LEDs during 1 second.''

See [[N900_Hardware_LED]] for hardware programming details.

** engine1_leds is in the form "0000rgb00" (9 digits, "1" or "0"), where rgb control which leds should participate. The 6 "0" in the above pattern correspond to the 6 kbd white leds controlled by mce via engine3, so readout of engine3_leds gives 111100011 ;-)
** engine1_load accepts a string as specified above (e.g. 9d804000427f0d7f7f007f0042000000). Though LP5523 has an absolute storage of 96 steps a 16bits, which can dynamically partitioned between the three engines, the driver limits this to a fixed 16 words a 16bit per engine

After that, when the state is changed to "run", the program will be run by the controller.

In order for the leds to work, the led_current of the appropriate leds need to be set to non-zero values. This is accomplished by writing to files leds:lp5523:[bgr]/'''led_current''' under the same directory. '''Don't mess with''' the default settings here that come with driver init, they are suitable and changing to higher values may and for certain values '''will kill your LEDS'''!.

== References ==
Also see [[N900_Hardware_LED]]!

<references />

[[Category:N900 Hardware]]
[[Category:Power users]]

LED patterns

2014-01-06T13:37:55Z

90.180.214.199: /* Low Level */

== N800 ==

The [[Nokia N800|N800]] has a single-colour (blue) LED behind the dpad.

== N810 ==

The [[Nokia N810|N810]] has an RGB LED.

== N900 ==

=== File Location ===

The software on the device that controls the LED colors is [[N900 Software MCE|MCE]].

The file defining patterns can be found in
/etc/mce/mce.ini

An application ([http://talk.maemo.org/showthread.php?t=27818 mcedit]) for modifying LED patterns was written for the N8x0, but this will not work with the [[Nokia N900|N900]] due to the new <code>mce.ini</code> format.

An app to edit LED patterns on the N900 is available in the [[extras]] repository ([http://maemo.org/downloads/product/Maemo5/led-pattern-editor Downloads Page]), [[LED Pattern Editor]]. This adds a way to edit LED patterns in the settings application.

=== Pattern Format ===

The patterns are broken down as follows:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern</tt>

(Though the LP5523 chip has 3 engines meant to control R, G, and B, the mce program exlusively uses engine3 for kbd backlight and so doesn't support pattern
definitions for engine3. mce is closed source and thus this can't be fixed in any reasonable way. If mce were open, an alternative compatible format was possible:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern;Engine3Pattern</tt>

where LEDsToMap was something like "000012300" to map the particular LED to either none, or Engine1..3 respectively.

We could also fix mce to allow pattern definitions of arbitrary length up to the max RAM available, which is 96 commands with all RAM allocated to one engine - this would need a patch to support doing this in lp5523.ko driver as well.
)

==== Priority ====

0-255, 0 is highest, 255 is lowest.

Since currently only a single pattern at a time can be displayed, this is used to assign importance to the LED patterns. Although only a single LED pattern can be displayed at any time, multiple patterns may be active, the pattern with the highest priority being displayed.

A common example of this is where the N900 is on charge, the battery is full (starting PatternBatteryFull with a priority of 40), and an SMS message is received (PatternCommunicationSMS with a priority of 30). On receipt of the SMS, the LED begins to display the flashing blue led of an SMS. Once that SMS has been dismissed, the green LED of the full battery notification is again displayed.

==== ScreenOn ====

* 0: only show pattern when the display is off
* 1: show pattern even when the display is on
* 2: only show pattern when the display is off, including acting dead
* 3: show pattern even when the display is on, including acting dead
* 4: only show pattern if the display is off, or if in acting dead
* 5: always show pattern, even if LED disabled

==== TimeOut ====

This is the time-out of the LED pattern in seconds. 0 for infinite, i.e. until the notification is dismissed.

If this is set to 20, the pattern will display for 20 seconds, and then stop.

==== LEDsToMap ====

There are two engines that can be used to make custom LED patterns.<ref name="engines">Actually there are three, but the third engine is used exclusively for the keyboard LED.</ref>

r, g, or b maps the corresponding colour channel to Engine 1.

R, G, or B maps the corresponding colour channel to Engine 2.

For example, "rG" maps the red channel to Engine 1, and the green channel to Engine 2.

You should avoid mapping the same channel to both engines, for example "rR", "gG" or "bB" - it's not supported by the hardware, makes no sense anyway, and therefore probably never has been tested.

==== Engine Pattern ====

This is a series of text that describes the speed and intensity of changes in the LED(s) being managed by that particular engine. See below for a breakdown of the patterns. Each can be at most 16 commands long.

=== Lysti Format Engine Patterns and Commands ===

The LED patterns are of the form
:<tt>9d8040007f007f0040ff7f007f000000</tt>

Breaking this down for ease of reading we get a list of 8 commands, each of which is four characters long. There may be up to 16 commands for a pattern (kernel driver limitation, the hardware could manage up to 96)
:<tt>9d80 4000 7f00 7f00 40ff 7f00 7f00 0000</tt>

==== 9d80 - Refresh Engine Multiplexer ====

This is to be used as the first command of every pattern. If this is excluded from the pattern, the led won't flash. (actually this command loads the first [and only] entry of a predefined [by kernel driver] multiplexer table in chip's RAM to the multiplexer register)

==== 40xx - Set channel brightness ====

Where xx are two hexadecimal digits, e.g. 00 (for a brightness of 0) or ff (for a brightness of 255).

==== xxyy - Adjust channel brightness ====

Increment or decrement the channel brightness over a period of time (xx) and a number of steps (yy).

Where xx and yy are hexadecimal digits

xx - Time (per step?)

yy - Number of steps

The following rules apply to these:
* If xx is even, the steps are increment steps and brightness will increase.
* If xx is odd, the steps are decrement steps and brightness will decrease.
* If xx is between 02 and 3f, a short step time is used (granularity 0.49ms)
* If xx is between 42 and 7f, a long step time is used (granularity 15.6ms)
* yy can be any value between 00 and ff (0 to 255)
* Pauses can be achieved by using 00 steps, e.g. 7f00 where, where the 7f is how long each step takes and 00 is how many increment steps to take.

The mce.ini instructions (/etc/mce/mce.ini) also state that
:Two consecutive increment/decrement sequences are needed to cover the entire range from 0-255
However I believe this is a throwback to the older patterns, and the full range of 00 to ff is available in a single step for the number of steps, since whether these are increment or decrement steps are now handled through use of even or odd xx values.

==== 0000 - Jump to start ====

Jump to the start of the pattern for this channel. You will see this at the end of most repeating patterns.

This command may not actually be needed to make the pattern repeat. If this is removed, the pattern will repeat anyway, although it's useful to have it there as an explicit command to repeat for clarity. If you wanted a pattern to run once and then terminate you would use the c000 command.

==== A000 .. BFFF - Branch (decrement and branch if non zero) ====

101<llllll><sssssss> : 16bit

llllll : 6bit; Loop count, 0=infinite loop, or max 63 loops

sssssss : 7 bit; Step number; Value to store to PC (0-95 actual progspace of LP5523 of 96 16bit commands. [Unclear if that's absolute address, or probably offset relative to start of program space assigned to the particular engine])

You can build MUCH SMARTER loops with this! ;-D

==== c000 - End pattern execution ====

(also d000 = with hw INT; c800/d800 = with PC reset. INT might serve to signal end-of-pattern to main CPU ->*)

The pattern is terminated without repeating.

''the following is about mce, not about how LP5523 chip works''

It is important to note here that although that pattern has stopped, it is still active *) until the Timeout time has passed. As a consequence of this any higher priority patterns (patterns with a lower priority value, since 0 is the highest and 255 is the lowest) will not be displayed until the pattern has fully expired. In the case that the timeout is 0, it will not display until the notification is dismissed.

==== Sending and receiving engine triggers ====

Further complexity in patterns can be added through use of triggers. This is especially useful if we want to synchronise the two engines in time, for example to wait until the LED has turned red before turning it immediately to green. Rather than waste time with steps doing nothing, we can simply wait for a trigger to be received from the other engine.

The following pattern does exactly that:
:<tt>PatternTest=29;1;0;rG;9d80''4000''08ff''e004''4000''c000'';9d80''e080''40ff''c000''</tt>

===== e002, e004, e008 - Send engine trigger =====

e002 - Send trigger to engine 1

e004 - Send trigger to engine 2

e008 - Send trigger to engine 3 (used by keyboard backlight)

A signal is sent from the current engine to signal another engine.

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function (unless you stop mce, so it doesn't mess with LP5523 anymore - see below).

===== e080, e100, e200 - Wait for engine trigger =====

e080 - Wait for trigger from engine 1

e100 - Wait for trigger from engine 2

e200 - Wait for trigger from engine 3 (used by keyboard backlight)

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function.

=== Default LED Patterns for Nokia N900 ===

PatternError=0;5;0;r;9d8040007f007f0040ff7f007f000000;9d800000
PatternDeviceOn=254;0;0;rgb;9d804000422043207f100000;9d800000
PatternDeviceSoftOff=253;0;0;rg;9d804000423f433f7f100000;9d800000
PatternPowerOn=9;3;0;rgb;9d80400042ff02ffc000;9d800000
PatternPowerOff=10;3;0;rgb;9d80400001ff43ff7f007f00c000;9d800000
PatternCommunicationCall=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationIM=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationSMS=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationEmail=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommonNotification=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternWebcamActive=20;1;0;r;9d80400004ffc0000000;9d800000
PatternBatteryCharging=50;4;0;rg;9d804000427f0d7f7f007f0042000000;9d800000
PatternBatteryFull=40;4;0;g;9d80407f0000;9d800000

=== Community-Made Patterns ===
''Please note that these patterns should each be on one line.''
''They can also be used for any notification by choosing the appropriately named "Pattern... for the start of the line.''

A traffic-light battery charging pattern, courtesy of [http://talk.maemo.org/showthread.php?p=512430#post512430 blue_led]
PatternBatteryCharging=50;4;0;Rg;9d80407f7f00e0047f0040007f007f007f00407f7f00e0047f007f000000;9d804000e080407fe0800000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=499305#post499305 mihapodb]. This pattern cuts quickly between blue and red.
PatternCommunicationEmail=30;1;0;rB;9d8040ff7f00e00440007f000000;9d80e08040ff7f0040000000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=540959#post540959 villo]. This pattern fades between red and blue.
PatternCommunicationEmail=30;1;0;rB;9d8004ff05ffe004e1000000;9d80e08004ff05ffe0020000

Cehteh's patterns with some comments

Slow dark glowing in cyan, never goes fully off, so you can locate the device in the dark:
PatternDeviceOn=254;0;0;gb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

Slow dark glowing in yellow, never goes fully off, so you can locate the device in the dark:
PatternBatteryCharging=50;3;0;rg;9d804001427f0d7f7f007f0042000000;9d800000

Slow dark glowing in white, never goes fully off, so you can locate the device in the dark:
PatternBatteryFull=40;3;0;rgb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

White, bright flashing (must be enabled in 'LEDPatterns=' ?):
PatternExample=42;1;30;rgb;9d8040007f007f0040ff42000000;9d800000

=== Step by step instructions ===
{{ambox
|type=notice
|text=There's a command
IroN900:~# /usr/bin/mceledpattern --help
Usage:
mceledpattern add[_vibra] <pattern_name> <pattern>
mceledpattern remove[_vibra] <pattern_name>

To replace existing pattern use add, to restore replaced pattern back to previous value use remove
Please check if it's default or came with one of my additional packages}}
* Open terminal
* Gain [[root access]]
* Make a backup (for your own convenience) from original mce.ini -file, for example:<pre>cp /etc/mce/mce.ini /etc/mce/mce.ini_old</pre>
* Open <code>/etc/mce/mce.ini</code> with a text editor (nano, vim, leafpad...)
* Search for a line:<pre>[LEDPatternLystiRX51]</pre>
* Make your changes to the lines below
* Save
* Restart mce -process. Either reboot or type in terminal:<pre>initctl stop mce; sleep 2; initctl start mce</pre>

Please note: restarting mce several times in 2 minutes will cause the system to think there is a problem with mce, and so won't start it. The initctl program will inform you of this. When it does, simply wait a while before trying again.

Alternatively, mce is started using [[dsmetool]] which monitors and reboots the device on failure.
This monitoring can be adjusted for more convenient hacking.

/etc/event.d/mce

* /usr/sbin/dsmetool -n -1 -t "/sbin/mce --force-syslog"

Replacing -t (start and restart) with -o (start once) eliminates this monitoring.

Please be aware that errors in editing these files could cause a reboot loop, which could require a reflash to stop.

=== Low Level ===
'''this section should get merged with [[N900_Hardware_LED]] !'''

The N8x0 had a LP5521<ref name="lp5521-spec">http://www.national.com/pf/LP/LP5521.html</ref> <ref name="lp5521-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/i2c/chips/lp5521.c</ref> programmable three channel controller LED Driver which handles the leds.
The N900 has a LP5523 <ref name="lp5523-spec">http://www.national.com/pf/LP/LP5523.html</ref> <ref name="leds-lp5523-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/leds/leds-lp5523.c</ref>, which has 3 engines like LP5521 but can drive 9 LEDs via a multiplexer. Actually the multiplexer is between the engine (CPU) and the 9 PWM blocks for the 9 LED outputs - each of those 9 PWM blocks has its own accessable registers for current and brightness, and they are exposed to sysfs. This chip also has double the RAM size for 'programs', plus 2 per-machine and one global register variable and a true set of conditional branch and arithmetic commands.

Alas the LP5523 driver doesn't support any of those advanced features of LP5523, and uses one of those engines for a kbd backlight ramp-up/down. 
''This could as well get done in mce by a 25ms timer that writes 40 new brightness values to the master control of kbd LEDs during 1 second.''

See [[N900_Hardware_LED]] for hardware programming details.

** engine1_leds is in the form "0000rgb00" (9 digits, "1" or "0"), where rgb control which leds should participate. The 6 "0" in the above pattern correspond to the 6 kbd white leds controlled by mce via engine3, so readout of engine3_leds gives 111100011 ;-)
** engine1_load accepts a string as specified above (e.g. 9d804000427f0d7f7f007f0042000000). Though LP5523 has an absolute storage of 96 steps a 16bits, which can dynamically partitioned between the three engines, the driver limits this to a fixed 16 words a 16bit per engine

After that, when the state is changed to "run", the program will be run by the controller.

In order for the leds to work, the led_current of the appropriate leds need to be set to non-zero values. This is accomplished by writing to files leds:lp5523:[bgr]/'''led_current''' under the same directory. '''Don't mess with''' the default settings here that come with driver init, they are suitable and changing to higher values may and for certain values '''will kill your LEDS'''!.

== References ==
Also see [[N900_Hardware_LED]]!

<references />

[[Category:N900 Hardware]]
[[Category:Power users]]

LED patterns

2014-01-06T13:36:57Z

90.180.214.199: /* Low Level */

== N800 ==

The [[Nokia N800|N800]] has a single-colour (blue) LED behind the dpad.

== N810 ==

The [[Nokia N810|N810]] has an RGB LED.

== N900 ==

=== File Location ===

The software on the device that controls the LED colors is [[N900 Software MCE|MCE]].

The file defining patterns can be found in
/etc/mce/mce.ini

An application ([http://talk.maemo.org/showthread.php?t=27818 mcedit]) for modifying LED patterns was written for the N8x0, but this will not work with the [[Nokia N900|N900]] due to the new <code>mce.ini</code> format.

An app to edit LED patterns on the N900 is available in the [[extras]] repository ([http://maemo.org/downloads/product/Maemo5/led-pattern-editor Downloads Page]), [[LED Pattern Editor]]. This adds a way to edit LED patterns in the settings application.

=== Pattern Format ===

The patterns are broken down as follows:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern</tt>

(Though the LP5523 chip has 3 engines meant to control R, G, and B, the mce program exlusively uses engine3 for kbd backlight and so doesn't support pattern
definitions for engine3. mce is closed source and thus this can't be fixed in any reasonable way. If mce were open, an alternative compatible format was possible:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern;Engine3Pattern</tt>

where LEDsToMap was something like "000012300" to map the particular LED to either none, or Engine1..3 respectively.

We could also fix mce to allow pattern definitions of arbitrary length up to the max RAM available, which is 96 commands with all RAM allocated to one engine - this would need a patch to support doing this in lp5523.ko driver as well.
)

==== Priority ====

0-255, 0 is highest, 255 is lowest.

Since currently only a single pattern at a time can be displayed, this is used to assign importance to the LED patterns. Although only a single LED pattern can be displayed at any time, multiple patterns may be active, the pattern with the highest priority being displayed.

A common example of this is where the N900 is on charge, the battery is full (starting PatternBatteryFull with a priority of 40), and an SMS message is received (PatternCommunicationSMS with a priority of 30). On receipt of the SMS, the LED begins to display the flashing blue led of an SMS. Once that SMS has been dismissed, the green LED of the full battery notification is again displayed.

==== ScreenOn ====

* 0: only show pattern when the display is off
* 1: show pattern even when the display is on
* 2: only show pattern when the display is off, including acting dead
* 3: show pattern even when the display is on, including acting dead
* 4: only show pattern if the display is off, or if in acting dead
* 5: always show pattern, even if LED disabled

==== TimeOut ====

This is the time-out of the LED pattern in seconds. 0 for infinite, i.e. until the notification is dismissed.

If this is set to 20, the pattern will display for 20 seconds, and then stop.

==== LEDsToMap ====

There are two engines that can be used to make custom LED patterns.<ref name="engines">Actually there are three, but the third engine is used exclusively for the keyboard LED.</ref>

r, g, or b maps the corresponding colour channel to Engine 1.

R, G, or B maps the corresponding colour channel to Engine 2.

For example, "rG" maps the red channel to Engine 1, and the green channel to Engine 2.

You should avoid mapping the same channel to both engines, for example "rR", "gG" or "bB" - it's not supported by the hardware, makes no sense anyway, and therefore probably never has been tested.

==== Engine Pattern ====

This is a series of text that describes the speed and intensity of changes in the LED(s) being managed by that particular engine. See below for a breakdown of the patterns. Each can be at most 16 commands long.

=== Lysti Format Engine Patterns and Commands ===

The LED patterns are of the form
:<tt>9d8040007f007f0040ff7f007f000000</tt>

Breaking this down for ease of reading we get a list of 8 commands, each of which is four characters long. There may be up to 16 commands for a pattern (kernel driver limitation, the hardware could manage up to 96)
:<tt>9d80 4000 7f00 7f00 40ff 7f00 7f00 0000</tt>

==== 9d80 - Refresh Engine Multiplexer ====

This is to be used as the first command of every pattern. If this is excluded from the pattern, the led won't flash. (actually this command loads the first [and only] entry of a predefined [by kernel driver] multiplexer table in chip's RAM to the multiplexer register)

==== 40xx - Set channel brightness ====

Where xx are two hexadecimal digits, e.g. 00 (for a brightness of 0) or ff (for a brightness of 255).

==== xxyy - Adjust channel brightness ====

Increment or decrement the channel brightness over a period of time (xx) and a number of steps (yy).

Where xx and yy are hexadecimal digits

xx - Time (per step?)

yy - Number of steps

The following rules apply to these:
* If xx is even, the steps are increment steps and brightness will increase.
* If xx is odd, the steps are decrement steps and brightness will decrease.
* If xx is between 02 and 3f, a short step time is used (granularity 0.49ms)
* If xx is between 42 and 7f, a long step time is used (granularity 15.6ms)
* yy can be any value between 00 and ff (0 to 255)
* Pauses can be achieved by using 00 steps, e.g. 7f00 where, where the 7f is how long each step takes and 00 is how many increment steps to take.

The mce.ini instructions (/etc/mce/mce.ini) also state that
:Two consecutive increment/decrement sequences are needed to cover the entire range from 0-255
However I believe this is a throwback to the older patterns, and the full range of 00 to ff is available in a single step for the number of steps, since whether these are increment or decrement steps are now handled through use of even or odd xx values.

==== 0000 - Jump to start ====

Jump to the start of the pattern for this channel. You will see this at the end of most repeating patterns.

This command may not actually be needed to make the pattern repeat. If this is removed, the pattern will repeat anyway, although it's useful to have it there as an explicit command to repeat for clarity. If you wanted a pattern to run once and then terminate you would use the c000 command.

==== A000 .. BFFF - Branch (decrement and branch if non zero) ====

101<llllll><sssssss> : 16bit

llllll : 6bit; Loop count, 0=infinite loop, or max 63 loops

sssssss : 7 bit; Step number; Value to store to PC (0-95 actual progspace of LP5523 of 96 16bit commands. [Unclear if that's absolute address, or probably offset relative to start of program space assigned to the particular engine])

You can build MUCH SMARTER loops with this! ;-D

==== c000 - End pattern execution ====

(also d000 = with hw INT; c800/d800 = with PC reset. INT might serve to signal end-of-pattern to main CPU ->*)

The pattern is terminated without repeating.

''the following is about mce, not about how LP5523 chip works''

It is important to note here that although that pattern has stopped, it is still active *) until the Timeout time has passed. As a consequence of this any higher priority patterns (patterns with a lower priority value, since 0 is the highest and 255 is the lowest) will not be displayed until the pattern has fully expired. In the case that the timeout is 0, it will not display until the notification is dismissed.

==== Sending and receiving engine triggers ====

Further complexity in patterns can be added through use of triggers. This is especially useful if we want to synchronise the two engines in time, for example to wait until the LED has turned red before turning it immediately to green. Rather than waste time with steps doing nothing, we can simply wait for a trigger to be received from the other engine.

The following pattern does exactly that:
:<tt>PatternTest=29;1;0;rG;9d80''4000''08ff''e004''4000''c000'';9d80''e080''40ff''c000''</tt>

===== e002, e004, e008 - Send engine trigger =====

e002 - Send trigger to engine 1

e004 - Send trigger to engine 2

e008 - Send trigger to engine 3 (used by keyboard backlight)

A signal is sent from the current engine to signal another engine.

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function (unless you stop mce, so it doesn't mess with LP5523 anymore - see below).

===== e080, e100, e200 - Wait for engine trigger =====

e080 - Wait for trigger from engine 1

e100 - Wait for trigger from engine 2

e200 - Wait for trigger from engine 3 (used by keyboard backlight)

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function.

=== Default LED Patterns for Nokia N900 ===

PatternError=0;5;0;r;9d8040007f007f0040ff7f007f000000;9d800000
PatternDeviceOn=254;0;0;rgb;9d804000422043207f100000;9d800000
PatternDeviceSoftOff=253;0;0;rg;9d804000423f433f7f100000;9d800000
PatternPowerOn=9;3;0;rgb;9d80400042ff02ffc000;9d800000
PatternPowerOff=10;3;0;rgb;9d80400001ff43ff7f007f00c000;9d800000
PatternCommunicationCall=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationIM=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationSMS=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationEmail=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommonNotification=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternWebcamActive=20;1;0;r;9d80400004ffc0000000;9d800000
PatternBatteryCharging=50;4;0;rg;9d804000427f0d7f7f007f0042000000;9d800000
PatternBatteryFull=40;4;0;g;9d80407f0000;9d800000

=== Community-Made Patterns ===
''Please note that these patterns should each be on one line.''
''They can also be used for any notification by choosing the appropriately named "Pattern... for the start of the line.''

A traffic-light battery charging pattern, courtesy of [http://talk.maemo.org/showthread.php?p=512430#post512430 blue_led]
PatternBatteryCharging=50;4;0;Rg;9d80407f7f00e0047f0040007f007f007f00407f7f00e0047f007f000000;9d804000e080407fe0800000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=499305#post499305 mihapodb]. This pattern cuts quickly between blue and red.
PatternCommunicationEmail=30;1;0;rB;9d8040ff7f00e00440007f000000;9d80e08040ff7f0040000000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=540959#post540959 villo]. This pattern fades between red and blue.
PatternCommunicationEmail=30;1;0;rB;9d8004ff05ffe004e1000000;9d80e08004ff05ffe0020000

Cehteh's patterns with some comments

Slow dark glowing in cyan, never goes fully off, so you can locate the device in the dark:
PatternDeviceOn=254;0;0;gb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

Slow dark glowing in yellow, never goes fully off, so you can locate the device in the dark:
PatternBatteryCharging=50;3;0;rg;9d804001427f0d7f7f007f0042000000;9d800000

Slow dark glowing in white, never goes fully off, so you can locate the device in the dark:
PatternBatteryFull=40;3;0;rgb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

White, bright flashing (must be enabled in 'LEDPatterns=' ?):
PatternExample=42;1;30;rgb;9d8040007f007f0040ff42000000;9d800000

=== Step by step instructions ===
{{ambox
|type=notice
|text=There's a command
IroN900:~# /usr/bin/mceledpattern --help
Usage:
mceledpattern add[_vibra] <pattern_name> <pattern>
mceledpattern remove[_vibra] <pattern_name>

To replace existing pattern use add, to restore replaced pattern back to previous value use remove
Please check if it's default or came with one of my additional packages}}
* Open terminal
* Gain [[root access]]
* Make a backup (for your own convenience) from original mce.ini -file, for example:<pre>cp /etc/mce/mce.ini /etc/mce/mce.ini_old</pre>
* Open <code>/etc/mce/mce.ini</code> with a text editor (nano, vim, leafpad...)
* Search for a line:<pre>[LEDPatternLystiRX51]</pre>
* Make your changes to the lines below
* Save
* Restart mce -process. Either reboot or type in terminal:<pre>initctl stop mce; sleep 2; initctl start mce</pre>

Please note: restarting mce several times in 2 minutes will cause the system to think there is a problem with mce, and so won't start it. The initctl program will inform you of this. When it does, simply wait a while before trying again.

Alternatively, mce is started using [[dsmetool]] which monitors and reboots the device on failure.
This monitoring can be adjusted for more convenient hacking.

/etc/event.d/mce

* /usr/sbin/dsmetool -n -1 -t "/sbin/mce --force-syslog"

Replacing -t (start and restart) with -o (start once) eliminates this monitoring.

Please be aware that errors in editing these files could cause a reboot loop, which could require a reflash to stop.

=== Low Level ===
'''this section should get merged with [[N900_Hardware_LED]] !'''

The N8x0 had a LP5521<ref name="lp5521-spec">http://www.national.com/pf/LP/LP5521.html</ref> <ref name="lp5521-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/i2c/chips/lp5521.c</ref> programmable three channel controller LED Driver which handles the leds.
The N900 has a LP5523 <ref name="lp5523-spec">http://www.national.com/pf/LP/LP5523.html</ref> <ref name="leds-lp5523-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/leds/leds-lp5523.c</ref>, which has 3 engines like LP5521 but can drive 9 LEDs via a multiplexer. Actually the multiplexer is between the engine (CPU) and the 9 PWM blocks for the 9 LED outputs - each of those 9 PWM blocks has its own accessable registers for current and brightness, and they are exposed to sysfs. This chip also has double the RAM size for 'programs', plus 2 per-machine and one global register variable and a true set of conditional branch and arithmetic commands.

Alas the LP5523 driver doesn't support any of those advanced features of LP5523, and uses one of those engines for a kbd backlight ramp-up/down. 
''This could as well get done in mce by a 25ms timer that writes 40 new brightness values to the master control of kbd LEDs during 1 second.''

See [[N900_Hardware_LED]] for hardware programming details.

** engine1_leds is in the form "0000rgb00" (9 digits, "1" or "0"), where rgb control which leds should participate. The 6 "0" in the above pattern correspond to the 6 kbd white leds controlled by mce via engine3, so readout of engine3_leds gives 111100011 ;-)
** engine1_load accepts a string as specified above (e.g. 9d804000427f0d7f7f007f0042000000). Though LP5523 has an absolute storage of 96 steps a 16bits, which can dynamically partitioned between the three engines, the driver is retarded and limits this to a fixed 16 words a 16bit per engine (<s>ToDo: check if driver supports >16 instructions / machine</s> no it doesn't :-/)
After that, when the state is changed to "run", the program will be run by the controller.

In order for the leds to work, the led_current of the appropriate leds need to be set to non-zero values. This is accomplished by writing to files leds:lp5523:[bgr]/'''led_current''' under the same directory. '''Don't mess with''' the default settings here that come with driver init, they are suitable and changing to higher values may and for certain values '''will kill your LEDS'''!.

== References ==
Also see [[N900_Hardware_LED]]!

<references />

[[Category:N900 Hardware]]
[[Category:Power users]]

LED patterns

2014-01-06T13:33:25Z

90.180.214.199: /* References */

== N800 ==

The [[Nokia N800|N800]] has a single-colour (blue) LED behind the dpad.

== N810 ==

The [[Nokia N810|N810]] has an RGB LED.

== N900 ==

=== File Location ===

The software on the device that controls the LED colors is [[N900 Software MCE|MCE]].

The file defining patterns can be found in
/etc/mce/mce.ini

An application ([http://talk.maemo.org/showthread.php?t=27818 mcedit]) for modifying LED patterns was written for the N8x0, but this will not work with the [[Nokia N900|N900]] due to the new <code>mce.ini</code> format.

An app to edit LED patterns on the N900 is available in the [[extras]] repository ([http://maemo.org/downloads/product/Maemo5/led-pattern-editor Downloads Page]), [[LED Pattern Editor]]. This adds a way to edit LED patterns in the settings application.

=== Pattern Format ===

The patterns are broken down as follows:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern</tt>

(Though the LP5523 chip has 3 engines meant to control R, G, and B, the mce program exlusively uses engine3 for kbd backlight and so doesn't support pattern
definitions for engine3. mce is closed source and thus this can't be fixed in any reasonable way. If mce were open, an alternative compatible format was possible:

:<tt>PatternName=Priority;ScreenOn;Timeout;LEDsToMap;Engine1Pattern;Engine2Pattern;Engine3Pattern</tt>

where LEDsToMap was something like "000012300" to map the particular LED to either none, or Engine1..3 respectively.

We could also fix mce to allow pattern definitions of arbitrary length up to the max RAM available, which is 96 commands with all RAM allocated to one engine - this would need a patch to support doing this in lp5523.ko driver as well.
)

==== Priority ====

0-255, 0 is highest, 255 is lowest.

Since currently only a single pattern at a time can be displayed, this is used to assign importance to the LED patterns. Although only a single LED pattern can be displayed at any time, multiple patterns may be active, the pattern with the highest priority being displayed.

A common example of this is where the N900 is on charge, the battery is full (starting PatternBatteryFull with a priority of 40), and an SMS message is received (PatternCommunicationSMS with a priority of 30). On receipt of the SMS, the LED begins to display the flashing blue led of an SMS. Once that SMS has been dismissed, the green LED of the full battery notification is again displayed.

==== ScreenOn ====

* 0: only show pattern when the display is off
* 1: show pattern even when the display is on
* 2: only show pattern when the display is off, including acting dead
* 3: show pattern even when the display is on, including acting dead
* 4: only show pattern if the display is off, or if in acting dead
* 5: always show pattern, even if LED disabled

==== TimeOut ====

This is the time-out of the LED pattern in seconds. 0 for infinite, i.e. until the notification is dismissed.

If this is set to 20, the pattern will display for 20 seconds, and then stop.

==== LEDsToMap ====

There are two engines that can be used to make custom LED patterns.<ref name="engines">Actually there are three, but the third engine is used exclusively for the keyboard LED.</ref>

r, g, or b maps the corresponding colour channel to Engine 1.

R, G, or B maps the corresponding colour channel to Engine 2.

For example, "rG" maps the red channel to Engine 1, and the green channel to Engine 2.

You should avoid mapping the same channel to both engines, for example "rR", "gG" or "bB" - it's not supported by the hardware, makes no sense anyway, and therefore probably never has been tested.

==== Engine Pattern ====

This is a series of text that describes the speed and intensity of changes in the LED(s) being managed by that particular engine. See below for a breakdown of the patterns. Each can be at most 16 commands long.

=== Lysti Format Engine Patterns and Commands ===

The LED patterns are of the form
:<tt>9d8040007f007f0040ff7f007f000000</tt>

Breaking this down for ease of reading we get a list of 8 commands, each of which is four characters long. There may be up to 16 commands for a pattern (kernel driver limitation, the hardware could manage up to 96)
:<tt>9d80 4000 7f00 7f00 40ff 7f00 7f00 0000</tt>

==== 9d80 - Refresh Engine Multiplexer ====

This is to be used as the first command of every pattern. If this is excluded from the pattern, the led won't flash. (actually this command loads the first [and only] entry of a predefined [by kernel driver] multiplexer table in chip's RAM to the multiplexer register)

==== 40xx - Set channel brightness ====

Where xx are two hexadecimal digits, e.g. 00 (for a brightness of 0) or ff (for a brightness of 255).

==== xxyy - Adjust channel brightness ====

Increment or decrement the channel brightness over a period of time (xx) and a number of steps (yy).

Where xx and yy are hexadecimal digits

xx - Time (per step?)

yy - Number of steps

The following rules apply to these:
* If xx is even, the steps are increment steps and brightness will increase.
* If xx is odd, the steps are decrement steps and brightness will decrease.
* If xx is between 02 and 3f, a short step time is used (granularity 0.49ms)
* If xx is between 42 and 7f, a long step time is used (granularity 15.6ms)
* yy can be any value between 00 and ff (0 to 255)
* Pauses can be achieved by using 00 steps, e.g. 7f00 where, where the 7f is how long each step takes and 00 is how many increment steps to take.

The mce.ini instructions (/etc/mce/mce.ini) also state that
:Two consecutive increment/decrement sequences are needed to cover the entire range from 0-255
However I believe this is a throwback to the older patterns, and the full range of 00 to ff is available in a single step for the number of steps, since whether these are increment or decrement steps are now handled through use of even or odd xx values.

==== 0000 - Jump to start ====

Jump to the start of the pattern for this channel. You will see this at the end of most repeating patterns.

This command may not actually be needed to make the pattern repeat. If this is removed, the pattern will repeat anyway, although it's useful to have it there as an explicit command to repeat for clarity. If you wanted a pattern to run once and then terminate you would use the c000 command.

==== A000 .. BFFF - Branch (decrement and branch if non zero) ====

101<llllll><sssssss> : 16bit

llllll : 6bit; Loop count, 0=infinite loop, or max 63 loops

sssssss : 7 bit; Step number; Value to store to PC (0-95 actual progspace of LP5523 of 96 16bit commands. [Unclear if that's absolute address, or probably offset relative to start of program space assigned to the particular engine])

You can build MUCH SMARTER loops with this! ;-D

==== c000 - End pattern execution ====

(also d000 = with hw INT; c800/d800 = with PC reset. INT might serve to signal end-of-pattern to main CPU ->*)

The pattern is terminated without repeating.

''the following is about mce, not about how LP5523 chip works''

It is important to note here that although that pattern has stopped, it is still active *) until the Timeout time has passed. As a consequence of this any higher priority patterns (patterns with a lower priority value, since 0 is the highest and 255 is the lowest) will not be displayed until the pattern has fully expired. In the case that the timeout is 0, it will not display until the notification is dismissed.

==== Sending and receiving engine triggers ====

Further complexity in patterns can be added through use of triggers. This is especially useful if we want to synchronise the two engines in time, for example to wait until the LED has turned red before turning it immediately to green. Rather than waste time with steps doing nothing, we can simply wait for a trigger to be received from the other engine.

The following pattern does exactly that:
:<tt>PatternTest=29;1;0;rG;9d80''4000''08ff''e004''4000''c000'';9d80''e080''40ff''c000''</tt>

===== e002, e004, e008 - Send engine trigger =====

e002 - Send trigger to engine 1

e004 - Send trigger to engine 2

e008 - Send trigger to engine 3 (used by keyboard backlight)

A signal is sent from the current engine to signal another engine.

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function (unless you stop mce, so it doesn't mess with LP5523 anymore - see below).

===== e080, e100, e200 - Wait for engine trigger =====

e080 - Wait for trigger from engine 1

e100 - Wait for trigger from engine 2

e200 - Wait for trigger from engine 3 (used by keyboard backlight)

Although the trigger information for engine 3 is listed we have no control over the keyboard LED, so it has no effect. Attempting to add a pattern for engine 3 after the pattern for engine 2 causes the pattern to no longer function.

=== Default LED Patterns for Nokia N900 ===

PatternError=0;5;0;r;9d8040007f007f0040ff7f007f000000;9d800000
PatternDeviceOn=254;0;0;rgb;9d804000422043207f100000;9d800000
PatternDeviceSoftOff=253;0;0;rg;9d804000423f433f7f100000;9d800000
PatternPowerOn=9;3;0;rgb;9d80400042ff02ffc000;9d800000
PatternPowerOff=10;3;0;rgb;9d80400001ff43ff7f007f00c000;9d800000
PatternCommunicationCall=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationIM=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationSMS=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommunicationEmail=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternCommonNotification=30;1;0;b;9d80400002ff03ff02ff03ff71080000;9d800000
PatternWebcamActive=20;1;0;r;9d80400004ffc0000000;9d800000
PatternBatteryCharging=50;4;0;rg;9d804000427f0d7f7f007f0042000000;9d800000
PatternBatteryFull=40;4;0;g;9d80407f0000;9d800000

=== Community-Made Patterns ===
''Please note that these patterns should each be on one line.''
''They can also be used for any notification by choosing the appropriately named "Pattern... for the start of the line.''

A traffic-light battery charging pattern, courtesy of [http://talk.maemo.org/showthread.php?p=512430#post512430 blue_led]
PatternBatteryCharging=50;4;0;Rg;9d80407f7f00e0047f0040007f007f007f00407f7f00e0047f007f000000;9d804000e080407fe0800000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=499305#post499305 mihapodb]. This pattern cuts quickly between blue and red.
PatternCommunicationEmail=30;1;0;rB;9d8040ff7f00e00440007f000000;9d80e08040ff7f0040000000

A police-siren style pattern, idea by [http://talk.maemo.org/showthread.php?p=540959#post540959 villo]. This pattern fades between red and blue.
PatternCommunicationEmail=30;1;0;rB;9d8004ff05ffe004e1000000;9d80e08004ff05ffe0020000

Cehteh's patterns with some comments

Slow dark glowing in cyan, never goes fully off, so you can locate the device in the dark:
PatternDeviceOn=254;0;0;gb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

Slow dark glowing in yellow, never goes fully off, so you can locate the device in the dark:
PatternBatteryCharging=50;3;0;rg;9d804001427f0d7f7f007f0042000000;9d800000

Slow dark glowing in white, never goes fully off, so you can locate the device in the dark:
PatternBatteryFull=40;3;0;rgb;9d804001620863087f007f007f007f007f007f007f007f007f007f007f000000;9d800000

White, bright flashing (must be enabled in 'LEDPatterns=' ?):
PatternExample=42;1;30;rgb;9d8040007f007f0040ff42000000;9d800000

=== Step by step instructions ===
{{ambox
|type=notice
|text=There's a command
IroN900:~# /usr/bin/mceledpattern --help
Usage:
mceledpattern add[_vibra] <pattern_name> <pattern>
mceledpattern remove[_vibra] <pattern_name>

To replace existing pattern use add, to restore replaced pattern back to previous value use remove
Please check if it's default or came with one of my additional packages}}
* Open terminal
* Gain [[root access]]
* Make a backup (for your own convenience) from original mce.ini -file, for example:<pre>cp /etc/mce/mce.ini /etc/mce/mce.ini_old</pre>
* Open <code>/etc/mce/mce.ini</code> with a text editor (nano, vim, leafpad...)
* Search for a line:<pre>[LEDPatternLystiRX51]</pre>
* Make your changes to the lines below
* Save
* Restart mce -process. Either reboot or type in terminal:<pre>initctl stop mce; sleep 2; initctl start mce</pre>

Please note: restarting mce several times in 2 minutes will cause the system to think there is a problem with mce, and so won't start it. The initctl program will inform you of this. When it does, simply wait a while before trying again.

Alternatively, mce is started using [[dsmetool]] which monitors and reboots the device on failure.
This monitoring can be adjusted for more convenient hacking.

/etc/event.d/mce

* /usr/sbin/dsmetool -n -1 -t "/sbin/mce --force-syslog"

Replacing -t (start and restart) with -o (start once) eliminates this monitoring.

Please be aware that errors in editing these files could cause a reboot loop, which could require a reflash to stop.

=== Low Level ===
'''this section should get merged with [[N900_Hardware_LED]] !'''

The N8x0 had a LP5521<ref name="lp5521-spec">http://www.national.com/pf/LP/LP5521.html</ref> <ref name="lp5521-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/i2c/chips/lp5521.c</ref> programmable three channel controller LED Driver which handles the leds.
The N900 has a LP5523 <ref name="lp5523-spec">http://www.national.com/pf/LP/LP5523.html</ref> <ref name="leds-lp5523-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/leds/leds-lp5523.c</ref>, which has 3 engines like LP5521 but can drive 9 LEDs via a multiplexer. Actually the multiplexer is between the engine (CPU) and the 9 PWM blocks for the 9 LED outputs - each of those 9 PWM blocks has its own accessable registers for current and brightness, and they are exposed to sysfs. This chip also has double the RAM size for 'programs', plus 2 per-machine and one global register variable and a true set of conditional branch and arithmetic commands.

Alas the LP5523 driver doesn't support any of those advanced features of LP5523, and even abuses one of those extremely smart engines for a stupid occasional kbd backlight ramp-up/down. 
''This could as well get done in mce by a 25ms timer that writes 40 new brightness values to the master control of kbd LEDs during 1 second. There's really no reason why you need to assign 1 of those 3 machines to this *occasional* short ramp function and break true rainbow 3 color effects on indicator LED. Sound rationale: while kbd bl ramp the ''CPU is awake anyway''. No obvious benefit in offloading the task to a LP5532 engine [except from saving 50 lines of code in mce]!)''

The controller can be programmed via "/sys/class/i2c-adapter/i2c-2/2-0032" (FIXME: is this stable?). In that directory there are three files corresponding to the three channels: engine1_mode, engine2_mode and engine3_mode. Each file "stores" one of "run", "load", "disabled" (it seems that there is another mode "direct" but it doesn't work):
* run: The program runs
* disabled: The channel is disabled - not running
* load: In that state, there are two more files in that directory:
** engine1_leds is in the form "0000rgb00" (9 digits, "1" or "0"), where rgb control which leds should participate. The 6 "0" in the above pattern correspond to the 6 kbd white leds controlled by mce via engine3, so readout of engine3_leds gives 111100011 ;-)
** engine1_load accepts a string as specified above (e.g. 9d804000427f0d7f7f007f0042000000). Though LP5523 has an absolute storage of 96 steps a 16bits, which can dynamically partitioned between the three engines, the driver is retarded and limits this to a fixed 16 words a 16bit per engine (<s>ToDo: check if driver supports >16 instructions / machine</s> no it doesn't :-/)
After that, when the state is changed to "run", the program will be run by the controller.

In order for the leds to work, the led_current of the appropriate leds need to be set to non-zero values. This is accomplished by writing to files leds:lp5523:[bgr]/'''led_current''' under the same directory. '''Don't mess with''' the default settings here that come with driver init, they are suitable and changing to higher values may and for certain values '''will kill your LEDS'''!.

NOTE: There must be a delay (how much? The specs of LP5521 mentions it) between writes to sysfs files.

== References ==
Also see [[N900_Hardware_LED]]!

<references />

[[Category:N900 Hardware]]
[[Category:Power users]]

N900 Hardware LED

2014-01-06T13:32:49Z

90.180.214.199: Yes, sysfs is stable, no, you do not need to wait between accessing /sys. Driver takes care of delays.

==Hardware==

The [[Nokia N900|N900]] has LP5523 <ref name="lp5523-spec">http://www.national.com/pf/LP/LP5523.html</ref> <ref name="leds-lp5523-driver">http://mxr.maemo.org/fremantle/source/kernel/drivers/leds/leds-lp5523.c</ref>, which has 3 engines like LP5521 (compatible though augmented instruction set) but can drive 9 LEDs via a multiplexer which maps each LED to one of the 3 engines. A LED also can be unassigned to any engine, in which case you can control it by writing to the corresponding brightness sysnode) which handles the keyboard and notification LED. (not the [[N900 Hardware Flash Torch|flash LEDs]] and red indicator light next to those, and also not the Infrared-LED used for CIR)

The controller can be programmed via "/sys/class/i2c-adapter/i2c-2/2-0032". In that directory there are three files corresponding to the three channels: <code>engine1_mode</code>, <code>engine2_mode</code> and <code>engine3_mode</code>. Each file "stores" one of <code>run</code>, <code>load</code>, <code>disabled</code> (it seems that there is another mode "direct" but it doesn't work)(direct mode requires explicit writes to PWM, current and multiplexing registers, which may not be supported in the code...):
* <code>run</code>: The program runs
* <code>disabled</code>: The channel is disabled - not running
* <code>load</code>: In that state, there are two more files in that directory:
** engine1_LEDs is in the form "0000rgb00" (9 digits, "1" or "0"), where rgb control which LEDs should participate. The 6 "0" in the above pattern correspond to the 6 kbd white LEDs controlled by MCE via engine3, so readout of engine3_leds gives 111100011 ;-)
** engine1_load accepts a string as specified above (e.g. 9d804000427f0d7f7f007f0042000000). LP5523 has an absolute storage of 96 steps a 16bits, which can dynamically partitioned between the three engines. (Supports 32-96 steps per engine, dynamically-assigned, alas the lp5523.ko driver is braindamaged and doesn't support more than 16 instructions per engine)
After that, when the state is changed to "run", the program will be ran by the controller.

In order for the LEDs to work, the led_current of the appropriate LEDs need to be set to non-zero values. This is accomplished by writing to files LEDs:lp5523:[bgr]/led_current under the same directory. Default values from kernel module init are suitable.

Despite the line
<source lang="c">
#define LP5523_DEFAULT_CURRENT 50 /* microAmps */
</source>
suggesting different, the units in there are 0.1 mA (100 µA per step is correct). So the driver init default "50" for all LEDs is 5 mA, and mce seems to set current to 0.2 mA (value 2 in the led_current sysnode) for B and G, and either to 0.2 mA or 0.8 mA for R. Probably settings as high as 100 for 10 mA are safe for the RGB LED, higher values might destroy the LED. (yes, correct, the RGB could be damaged from heat if set to more than 10 mA on all 3 LEDs)

''BEWARE!
register addr 0x3B: GPO
LP5523 has one General Purpose Output pin (GPO).
Status of the pin can be controlled with this register. Also,
'''INT pin can be configured to function as a GPO''' by setting
the bit INT_CONF. When INT is configured to function as
a GPO, '''output level is defined by the VDD voltage'''.
3B — Bit [2] INT_CONF
0 = INT pin is set to function as an interrupt pin (default).
1 = INT pin is configured to function as a GPO.

INT is routed directly to a SOC GPIO that is not designed to take voltages >1.8V ! So setting 0x3B:2 to 1 may fry your CPU
''

==Software==

== References ==

also see [[LED_patterns]] of which this page is a "fork" without cleaning the original page, so now there are two versions with almost identical but slightly complementary info

Since beginning of 2012 a datasheet for LP5523 is available from TI: http://www.ti.com/product/lp5523 Direct link: http://www.ti.com/general/docs/lit/getliterature.tsp?literatureNumber=snvs550d&fileType=pdf

<references />

[[Category:N900 Hardware]]