Documentation/leds/leds-class-multicolor.rst

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