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