1*55d5d3b4SDan Murphy.. SPDX-License-Identifier: GPL-2.0 2*55d5d3b4SDan Murphy 3*55d5d3b4SDan Murphy==================================== 4*55d5d3b4SDan MurphyMulticolor LED handling under Linux 5*55d5d3b4SDan Murphy==================================== 6*55d5d3b4SDan Murphy 7*55d5d3b4SDan MurphyDescription 8*55d5d3b4SDan Murphy=========== 9*55d5d3b4SDan MurphyThe multicolor class groups monochrome LEDs and allows controlling two 10*55d5d3b4SDan Murphyaspects of the final combined color: hue and lightness. The former is 11*55d5d3b4SDan Murphycontrolled via the multi_intensity array file and the latter is controlled 12*55d5d3b4SDan Murphyvia brightness file. 13*55d5d3b4SDan Murphy 14*55d5d3b4SDan MurphyMulticolor Class Control 15*55d5d3b4SDan Murphy======================== 16*55d5d3b4SDan MurphyThe multicolor class presents files that groups the colors as indexes in an 17*55d5d3b4SDan Murphyarray. These files are children under the LED parent node created by the 18*55d5d3b4SDan Murphyled_class framework. The led_class framework is documented in led-class.rst 19*55d5d3b4SDan Murphywithin this documentation directory. 20*55d5d3b4SDan Murphy 21*55d5d3b4SDan MurphyEach colored LED will be indexed under the multi_* files. The order of the 22*55d5d3b4SDan Murphycolors will be arbitrary. The multi_index file can be read to determine the 23*55d5d3b4SDan Murphycolor name to indexed value. 24*55d5d3b4SDan Murphy 25*55d5d3b4SDan MurphyThe multi_index file is an array that contains the string list of the colors as 26*55d5d3b4SDan Murphythey are defined in each multi_* array file. 27*55d5d3b4SDan Murphy 28*55d5d3b4SDan MurphyThe multi_intensity is an array that can be read or written to for the 29*55d5d3b4SDan Murphyindividual color intensities. All elements within this array must be written in 30*55d5d3b4SDan Murphyorder for the color LED intensities to be updated. 31*55d5d3b4SDan Murphy 32*55d5d3b4SDan MurphyDirectory Layout Example 33*55d5d3b4SDan Murphy======================== 34*55d5d3b4SDan Murphyroot:/sys/class/leds/multicolor:status# ls -lR 35*55d5d3b4SDan Murphy-rw-r--r-- 1 root root 4096 Oct 19 16:16 brightness 36*55d5d3b4SDan Murphy-r--r--r-- 1 root root 4096 Oct 19 16:16 max_brightness 37*55d5d3b4SDan Murphy-r--r--r-- 1 root root 4096 Oct 19 16:16 multi_index 38*55d5d3b4SDan Murphy-rw-r--r-- 1 root root 4096 Oct 19 16:16 multi_intensity 39*55d5d3b4SDan Murphy 40*55d5d3b4SDan MurphyMulticolor Class Brightness Control 41*55d5d3b4SDan Murphy=================================== 42*55d5d3b4SDan MurphyThe brightness level for each LED is calculated based on the color LED 43*55d5d3b4SDan Murphyintensity setting divided by the global max_brightness setting multiplied by 44*55d5d3b4SDan Murphythe requested brightness. 45*55d5d3b4SDan Murphy 46*55d5d3b4SDan Murphyled_brightness = brightness * multi_intensity/max_brightness 47*55d5d3b4SDan Murphy 48*55d5d3b4SDan MurphyExample: 49*55d5d3b4SDan MurphyA user first writes the multi_intensity file with the brightness levels 50*55d5d3b4SDan Murphyfor each LED that are necessary to achieve a certain color output from a 51*55d5d3b4SDan Murphymulticolor LED group. 52*55d5d3b4SDan Murphy 53*55d5d3b4SDan Murphycat /sys/class/leds/multicolor:status/multi_index 54*55d5d3b4SDan Murphygreen blue red 55*55d5d3b4SDan Murphy 56*55d5d3b4SDan Murphyecho 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity 57*55d5d3b4SDan Murphy 58*55d5d3b4SDan Murphyred - 59*55d5d3b4SDan Murphy intensity = 138 60*55d5d3b4SDan Murphy max_brightness = 255 61*55d5d3b4SDan Murphygreen - 62*55d5d3b4SDan Murphy intensity = 43 63*55d5d3b4SDan Murphy max_brightness = 255 64*55d5d3b4SDan Murphyblue - 65*55d5d3b4SDan Murphy intensity = 226 66*55d5d3b4SDan Murphy max_brightness = 255 67*55d5d3b4SDan Murphy 68*55d5d3b4SDan MurphyThe user can control the brightness of that multicolor LED group by writing the 69*55d5d3b4SDan Murphyglobal 'brightness' control. Assuming a max_brightness of 255 the user 70*55d5d3b4SDan Murphymay want to dim the LED color group to half. The user would write a value of 71*55d5d3b4SDan Murphy128 to the global brightness file then the values written to each LED will be 72*55d5d3b4SDan Murphyadjusted base on this value. 73*55d5d3b4SDan Murphy 74*55d5d3b4SDan Murphycat /sys/class/leds/multicolor:status/max_brightness 75*55d5d3b4SDan Murphy255 76*55d5d3b4SDan Murphyecho 128 > /sys/class/leds/multicolor:status/brightness 77*55d5d3b4SDan Murphy 78*55d5d3b4SDan Murphyadjusted_red_value = 128 * 138/255 = 69 79*55d5d3b4SDan Murphyadjusted_green_value = 128 * 43/255 = 21 80*55d5d3b4SDan Murphyadjusted_blue_value = 128 * 226/255 = 113 81*55d5d3b4SDan Murphy 82*55d5d3b4SDan MurphyReading the global brightness file will return the current brightness value of 83*55d5d3b4SDan Murphythe color LED group. 84*55d5d3b4SDan Murphy 85*55d5d3b4SDan Murphycat /sys/class/leds/multicolor:status/brightness 86*55d5d3b4SDan Murphy128 87