leds-class-multicolor.rst

  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..