[PATCH v4 1/2] leds: multicolor: Add sysfs interface definition

[PATCH v4 1/2] leds: multicolor: Add sysfs interface definition

[Dan Murphy]

Add a documentation of LED Multicolor LED class specific
sysfs attributes.

Signed-off-by: Dan Murphy <dmurphy@ti.com>
---

v4 - Add LED class parent brightness definition to the text - https://lore.kernel.org/patchwork/patch/1078398/

 .../ABI/testing/sysfs-class-led-multicolor    | 74 +++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-led-multicolor

diff --git a/Documentation/ABI/testing/sysfs-class-led-multicolor b/Documentation/ABI/testing/sysfs-class-led-multicolor
new file mode 100644
index 000000000000..ec2b6ac63ecc
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-multicolor
@@ -0,0 +1,74 @@
+What:		/sys/class/leds/<led>/brightness
+Date:		April 2019
+KernelVersion:	5.2
+Contact:	Dan Murphy <dmurphy@ti.com>
+Description:	read/write
+		The multicolor class will redirect the device drivers call back
+		function for brightness control to the multicolor class
+		brightness control function.
+
+		Writing to this file will update all LEDs within the group to a
+		calculated percentage of what each color LED in the group is set
+		to.  Please refer to the leds-class-multicolor.txt in the
+		Documentation directory for a complete description.
+
+		The value of the color is from 0 to
+		/sys/class/leds/<led>/max_brightness.
+
+What:		/sys/class/leds/<led>/colors/sync_enable
+Date:		April 2019
+KernelVersion:	5.2
+Contact:	Dan Murphy <dmurphy@ti.com>
+Description:	read/write
+		Writing a 1 to this file will enable the synchronization of all
+		the defined color LEDs within the LED node.  Brightness values
+		for each LED will be stored and written when sync is set to 1.
+		Writing a 0 to this file will disable syncing and allow
+		individual control of the LEDs brightness settings.
+
+What:		/sys/class/leds/<led>/colors/sync
+Date:		April 2019
+KernelVersion:	5.2
+Contact:	Dan Murphy <dmurphy@ti.com>
+Description:	write only
+		Writing a 1 to this file while sync_enable is set to 1 will
+		write the current brightness values to all defined LEDs within
+		the LED node.  All LEDs defined will be configured based
+		on the brightness that has been requested.
+
+		If sync_enable is set to 0 then writing a 1 to sync has no
+		affect on the LEDs.
+
+What:		/sys/class/leds/<led>/colors/<led_color>/brightness
+Date:		April 2019
+KernelVersion:	5.2
+Contact:	Dan Murphy <dmurphy@ti.com>
+Description:	read/write
+		The led_color directory is dynamically created based on the
+		colors defined by the registrar of the class.
+		The led_color can be but not limited to red, green, blue,
+		white, amber, yellow and violet.  Drivers can also declare a
+		LED color for presentation.  There is one directory per color
+		presented.  The brightness file is created under each
+		led_color directory and controls the individual LED color
+		setting.
+
+		If sync is enabled then	writing the brightness value of the LED
+		is deferred until a 1 is written to
+		/sys/class/leds/<led>/color/sync.  If syncing is
+		disabled then the LED brightness value will be written
+		immediately to the LED driver.
+
+		The value of the color is from 0 to
+		/sys/class/leds/<led>/colors/<led_color>/max_brightness.
+
+What:		/sys/class/leds/<led>/colors/<led_color>/max_brightness
+Date:		April 2019
+KernelVersion:	5.2
+Contact:	Dan Murphy <dmurphy@ti.com>
+Description:	read only
+		Maximum brightness level for the LED color, default is
+		255 (LED_FULL).
+
+		If the LED does not support different brightness levels, this
+		should be 1.
-- 
2.21.0.5.gaeb582a983

[PATCH v4 2/2] documention: leds: Add multicolor class documentation

[Dan Murphy]

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@ti.com>
---

v4 - Add LED class parent brightness description - https://lore.kernel.org/patchwork/patch/1078398/

 Documentation/leds/leds-class-multicolor.txt | 159 +++++++++++++++++++
 1 file changed, 159 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..c8658a068361
