touchscreen.yaml

  1# SPDX-License-Identifier: GPL-2.0
  2%YAML 1.2
  3---
  4$id: http://devicetree.org/schemas/input/touchscreen/touchscreen.yaml#
  5$schema: http://devicetree.org/meta-schemas/core.yaml#
  6
  7title: Common touchscreen
  8
  9maintainers:
 10  - Dmitry Torokhov <dmitry.torokhov@gmail.com>
 11
 12properties:
 13  panel:
 14    description: If this touchscreen is integrally connected to a panel, this
 15      is a reference to that panel. The presence of this reference indicates
 16      that the touchscreen should be power sequenced together with the panel
 17      and that they may share power and/or reset signals.
 18    $ref: /schemas/types.yaml#/definitions/phandle
 19
 20  touchscreen-min-x:
 21    description: minimum x coordinate reported
 22    $ref: /schemas/types.yaml#/definitions/uint32
 23    default: 0
 24
 25  touchscreen-min-y:
 26    description: minimum y coordinate reported
 27    $ref: /schemas/types.yaml#/definitions/uint32
 28    default: 0
 29
 30  touchscreen-size-x:
 31    description: horizontal resolution of touchscreen (maximum x coordinate reported + 1)
 32    $ref: /schemas/types.yaml#/definitions/uint32
 33
 34  touchscreen-size-y:
 35    description: vertical resolution of touchscreen (maximum y coordinate reported + 1)
 36    $ref: /schemas/types.yaml#/definitions/uint32
 37
 38  touchscreen-max-pressure:
 39    description: maximum reported pressure (arbitrary range dependent on the controller)
 40    $ref: /schemas/types.yaml#/definitions/uint32
 41
 42  touchscreen-min-pressure:
 43    description: minimum pressure on the touchscreen to be achieved in order
 44      for the touchscreen driver to report a touch event.
 45    $ref: /schemas/types.yaml#/definitions/uint32
 46
 47  touchscreen-fuzz-x:
 48    description: horizontal noise value of the absolute input device (in pixels)
 49    $ref: /schemas/types.yaml#/definitions/uint32
 50
 51  touchscreen-fuzz-y:
 52    description: vertical noise value of the absolute input device (in pixels)
 53    $ref: /schemas/types.yaml#/definitions/uint32
 54
 55  touchscreen-fuzz-pressure:
 56    description: pressure noise value of the absolute input device (arbitrary
 57      range dependent on the controller)
 58    $ref: /schemas/types.yaml#/definitions/uint32
 59
 60  touchscreen-average-samples:
 61    description: Number of data samples which are averaged for each read (valid
 62      values dependent on the controller)
 63    $ref: /schemas/types.yaml#/definitions/uint32
 64
 65  touchscreen-inverted-x:
 66    description: X axis is inverted
 67    type: boolean
 68
 69  touchscreen-inverted-y:
 70    description: Y axis is inverted
 71    type: boolean
 72
 73  touchscreen-swapped-x-y:
 74    description: X and Y axis are swapped
 75                 Swapping is done after inverting the axis
 76    type: boolean
 77
 78  touchscreen-x-mm:
 79    description: horizontal length in mm of the touchscreen
 80
 81  touchscreen-y-mm:
 82    description: vertical length in mm of the touchscreen
 83
 84  touchscreen-x-plate-ohms:
 85    description: Resistance of the X-plate in Ohms
 86
 87  touchscreen-y-plate-ohms:
 88    description: Resistance of the Y-plate in Ohms
 89
 90  touch-overlay:
 91    description: |
 92      List of nodes defining segments (touch areas) on the touchscreen.
 93
 94      This object can be used to describe a series of segments to restrict
 95      the region within touch events are reported or buttons with a specific
 96      functionality.
 97
 98      This is of special interest if the touchscreen is shipped with a physical
 99      overlay on top of it with a frame that hides some part of the original
