Re: [PATCH v5 1/3] dt-bindings: input: microchip,cap11xx: add advanced sensitivity settings

[Jiri Valek - 2N <jiriv@axis.com>]

On 11/10/23 09:22, Krzysztof Kozlowski wrote:
> On 08/11/2023 16:56, Jiri Valek - 2N wrote:
>> Add support for advanced sensitivity settings and signal guard feature.
>>
>> Signed-off-by: Jiri Valek - 2N <jiriv@axis.com>
>> ---
>>  .../bindings/input/microchip,cap11xx.yaml     | 76 ++++++++++++++++++-
>>  1 file changed, 73 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/devicetree/bindings/input/microchip,cap11xx.yaml b/Documentation/devicetree/bindings/input/microchip,cap11xx.yaml
>> index 5b5d4f7d3482..aa97702c43ef 100644
>> --- a/Documentation/devicetree/bindings/input/microchip,cap11xx.yaml
>> +++ b/Documentation/devicetree/bindings/input/microchip,cap11xx.yaml
>> @@ -45,13 +45,13 @@ properties:
>>        Enables the Linux input system's autorepeat feature on the input device.
>>  
>>    linux,keycodes:
>> -    minItems: 6
>> -    maxItems: 6
>> +    minItems: 3
>> +    maxItems: 8
>>      description: |
>>        Specifies an array of numeric keycode values to
>>        be used for the channels. If this property is
>>        omitted, KEY_A, KEY_B, etc are used as defaults.
>> -      The array must have exactly six entries.
>> +      The number of entries must correspond to the number of channels.
>>  
>>    microchip,sensor-gain:
>>      $ref: /schemas/types.yaml#/definitions/uint32
>> @@ -70,6 +70,55 @@ properties:
>>        open drain. This property allows using the active
>>        high push-pull output.
>>  
>> +  microchip,sensitivity-delta-sense:
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    default: 32
>> +    enum: [1, 2, 4, 8, 16, 32, 64, 128]
>> +    description:
>> +      Optional parameter. Controls the sensitivity multiplier of a touch detection.
>> +      At the more sensitive settings, touches are detected for a smaller delta
> 
> Which values are more sensitive?

Higher value means more sensitive settings.
I will add this line to description.

> 
>> +      capacitance corresponding to a “lighter” touch.
> 
> Looks like you use some non-ASCII characters for ".

I will fix it.

> 
>> +
>> +  microchip,signal-guard:
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    minItems: 3
>> +    maxItems: 8
>> +    items:
>> +      minimum: 0
>> +      maximum: 1
>> +    description: |
>> +      Optional parameter supported only for CAP129x.
>> +      0 - off
>> +      1 - on
>> +      The signal guard isolates the signal from virtual grounds.
>> +      If enabled then the behavior of the channel is changed to signal guard.
>> +      The number of entries must correspond to the number of channels.
>> +
>> +  microchip,input-treshold:
> 
> typo: threshold

I will fix it in Documentation and also in source code.
Copy paste error...

> 
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    minItems: 3
>> +    maxItems: 8
>> +    items:
>> +      minimum: 0
>> +      maximum: 127
>> +    description:
>> +      Optional parameter. Specifies the delta threshold that is used to
> 
> Drop everywhere the "optional parameter". It's redundant. required:
> block tells what is / is not optional.

OK will be fixed.

> 
>> +      determine if a touch has been detected.
> 
> In what units are the values?

According to the datasheet it is dimensionless, no more info.
A higher value means a larger difference in capacitance is required for a touch to be registered.

> 
>> +      The number of entries must correspond to the number of channels.
>> +
>> +  microchip,calib-sensitivity:
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    minItems: 3
>> +    maxItems: 8
>> +    items:
>> +      minimum: 1
>> +      maximum: 4
>> +    description:
>> +      Optional parameter supported only for CAP129x. Specifies an array of
>> +      numeric values that controls the gain used by the calibration routine to
>> +      enable sensor inputs to be more sensitive for proximity detection.
> 
> Gain is usually in dB, isn't it?

Usually yes, but again there are no units in datasheet.
There is note that gain is based on capacitance touch pad capacitance range
1 - 5-50pF
2 - 0-25pF 
4 - 0-12.5pF
I will add this to description and change items to enum: [1, 2, 4]

> 
>> +      The number of entries must correspond to the number of channels.
>> +
>>  patternProperties:
>>    "^led@[0-7]$":
> 
> 
> Best regards,
> Krzysztof
> 

So are these changes fine for you?
If yes I prepare new patch revision.

Best regards,
Jiri