--- /dev/null
+++ b/Documentation/leds/leds-class-multicolor.txt
@@ -0,0 +1,159 @@
+
+Multi Color LED handling under Linux
+=================================================
+
+Author: Dan Murphy <dmurphy@ti.com>
+
+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 brightness 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 brightness and max_brightness files are presented for each LED.
+
+Under the "colors" directory there are two files created: "sync" and
+"sync_enable". The sync_enable file controls whether the LED brightness
+value is set real time or if the LED brightness value setting is deferred until
+the "sync" file is written.  If sync_enable is set then writing to each LED
+"brightness" file will store the brightness value.  Once the "sync" file is
+written then each LED color defined in the node will write the brightness of
+the LED in the device driver.
+
+If "sync_enable" is not set then writing the brightness value of the LED to the
+device driver is done immediately.  Writing the "sync" file has no affect.
+
+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
+--w-------    1 root     root          4096 Jun 28 20:21 sync
+-rw-------    1 root     root          4096 Jun 28 20:22 sync_enable
+
+colors/blue:
+-rw-------    1 root     root          4096 Jun 28 20:21 brightness
+-r--------    1 root     root          4096 Jun 28 20:27 max_brightness
+
+colors/green:
+-rw-------    1 root     root          4096 Jun 28 20:22 brightness
+-r--------    1 root     root          4096 Jun 28 20:27 max_brightness
+
+colors/red:
+-rw-------    1 root     root          4096 Jun 28 20:21 brightness
+-r--------    1 root     root          4096 Jun 28 20:27 max_brightness
+
+Example of Writing LEDs with Sync Enabled
+-----------------------------------------
+Below the red, green and blue LEDs are set to corresponding values.  These
+values are stored and not written until the sync file is written.
+
+cd /sys/class/leds/rgb:grouped_leds/colors
+
+echo 1 > sync_enable
+
+echo 100 > red/brightness
+echo 80 > green/brightness
+echo 180 > blue/brightness
+
+* LED device driver has not been updated and the LED states have not changed.
+* Writing the LED brightness files again will only change the stored value and
+* not the device driver value.
+
+echo 1 > sync
+
+* LED device driver has been updated; the LEDs should present the brightness
+* levels that have been set.  Since sync_enable is still enabled writing to the
+* LED brightness files will not change the current brightnesses.
+
+Example of Writing LEDs with Sync Disabled
+------------------------------------------
+Below the values of each LED are written to the device driver immediately upon
+request.
+
+cd /sys/class/leds/rgb:grouped_leds/colors
+
+echo 0 > sync_enable
+
+echo 100 > red/brightness // Red LED should be on with the current brightness
+echo 80 > green/brightness // Green LED should be on with the current brightness
+echo 180 > blue/brightness // Blue LED should be on with the current brightness
+.
+.
+.
+echo 0 > green/brightness // Green LED should be off
+
+Multicolor Class Brightness Control
+-----------------------------------
+The multicolor class will redirect the device drivers call back
+function for brightness control to the multicolor class brightness
+control function.
+
+The brightness level for each LED is calculated based on the color LED
+brightness setting divided by the color LED max brightness setting multiplied by
+the requested value.
+
+led_brightness = requested_value*(led_color_brightness/led_color_max_brightness)
+
+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/brightness
+echo 43 > /sys/class/leds/rgb:grouped_leds/green/brightness
+echo 226 > /sys/class/leds/rgb:grouped_leds/blue/brightness
+
+red -
+	brightness = 138
+	max_brightness = 255
+green -
+	brightness = 43
+	max_brightness = 255
+blue -
+	brightness = 226
+	max_brightness = 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
+
+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
+
+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
+
+
-- 
2.21.0.5.gaeb582a983

Re: [PATCH v4 2/2] documention: leds: Add multicolor class documentation

[Jacek Anaszewski]

[-- Attachment #1: Type: text/plain, Size: 2318 bytes --]

Hi Dan,

On 5/30/19 8:16 PM, Dan Murphy wrote:
[...]
> +Multicolor Class Brightness Control
> +-----------------------------------
> +The multicolor class will redirect the device drivers call back
> +function for brightness control to the multicolor class brightness
> +control function.
> +
> +The brightness level for each LED is calculated based on the color LED
> +brightness setting divided by the color LED max brightness setting multiplied by
> +the requested value.
> +
> +led_brightness = requested_value*(led_color_brightness/led_color_max_brightness)
> +
> +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/brightness
> +echo 43 > /sys/class/leds/rgb:grouped_leds/green/brightness
> +echo 226 > /sys/class/leds/rgb:grouped_leds/blue/brightness
> +
> +red -
> +	brightness = 138
> +	max_brightness = 255
> +green -
> +	brightness = 43
> +	max_brightness = 255
> +blue -
> +	brightness = 226
> +	max_brightness = 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
> +
> +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
> +
> +Reading the parent brightness file will return the current brightness value of
> +the color LED group.

I've tested this algorithm with python script and at least on my LED 
monitor it works as expected. Attached is the script I've come up with.

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

[-- Attachment #2: led_color.py --]
[-- Type: text/x-python, Size: 827 bytes --]

#!/usr/bin/python3.5

from PIL import Image
import sys
import time

WIDTH = 500
HEIGHT = 500

def print_usage():
        print ('Usage: led_color.py RED GREEN BLUE TOP_BRIGHTNESS')
        sys.exit(0)

def main():
    if len(sys.argv) != 5:
            print_usage()

    MAX_R = int(sys.argv[4])
    MAX_G = int(sys.argv[4])
    MAX_B = int(sys.argv[4])

    R = int(sys.argv[1])
    G = int(sys.argv[2])
    B = int(sys.argv[3])
    TB = int(sys.argv[4])

    for BR in range(1,TB+1):
        OUT_R = int(BR * R / MAX_R)
        OUT_G = int(BR * G / MAX_G)
        OUT_B = int(BR * B / MAX_B)

        print("red: {}, green: {}, blue: {}".format(OUT_R, OUT_G, OUT_B))

        img = Image.new("RGB", (WIDTH,HEIGHT), (OUT_R,OUT_G,OUT_B))
        img.show()
        time.sleep(0.1)


if __name__ == "__main__":
        main()