100      touchscreen area. Printed buttons on that overlay are also a typical
101      use case.
102
103      A new touchscreen area is defined as a sub-node without a key code. If a
104      key code is defined in the sub-node, it will be interpreted as a button.
105
106      The x-origin and y-origin properties of a touchscreen area define the
107      offset of a new origin from where the touchscreen events are referenced.
108      This offset is applied to the events accordingly. The x-size and y-size
109      properties define the size of the touchscreen effective area.
110
111      The following example shows a new touchscreen area with the new origin
112      (0',0') for the touch events generated by the device.
113
114                   Touchscreen (full area)
115         ┌────────────────────────────────────────┐
116         │    ┌───────────────────────────────┐   │
117         │    │                               │   │
118         │    ├ y-size                        │   │
119         │    │                               │   │
120         │    │       touchscreen area        │   │
121         │    │         (no key code)         │   │
122         │    │                               │   │
123         │    │            x-size             │   │
124         │   ┌└──────────────┴────────────────┘   │
125         │(0',0')                                 │
126        ┌└────────────────────────────────────────┘
127      (0,0)
128
129      where (0',0') = (0+x-origin,0+y-origin)
130
131      Sub-nodes with key codes report the touch events on their surface as key
132      events instead.
133
134      The following example shows a touchscreen with a single button on it.
135
136              Touchscreen (full area)
137        ┌───────────────────────────────────┐
138        │                                   │
139        │                                   │
140        │   ┌─────────┐                     │
141        │   │button 0 │                     │
142        │   │KEY_POWER│                     │
143        │   └─────────┘                     │
144        │                                   │
145        │                                   │
146       ┌└───────────────────────────────────┘
147      (0,0)
148
149      Segments defining buttons and clipped toushcreen areas can be combined
150      as shown in the following example.
151      In that case only the events within the touchscreen area are reported
152      as touch events. Events within the button areas report their associated
153      key code. Any events outside the defined areas are ignored.
154
155                  Touchscreen (full area)
156        ┌─────────┬──────────────────────────────┐
157        │         │                              │
158        │         │    ┌───────────────────────┐ │
159        │ button 0│    │                       │ │
160        │KEY_POWER│    │                       │ │
161        │         │    │                       │ │
162        ├─────────┤    │   touchscreen area    │ │
163        │         │    │     (no key code)     │ │
164        │         │    │                       │ │
165        │ button 1│    │                       │ │
166        │ KEY_INFO│   ┌└───────────────────────┘ │
167        │         │(0',0')                       │
168       ┌└─────────┴──────────────────────────────┘
169      (0,0)
170
171    type: object
172
173    patternProperties:
174      '^segment-':
175        type: object
176        description:
177          Each segment is represented as a sub-node.
178        properties:
179          x-origin:
180            description: horizontal origin of the node area
181            $ref: /schemas/types.yaml#/definitions/uint32
182
183          y-origin:
184            description: vertical origin of the node area
185            $ref: /schemas/types.yaml#/definitions/uint32
186
187          x-size:
188            description: horizontal resolution of the node area
189            $ref: /schemas/types.yaml#/definitions/uint32
190
191          y-size:
192            description: vertical resolution of the node area
193            $ref: /schemas/types.yaml#/definitions/uint32
194
195          label:
196            description: descriptive name of the segment
197            $ref: /schemas/types.yaml#/definitions/string
198
199          linux,code: true
200
201        required:
202          - x-origin
203          - y-origin
204          - x-size
205          - y-size
206
207        unevaluatedProperties: false
208
209  debounce-delay-us:
210    description: Minimum duration in microseconds a signal must remain stable
211      to be considered valid.
212
213dependencies:
214  touchscreen-size-x: [ touchscreen-size-y ]
215  touchscreen-size-y: [ touchscreen-size-x ]
216  touchscreen-x-mm: [ touchscreen-y-mm ]
217  touchscreen-y-mm: [ touchscreen-x-mm ]
218
219additionalProperties: true