diff mbox series

[v5,2/9] documention: leds: Add multicolor class documentation

Message ID 20190911180115.21035-3-dmurphy@ti.com
State New
Headers show
Series None | expand

Commit Message

Dan Murphy Sept. 11, 2019, 6:01 p.m. UTC 
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>

---
 Documentation/leds/index.rst                 |   1 +
 Documentation/leds/leds-class-multicolor.rst | 149 +++++++++++++++++++
 2 files changed, 150 insertions(+)
 create mode 100644 Documentation/leds/leds-class-multicolor.rst

-- 
2.22.0.214.g8dca754b1e

Comments

Pavel Machek Sept. 12, 2019, 8:55 p.m. UTC | #1 
Hi!

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


I don't really like the directories... A bit too much complexity, and
it will have a memory footprint, too.

I'd expect max_intensity to be same for all the leds in
rgb:grouped_leds... Could we simply rely on max_brightness file?

[If not, would one "max_intensity" file in rgb:grouped_leds be
enough?]

Best regards,
							Pavel
							
-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
Dan Murphy Sept. 13, 2019, 2:09 a.m. UTC | #2 
Hello Pavel

Thanks for looking at this again

On 9/12/19 3:55 PM, Pavel Machek wrote:
> Hi!

>

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

> I don't really like the directories... A bit too much complexity, and

> it will have a memory footprint, too.


The directories should be fine to have I am not seeing the complexity. 
Is memory footprint really an issue? Maybe in the IoT space but this is 
small and memory footprint should be able to handle this for IoT and 
larger systems.

Having dedicated directories and files clears up issues for user space 
to know about the parameters for each LED especially with the color_mix 
file which I still am not a fan of, but conceded and implemented 
anyway.  It also gives the user space flexibility to call the monochrome 
LEDs specific intensity file.  The user space can either use the color 
intensity file or the color_mix file it is a choice for them to make.

This code was modeled off the LP50xx device which has individual LED 
intensity controls as well as a overall brightness control. Since we 
have no feedback from user space folks I feel we have to give some 
options not very many but some.

>

> I'd expect max_intensity to be same for all the leds in

> rgb:grouped_leds... Could we simply rely on max_brightness file?


I went under the assumption that not all grouped LEDs would have the 
same max_intensity.

I don't have specific use cases but wanted this as an option.

Dan

> [If not, would one "max_intensity" file in rgb:grouped_leds be

> enough?]

>

> Best regards,

> 							Pavel

>
Jacek Anaszewski Sept. 15, 2019, 12:45 p.m. UTC | #3 
On 9/12/19 10:55 PM, Pavel Machek wrote:
> Hi!

> 

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

> 

> I don't really like the directories... A bit too much complexity, and

> it will have a memory footprint, too.


We will need separate intensity files for each color anyway so separate
max_brightness can go along in the sub-dir - it will be cleaner this
way and will leave some flexibility regarding max intensity supported
by the LED.

And I'm saying about the need for separate intensity files because
I've changed my mind regarding color_mix file, basing on the recent
experience with trigger file PAGE_SIZE limit rework. That said, I am
no longer eager to accept any exception for one-value-per-file rule.

This of course render color_mix file format unacceptable. In a new
approach intensity files will only cache the values and actual write
to registers will occur on write to the brightness file.

> I'd expect max_intensity to be same for all the leds in

> rgb:grouped_leds... Could we simply rely on max_brightness file?

This may not be necessarily true if one will add gpio LED
to the cluster of PWM LEDs.

> [If not, would one "max_intensity" file in rgb:grouped_leds be

> enough?]

> 

> Best regards,

> 							Pavel

> 							

> 


-- 
Best regards,
Jacek Anaszewski
diff mbox series

Patch

diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst
index 060f4e485897..bc70c6aa7138 100644
--- a/Documentation/leds/index.rst
+++ b/Documentation/leds/index.rst
@@ -9,6 +9,7 @@  LEDs
 
    leds-class
    leds-class-flash
+   leds-class-multicolor
    ledtrig-oneshot
    ledtrig-transient
    ledtrig-usbport
diff --git a/Documentation/leds/leds-class-multicolor.rst b/Documentation/leds/leds-class-multicolor.rst
new file mode 100644
index 000000000000..0b40c85f417a
--- /dev/null
+++ b/Documentation/leds/leds-class-multicolor.rst
@@ -0,0 +1,149 @@ 
+====================================
+Multi Color LED handling under Linux
+====================================
+
+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.rst within this
+documentation directory.
+
+Each colored LED is given its own directory.  These directories will be one of
+LED_COLOR_ID_* definitions from the header include/dt-bindings/leds/common.h.
+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.  The LEDs brightness will be
+updated on the next call to the parent brightness file.
+
+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 "80 00 80" > 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 example blue is at ID 0 and amber ID is 1 so the user would write
+echo "<blue> <amber>" > color_mix
+
+echo "38 80" > 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
+
+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 necessary 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
+
+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