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======================== 34.. code-block:: console 35 36 root:/sys/class/leds/multicolor:status# ls -lR 37 -rw-r--r-- 1 root root 4096 Oct 19 16:16 brightness 38 -r--r--r-- 1 root root 4096 Oct 19 16:16 max_brightness 39 -r--r--r-- 1 root root 4096 Oct 19 16:16 multi_index 40 -rw-r--r-- 1 root root 4096 Oct 19 16:16 multi_intensity 41 42.. 43 44Multicolor Class Brightness Control 45=================================== 46The brightness level for each LED is calculated based on the color LED 47intensity setting divided by the global max_brightness setting multiplied by 48the requested brightness. 49 50``led_brightness = brightness * multi_intensity/max_brightness`` 51 52Example: 53A user first writes the multi_intensity file with the brightness levels 54for each LED that are necessary to achieve a certain color output from a 55multicolor LED group. 56 57.. code-block:: console 58 59 # cat /sys/class/leds/multicolor:status/multi_index 60 green blue red 61 62 # echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity 63 64 red - 65 intensity = 138 66 max_brightness = 255 67 green - 68 intensity = 43 69 max_brightness = 255 70 blue - 71 intensity = 226 72 max_brightness = 255 73 74.. 75 76The user can control the brightness of that multicolor LED group by writing the 77global 'brightness' control. Assuming a max_brightness of 255 the user 78may want to dim the LED color group to half. The user would write a value of 79128 to the global brightness file then the values written to each LED will be 80adjusted base on this value. 81 82.. code-block:: console 83 84 # cat /sys/class/leds/multicolor:status/max_brightness 85 255 86 # echo 128 > /sys/class/leds/multicolor:status/brightness 87 88.. 89 90.. code-block:: none 91 92 adjusted_red_value = 128 * 138/255 = 69 93 adjusted_green_value = 128 * 43/255 = 21 94 adjusted_blue_value = 128 * 226/255 = 113 95 96.. 97 98Reading the global brightness file will return the current brightness value of 99the color LED group. 100 101.. code-block:: console 102 103 # cat /sys/class/leds/multicolor:status/brightness 104 128 105 106.. 107