tests_kernel.test_wacom_generic module — hid-tools documentation

# tests_kernel.test_wacom_generic module

Tests for the Wacom driver generic codepath.

This module tests the function of the Wacom driver’s generic codepath. The generic codepath is used by devices which are not explicitly listed in the driver’s device table. It uses the device’s HID descriptor to decode reports sent by the device.

class BaseTablet(rdesc, name=None, info=None)

  Bases: `UHIDTestDevice`

  Skeleton object for all kinds of tablet devices.

  create_report(x, y, pressure, buttons=None, toolid=None, proximity=None, reportID=None)

    Return an input report for this device.

    Parameters:

      - x – absolute x

      - y – absolute y

      - pressure – pressure

      - buttons – stylus button state. Use `None` for unchanged.

      - toolid – tool identifiers. Use `None` for unchanged.

      - proximity – a ProximityState indicating the sensor’s ability to detect and report attributes of this tool. Use `None` for unchanged.

      - reportID – the numeric report ID for this report, if needed

  create_report_heartbeat(reportID)

    Return a heartbeat input report for this device.

    Heartbeat reports generally contain battery status information, among other things.

  create_report_offset(rdesc)
  create_report_pad(reportID, ring, ek0)
  event(x, y, pressure, buttons=None, toolid=None, proximity=None)

    Send an input event on the default report ID.

    Parameters:

      - x – absolute x

      - y – absolute y

      - buttons – stylus button state. Use `None` for unchanged.

      - toolid – tool identifiers. Use `None` for unchanged.

      - proximity – a ProximityState indicating the sensor’s ability to detect and report attributes of this tool. Use `None` for unchanged.

  event_heartbeat(reportID)

    Send a heartbeat event on the requested report ID.

  event_pad(reportID, ring=None, ek0=None)

    Send a pad event on the requested report ID.

  get_report(req, rnum, rtype)

    Callback invoked when a process calls SetReport on this UHID device.

    Return `(0, [data bytes])` on success or `(errno, [])` on failure.

    The default method always returns `(EIO, [])` for a failure. Override this in your device if you want GetReport to succeed.

    Parameters:

      - req – the request identifier

      - rnum –

        ???

      - rtype – one of `UHID_FEATURE_REPORT`, `UHID_INPUT_REPORT`, or `UHID_OUTPUT_REPORT`

  match_evdev_rule(application, evdev)

    Filter out evdev nodes based on the requested application.

    The Wacom driver may create several device nodes for each USB interface device. It is crucial that we run tests with the expected device node or things will obviously go off the rails. Use the Wacom driver’s usual naming conventions to apply a sensible default filter.

class BaseTest

  Bases: `object`

  class TestTablet

    Bases: `TestUhid`

    assertName(uhdev, type)

      Assert that the name is as we expect.

      The Wacom driver applies a number of decorations to the name provided by the hardware. We cannot rely on the definition of this assertion from the base class to work properly.

    get_usages(uhdev)
    kernel_modules: list[KernelModule] = [KernelModule(driver_name='wacom', module_name='wacom')]
    sync_and_assert_events(report, expected_events, auto_syn=True, strict=False)

      Assert we see the expected events in response to a report.

    test_descriptor_physicals()

      Verify that all HID usages which should have a physical range actually do, and those which shouldn’t don’t. Also verify that the associated unit is correct and within a sensible range.

    test_prop_direct()

      Todo: Verify that INPUT_PROP_DIRECT is set on display devices.

    test_prop_pointer()

      Todo: Verify that INPUT_PROP_POINTER is set on opaque devices.

class Buttons(primary=None, secondary=None, tertiary=None)

  Bases: `object`

  Stylus button state.

  Describes the state of each of the buttons / “side switches” that may be present on a stylus. Buttons set to ‘None’ indicate the state is “unchanged” since the previous event.

  static clear()

    Button object with all states cleared.

  fill(reportdata)

    Fill a report with approrpiate HID properties/values.

