[PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

Add documentation and example for dt-bindings EL15203000.
LED board (aka RED LED board) from Crane Merchandising Systems.

Signed-off-by: Oleh Kravchenko <oleg@kaa.org.ua>
---
 .../bindings/leds/leds-el15203000.txt         | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/leds/leds-el15203000.txt

diff --git a/Documentation/devicetree/bindings/leds/leds-el15203000.txt b/Documentation/devicetree/bindings/leds/leds-el15203000.txt
new file mode 100644
index 000000000000..457fd8d7226f
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-el15203000.txt
@@ -0,0 +1,53 @@
+Crane Merchandising System - el15203000 LED driver
+--------------------------------------------------
+
+This LED Board (aka RED LEDs board) is widely used in coffee vending machines
+produced by Crane Merchandising Systems.
+
+Required properties:
+- compatible : "crane,el15203000"
+- reg :
+	see Documentation/devicetree/bindings/spi/spi-bus.txt
+- spi-max-frequency : (optional)
+	see Documentation/devicetree/bindings/spi/spi-bus.txt
+
+LED sub-node properties:
+- label :
+	see Documentation/devicetree/bindings/leds/common.txt
+- linux,default-trigger : (optional)
+	see Documentation/devicetree/bindings/leds/common.txt
+- max-brightness : (optional)
+	Specify here 2 if LED has special effect. Effects by LED type:
+	- Pipe has leaking
+	- Screen Frame has blinking
+
+Example
+-------
+
+led-controller@0 {
+	compatible = "crane,el15203000";
+	reg = <0>;
+	spi-max-frequency = <50000>;
+	#address-cells = <1>;
+	#size-cells = <0>;
+
+	/* water pipe */
+	pipe@50 {
+		reg = <0x50>;
+		label = "red:pipe";
+		max-brightness = <2>;
+	};
+
+	/* screen frame */
+	screen@53 {
+		reg = <0x53>;
+		label = "red:screen";
+		max-brightness = <2>;
+	};
+
+	/* vending area */
+	vend@56 {
+		reg = <0x56>;
+		label = "red:vend";
+	};
+};
-- 
2.21.0

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Dan Murphy]

Oleh

On 6/7/19 1:40 PM, Oleh Kravchenko wrote:
> Add documentation and example for dt-bindings EL15203000.
> LED board (aka RED LED board) from Crane Merchandising Systems.
>
> Signed-off-by: Oleh Kravchenko <oleg@kaa.org.ua>
> ---
>   .../bindings/leds/leds-el15203000.txt         | 53 +++++++++++++++++++
>   1 file changed, 53 insertions(+)
>   create mode 100644 Documentation/devicetree/bindings/leds/leds-el15203000.txt
>
> diff --git a/Documentation/devicetree/bindings/leds/leds-el15203000.txt b/Documentation/devicetree/bindings/leds/leds-el15203000.txt
> new file mode 100644
> index 000000000000..457fd8d7226f
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/leds/leds-el15203000.txt
> @@ -0,0 +1,53 @@
> +Crane Merchandising System - el15203000 LED driver
> +--------------------------------------------------
> +
> +This LED Board (aka RED LEDs board) is widely used in coffee vending machines
> +produced by Crane Merchandising Systems.
> +
> +Required properties:
> +- compatible : "crane,el15203000"
> +- reg :
> +	see Documentation/devicetree/bindings/spi/spi-bus.txt
> +- spi-max-frequency : (optional)
> +	see Documentation/devicetree/bindings/spi/spi-bus.txt
> +
> +LED sub-node properties:
> +- label :
> +	see Documentation/devicetree/bindings/leds/common.txt

Add this

Optional LED sub-node properties:

And remove (optional) from the below.

> +- linux,default-trigger : (optional)
> +	see Documentation/devicetree/bindings/leds/common.txt
> +- max-brightness : (optional)
> +	Specify here 2 if LED has special effect. Effects by LED type:

s/Specify here 2/Specify 2

But this is not really max_brightness now this is a feature and now does 
not make sense in this context

You may need to use something different for this property or expose a 
file in the driver.


> +	- Pipe has leaking
> +	- Screen Frame has blinking
> +
> +Example
> +-------
> +
> +led-controller@0 {
> +	compatible = "crane,el15203000";
> +	reg = <0>;
> +	spi-max-frequency = <50000>;
> +	#address-cells = <1>;
> +	#size-cells = <0>;
> +
> +	/* water pipe */
> +	pipe@50 {
> +		reg = <0x50>;
> +		label = "red:pipe";
> +		max-brightness = <2>;
> +	};
> +
> +	/* screen frame */
> +	screen@53 {
> +		reg = <0x53>;
> +		label = "red:screen";
> +		max-brightness = <2>;
> +	};
> +
> +	/* vending area */
> +	vend@56 {
> +		reg = <0x56>;
> +		label = "red:vend";
> +	};
> +};

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

