1.. SPDX-License-Identifier: GPL-2.0
2
3====================================
4Multicolor LED handling under Linux
5====================================
6
7Description
8===========
9The multicolor class groups monochrome LEDs and allows controlling two
10aspects of the final combined color: hue and lightness. The former is
11controlled via the multi_intensity array file and the latter is controlled
12via brightness file.
13
14Multicolor Class Control
15========================
16The multicolor class presents files that groups the colors as indexes in an
17array.  These files are children under the LED parent node created by the
18led_class framework.  The led_class framework is documented in led-class.rst
19within this documentation directory.
20
21Each colored LED will be indexed under the multi_* files. The order of the
22colors will be arbitrary. The multi_index file can be read to determine the
23color name to indexed value.
24
25The multi_index file is an array that contains the string list of the colors as
26they are defined in each multi_* array file.
27
28The multi_intensity is an array that can be read or written to for the
29individual color intensities.  All elements within this array must be written in
30order for the color LED intensities to be updated.
31
32Directory Layout Example
33========================
34root:/sys/class/leds/multicolor:status# ls -lR
35-rw-r--r--    1 root     root          4096 Oct 19 16:16 brightness
36-r--r--r--    1 root     root          4096 Oct 19 16:16 max_brightness
37-r--r--r--    1 root     root          4096 Oct 19 16:16 multi_index
38-rw-r--r--    1 root     root          4096 Oct 19 16:16 multi_intensity
39
40Multicolor Class Brightness Control
41===================================
42The brightness level for each LED is calculated based on the color LED
43intensity setting divided by the global max_brightness setting multiplied by
44the requested brightness.
45
46led_brightness = brightness * multi_intensity/max_brightness
47
48Example:
49A user first writes the multi_intensity file with the brightness levels
50for each LED that are necessary to achieve a certain color output from a
51multicolor LED group.
52
53cat /sys/class/leds/multicolor:status/multi_index
54green blue red
55
56echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity
57
58red -
59	intensity = 138
60	max_brightness = 255
61green -
62	intensity = 43
63	max_brightness = 255
64blue -
65	intensity = 226
66	max_brightness = 255
67
68The user can control the brightness of that multicolor LED group by writing the
69global 'brightness' control.  Assuming a max_brightness of 255 the user
70may want to dim the LED color group to half.  The user would write a value of
71128 to the global brightness file then the values written to each LED will be
72adjusted base on this value.
73
74cat /sys/class/leds/multicolor:status/max_brightness
75255
76echo 128 > /sys/class/leds/multicolor:status/brightness
77
78adjusted_red_value = 128 * 138/255 = 69
79adjusted_green_value = 128 * 43/255 = 21
80adjusted_blue_value = 128 * 226/255 = 113
81
82Reading the global brightness file will return the current brightness value of
83the color LED group.
84
85cat /sys/class/leds/multicolor:status/brightness
86128
87