Re: [PATCH v4 2/4] dt-bindings: touchscreen: add overlay-touchscreen and overlay-buttons properties

[Javier Carrasco]

Hi Rob,

On 31.08.23 13:48, Rob Herring wrote:
> On Thu, Aug 24, 2023 at 03:17:10PM +0200, Javier Carrasco wrote:
>> The overlay-touchscreen object defines an area within the touchscreen
>> where touch events are reported and their coordinates get converted to
>> the overlay origin. This object avoids getting events from areas that
>> are physically hidden by overlay frames.
>>
>> For touchscreens where overlay buttons on the touchscreen surface are
>> provided, the overlay-buttons object contains a node for every button
>> and the key event that should be reported when pressed.
>>
>> Signed-off-by: Javier Carrasco <javier.carrasco@xxxxxxxxxxxxxx>
>> ---
>>  .../bindings/input/touchscreen/touchscreen.yaml    | 152 +++++++++++++++++++++
>>  1 file changed, 152 insertions(+)
>>
>> diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
>> index 895592da9626..d90cbb4932b5 100644
>> --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
>> +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
>> @@ -80,6 +80,158 @@ properties:
>>    touchscreen-y-plate-ohms:
>>      description: Resistance of the Y-plate in Ohms
>>  
>> +  overlay-touchscreen:
>> +    description: Clipped touchscreen area
>> +
>> +      This object can be used to describe a frame that restricts the area
>> +      within touch events are reported, ignoring the events that occur outside
>> +      this area. This is of special interest if the touchscreen is shipped
>> +      with a physical overlay on top of it with a frame that hides some part
>> +      of the original touchscreen area.
>> +
>> +      The x-origin and y-origin properties of this object define the offset of
>> +      a new origin from where the touchscreen events are referenced.
>> +      This offset is applied to the events accordingly. The x-size and y-size
>> +      properties define the size of the overlay-touchscreen (effective area).
>> +
>> +      The following example shows the new touchscreen area and the new origin
>> +      (0',0') for the touch events generated by the device.
>> +
>> +                   Touchscreen (full area)
>> +         ┌────────────────────────────────────────┐
>> +         │    ┌───────────────────────────────┐   │
>> +         │    │                               │   │
>> +         │    ├ y-size                        │   │
>> +         │    │                               │   │
>> +         │    │      overlay-touchscreen      │   │
>> +         │    │                               │   │
>> +         │    │                               │   │
>> +         │    │            x-size             │   │
>> +         │   ┌└──────────────┴────────────────┘   │
>> +         │(0',0')                                 │
>> +        ┌└────────────────────────────────────────┘
>> +      (0,0)
>> +
>> +     where (0',0') = (0+x-origin,0+y-origin)
> 
> What happens if touchscreen-inverted-x/y are set?
> 
> Though the existing binding never defines what the non-inverted 
> orientation is.
> 
This feature acts on the raw input values and the inversion is carried
out afterwards.The events will be inverted within the defined frame,
which is probably the expected behavior.

>> +
>> +    type: object
>> +
>> +    properties:
>> +      x-origin:
>> +        description: horizontal origin of the clipped area
>> +        $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +      y-origin:
>> +        description: vertical origin of the clipped area
>> +        $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +      x-size:
>> +        description: horizontal resolution of the clipped area
>> +        $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +      y-size:
>> +        description: vertical resolution of the clipped area
>> +        $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +        required:
>> +          - x-origin
>> +          - y-origin
>> +          - x-size
>> +          - y-size
>> +
>> +  overlay-buttons:
>> +    description: list of nodes defining the buttons on the touchscreen
>> +
>> +      This object can be used to describe buttons on the touchscreen area,
>> +      reporting the touch events on their surface as key events instead of
>> +      the original touch events.
>> +
>> +      This is of special interest if the touchscreen is shipped with a
>> +      physical overlay on top of it where a number of buttons with some
>> +      predefined functionality are printed. In that case a specific behavior
>> +      is expected from those buttons instead of raw touch events.
>> +
>> +      The overlay-buttons properties define a per-button area as well as an
>> +      origin relative to the real touchscreen origin. Touch events within the
>> +      button area are reported as the key event defined in the linux,code
>> +      property. Given that the key events do not provide coordinates, the
>> +      button origin is only used to place the button area on the touchscreen
>> +      surface. Any event outside the overlay-buttons object is reported as a
>> +      touch event with no coordinate transformation.
>> +
>> +      The following example shows a touchscreen with a single button on it
>> +
>> +              Touchscreen (full area)
>> +        ┌───────────────────────────────────┐
>> +        │                                   │
>> +        │                                   │
>> +        │   ┌─────────┐                     │
>> +        │   │button 0 │                     │
>> +        │   │KEY_POWER│                     │
>> +        │   └─────────┘                     │
>> +        │                                   │
>> +        │                                   │
>> +       ┌└───────────────────────────────────┘
>> +     (0,0)
>> +
>> +      The overlay-buttons object can  be combined with the overlay-touchscreen
>> +      object as shown in the following example. In that case only the events
>> +      within the overlay-touchscreen object are reported as touch events.
>> +
>> +                  Touchscreen (full area)
>> +        ┌─────────┬──────────────────────────────┐
>> +        │         │                              │
>> +        │         │    ┌───────────────────────┐ │
>> +        │ button 0│    │                       │ │
>> +        │KEY_POWER│    │                       │ │
>> +        │         │    │                       │ │
>> +        ├─────────┤    │  overlay-touchscreen  │ │
>> +        │         │    │                       │ │
>> +        │         │    │                       │ │
>> +        │ button 1│    │                       │ │
>> +        │ KEY_INFO│   ┌└───────────────────────┘ │
>> +        │         │(0',0')                       │
>> +       ┌└─────────┴──────────────────────────────┘
>> +     (0,0)
>> +
>> +    type: object
>> +
>> +    patternProperties:
>> +      '^button-':
>> +        type: object
>> +        description:
>> +          Each button (key) is represented as a sub-node.
>> +
>> +        properties:
>> +          label:
>> +            $ref: /schemas/types.yaml#/definitions/string
>> +            description: descriptive name of the button
>> +
>> +          linux,code: true
>> +
>> +          x-origin:
>> +            description: horizontal origin of the button area
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +          y-origin:
>> +            description: vertical origin of the button area
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +          x-size:
>> +            description: horizontal resolution of the button area
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +          y-size:
>> +            description: vertical resolution of the button area
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +        required:
>> +          - linux,code
>> +          - x-origin
>> +          - y-origin
>> +          - x-size
>> +          - y-size
> 
> We have the same properties defined twice. Move all the common ones to a 
> $def entry and then reference it here and in overlay-touchscreen.
> 
> $defs:
>   overlay-node:
>     type: object
>     properties:
>       x-origin:
>       ...
> 
> And then here:
> 
> '^button-':
>   $ref: '#/$defs/overlay-node
>   unevaluatedProperties: false
> 
>   properties:
>     label:
>       ...
> 
> 
> Rob
Thank your for your feedback, I will send a next version with this
modification in it.

Best regards,
Javier Carrasco