[-- Attachment #1.1: Type: text/plain, Size: 961 bytes --]



07.06.19 23:14, Dan Murphy пише:
> Oleh
> 
> On 6/7/19 1:40 PM, Oleh Kravchenko wrote:
>> +LED sub-node properties:
>> +- label :
>> +    see Documentation/devicetree/bindings/leds/common.txt
> 
> Add this
> 
> Optional LED sub-node properties:
> 
> And remove (optional) from the below.
> 

Done

>> +- linux,default-trigger : (optional)
>> +    see Documentation/devicetree/bindings/leds/common.txt
>> +- max-brightness : (optional)
>> +    Specify here 2 if LED has special effect. Effects by LED type:
> 
> s/Specify here 2/Specify 2
> 

Done

> But this is not really max_brightness now this is a feature and now does not make sense in this context
> 
> You may need to use something different for this property or expose a file in the driver.
> 
> 

Protocol for this board define 0x32 as brightness level.
This behaviur needed to keep backward compatibity.


-- 
Best regards,
Oleh Kravchenko



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Dan Murphy]

Oleh

On 6/7/19 3:53 PM, Oleh Kravchenko wrote:
>
> 07.06.19 23:14, Dan Murphy пише:
>> Oleh
>>
>> On 6/7/19 1:40 PM, Oleh Kravchenko wrote:
>>> +LED sub-node properties:
>>> +- label :
>>> +    see Documentation/devicetree/bindings/leds/common.txt
>> Add this
>>
>> Optional LED sub-node properties:
>>
>> And remove (optional) from the below.
>>
> Done
>
>>> +- linux,default-trigger : (optional)
>>> +    see Documentation/devicetree/bindings/leds/common.txt
>>> +- max-brightness : (optional)
>>> +    Specify here 2 if LED has special effect. Effects by LED type:
>> s/Specify here 2/Specify 2
>>
> Done
>
>> But this is not really max_brightness now this is a feature and now does not make sense in this context
>>
>> You may need to use something different for this property or expose a file in the driver.
>>
>>
> Protocol for this board define 0x32 as brightness level.
> This behaviur needed to keep backward compatibity.
>
>
Backwards compatibility to what?

This is a new driver there should be no DT that has this compatible or 
definition.

I will let Rob ack or nack this node.

Dan

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

[-- Attachment #1.1: Type: text/plain, Size: 614 bytes --]

Dan,

On 08.06.19 00:04, Dan Murphy wrote:
> Oleh
> But this is not really max_brightness now this is a feature and now
> does not make sense in this context
>>>
>>> You may need to use something different for this property or expose
>>> a file in the driver.
>>>
>>>
>> Protocol for this board define 0x32 as brightness level.
>> This behaviur needed to keep backward compatibity.
>>
>>
> Backwards compatibility to what?
With old/new boards.
>
> This is a new driver there should be no DT that has this compatible or
> definition.
>
> I will let Rob ack or nack this node.
>
> Dan
>



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Jacek Anaszewski]

Hi Oleh.

On 6/7/19 11:17 PM, Oleh Kravchenko wrote:
> Dan,
> 
> On 08.06.19 00:04, Dan Murphy wrote:
>> Oleh
>> But this is not really max_brightness now this is a feature and now
>> does not make sense in this context
>>>>
>>>> You may need to use something different for this property or expose
>>>> a file in the driver.
>>>>
>>>>
>>> Protocol for this board define 0x32 as brightness level.
>>> This behaviur needed to keep backward compatibity.
>>>
>>>
>> Backwards compatibility to what?
> With old/new boards.

You have in your driver the following:

+ * BRIGHTNESS	Can be 0x30 (OFF), 0x31 (ON).
+ * 		0x32 (Effect) can be used for 0x50 (leaking) and
+ * 		for 0x53 (blinking)

If your max-brightness DT property is to be used for controlling this,
then I don't see how it would be backward compatible with anything.

Clearly, you don't need max-brightness DT property at all.

For blinking you can use blink_set op. To be able to recommend
you anoptimal solution for the effect we would need more
details regarding its nature.