class OpaqueCTLTablet(rdesc=[6, 13, 255, 9, 1, 161, 1, 133, 16, 9, 32, 53, 0, 69, 0, 21, 0, 37, 1, 161, 0, 9, 66, 9, 68, 9, 90, 9, 69, 9, 60, 9, 50, 9, 54, 37, 1, 117, 1, 149, 7, 129, 2, 149, 1, 129, 3, 10, 48, 1, 101, 17, 85, 13, 71, 128, 62, 0, 0, 39, 128, 62, 0, 0, 117, 24, 149, 1, 129, 2, 10, 49, 1, 71, 40, 35, 0, 0, 39, 40, 35, 0, 0, 129, 2, 9, 48, 85, 0, 101, 0, 71, 0, 0, 0, 0, 38, 255, 15, 117, 16, 129, 2, 117, 8, 149, 6, 129, 3, 10, 50, 1, 37, 63, 117, 8, 149, 1, 129, 2, 9, 91, 9, 92, 23, 0, 0, 0, 128, 39, 255, 255, 255, 127, 117, 32, 149, 2, 129, 2, 9, 119, 21, 0, 38, 255, 15, 117, 16, 149, 1, 129, 2, 192, 192], name=None, info=(3, 1386, 39321))

  Bases: `BaseTablet`

  Opaque tablet similar to something in the CTL product line.

  A pen-only tablet with most basic features you would expect from an actual device. Position, eraser, pressure, barrel buttons. Uses the Wacom vendor-defined usage page.

  report_descriptor = [6, 13, 255, 9, 1, 161, 1, 133, 16, 9, 32, 53, 0, 69, 0, 21, 0, 37, 1, 161, 0, 9, 66, 9, 68, 9, 90, 9, 69, 9, 60, 9, 50, 9, 54, 37, 1, 117, 1, 149, 7, 129, 2, 149, 1, 129, 3, 10, 48, 1, 101, 17, 85, 13, 71, 128, 62, 0, 0, 39, 128, 62, 0, 0, 117, 24, 149, 1, 129, 2, 10, 49, 1, 71, 40, 35, 0, 0, 39, 40, 35, 0, 0, 129, 2, 9, 48, 85, 0, 101, 0, 71, 0, 0, 0, 0, 38, 255, 15, 117, 16, 129, 2, 117, 8, 149, 6, 129, 3, 10, 50, 1, 37, 63, 117, 8, 149, 1, 129, 2, 9, 91, 9, 92, 23, 0, 0, 0, 128, 39, 255, 255, 255, 127, 117, 32, 149, 2, 129, 2, 9, 119, 21, 0, 38, 255, 15, 117, 16, 149, 1, 129, 2, 192, 192]

class OpaqueTablet(rdesc=[5, 13, 9, 1, 161, 1, 133, 1, 9, 32, 161, 0, 9, 66, 9, 50, 21, 0, 37, 1, 117, 1, 149, 2, 129, 2, 149, 6, 129, 3, 5, 1, 9, 48, 39, 128, 62, 0, 0, 71, 128, 62, 0, 0, 101, 17, 85, 13, 117, 16, 149, 1, 129, 2, 9, 49, 39, 40, 35, 0, 0, 71, 40, 35, 0, 0, 129, 2, 192, 192], name=None, info=(3, 1386, 39321))

  Bases: `BaseTablet`

  Bare-bones opaque tablet with a minimum of features.

  A tablet stripped down to its absolute core. It is capable of reporting X/Y position and if the pen is in contact. No pressure, no barrel switches, no eraser. Notably it does report an “In Range” flag, but this is only because the Wacom driver expects one to function properly. The device uses only standard HID usages, not any of Wacom’s vendor-defined pages.

  report_descriptor = [5, 13, 9, 1, 161, 1, 133, 1, 9, 32, 161, 0, 9, 66, 9, 50, 21, 0, 37, 1, 117, 1, 149, 2, 129, 2, 149, 6, 129, 3, 5, 1, 9, 48, 39, 128, 62, 0, 0, 71, 128, 62, 0, 0, 101, 17, 85, 13, 117, 16, 149, 1, 129, 2, 9, 49, 39, 40, 35, 0, 0, 71, 40, 35, 0, 0, 129, 2, 192, 192]

class PTHX60_Pen(rdesc=None, name=None, info=None)

  Bases: `BaseTablet`

  Pen interface of a PTH-660 / PTH-860 / PTH-460 tablet.

  This generation of devices are nearly identical to each other, though the PTH-460 uses a slightly different descriptor construction (splits the pad among several physical collections)

class PenTabletTest

  Bases: `TestTablet`

  assertName(uhdev)

    Assert that the name is as we expect.

    The Wacom driver applies a number of decorations to the name provided by the hardware. We cannot rely on the definition of this assertion from the base class to work properly.

class PhysRange(unit, min_size, max_size)

  Bases: `object`

  Range of HID physical values, with units.

  CENTIMETER = <hidtools.hid.HidUnit object>
  DEGREE = <hidtools.hid.HidUnit object>
  contains(field)

    Check if the physical size of the provided field is in range.

    Compare the physical size described by the provided HID field against the range of sizes described by this object. This is an exclusive range comparison (e.g. 0 cm is not within the range 0 cm - 5 cm) and exact unit comparison (e.g. 1 inch is not within the range 0 cm - 5 cm).

