absolute_coordinate_ranges.html 11 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
<!-- HTML header for doxygen 1.8.8-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <!-- For Mobile Devices -->
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
        <meta name="generator" content="Doxygen 1.8.11"/>
        <script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
        <title>libinput: Coordinate ranges for absolute axes</title>
        <!--<link href="tabs.css" rel="stylesheet" type="text/css"/>-->
        <script type="text/javascript" src="dynsections.js"></script>
        <link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { init_search(); });
</script>
        <script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    extensions: ["tex2jax.js"],
    jax: ["input/TeX","output/HTML-CSS"],
});
</script><script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
        <link href="doxygen.css" rel="stylesheet" type="text/css" />
        <link href="customdoxygen.css" rel="stylesheet" type="text/css"/>
<link href="bootstrap.css" rel="stylesheet" type="text/css"/>
        <link href="bootstrap.css" rel="stylesheet" type="text/css" />
        <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/js/bootstrap.min.js"></script>
        <script type="text/javascript" src="doxy-boot.js"></script>
    </head>
    <body>
        <nav class="navbar navbar-default" role="navigation">
            <div class="container">
                <div class="navbar-header">
                    <a class="navbar-brand">libinput 1.4.1</a>
                </div>
            </div>
        </nav>
        <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
            <div class="content" id="content">
                <div class="container">
                    <div class="row">
                        <div class="col-sm-12 panel panel-default" style="padding-bottom: 15px;">
                            <div style="margin-bottom: 15px;">
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="touchpads.html">Touchpads</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Coordinate ranges for absolute axes </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>libinput requires that all touchpads provide a correct axis range and resolution.</p>
<p>These are used to enable or disable certain features or adapt the interaction with the touchpad. For example, the software button area is narrower on small touchpads to avoid reducing the interactive surface too much. Likewise, palm detection works differently on small touchpads as palm interference is less likely to happen.</p>
<p>Touchpads with incorrect axis ranges generate error messages in the form: </p><blockquote class="doxtable">
<p>Axis 0x35 value 4000 is outside expected range [0, 3000] </p>
</blockquote>
<p>This error message indicates that the ABS_MT_POSITION_X axis (i.e. the x axis) generated an event outside the expected range of 0-3000. In this case the value was 4000. This discrepancy between the coordinate range the kernels advertises vs. what the touchpad sends can be the source of a number of perceived bugs in libinput.</p>
<h1><a class="anchor" id="absolute_coordinate_ranges_fix"></a>
Measuring and fixing touchpad ranges</h1>
<p>To fix the touchpad you need to:</p><ol type="1">
<li>measure the physical size of your touchpad in mm</li>
<li>run touchpad-edge-detector</li>
<li>trim the udev match rule to something sensible</li>
<li>replace the resolution with the calculated resolution based on physical settings</li>
<li>test locally</li>
<li>send a patch to the systemd project</li>
</ol>
<p>Detailed explanations are below.</p>
<p><a href="http://freedesktop.org/wiki/Software/libevdev/">libevdev</a> provides a tool called <b>touchpad-edge-detector</b> that allows measuring the touchpad's input ranges. Run the tool as root against the device node of your touchpad device and repeatedly move a finger around the whole outside area of the touchpad. Then control+c the process and note the output. An example output is below:</p>
<div class="fragment"><div class="line">$&gt; sudo touchpad-edge-detector /dev/input/event4</div><div class="line">Touchpad SynPS/2 Synaptics TouchPad on /dev/input/event4</div><div class="line">Move one finger around the touchpad to detect the actual edges</div><div class="line">Kernel says:    x [1024..3112], y [2024..4832]</div><div class="line">Touchpad sends: x [2445..4252], y [3464..4071]</div><div class="line"></div><div class="line">Touchpad size as listed by the kernel: 49x66mm</div><div class="line">Calculate resolution as:</div><div class="line">        x axis: 2088/&lt;width in mm&gt;</div><div class="line">        y axis: 2808/&lt;height in mm&gt;</div><div class="line"></div><div class="line">Suggested udev rule:</div><div class="line"><span class="preprocessor"># &lt;Laptop model description goes here&gt;</span></div><div class="line">evdev:name:SynPS/2 Synaptics TouchPad:dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn20ARS25701:pvrThinkPadT440s:rvnLENOVO:rn20ARS25701:rvrSDK0E50512STD:cvnLENOVO:ct10:cvrNotAvailable:*</div><div class="line"> EVDEV_ABS_00=2445:4252:&lt;x resolution&gt;</div><div class="line"> EVDEV_ABS_01=3464:4071:&lt;y resolution&gt;</div><div class="line"> EVDEV_ABS_35=2445:4252:&lt;x resolution&gt;</div><div class="line"> EVDEV_ABS_36=3464:4071:&lt;y resolution&gt;</div></div><!-- fragment --><p>Note the discrepancy between the coordinate range the kernels advertises vs. what the touchpad sends. To fix the advertised ranges, the udev rule should be taken and trimmed before being sent to the <a href="https://github.com/systemd/systemd">systemd project</a>. An example commit can be found <a href="https://github.com/systemd/systemd/commit/26f667eac1c5e89b689aa0a1daef6a80f473e045">here</a>.</p>
<p>In most cases the match can and should be trimmed to the system vendor (svn) and the product version (pvr), with everything else replaced by a wildcard (*). In this case, a Lenovo T440s, a suitable match string would be:</p><div class="fragment"><div class="line">evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s*</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>hwdb match strings only allow for alphanumeric ascii characters. Use a wildcard (* or ?, whichever appropriate) for special characters.</dd></dl>
<p>The actual axis overrides are in the form: </p><div class="fragment"><div class="line"><span class="preprocessor"># axis number=min:max:resolution</span></div><div class="line"><span class="preprocessor"> EVDEV_ABS_00=2445:4252:42</span></div></div><!-- fragment --><p> or, if the range is correct but the resolution is wrong </p><div class="fragment"><div class="line"><span class="preprocessor"># axis number=::resolution</span></div><div class="line"><span class="preprocessor"> EVDEV_ABS_00=::42</span></div></div><!-- fragment --><p>Note the leading single space. The axis numbers are in hex and can be found in <em>linux/input-event-codes.h</em>. For touchpads ABS_X, ABS_Y, ABS_MT_POSITION_X and ABS_MT_POSITION_Y are required.</p>
<dl class="section note"><dt>Note</dt><dd>The touchpad's ranges and/or resolution should only be fixed when there is a significant discrepancy. A few units do not make a difference and a resolution that is off by 2 or less usually does not matter either.</dd></dl>
<p>Once a match and override rule has been found, follow the instructions at the top of the <a href="https://github.com/systemd/systemd/blob/master/hwdb/60-evdev.hwdb">60-evdev.hwdb</a> file to save it locally and trigger the udev hwdb reload. Rebooting is always a good idea. If the match string is correct, the new properties will show up in the output of </p><div class="fragment"><div class="line">udevadm info /sys/<span class="keyword">class</span>/input/event4</div></div><!-- fragment --><p>Adjust the command for the event node of your touchpad. A udev builtin will apply the new axis ranges automatically.</p>
<p>When the axis override is confirmed to work, please submit it as a patch to the <a href="https://github.com/systemd/systemd">systemd project</a> or if that is not possible as a libinput bug here: <a href="https://bugs.freedesktop.org/enter_bug.cgi?product=Wayland&component=libinput">https://bugs.freedesktop.org/enter_bug.cgi?product=Wayland&amp;component=libinput</a> </p>
</div></div><!-- contents -->
<!-- HTML footer for doxygen 1.8.8-->
<!-- start footer part -->
</div>
</div>
</div>
</div>
</div>
<hr class="footer"/><address class="footer"><small>
Generated on Fri Aug 5 2016 11:29:52 for libinput by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.11
</small></address>
</body>
</html>