>> This is a new driver there should be no DT that has this compatible or
>> definition.
>>
>> I will let Rob ack or nack this node.
>>
>> Dan
>>
> 
> 

-- 
Best regards,
Jacek Anaszewski

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Dan Murphy]

Oleh

On 6/7/19 4:17 PM, Oleh Kravchenko wrote:
> Dan,
>
> On 08.06.19 00:04, Dan Murphy wrote:
>> Oleh
>> But this is not really max_brightness now this is a feature and now
>> does not make sense in this context
>>>> You may need to use something different for this property or expose
>>>> a file in the driver.
>>>>
>>>>
>>> Protocol for this board define 0x32 as brightness level.
>>> This behaviur needed to keep backward compatibity.
>>>
>>>
>> Backwards compatibility to what?
> With old/new boards.

This does not make sense.

How would a device tree entry or a file that controls the blinking have 
to deal with the hardware?

If it allows feature setting then you should create a bool in the device 
tree.

el15203000-blink;

If the board supports the feature you set this and create a file to 
dis/enable the feature.

If the board does not support it then no file is created.

max_brightness for this device appears to be 1.

Dan


>> This is a new driver there should be no DT that has this compatible or
>> definition.
>>
>> I will let Rob ack or nack this node.
>>
>> Dan
>>
>

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

