touchscreen
===========
**Source code:** `touchscreen.py <https://chromium.googlesource.com/chromiumos/platform/factory/+/refs/heads/main/py/test/pytests/touchscreen.py>`_

Tests touchscreen or stylus by drawing in any order or in spiral pattern.

Description
-----------
In this test, screen area is segmented into `x_segments` x `y_segments` blocks.
If argument `spiral_mode` is True, the operator has to swipe the blocks in
clockwise spiral pattern. Otherwise the operator has to touch all the blocks in
arbitrary order.

In `spiral_mode`, the pattern is:

1. Starting from upper-left block, move to rightmost block.
2. Then move down, left, up, to draw a outer rectangular circle.
3. Move to the inner upper-left block (1, 1), repeat 1-2.
4. Until the center block is reached.

The index of block (x, y) is defined as::

  index =  x + y * x_segments (number of blocks in x-axis).

For, example, a 3x3 grid::

  0 1 2
  3 4 5
  6 7 8

The clockwise spiral drawing sequence is: 0, 1, 2, 5, 8, 7, 6, 3, 4.

There are two modes available: end-to-end mode and evdev mode.

- End-to-end mode uses Chrome touch event API.
- Evdev mode uses Linux evdev.

Test logic is in touchscreen.js.

Test Procedure
--------------
1. Once the test started, it would be set to fullscreen and shows
   `x_segments` x `y_segments` grey blocks.
2. Draw these blocks green by touching them (or move your stylus to make it
   hovering on a block in hover mode) in specified order. Test will pass after
   all blocks being green.
3. If there is any problem with the touch device, press Escape to abort and
   mark this test failed.
4. If `timeout_secs` is set and the test couldn't be passed in `timeout_secs`
   seconds, the test will fail automatically.

Dependency
----------
- End-to-end mode is based on Chrome touch event API.
- Non end-to-end mode is based on Linux evdev.

Examples
--------
To test touchscreen with 30x20 blocks, add this in test list:

.. test_list::

  generic_touchscreen_examples:TouchscreenTests.Touchscreen30x20

To test touchscreen without time limit:

.. test_list::

  generic_touchscreen_examples:TouchscreenTests.TouchscreenWithoutTimeLimit

To test touchscreen in end-to-end mode:

.. test_list::

  generic_touchscreen_examples:TouchscreenTests.TouchscreenE2EMode

To test touchscreen without spiral order restriction:

.. test_list::

  generic_touchscreen_examples:TouchscreenTests.TouchscreenArbitraryOrder

To test stylus in hover mode:

.. test_list::

  generic_touchscreen_examples:TouchscreenTests.StylusSpiralHoverMode

To test stylus in touch mode:

.. test_list::

  generic_touchscreen_examples:TouchscreenTests.StylusSpiralTouchMode

Trouble Shooting
----------------
If you find the spiral test keeps failing, here are some tips:

1. Use end-to-end mode to see if it helps.
2. Use the tool `evtest` to check touch events reported by driver.

If seeing unexpected touch events in `evtest`, here are some thoughts:

1. Check if the motherboard and operator are properly grounded.
2. Remove all external connections to the DUT (including power adaptor, ethernet
   cable, usb hub).
3. Check if there are noises coming from the grounding line. Maybe move the DUT
   out of the manufacturing line to see if it helps.
4. Flash touchscreen firmware to a different version. Maybe it's too sensitive.


Test Arguments
--------------
.. list-table::
   :widths: 20 10 60
   :header-rows: 1
   :align: left

   * - Name
     - Type
     - Description

   * - x_segments
     - int
     - (optional; default: ``5``) Number of segments in x-axis.

   * - y_segments
     - int
     - (optional; default: ``5``) Number of segments in y-axis.

   * - retries
     - int
     - (optional; default: ``5``) Number of retries (for spiral_mode).

   * - demo_interval_ms
     - int
     - (optional; default: ``150``) Interval (ms) to show drawing pattern (for spiral mode). <= 0 means no demo.

   * - stylus
     - bool
     - (optional; default: ``False``) Testing stylus or not.

   * - e2e_mode
     - bool
     - (optional; default: ``False``) Perform end-to-end test or not (for touchscreen).

   * - spiral_mode
     - bool
     - (optional; default: ``True``) Do blocks need to be drawn in spiral order or not.

   * - device_filter
     - int, str, None
     - (optional; default: ``None``) Evdev input event id or name.

   * - hover_mode
     - bool
     - (optional; default: ``False``) Test hovering or touching (for stylus).

   * - timeout_secs
     - int, None
     - (optional; default: ``20``) Timeout for the test. None for no time limit.

   * - angle_compensation
     - ['angle_0', 'angle_180', 'angle_270', 'angle_90']
     - (optional; default: ``0``) Specify a degree to compensate the orientation difference between panel and system in counter-clockwise direction. It is used when panel scanout is different from default system orientation, i.e., a angle difference between the instruction line displayed on screen and the position read from evdev.