Hi Dan, Thanks for the update. I have some nits below, please take a look. On 7/1/19 10:46 PM, Dan Murphy wrote: > Add the support documentation on the multicolor LED framework. > This document defines the directores and file generated by the > multicolor framework. It also documents usage. > > Signed-off-by: Dan Murphy <dmurphy@xxxxxx> > --- > Documentation/leds/leds-class-multicolor.txt | 152 +++++++++++++++++++ > 1 file changed, 152 insertions(+) > create mode 100644 Documentation/leds/leds-class-multicolor.txt > > diff --git a/Documentation/leds/leds-class-multicolor.txt b/Documentation/leds/leds-class-multicolor.txt > new file mode 100644 > index 000000000000..01175288502e > --- /dev/null > +++ b/Documentation/leds/leds-class-multicolor.txt > @@ -0,0 +1,152 @@ > + > +Multi Color LED handling under Linux > +================================================= > + > +Author: Dan Murphy <dmurphy@xxxxxx> > + > +Description > +----------- > +There are varying monochrome LED colors available for application. These > +LEDs can be used as a single use case LED or can be mixed with other color > +LEDs to produce the full spectrum of color. Color LEDs that are grouped > +can be presented under a single LED node with individual color control. > +The multicolor class groups these LEDs and allows dynamically setting the value > +of a single LED or setting the intensity values of the LEDs in the group and > +updating the LEDs virtually simultaneously. > + > +Multicolor Class Control > +------------------------- > +The multicolor class presents the LED groups under a directory called "colors". > +This directory is a child under the LED parent node created by the led_class > +framework. The led_class framework is documented in led-class.txt within this > +documentation directory. > + > +Each colored LED is given its own directory. These directories can be, but not > +limited to red, green, blue, white, amber, yellow and violet. Under these > +directories the intensity and max_intensity files are presented for each LED. > + > + > +Directory Layout Example > +------------------------ > +root:/sys/class/leds/rgb:grouped_leds# ls -lR colors/ > +colors/: > +drwxr-xr-x 2 root root 0 Jun 28 20:21 blue > +drwxr-xr-x 2 root root 0 Jun 28 20:21 green > +drwxr-xr-x 2 root root 0 Jun 28 20:21 red > +-rw------- 1 root root 4096 Jun 28 20:21 color_mix > + > +colors/blue: > +-rw------- 1 root root 4096 Jun 28 20:21 intensity > +-r-------- 1 root root 4096 Jun 28 20:27 max_intensity > +-r-------- 1 root root 4096 Jun 28 20:21 color_id > + > +colors/green: > +-rw------- 1 root root 4096 Jun 28 20:22 intensity > +-r-------- 1 root root 4096 Jun 28 20:27 max_intensity > +-r-------- 1 root root 4096 Jun 28 20:21 color_id > + > +colors/red: > +-rw------- 1 root root 4096 Jun 28 20:21 intensity > +-r-------- 1 root root 4096 Jun 28 20:27 max_intensity > +-r-------- 1 root root 4096 Jun 28 20:21 color_id > + > +Multicolor Color Mixing > +----------------------- > +Multicolor monochrome LEDs intensity can be modified and mixed to produce a > +varying array of colors. The color_mix file gives the user the ability to write > +all the monochrome LEDs registered in the directory with a single call. > +To create a specific color from monochrome LEDs the color_mix file needs to be > +written with each color's intensity. The order in which the monochrome LEDs > +should be written is based on the colors color_id. > + > +For example: > +cat /sys/class/leds/rgb:grouped_leds/red/color_id > +0 > +cat /sys/class/leds/rgb:grouped_leds/green/color_id > +1 > +cat /sys/class/leds/rgb:grouped_leds/blue/color_id > +2 > + > +red - color_id = 0 > +green - color_id = 1 > +blue - color_id = 2 > + > +These id's are the order in which to write the color_mix file. > + > +echo "<red> <green> <blue>" > color_mix > + > +echo "0x80 0x00 0x80" > color_mix > + > +The order of the monochrome LEDs are determined during multicolor class > +registration and will not change unless unregistered and re-registered. > + > +Other example with amber monochrome LED: > +blue - color_id = 0 > +amber - color_id = 1 > + > +In this exampe blue is at ID 0 and amber ID is 1 so the user would write > +echo "<blue> <amber>" > color_mix > + > +echo "0x38 0x80" > color_mix > + > +If a single monochrome LED needs to be modified then the user would write the > +colors/<color>/intensity file. > + > + > +Multicolor Class Brightness Control > +----------------------------------- > +The multiclor class framework will calculate each monochrome LEDs intensity. > + > +The brightness level for each LED is calculated based on the color LED > +intensity setting divided by the color LED max intensity setting multiplied by > +the requested value. > + > +led_brightness = requested_value*(led_color_intensity/led_color_max_intensity) Please drop parentheses here as pointed out before in the code review. > + > +Example: > +Three LEDs are present in the group as defined in "Directory Layout Example" > +within this document. > + > +A user first writes the color LED brightness file with the brightness level that > +is neccesary to achieve a blueish violet output from the RGB LED group. > + > +echo 138 > /sys/class/leds/rgb:grouped_leds/red/intensity > +echo 43 > /sys/class/leds/rgb:grouped_leds/green/intensity > +echo 226 > /sys/class/leds/rgb:grouped_leds/blue/intensity > + > +red - > + intensity = 138 > + max_intensity = 255 > +green - > + intensity = 43 > + max_intensity = 255 > +blue - > + intensity = 226 > + max_intensity = 255 > + > +The user can control the brightness of that RGB group by writing the parent > +'brightness' control. Assuming a parent max_brightness of 255 the user may want > +to dim the LED color group to half. The user would write a value of 128 to the > +parent brightness file then the values written to each LED will be adjusted > +base on this value We probably need to state here that any amendment to color intensity values resets brightness to its max value. > +cat /sys/class/leds/rgb:grouped_leds/max_brightness > +255 > +echo 128 > /sys/class/leds/rgb:grouped_leds/brightness > + > +adjusted_red_value = 128 * (138/255) = 69 > +adjusted_green_value = 128 * (43/255) = 21 > +adjusted_blue_value = 128 * (226/255) = 113 Drop parentheses. > + > +Reading the parent brightness file will return the current brightness value of > +the color LED group. > + > +cat /sys/class/leds/rgb:grouped_leds/max_brightness > +255 > + > +echo 128 > /sys/class/leds/rgb:grouped_leds/brightness > + > +cat /sys/class/leds/rgb:grouped_leds/max_brightness > +128 > + > + > -- Best regards, Jacek Anaszewski