[-- Attachment #1.1: Type: text/plain, Size: 1842 bytes --]

Jacek,

08.06.19 00:23, Jacek Anaszewski пише:
> Hi Oleh.
> 
> On 6/7/19 11:17 PM, Oleh Kravchenko wrote:
>> Dan,
>>
>> On 08.06.19 00:04, Dan Murphy wrote:
>>> Oleh
>>> But this is not really max_brightness now this is a feature and now
>>> does not make sense in this context
>>>>>
>>>>> You may need to use something different for this property or expose
>>>>> a file in the driver.
>>>>>
>>>>>
>>>> Protocol for this board define 0x32 as brightness level.
>>>> This behaviur needed to keep backward compatibity.
>>>>
>>>>
>>> Backwards compatibility to what?
>> With old/new boards.
> 
> You have in your driver the following:
> 
> + * BRIGHTNESS    Can be 0x30 (OFF), 0x31 (ON).
> + *         0x32 (Effect) can be used for 0x50 (leaking) and
> + *         for 0x53 (blinking)
> 
> If your max-brightness DT property is to be used for controlling this,
> then I don't see how it would be backward compatible with anything.
> 
> Clearly, you don't need max-brightness DT property at all.

What I should do with board which accept brightness in range 0x30 - 0x3a?
Where 0x3a means special effect.

> 
> For blinking you can use blink_set op. To be able to recommend
> you anoptimal solution for the effect we would need more
> details regarding its nature.

Thanks, I will do that.
But how to properly handle other effects? Not only blinking?

And how to define it by device tree?
Driver can't get this information about what is really supported.
I don't want define effect code inside DT.

 
>>> This is a new driver there should be no DT that has this compatible or
>>> definition.
>>>
>>> I will let Rob ack or nack this node.
>>>
>>> Dan
>>>
>>
>>
> 

-- 
Best regards,
Oleh Kravchenko
Phone: +380972763224 | oleg@kaa.org.ua | Skype: oleg_krava


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

[-- Attachment #1.1: Type: text/plain, Size: 853 bytes --]

Hello Jacek,

08.06.19 00:48, Oleh Kravchenko пише:
> Jacek,
> 
>> For blinking you can use blink_set op. To be able to recommend
>> you anoptimal solution for the effect we would need more
>> details regarding its nature.
> 
> Thanks, I will do that.
> But how to properly handle other effects? Not only blinking?

	int		(*blink_set)(struct led_classdev *led_cdev,
				     unsigned long *delay_on,
				     unsigned long *delay_off);

My LED board doesn't support any delay settings at all.
Should I always set delay_on, delay_off to zero?

 
> And how to define it by device tree?
> Driver can't get this information about what is really supported.
> I don't want define effect code inside DT.
> 
>  
>>>> This is a new driver there should be no DT that has this compatible or

-- 
Best regards,
Oleh Kravchenko



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Jacek Anaszewski]

Hi Oleh,

On 6/7/19 11:48 PM, Oleh Kravchenko wrote:
> Jacek,
> 
> 08.06.19 00:23, Jacek Anaszewski пише:
>> Hi Oleh.
>>
>> On 6/7/19 11:17 PM, Oleh Kravchenko wrote:
>>> Dan,
>>>
>>> On 08.06.19 00:04, Dan Murphy wrote:
>>>> Oleh
>>>> But this is not really max_brightness now this is a feature and now
>>>> does not make sense in this context
>>>>>>
>>>>>> You may need to use something different for this property or expose
>>>>>> a file in the driver.
>>>>>>
>>>>>>
>>>>> Protocol for this board define 0x32 as brightness level.
>>>>> This behaviur needed to keep backward compatibity.
>>>>>
>>>>>
>>>> Backwards compatibility to what?
>>> With old/new boards.
>>
>> You have in your driver the following:
>>
>> + * BRIGHTNESS    Can be 0x30 (OFF), 0x31 (ON).
>> + *         0x32 (Effect) can be used for 0x50 (leaking) and
>> + *         for 0x53 (blinking)
>>
>> If your max-brightness DT property is to be used for controlling this,
>> then I don't see how it would be backward compatible with anything.
>>
>> Clearly, you don't need max-brightness DT property at all.
> 
> What I should do with board which accept brightness in range 0x30 - 0x3a?
> Where 0x3a means special effect.

I believe 0x3a is a typo since above you have 0x32 for the effect.

Anyway, we shouldn't propagate hardware design flaws to the userspace
interface. You have ON/OFF register values for manipulating brightness,
so use them appropriately. struct led_classdev's max_brightness property
should be set to 1, as already pointed out by Dan.

>> For blinking you can use blink_set op. To be able to recommend
>> you anoptimal solution for the effect we would need more
>> details regarding its nature.
> 
> Thanks, I will do that.
> But how to properly handle other effects? Not only blinking?

For the effects we could probably use pattern trigger, but we need
more information on how it can be configured.

> And how to define it by device tree?
> Driver can't get this information about what is really supported.
> I don't want define effect code inside DT.

We now have led-pattern DT property, which allows to initialize a LED
with the DT provided pattern
(see Documentation/devicetree/bindings/leds/common.txt).

>>>> This is a new driver there should be no DT that has this compatible or
>>>> definition.
>>>>
>>>> I will let Rob ack or nack this node.
>>>>
>>>> Dan
>>>>
>>>
>>>
>>
> 

-- 
Best regards,
Jacek Anaszewski

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

[-- Attachment #1.1: Type: text/plain, Size: 2253 bytes --]

Hello Jacek,

11.06.19 22:52, Jacek Anaszewski пише:
> On 6/11/19 2:01 PM, Pavel Machek wrote:
>> Hi!
>>
>>>> I just want to clerify - for now LEDs board has 2 from 3 LEDs with effect function.
>>>>
>>>> 1. Screen frame led is just blinking, so blink_set() is fit well to this.
>>>> 2. Pipe led actually consist from 3 leds and when effect is enabled next pattern is used:
>>>>
>>>>        ^
>>>>        |
>>>> LED1  >   OFF  ON   ON   ON
>>>>        |
>>>> LED2  >   OFF  OFF  ON   ON
>>>>        |
>>>> LED3  >   OFF  OFF  OFF  ON
>>>>        |
>>>>        +----^----^----^----^----> time
>>>
>>> Pattern trigger applies to a single LED so it won't fit for this
>>> pattern.
>>>
>>> Currently we don't support patterns spanning on multiple LEDs,
>>> so you would have to come up with your own solution.
>>>
>>> What I can recommend is a trigger that would be created by your driver
>>> and would activate this sequence.
>>
>> Yes, please.
>>
>> While adding custom files to sysfs may appear easier, we'll need
>> "led-specific-triggers" for other reasons.
> 
> For what reasons exactly?
> 
> This is similar to the generic hw trigger support proposed by
> Marek Behun. In the reply to that patch I asked some questions [0].
> So far the mechanism looks too me awkward and not introducing any
> novelty besides requiring one more step - setting the trigger.
> 
>> And for the record... Handling 3 LEDs as one is not something usual in
>> the LED subsystem; I guess it makes sense in your specific case, but
>> hopefully noone will copy that design.
>>
>> (I guess they are not individually controllable?)
>>
>>                                     Pavel
>>
> 
> [0] https://www.spinics.net/lists/linux-leds/msg12269.html
> 

I just figure out that this Pipe LED actually consist from 5 LEDs, not 3 :)
And supports next level 'brightness' from SPI driver:
- '0' Off
- '1' On
- '2' Cascade (waterfall down)
 -'3' InverseCascade (waterfall up)
- '4' Bounce
- '5' InverseBounce

Please advice, can I proceed with sys attribute file to set '2'..'5' levels?

-- 
Best regards,
Oleh Kravchenko


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Jacek Anaszewski]