class ProximityState(*values)

  Bases: `Enum`

  Enumeration of allowed proximity states.

  IN_PROXIMITY = 1
  IN_RANGE = 2
  OUT = 0
  fill(reportdata)

    Fill a report with approrpiate HID properties/values.

class ReportData

  Bases: `object`

  Placeholder for HID report values.

class TestDTH2452Tablet

  Bases: `TestMultitouch`, `TouchTabletTest`

  class ContactIds(contact_id, tracking_id, slot_num)

    Bases: `tuple`

    contact_id

      Alias for field number 0

    slot_num

      Alias for field number 2

    tracking_id

      Alias for field number 1

  assert_contact(evdev, contact_ids, t=0)

    Assert properties of a contact generated by make_contact.

  assert_contacts(evdev, data, t=0)

    Assert properties of a list of contacts generated by make_contacts.

  confidence_change_assert_playback(uhdev, evdev, timeline)

    Assert proper behavior of contacts that move and change tipswitch / confidence status over time.

    Given a timeline list of touch states to iterate over, verify that the contacts move and are reported as up/down as expected by the state of the tipswitch and confidence bits.

  create_device()
  make_contact(contact_id=0, t=0)

    Make a single touch contact that can move over time.

    Creates a touch object that has a well-known position in space that does not overlap with other contacts. The value of t may be incremented over time to move the point along a linear path.

  make_contacts(n, t=0)

    Make multiple touch contacts that can move over time.

    Returns a list of n touch objects that are positioned at well-known locations. The value of t may be incremented over time to move the points along a linear path.

  test_confidence_false()

    Bring a finger in contact with the tablet with confidence set to false.

    Ensure that the confidence bit being set to false should not result in a touch event.

  test_confidence_gain_a()

    Transition a contact that was always non-confident to confident.

    Ensure that the confident contact is reported normally.

  test_confidence_gain_b()

    Transition a contact from non-confident to confident.

    Ensure that the confident contact is reported normally.

  test_confidence_loss_a()

    Transition a confident contact to a non-confident contact by first clearing the tipswitch.

    Ensure that the driver reports the transitioned contact as being removed and that other contacts continue to report normally. This mode of confidence loss is used by the DTH-2452.

  test_confidence_loss_b()

    Transition a confident contact to a non-confident contact by cleraing both tipswitch and confidence bits simultaneously.

    Ensure that the driver reports the transitioned contact as being removed and that other contacts continue to report normally. This mode of confidence loss is used by some AES devices.

  test_confidence_loss_c()

    Transition a confident contact to a non-confident contact by clearing only the confidence bit.

    Ensure that the driver reports the transitioned contact as being removed and that other contacts continue to report normally.

  test_confidence_multitouch()

    Bring multiple fingers in contact with the tablet, some with the confidence bit set, and some without.

    Ensure that all confident touches are reported and that all non- confident touches are ignored.

  test_contact_id_0()

    Bring a finger in contact with the tablet, then hold it down and remove it.

    Ensure that even with contact ID = 0 which is usually given as an invalid touch event by most tablets with the exception of a few, that given the confidence bit is set to 1 it should process it as a valid touch to cover the few tablets using contact ID = 0 as a valid touch value.

class TestOpaqueCTLTablet

  Bases: `TestOpaqueTablet`

  create_device()
  test_buttons()

    Test that the barrel buttons (side switches) work as expected.

    Press and release each button individually to verify that we get the expected events.

class TestOpaqueTablet

  Bases: `PenTabletTest`

  create_device()
  test_sanity()

    Bring a pen into contact with the tablet, then remove it.

    Ensure that we get the basic tool/touch/motion events that should be sent by the driver.

class TestPTHX60_Pen

  Bases: `TestOpaqueCTLTablet`

  create_device()
  empty_pad_sync(num, denom, reverse)

    Test that multiple pad collections do not trigger empty syncs.

  set_device_params(request)
  test_descriptor_physicals()

    Verify that all HID usages which should have a physical range actually do, and those which shouldn’t don’t. Also verify that the associated unit is correct and within a sensible range.

  test_empty_pad_sync()
  test_heartbeat_spurious()

    Test that the heartbeat report does not send spurious events.

class ToolID(serial, tooltype)

  Bases: `object`

  Stylus tool identifiers.

  Contains values used to identify a specific stylus, e.g. its serial number and tool-type identifier. Values of `0` may sometimes be used for the out-of-range condition.

  static clear()

    ToolID object with all fields cleared.

  fill(reportdata)

    Fill a report with approrpiate HID properties/values.

class TouchTabletTest

  Bases: `TestTablet`

  assertName(uhdev)

    Assert that the name is as we expect.

    The Wacom driver applies a number of decorations to the name provided by the hardware. We cannot rely on the definition of this assertion from the base class to work properly.