Hi Oleh,

On 7/9/19 12:00 AM, Oleh Kravchenko wrote:
> Hello Jacek,
> 
> 11.06.19 22:52, Jacek Anaszewski пише:
>> On 6/11/19 2:01 PM, Pavel Machek wrote:
>>> Hi!
>>>
>>>>> I just want to clerify - for now LEDs board has 2 from 3 LEDs with effect function.
>>>>>
>>>>> 1. Screen frame led is just blinking, so blink_set() is fit well to this.
>>>>> 2. Pipe led actually consist from 3 leds and when effect is enabled next pattern is used:
>>>>>
>>>>>        ^
>>>>>        |
>>>>> LED1  >   OFF  ON   ON   ON
>>>>>        |
>>>>> LED2  >   OFF  OFF  ON   ON
>>>>>        |
>>>>> LED3  >   OFF  OFF  OFF  ON
>>>>>        |
>>>>>        +----^----^----^----^----> time
>>>>
>>>> Pattern trigger applies to a single LED so it won't fit for this
>>>> pattern.
>>>>
>>>> Currently we don't support patterns spanning on multiple LEDs,
>>>> so you would have to come up with your own solution.
>>>>
>>>> What I can recommend is a trigger that would be created by your driver
>>>> and would activate this sequence.
>>>
>>> Yes, please.
>>>
>>> While adding custom files to sysfs may appear easier, we'll need
>>> "led-specific-triggers" for other reasons.
>>
>> For what reasons exactly?
>>
>> This is similar to the generic hw trigger support proposed by
>> Marek Behun. In the reply to that patch I asked some questions [0].
>> So far the mechanism looks too me awkward and not introducing any
>> novelty besides requiring one more step - setting the trigger.
>>
>>> And for the record... Handling 3 LEDs as one is not something usual in
>>> the LED subsystem; I guess it makes sense in your specific case, but
>>> hopefully noone will copy that design.
>>>
>>> (I guess they are not individually controllable?)
>>>
>>>                                     Pavel
>>>
>>
>> [0] https://www.spinics.net/lists/linux-leds/msg12269.html
>>
> 
> I just figure out that this Pipe LED actually consist from 5 LEDs, not 3 :)
> And supports next level 'brightness' from SPI driver:
> - '0' Off
> - '1' On
> - '2' Cascade (waterfall down)
>  -'3' InverseCascade (waterfall up)
> - '4' Bounce
> - '5' InverseBounce
> 
> Please advice, can I proceed with sys attribute file to set '2'..'5' levels?

It looks like pattern trigger is the most appropriate solution for the
effects 2-5. Your driver will need to implement pattern_set op for the
LEDs supporting the effects, and then the effect will be enabled after
writing required sequence to the hw_pattern file. You will need to come
up with a sequence of values that the driver will recognize as a request
of enabling given hardware effect. Please compare
drivers/leds/leds-sc27xx-bltc.c and its ABI documentation [0] for
reference. See also hw_pattern file description in [1].

[0] Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
[1] Documentation/ABI/testing/sysfs-class-led-trigger-pattern

-- 
Best regards,
Jacek Anaszewski

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

Thank you for advice!

16.07.19 21:41, Jacek Anaszewski пише:
> Hi Oleh,
>
> On 7/9/19 12:00 AM, Oleh Kravchenko wrote:
>>
>> I just figure out that this Pipe LED actually consist from 5 LEDs, not 3 :)
>> And supports next level 'brightness' from SPI driver:
>> - '0' Off
>> - '1' On
>> - '2' Cascade (waterfall down)
>>  -'3' InverseCascade (waterfall up)
>> - '4' Bounce
>> - '5' InverseBounce
>>
>> Please advice, can I proceed with sys attribute file to set '2'..'5' levels?
> It looks like pattern trigger is the most appropriate solution for the
> effects 2-5. Your driver will need to implement pattern_set op for the
> LEDs supporting the effects, and then the effect will be enabled after
> writing required sequence to the hw_pattern file. You will need to come
> up with a sequence of values that the driver will recognize as a request
> of enabling given hardware effect. Please compare
> drivers/leds/leds-sc27xx-bltc.c and its ABI documentation [0] for
> reference. See also hw_pattern file description in [1].
>
> [0] Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
> [1] Documentation/ABI/testing/sysfs-class-led-trigger-pattern
>