File: xboxdrv.1

package info (click to toggle)
xboxdrv 0.8.8-1
  • links: PTS, VCS
  • area: main
  • in suites: buster, stretch
  • size: 2,300 kB
  • ctags: 2,447
  • sloc: cpp: 19,635; xml: 3,202; ansic: 507; python: 492; sh: 105; makefile: 34; ruby: 19
file content (2434 lines) | stat: -rw-r--r-- 79,685 bytes parent folder | download | duplicates (2)
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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
'\" t -*- coding: us-ascii -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH "xboxdrv " 1 2011-07-20 0.8.3 "User Commands"
.SH NAME
xboxdrv
\- A Xbox/Xbox360 gamepad driver that works in userspace 
.SH SYNOPSIS
'nh
.fi
.ad l
\fBxboxdrv\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[OPTION]\&... [--] [COMMAND] [ARGUMENTS]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBxboxdrv\fR is a driver for Xbox and Xbox360
gamepads. It works by reading the raw data from the controller
with the userspace library libusb and then passes the
interpreted data to the kernel via uinput. This
allows \fBxboxdrv\fR to provide regular joystick
and event devices, which makes it compatible with all Linux
software.
.PP
Aside from the pure driver, \fBxboxdrv\fR also
includes a rich set of configuration options that allow you to
tweak the abilities of the virtual input devices that xboxdrv
will create. This includes basic button and axis remapping, as
well as more complicated things like mouse and keyboard emulation,
auto-fire and throttle control emulation.
.PP
It is also possible for \fBxboxdrv\fR to read input
data directly from an event device, this allows the use of the
configurability of \fBxboxdrv\fR on regular PC
joysticks, keyboards and mice and thus
lets \fBxboxdrv\fR serve a similar purpose
as \fBjoy2key\fR. See the
option \*(T<\fB\-\-evdev\fR\*(T> below for more information.
.PP
When a \*(T<\fBCOMMAND\fR\*(T> is provided xboxdrv will launch
that application and be running till that application exits.
This is a convenience function to make it easier to use xboxdrv
in wrapper scripts. See the section
[Writing Start-Up Scripts for Games]
for more information.
.SH OPTIONS
.SS "GENERAL OPTIONS"
.TP 
\*(T<\fB\-h\fR\*(T>, \*(T<\fB\-\-help\fR\*(T>
Display help text and exit.
.TP 
\-V, \-\-version
Print the version number and exit.
.TP 
\*(T<\fB\-v\fR\*(T>, \*(T<\fB\-\-verbose\fR\*(T>
Print verbose messages.
.TP 
\*(T<\fB\-\-debug\fR\*(T>
Print even more verbose messages then \*(T<\fB\-\-verbose\fR\*(T>.
.TP 
\*(T<\fB\-s\fR\*(T>, \*(T<\fB\-\-silent\fR\*(T>
Do not display controller events on the terminal. For
regular use this option should always be used as output
data to the terminal can eat up quite a bit of CPU.
.TP 
\*(T<\fB\-\-quiet\fR\*(T>
Do not display startup text and suppress most other output.
.TP 
\*(T<\fB\-\-priority\fR\*(T> \fIPRIORITY\fR
Possible values for \fIPRIORITY\fR
are "normal" and "realtime". Realtime scheduling gives
the xboxdrv process higher priority and thus allows it
to function properly even when the machine is under
load.

Note that realtime priority requires running xboxdrv as
root, when running xboxdrv as user there is no way to
increase the priority.

This option is deprecated,
use \fBchrt\fR(1)
instead to achive the same effect.
.SS "LIST OPTIONS"
.TP 
\*(T<\fB\-\-help\-led\fR\*(T>
List possible values for the led.
.TP 
\*(T<\fB\-\-help\-devices\fR\*(T>
List supported devices.
.TP 
\*(T<\fB\-\-list\-supported\-devices\fR\*(T>
List supported devices (used by xboxdrv-daemon.py).
.TP 
\*(T<\fB\-\-list\-supported\-devices\-xpad\fR\*(T>
List supported devices in \*(T<\fIxpad.c\fR\*(T> style.
.TP 
\*(T<\fB\-\-help\-abs\fR\*(T>
List all allowed EV_ABS symbols.
.TP 
\*(T<\fB\-\-help\-rel\fR\*(T>
List all allowed EV_REL symbols.
.TP 
\*(T<\fB\-\-help\-key\fR\*(T>
List all allowed EV_KEY symbols.
.TP 
\*(T<\fB\-\-help\-x11keysym\fR\*(T>
List all allowed X11 Keysym symbols.
.TP 
\*(T<\fB\-\-help\-axis\fR\*(T>
List all allowed XboxAxis symbols.
.TP 
\*(T<\fB\-\-help\-button\fR\*(T>
List all allowed XboxButton symbols.
.TP 
\*(T<\fB\-\-help\-all\fR\*(T>
List all symbols that can be used
in \*(T<\fB\-\-ui\-buttonmap\fR\*(T>, \*(T<\fB\-\-ui\-axismap\fR\*(T>, \*(T<\fB\-\-buttonmap\fR\*(T>
and \*(T<\fB\-\-axismap\fR\*(T>. This option is the same as
\*(T<\fB\-\-help\-abs\fR\*(T>,
\*(T<\fB\-\-help\-rel\fR\*(T>,
\*(T<\fB\-\-help\-key\fR\*(T>,
\*(T<\fB\-\-help\-x11keysym\fR\*(T>,
\*(T<\fB\-\-help\-axis\fR\*(T> and
\*(T<\fB\-\-help\-button\fR\*(T>.
.SS "CONFIG FILE OPTIONS"
.TP 
\*(T<\fB\-c\fR\*(T>, \*(T<\fB\-\-config\fR\*(T> \fIFILE\fR
Reads configuration information from \fIFILE\fR.
Configurations from file are handling as if they would
be command line options at the position
of \*(T<\fB\-\-config\fR\*(T> \fIFILE\fR.

The syntax
of \fIFILE\fR is
the familiar INI syntax used for many configuration
files. Regular key/value pairs must go into the
[xboxdrv] section. '#' and ';' can be used for comments.
Key names have for most part the same name as command
line options. Command line options that take a list of
input mappings (\-\-ui\-buttonmap, \-\-ui\-axismap,
\-\-evdev\-absmap, ...) can be split of into their own
section for better readability.

The \*(T<\fIexamples/\fR\*(T> directory contains
some example configuration files.

.nf
\*(T<[xboxdrv]
silent=true
deadzone=6000
dpad\-as\-button=true
trigger\-as\-button=true

[ui\-axismap]
x2=REL_X:10
y2=REL_Y:\-10
x1=KEY_A:KEY_D
y1=KEY_W:KEY_S

[ui\-buttonmap]
a=KEY_LEFTSHIFT
b=BTN_C
x=BTN_EXTRA
y=KEY_C

[ui\-buttonmap]
lb=BTN_RIGHT
rb=KEY_SPACE

[ui\-buttonmap]
lt=KEY_Z
rt=BTN_LEFT

[ui\-buttonmap]
dl=KEY_4
dr=KEY_2
du=REL_WHEEL:\-1:150
dd=REL_WHEEL:1:150

[ui\-buttonmap]
back=KEY_TAB
start=KEY_ESC

# EOF #\*(T>
.fi
.TP 
\*(T<\fB\-\-alt\-config\fR\*(T> \fIFILE\fR
A shortcut for
writing \*(T<\fB\-\-next\-config\fR\*(T> \*(T<\fB\-\-config\fR\*(T> \fIFILE\fR.

To load multiple configuration options use:

.nf
\*(T<xboxdrv \-\-config first.ini \-\-alt\-config second.ini \-\-alt\-config third.ini\*(T>
.fi
.TP 
\*(T<\fB\-o\fR\*(T>, \*(T<\fB\-\-option\fR\*(T> \fINAME=VALUE\fR
Set an option as if it would come from a config file from the command line.
.TP 
\*(T<\fB\-\-write\-config\fR\*(T> \fIFILE\fR
Write an example configuration file to \fIFILE\fR.
.SS "DAEMON OPTIONS"
.TP 
\*(T<\fB\-D\fR\*(T>, \*(T<\fB\-\-daemon\fR\*(T>
Run xboxdrv as daemon. If this option is given xboxdrv
will listen to udev for USB connection events and launch
driver threads for newly connected controllers.

Configuration options can still be supplied as usual.
Note however that xboxdrv when run as daemon will not
create new uinput devices on demand, instead it will
only create devices once at startup for the given
configurations and then assign new controllers to these
configurations. While this means xboxdrv can't support
an unlimited number of controllers, it also means that
xboxdrv can allow hot plugging even for applications
that don't support it themselves, as applications will
only see the permanent device files, not the controller
that xboxdrv will change around under the hood.

An example configuration that supports three controller
would look like this:

.nf
\*(T<xboxdrv \-\-daemon \e
    # config options for the first controller
  \-\-next\-controller \e
    # config options for the second controller
  \-\-next\-controller
    # config options for the third controller\*(T>
.fi

The \*(T<\fB\-\-match\fR\*(T> option can be used to limit
the controller slots to only those controllers that
match the given RULE and thus be used to assign
configurations only to specific controllers.
.TP 
\*(T<\fB\-\-detach\fR\*(T>
Detaches xboxdrv from the current shell, only valid
if \*(T<\fB\-\-daemon\fR\*(T> is given.
.TP 
\*(T<\fB\-\-pid\-file\fR\*(T> \fIFILE\fR
Write the xboxdrv daemon process id to FILE.
.TP 
\*(T<\fB\-\-dbus\fR\*(T> \fIBUS\fR
Set which bus type xboxdrv should connect to. Allowed
values for BUS are session,
system,
disabled and
auto. The default is
auto, which will detect the
appropriate bus type depending on if xboxdrv is run as
root (system or as user
(session). Running with
disabled will disable D-Bus support
completely.
.TP 
\*(T<\fB\-\-on\-connect\fR\*(T> \fIEXE\fR
Launches \fIEXE\fR
when a controller gets connected. As arguments
"\fIBUSDEV\fR:\fIDEVNUM\fR",
"\fIidVendor\fR:\fIidProduct\fR",
"\fINAME\fR are provided.
.TP 
\*(T<\fB\-\-on\-disconnect\fR\*(T> \fIEXE\fR
Launches \fIEXE\fR
when a controller gets disconnected. As arguments
"\fIBUSDEV\fR:\fIDEVNUM\fR",
"\fIidVendor\fR:\fIidProduct\fR",
"\fINAME\fR are provided.
.SS "DEVICE OPTIONS"
.TP 
\*(T<\fB\-L\fR\*(T>, \*(T<\fB\-\-list\-controller\fR\*(T>
List available controllers on the system.
.TP 
\*(T<\fB\-i\fR\*(T>, \*(T<\fB\-\-id\fR\*(T> \fIN\fR
Use controller with id N (default: 0),
use \*(T<\fB\-\-list\-controller\fR\*(T> to obtain a list
of available controller.
.TP 
\*(T<\fB\-w\fR\*(T>, \*(T<\fB\-\-wid\fR\*(T> \fIN\fR
Use wireless controller with wid N (default: 0).
.TP 
\*(T<\fB\-\-device\-by\-path\fR\*(T> \fIBUS:DEV\fR
Use the controller at BUS:DEV, do not do any automatic
scanning. Useful for cases when a controller isn't known
by xboxdrv, but supports one of the given protocols.
.TP 
\*(T<\fB\-\-device\-by\-id\fR\*(T> \fIVENDOR:PRODUCT\fR
Use device that matches VENDOR:PRODUCT (as returned
by \fBlsusb\fR). Useful for cases when a
controller isn't known by xboxdrv, but supports one of
the given protocols.
.TP 
\*(T<\fB\-\-type\fR\*(T> \fITYPE\fR
Ignore autodetection and enforce the controller type.
Possible values
for \fITYPE\fR:
.RS 
.TP 0.2i
\(bu
xbox
.TP 0.2i
\(bu
xbox-mat
.TP 0.2i
\(bu
xbox360
.TP 0.2i
\(bu
xbox360-wireless
.TP 0.2i
\(bu
xbox360-guitar
.TP 0.2i
\(bu
firestorm
.TP 0.2i
\(bu
firestorm-vsb
.TP 0.2i
\(bu
saitek-p2500
.TP 0.2i
\(bu
generic-usb
.RE

The \*(T<\fBgeneric\-usb\fR\*(T> type is a special type
that will work with any USB controller, it will however
not interpret the input it gets, but just dump it to the
console for development purposes.
See \*(T<\fB\-\-generic\-usb\-spec\fR\*(T> for further
information.
.TP 
\*(T<\fB\-d\fR\*(T>, \*(T<\fB\-\-detach\-kernel\-driver\fR\*(T>
Detaches the kernel driver that is currently associated
with the given device. This is useful when you have the
xpad module loaded and want to use xboxdrv without
unloading it.
.TP 
\*(T<\fB\-\-generic\-usb\-spec\fR\*(T> \fINAME=VALUE,...\fR
Allows one to specify from which
endpoint \*(T<\fBgeneric\-usb\fR\*(T> will read. The
spec as the form
of \fINAME=VALUE,...\fR. Allowed values are:
.RS 
.TP 
vid=HEX
The vendor id of the controller to which this spec applies
.TP 
pid=HEX
The product id of the controller to which this spec applies
.TP 
if=NUM
The interface from which GenericUSBController should be read
.TP 
ep=NUM
The endpoint from which GenericUSBController should be read
.RE
.SS "EVDEV OPTION"
.TP 
\*(T<\fB\-\-evdev\fR\*(T> \fIDEVICE\fR
Allows you to read input data from a regular event
device. This allows you to
use \fBxboxdrv\fR on regular PC
joysticks. The data that is read from the event device
is converted internally into a XboxMsg object and then
passed through the same configuration pipeline as it
would be for a regular Xbox360 controller. This allows
you to make use of all the regular configurability, but
limits you to the number of axis and buttons that an
Xbox360 controller provides.

As a regular PC joystick will most likely already create
a \*(T<\fI/dev/input/jsX\fR\*(T> device by itself,
you might need to get rid of that so that a game will
properly detect the joystick device created
by \fBxboxdrv\fR. The easiest way to
accomplish that is to simply delete the old joystick and
rename the device that \fBxboxdrv\fR
created to \*(T<\fI/dev/input/js0\fR\*(T>. When you
use udev, this operation should be harmless and
automatically reverse itself when you remove the
controller and plug it back in or when you reboot the
computer.
.TP 
\*(T<\fB\-\-evdev\-debug\fR\*(T>
The evdev event handler will print all received events
to stdout, this makes it easy to see which events a
given controller sends.
.TP 
\*(T<\fB\-\-evdev\-no\-grab\fR\*(T>
By default the evdev driver will grab the device, thus
making it impossible for other applications to receive
events from that device. This is done to avoid confusing
applications, as otherwise an app would receive every
event twice, once from the original device and once from
the virtual xboxdrv one. In some cases this behaviour is
undesired, such when mapping only an otherwise
unhandled subset of keys of an device, i.e. mapping the
multimedia keys on a keyboard, so this option turns the
grab off.
.TP 
\*(T<\fB\-\-evdev\-absmap\fR\*(T> \fIABSMAP,...\fR
.nf
\*(T<ABSMAP = EVDEV_ABS [ "+", "\-" ] "=" XBOXAXIS ;\*(T>
.fi

Sets how evdev events are mapped to Xbox axis
events. An example configuration would look like this:

.nf
\*(T<\-\-evdev\-absmap ABS_X=x1,ABS_Y=y1,ABS_RZ=x2,ABS_THROTTLE=y2,ABS_HAT0X=dpad_x,ABS_HAT0Y=dpad_y\*(T>
.fi

\fBxboxdrv\fR will output on startup a full
list of event names that the given event device
supports and that can be used in place of \fIEVDEV_ABS\fR.

It is also possible to map half-axis with a command like:

.nf
\*(T<\-\-evdev\-absmap ABS_Y+=LT,ABS_Y\-=RT\*(T>
.fi

This will map the upward movement of the Y axis to the
left trigger and the downward movement to the right
trigger. 
.TP 
\*(T<\fB\-\-evdev\-keymap\fR\*(T> \fIKEYMAP\fR
Sets how evdev events are mapped to Xbox controller
events. An example configuration would look like this:

.nf
\*(T<\-\-evdev\-keymap BTN_TRIGGER=a,BTN_THUMB=b,BTN_THUMB2=x\*(T>
.fi

\fBxboxdrv\fR will output on start a full
list of event names that the given event device
supports.
.SS "STATUS OPTIONS"
.TP 
\*(T<\fB\-l\fR\*(T>, \*(T<\fB\-\-led\fR\*(T> \fINUM\fR
Set LED status. Possible values for \fINUM\fR are:

\fBLED Status Codes\fR
.TS
r l.
T{
Num
T}	T{
Behavior
T}
.T&
r l.
T{
0
T}	T{
off
T}
T{
1
T}	T{
all blinking
T}
T{
2
T}	T{
1/top-left blink, then on
T}
T{
3
T}	T{
2/top-right blink, then on
T}
T{
4
T}	T{
3/bottom-left blink, then on
T}
T{
5
T}	T{
4/bottom-right blink, then on
T}
T{
6
T}	T{
1/top-left on
T}
T{
7
T}	T{
2/top-right on
T}
T{
8
T}	T{
3/bottom-left on
T}
T{
9
T}	T{
4/bottom-right on
T}
T{
10
T}	T{
rotate
T}
T{
11
T}	T{
blink
T}
T{
12
T}	T{
blink slower
T}
T{
13
T}	T{
rotate with two lights
T}
T{
14
T}	T{
blink
T}
T{
15
T}	T{
blink once
T}
.TE
.TP 
\*(T<\fB\-\-rumble\-gain\fR\*(T> \fIAMOUNT\fR
You can change the rumble strength via:

.nf
\*(T<$ xboxdrv \-\-rumble\-gain 50%\*(T>
.fi

Values larger then 100% are possible as well and will
amplify small rumble commands, rumble commands already
at the maximum will stay unchanged.
.TP 
\*(T<\fB\-q\fR\*(T>, \*(T<\fB\-\-quit\fR\*(T>
Exit xboxdrv after setting LED or rumble values.
.SS "CHATPAD OPTIONS (EXPERIMENTAL)"
Chatpad support is still experimental. Basic keyboard usage
will work, there is however currently no support for
customization or the green and orange key modifiers.
.PP
Starting xboxdrv multiple times in a row with
the \*(T<\fB\-\-chatpad\fR\*(T> option can crash the
controller. Unplugging it and plugging it back in should reset
it.
.TP 
\*(T<\fB\-\-chatpad\fR\*(T>
Enables the support for the Xbox360 Chatpad. WARNING:
This is preliminary code, it will crash your gamepad
when xboxdrv is started multiple times and won't provide
proper keymapping for any of the umlauts and special
characters.
.TP 
\*(T<\fB\-\-chatpad\-no\-init\fR\*(T>
This will start chatpad support with out sending the
init sequence, thus potentially avoiding crashing the
controller if xboxdrv is started multiple times.
.TP 
\*(T<\fB\-\-chatpad\-debug\fR\*(T>
Output raw chatpad data to the stdout for debugging purpose.
.SS "HEADSET OPTIONS (EXPERIMENTAL, XBOX360 USB ONLY)"
Xboxdrv does not support the headset, the options below are
for developers only and will dump raw headset data, not .wav
files.
.TP 
\*(T<\fB\-\-headset\fR\*(T>
Enable headset support and dump incoming data to stdout.
.TP 
\*(T<\fB\-\-headset\-dump\fR\*(T> \fIFILE\fR
Enable headset support and dump incoming data to FILE.
.TP 
\*(T<\fB\-\-headset\-play\fR\*(T> \fIFILE\fR
Enable headset support and send FILE to the headset for playback.
.SS "FORCE FEEDBACK"
.TP 
\*(T<\fB\-\-force\-feedback\fR\*(T>
Enables the standard kernel force feedback interface. It
is disabled by default as it causes trouble with some
applications running in Wine.

Since the Xbox360 controller supports just rumble not full force
feedback, xboxdrv tries to emulate other effects. This emulation
hasn't been tested much and might not always work as expected. Bug
reports and test cases are welcome.

Note that you must close the application that is using force feedback
always before you close the xboxdrv driver, else you might end up with
a hanging non-interruptable xboxdrv process that will require a reboot
to get rid of.

When using xboxdrv in daemon mode with multiple
controller slots you have to enable force feedback for
each slot separately.
.TP 
\*(T<\fB\-\-ff\-device\fR\*(T> \fIDEVICEID\fR
Select to which virtual device the force-feedback
callbacks will be connected to, it defaults to
joystick. Other allowed values are
mouse,
keyboard and any integer number.
See \*(T<\fB\-\-ui\-buttonmap\fR\*(T> for further
information on how device-ids work.
.TP 
\*(T<\fB\-R\fR\*(T>, \*(T<\fB\-\-test\-rumble\fR\*(T>
Pressing LT will move the left rumble motor and pressing
RT will move the right one. Rumble motor strength
depends on how hard you press. This is useful for
testing the rumble motors.
.TP 
\*(T<\fB\-r\fR\*(T>, \*(T<\fB\-\-rumble\fR\*(T> \fIL,R\fR
Set the speed for both rumble motors. Values from 0 to 255 are accepted, the default is 0,0.
.SS "CONTROLLER SLOT OPTIONS"
Controller slots are used when running xboxdrv in daemon mode.
Each slot represents a complete controller configuration. If
you want to use multiple controller in daemon mode you have to
supply multiple controller slots.
.TP 
\*(T<\fB\-\-controller\-slot\fR\*(T> \fIN\fR
Switches to the controller slot with the number N, numbering starts at zero.
.TP 
\*(T<\fB\-\-next\-controller\fR\*(T>
Switches to the next controller slot.
.TP 
\*(T<\fB\-\-match\fR\*(T> \fIRULE,...\fR
Limits a controller slot to devices that match any one
of the given rules. Possible match rules are:
.RS 
.TP 
usbid=\fIVENDOR\fR:\fIPRODUCT\fR
Match controllers that have the
given USB vendor and product ids.
.TP 
vendor=\fIVENDOR\fR
Match controllers that have the
given USB idVendor.
.TP 
product=\fIPRODUCT\fR
Match controllers that have the
given USB idProduct.
.TP 
property=\fIPROPERTY\fR:\fIVALUE\fR
Match against an arbitrary udev property, with
name \fIPROPERTY\fR and
value \fIVALUE\fR.
.TP 
usbpath=\fIBUS\fR:\fIDEV\fR
Match against the USB path given
by \fIBUS\fR
and \fIDEV\fR.
.TP 
usbserial=\fISERIAL\fR
Match against the USB iSerial number.
.RE
.TP 
\*(T<\fB\-\-match\-group\fR\*(T> \fIRULE,...\fR
Limits a controller slot to devices that match all of
the given rules. Possible match rules are the same as
for \*(T<\fB\-\-match\fR\*(T>.
.SS "CONFIG SLOT OPTIONS"
You can use multiple configurations, called config slots, with
your controller. You switch between those multiple
configurations by pressing the Guide button by default, but
you can also set another button via the option \*(T<\fB\-\-toggle\fR\*(T>.
.TP 
\*(T<\fB\-\-config\-slot\fR\*(T> \fINUM\fR
Select the config slot \fINUM\fR.
.TP 
\*(T<\fB\-\-next\-config\fR\*(T>
Allows the creation of an alternative uinput
configuration to which one can toggle at runtime by
pressing the ui-toggle button (defaults to guide).

.nf
\*(T<$ xboxdrv \e
    \-\-mouse \e
  \-\-next\-config 
    \-\-ui\-axismap X1=ABS_X,Y1=ABS_Y \e
    \-\-ui\-buttonmap A=JS_0,B=JS_1\*(T>
.fi

The above configuration would install mouse emulation as
first configuration and a simple joystick emulation as
second configuration. Allowing toggling between mouse
emulation and joystick handling by pressing the guide
button.

Not that \*(T<\fB\-\-next\-config\fR\*(T> is currently limited
to only configurations done
with \*(T<\fB\-\-ui\-buttonmap\fR\*(T>
and \*(T<\fB\-\-ui\-axismap\fR\*(T>, autofire, throttle
emulation, deadzones and all other things can currently
not be switched at runtime.
.TP 
\*(T<\fB\-\-toggle\fR\*(T> \fIXBOXBTN\fR
Sets the button that will be used to toggle between
different different configurations. A value of 'void'
will disable the toggle button. If no toggle button is
specified, the guide button will be used to toggle
between configurations.
.SS "CONFIGURATION OPTIONS"
.TP 
\*(T<\fB\-\-modifier \fR\*(T>\fIMOD\fR
Add a modifier to the modifier stack, see
[Modifier] for
a full list of possible modifier.
.TP 
\*(T<\fB\-\-timeout \fR\*(T>\fIMSEC\fR
Specify the number of milliseconds that xboxdrv will wait
for events from the controller before moving on and
processing things like auto-fire or relative-axis.
Default value is 10, smaller values will give you a
higher resolution auto fire and relative event movement, but will waste some more
CPU.
.TP 
\*(T<\fB\-b, \-\-buttonmap BUTTON=BUTTON,...\fR\*(T>
Button remapping is available via the \*(T<\fB\-\-buttonmap\fR\*(T> option. If you want
to swap button A and B start with:

.nf
\*(T<$ xboxdrv \-\-buttonmap A=B,B=A\*(T>
.fi

If you want all face buttons send out A button events:

.nf
\*(T<$ xboxdrv \-\-buttonmap B=A,X=A,Y=A\*(T>
.fi

Possible button names are (aliases are in parenthesis):

\fBButton Names\fR
.TS
allbox ;
l l.
T{
Name
T}	T{
Description
T}
.T&
l l.
T{
start, back
T}	T{
start, back buttons
T}
T{
guide
T}	T{
big X-button in the middle (Xbox360 only)
T}
T{
a(1), b(2), x(3), y(4)
T}	T{
face buttons
T}
T{
black, white
T}	T{
black, white buttons (Xbox1 only, mapped to lb, rb on Xbox360)
T}
T{
lb(5), rb(6)
T}	T{
shoulder buttons (Xbox360 only, mapped to black, white on Xbox1)
T}
T{
lt(7), rt(8)
T}	T{
analog trigger (needs \-\-trigger\-as\-button option)
T}
T{
tl, tr
T}	T{
pressing the left or right analog stick
T}
T{
du(up), dd(down), dl(left), dr(right)
T}	T{
dpad directions (needs \-\-dpad\-as\-button option)
T}
T{
green, red, yellow, blue, orange
T}	T{
guitar buttons
T}
.TE

Just like with \*(T<\fB\-\-ui\-buttonmap\fR\*(T> you can add button filter to each button.
.TP 
\*(T<\fB\-\-axismap\fR\*(T> \fIAXIS=MAPPING,...\fR
Axis remapping is available via \-\-axismap and works the same as button
mapping. In addition you can supply a sign to indicate that an axis
should be inverted. So if you want to invert the y1 axis start with:

.nf
\*(T<$ xboxdrv \-\-axismap \-Y1=Y1\*(T>
.fi

If you want to swap the left and right stick start with:

.nf
\*(T<$ xboxdrv \-\-axismap X2=X1,Y2=Y1,X1=X2,Y1=Y2\*(T>
.fi

Possible axis names are: x1, y1, x2, y2, lt, rt

Swaping lt or rt with x1, y1, x2, y2 will not work properly, since
their range is different.

Just like with \*(T<\fB\-\-ui\-axismap\fR\*(T> you can add axis filter to each axis.
.SS "MODIFIER PRESET CONFIGURATION OPTIONS"
The options in this sections are sortcuts
for \*(T<\fB\-\-modifier\fR\*(T> options.
Unlike \*(T<\fB\-\-modifier\fR\*(T> they are not order
depended, but have a predefined order that is used no matter
the order in which the options are given.
.TP 
\*(T<\fB\-\-autofire BUTTON=FREQUENCY,...\fR\*(T>
Autofire mapping allows you to let a button automatically fire with a
given frequency in milliseconds:

.nf
\*(T<$ xboxdrv \-\-autofire A=250\*(T>
.fi

Combining \*(T<\fB\-\-autofire\fR\*(T> with button map allows you to have one button act
as autofire while another one, emitting the same signal, acts normally.

.nf
\*(T<$ xboxdrv \-\-autofire B=250 \-\-buttonmap B=A\*(T>
.fi
.TP 
\*(T<\fB\-\-axis\-sensitivty \fR\*(T>\fIAXIS=SENSITIVITY\fR,...
The sensitive of an axis can be adjusted via \-\-axis\-sensitivty:

.nf
\*(T<$ xboxdrv \-\-axis\-sensitivty X1=\-1.0,Y1=\-1.0\*(T>
.fi

A value of 0 gives you the default linear sensitivity,
values larger then 0 will give you higher sensitivity,
while values smaller then 0 will give you lower
sensitivity. Sensitivity values in the range of [\-1, 1]
will generally give good results, everything beyond that
won't be of much practical use.

Sensitivity works by applying:

.nf
\*(T<t = 2 ** sensitivity;
pos = (1.0f \- (1.0f \- pos) ** t) ** (1 / t);\*(T>
.fi

To the value of the axis, this means that both the
minimum value and the maximum value of the axis will
always stay the same, just the response inbetween
changes.

For a complete freeform way to change the axis response
see the \*(T<\fBResponse Curve Filter\fR\*(T>.
.TP 
\*(T<\fB\-\-calibration \fR\*(T>\fICALIBRATIONSPEC\fR
If your gamepad for some reason can't reach the maximum value or isn't
centered properly you can fix that via the calibration options:

.nf
\*(T<$ xboxdrv \-\-calibration X2=\-32768:0:32767\*(T>
.fi

X2 is the axis name and the three values that follow are min, center
and max. Simply insert the values that jstest reports when your axis
is in the respective positions.

You can also use the calibration option if you want to make your
joystick more sensitive. A setting of:

.nf
\*(T<xboxdrv \-\-calibration AXIS=MIN:CENTER:MAX,...\*(T>
.fi

Will cause the joystick device report maximum position when your
stick is only moved half the way.
.TP 
\*(T<\fB\-\-deadzone \fR\*(T>\fINUM\fR
The deadzone is the area at which the sticks do not report any
events. The default is zero, which gives the best sensitifity but
might also cause trouble in some games in that the character or camera
might move without moving the stick. To fix this one has to set the
value to something higher:

.nf
\*(T<$ xboxdrv \-\-deadzone 4000\*(T>
.fi

A value of 4000 works quite well for most games.

You can also give the deadzone in percentage:

.nf
\*(T<$ xboxdrv \-\-deadzone 15%\*(T>
.fi
.TP 
\*(T<\fB\-\-deadzone\-trigger \fR\*(T>\fINUM\fR
The left and right trigger have a separate deadzone value which can be
specified with:

.nf
\*(T<$ xboxdrv \-\-deadzone\-trigger 15%  \*(T>
.fi
.TP 
\*(T<\fB\-\-dpad\-rotation\fR\*(T> \fIDEGREE\fR
Allows you to rotate the
dpad. \fIDEGREE\fR
must be a multiple of 45. This can be useful in
isometric games where the playfield itself is rotated,
thus a:

.nf
\*(T<xboxdrv \-\-dpad\-rotation 45\*(T>
.fi

Will give you controls that are relative to your
character instead of your viewpoint.
.TP 
\*(T<\fB\-\-four\-way\-restrictor\fR\*(T>
The \*(T<\fB\-\-four\-way\-restrictor\fR\*(T> option allows one to
limit the movement on both analogsticks to only four
directions (up, down, left, right), the diagonals (up/left,
up/right, down/left, down/right) are filtered out from the
output. This option is useful for games such as Tetris, that
don't need diagonals and where you don't want to accidentally
trigger the down-move while trying to do a left/right move.
.TP 
\*(T<\fB\-\-relative\-axis AXIS=NUM,...\fR\*(T>
The function \*(T<\fB\-\-relative\-axis\fR\*(T> allows you
to change the behaviour of an axis so that your movement
of it moves its value up or down instead of applying it
directly. This allows you to simulate throttle control
for flightsim games.

Since the axis might be upside down, you might want to use
the \*(T<\fB\-\-axismap\fR\*(T> function to reverse it.

.nf
\*(T<$ xboxdrv \-\-relative\-axis y2=64000 \-\-axismap \-y2=y2\*(T>
.fi
.TP 
\*(T<\fB\-\-square\-axis\fR\*(T>
The Xbox360 gamepad, as most other current day gamepads,
features a circular movement range, which restricts the
movement so that the distance to the center never gets
beyond 1. This means that when you have the controller
at the top/left the value reported is (0.7, 0.7)
(i.e. length 1, angle 45) instead of (1,1). This
behaviour is different then most classic PC joysticks,
which had a square range and would report (1,1) when
hold in the top/left corner.

Some old games (i.e. mostly DOS stuff) require a
square movement range and will not function properly
with the Xbox360 gamepad. Via the
\*(T<\fB\-\-square\-axis\fR\*(T> option you can work around this issue and diagonals will
be reported as (1,1).
.SS "UINPUT PRESET CONFIGURATION OPTIONS"
The following options are simple shortcuts for common
configurations that can be accomplished manually 
by using \*(T<\fB\-\-ui\-buttonmap\fR\*(T>
and \*(T<\fB\-\-ui\-axismap\fR\*(T>.
.TP 
\*(T<\fB\-\-trigger\-as\-button\fR\*(T>
LT and RT send button instead of axis events
.TP 
\*(T<\fB\-\-trigger\-as\-zaxis\fR\*(T>
Combine LT and RT to form a zaxis instead
.TP 
\*(T<\fB\-\-dpad\-as\-button\fR\*(T>
The DPad sends button instead of axis events.
.TP 
\*(T<\fB\-\-dpad\-only\fR\*(T>
Both sticks are ignored, only the DPad sends out axis
events. Useful for games that might get confused by
additional analog axis. Combining this option
with \*(T<\fB\-\-trigger\-as\-button\fR\*(T> is recommend
in most situations.
.TP 
\*(T<\fB\-\-guitar\fR\*(T>
Sets a predefined button and axis mapping for use with
guitar controllers. This mainly gets rid of a few
unnecessary buttons and axis not used by a guitar
controller.
.TP 
\*(T<\fB\-m, \-\-mouse\fR\*(T>
Lets the controller act as a mouse. It is indendical to:

.nf
\*(T<$ xboxdrv \e
  \-\-dpad\-as\-button
  \-\-deadzone 4000
  \-\-trigger\-as\-zaxis
  \-\-axismap "\-y2=y2,\-trigger=trigger"
  \-\-ui\-axismap "x1=REL_X:15:20,y1=REL_Y:15:20,y2=REL_WHEEL:5:100,x2=REL_HWHEEL:5:100,trigger=REL_WHEEL:5:100"
  \-\-ui\-buttonmap "a=BTN_LEFT,b=BTN_RIGHT,x=BTN_MIDDLE,y=KEY_ENTER,rb=KEY_PAGEDOWN,lb=KEY_PAGEUP,"
  \-\-ui\-buttonmap "dl=KEY_LEFT,dr=KEY_RIGHT,du=KEY_UP,dd=KEY_DOWN,"
  \-\-ui\-buttonmap "start=KEY_FORWARD,back=KEY_BACK,guide=KEY_ESC,tl=void,tr=void"\*(T>
.fi

You can customize it by the usual means, just make sure
that \*(T<\fB\-\-mouse\fR\*(T> comes before your
customization options on the command line.

Note that if you have your mouse buttons switched you must
adjust the above to match your mouse configuration or the
button events will come out wrong.
.TP 
\*(T<\fB\-\-mimic\-xpad\fR\*(T>
Causes xboxdrv to use the same axis and button names as
the xpad kernel driver for wired Xbox360 controller
.TP 
\*(T<\fB\-\-mimic\-xpad\-wireless\fR\*(T>
Causes xboxdrv to use the same axis and button names as
the xpad kernel driver for wired Xbox360 controller
.SS "UINPUT CONFIGURATION OPTIONS"
.TP 
\*(T<\fB\-\-no\-uinput\fR\*(T>
Do not to start UInput, instead simply read events from the controller, useful for debugging.
.TP 
\*(T<\fB\-\-no\-extra\-devices\fR\*(T>
By default xboxdrv will allocate multiple uinput devices
and sort events to each of them. Thus mouse related
events like BTN_LEFT or REL_X will go to a virtual mouse
device, while ABS_X events would go to a virtual
joystick device and KEY_ESC would go to a virtual
keyboard device.

This option disables that automatism and all events will
go to the same virtual device.

Manual assignment to a specific device (i.e.
KEY_ESC@keyboard, BTN_A@joystick, ...) is still possible.
.TP 
\*(T<\fB\-\-no\-extra\-events\fR\*(T>
By default xboxdrv will allocate multiple uinput devices
and sort events to each of them. Thus mouse related
events like BTN_LEFT or REL_X will go to a virtual mouse
device, while ABS_X events would go to a virtual
joystick device and KEY_ESC would go to a virtual
keyboard device.

To make sure sure that a mouse, keyboard or joystick
device is properly detected by Xorg, the kernel or
libraries such SDL xboxdrv will insert extra dummy
events. For example a mouse device needs REL_X and REL_Y
events to be detected as such, but a configuration that
only wants to emulate the mouse buttons won't provide
those, thus xboxdrv will add them automatically.
The \*(T<\fB\-\-no\-extra\-events\fR\*(T> option will
switch this behaviour off.
.TP 
\*(T<\fB\-\-device\-name NAME\fR\*(T>
Changes the descriptive name the device will have. This
options acts the same as
\-\-device\-names \fICURRENTSLOT\fR.auto=\fINAME\fR
.TP 
\*(T<\fB\-\-device\-names TYPE.SLOT=NAME,...\fR\*(T>
Changes the descriptive name the device will
have. \fITYPE\fR is one of mouse,
keyboard, joystick, auto
or a number. \fISLOT\fR is a slot
number or auto.
The auto name acts as wild card and
matches everything.
.TP 
\*(T<\fB\-\-device\-usbid VENDOR:PRODUCT:VERSION:BUS\fR\*(T>
Changes the vendor, product, version and bus id that the
device will have. The last two arguments are optional.
This options acts the same as
\-\-device\-usbids \fICURRENTSLOT\fR.auto=\fIVENDOR:PRODUCT:VERSION:BUS\fR
.TP 
\*(T<\fB\-\-device\-usbids TYPE.SLOT=VENDOR:PRODUCT:VERSION:BUS,...\fR\*(T>
Changes the vendor, product, version and bus id the device will
have. \fITYPE\fR is one of mouse,
keyboard, joystick, auto
or a number. \fISLOT\fR is a slot
number or auto.
The auto name acts as wild card and
matches everything.
.TP 
\*(T<\fB\-\-ui\-clear\fR\*(T>
Removes all uinput mappings and will leave the driver in
a blank state and only map those things you added
yourself. If you only want to get rid of individual
buttons you can use the 'void' event.
.TP 
\*(T<\fB\-\-ui\-buttonmap\fR\*(T> \fIUIBUTTONSPEC,...\fR
.nf
\*(T<UIBUTTONSPEC = XBOXBUTTON [ "+" XBOXBUTTON ] [ "^" FILTER ] ... "=" ( RELSPEC | BTNSPEC | EXECSPEC ) ;
RELSPEC      = [ DEVICEID "\-" ] "REL_" [ ":" [ VALUE ] [ ":" REPEAT ] ] ;
BTNSPEC      = [ DEVICEID "\-" ] ( ( "BTN_" NAME ) | ( "KEY_" NAME ) ) { "+" BTNSPEC } ;
EXECSPEC     = PROGRAM { ":" ARGUMENT } ;
XBOXBUTTON   = "a" | "b" | "x" | "y" | "lb" | "rb" | "lt" | "rt" | 
               "tl" | "tr" | "start" | "select" | "back" | "guide" | "black" | "white" ;
FILTER       = "toggle" | "invert" | "autofire" [ ":" RATE ] [ ":" DELAY ] | log [ ":" STRING ] ;
NAME         = STRING ;
VALUE        = NUMBER ;
REPEAT       = NUMBER ;
DEVICEID     = NUMBER ;\*(T>
.fi

Allows you to change the event code that is send to the
kernel for buttons. The usage is similar to the normal button
mapping, except that the right hand side is an event name from
\*(T<\fI/usr/include/linux/input.h\fR\*(T>. You can
use all \fBKEY_\fR or \fBBTN_\fR 
codes for \*(T<\fB\-\-ui\-buttonmap\fR\*(T>.

If the right hand side is left empty all the supplied
filters will be added to the already existing button
binding instead of a new one.

Aside from the named keys, you can also give the input
code directly as number via the
syntax \fBKEY_#\fINUM\fB\fR.

Instead of the low level \fBKEY_\fR names,
which represent keycodes, you can also use the higher
level X11 keysyms \fBXK_\fR, the keysyms have
the advantage that they map directly to the key you
expect, while a \fBKEY_\fR name gets mangled
by the X11 keymap and will often not report what you
expect in case you use a keymap that is different then
your keyboard (i.e. dvorak on a qwerty keyboard).

A full list of valid X11 keysyms can be optained
with \*(T<\fB\-\-help\-x11keysym\fR\*(T>.

For joystick buttons there is in addition to the \fBBTN_JOYSTICK\fR, \fBBTN_X\fR,
etc. macros the special name \fBJS_$NUM\fR, which sets the given button to
the $NUMS joystick button, i.e.:

.nf
\*(T<$ xboxdrv \-\-ui\-clear \-\-ui\-buttonmap A=JS_0,B=JS_1\*(T>
.fi

Note that this will only work if no other joystick
button ids are in the way.

You can also map a button to a \fBREL_\fR
event. In that case you can supply additional paramaters in the form of:

.nf
\*(T<$ xboxdrv \-\-ui\-buttonmap X=REL_???:VALUE:REPEAT\*(T>
.fi

\fIVALUE\fR gives the value of the event (default: 10)

\fIREPEAT\fR
gives the number of millisecond to pass before the event
is fired again (default: 5)

The special 'void' event allows you to clear any
existing bindings for a given button, which can be
useful in cases when a game only supports a limited
number of buttons.

You can also prepend a device_id to the UIBUTTONSPEC
which allows you to create multiple uinput devices. By
default 'auto' is assumed as device_id which
automatically try to do the right thing, sending
keyboard events to a keyboard device and mouse events to
a mouse device. Other possible values are 'mouse' and
\&'keyboard'. A device_id of '0' refers to the first
joystick device, values larger then 0 to the second,
third, etc. 

Note that the 'mouse' and 'keyboard' device_id names do
not give you a mouse or keyboard device, these are just
symbolic names for the devices into which xboxdrv will
sort events that look like a mouse or keyboard
event. The final determination of which device gets
handled as what will be done by the Kernel or Xorg
depending on what events a device provides. 

An example configuration making use of device_id would look like this:

.nf
\*(T<xboxdrv \-s \e
  \-\-ui\-clear \e
  \-\-ui\-buttonmap A=JS_0@0,B=JS_1@0 \-\-ui\-axismap X2=ABS_X@0,Y2=ABS_Y@0
  \-\-ui\-buttonmap X=JS_0@0,Y=1\-JS_1@0 \-\-ui\-axismap X2=ABS_X@1,Y2=ABS_Y@1\*(T>
.fi

In this example the left stick creates a joystick device
and the right stick creates a separate joystick device.

When using multiple controller slots you can
additionally append the slot id and thus assign events
across controller slot boundaries. The syntax for that
is:

.nf
\*(T<BTN_A@{deviceid}.{slotid}\*(T>
.fi

Instead of giving just a single button, it is also
possible to give two buttons
to \*(T<\fB\-\-ui\-buttonmap\fR\*(T> to allow shifting:

.nf
\*(T<xboxdrv \-s \e
  \-\-ui\-clear \e
  \-\-ui\-buttonmap A=JS_0,B=JS_1,LB+A=JS_2,LB+B=JS_3\*(T>
.fi

In this example LB acts as shift button, if A is pressed
without LB it will send out a JS_0 event, but if LB is
pressed it will send a JS_2 event instead. This allows
you to multiply the number of available buttons on the
controller.

See the section KEYBOARD EMULATION below on how to
resolve issues with Xorg not detecting the virtual
keyboard that xboxdrv creates.

You can also apply filters to button events:

.nf
\*(T<xboxdrv \-s \e
  \-\-ui\-buttonmap A^toggle=JS_0\*(T>
.fi

For documentation on the filters you can apply to events
see [Button Filter].
.TP 
\*(T<\fB\-\-ui\-axismap\fR\*(T> \fIUIAXISSPEC,...\fR
.nf
\*(T<UIAXISSPEC = [ XBOXBTN "+" ] XBOXAXIS { "^" FILTER }  "=" ( RELSPEC | RELREP | KEYSPEC | ABSSPEC ) ;
KEYSPEC    = [ "key:" ] "KEY_" NAME ":" "KEY_" NAME ":" THRESHOLD ;
RELSPEC    = [ "rel:" ] "REL_" NAME ":" VALUE ":" REPEAT ;
RELREP     = "rel\-repeat:" "REL_" NAME ":" VALUE ":" REPEAT ;
ABSSPEC    = [ "abs:" ] "ABS_" NAME ;
FILTER     = ( "calibration" | "cal" ) ":" MIN ":" CENTER ":" MAX |
             ( "sensitifity" | "sen" ) ":" SENSITIFITY |
             ( "deadzone" | "dead" ) ":" MIN ":" MAX ":" SMOOTH |
             ( "relative" | "rel" ) ":" SPEED  |
             ( "responsecurve" | "response" | "resp" ) { ":" VALUE }
XBOXBTN    = "a" | "b" | "x" | "y" | "start" | "back" | "guide" | "lb" | "rb" | ...
XBOXAXIS   = "x1" | "y1" | "x2" | "y2" | "z" | "lt" | "rt" | "dpad_x" | "dpad_y" ;
VALUE      = NUMBER ;
REPEAT     = NUMBER ;
THRESHOLD  = NUMBER ;
NAME       = STRING ;\*(T>
.fi

Similar to \*(T<\fB\-\-ui\-buttonmap\fR\*(T> this option
allows you to change the event code that is send to the
kernel for axes. The events that are available are the
same as for \*(T<\fB\-\-ui\-buttonmap\fR\*(T>.

.nf
\*(T<$ xboxdrv \-\-ui\-axismap X1=REL_???:VALUE:REPEAT\*(T>
.fi

\fIVALUE\fR gives
the maximum value of the event, the actual value that gets send
is \fIVALUE\fR * axis_state.
(default: 10)

\fIREPEAT\fR
gives the number of millisecond to pass before the event
is fired again (default: 5).

The value of \-1 has a special meaning, it will result in
the REL event being fired as soon as possible (i.e.
every \fItimeout\fR milliseconds).
This is the recomment way for handling mouse emulation,
as it will keep REL events syncronized and thus avoid
jaggies in the movement, that will result from manually
specifying a timeout.

.nf
\*(T<$ xboxdrv \-\-ui\-axismap X1=KEY_UP:KEY_DOWN:THRESHOLD\*(T>
.fi

\fIKEY_UP\fR gives the keycode to be send when the axis is moved up

\fIKEY_DOWN\fR gives the keycode to be send when the axis is moved down

\fITHRESHOLD\fR gives the threshold that triggers the sending of an event

Just like \*(T<\fB\-\-ui\-buttonmap\fR\*(T>, you can
also use shift keys in place of the XBOXAXIS:

.nf
\*(T<$ xboxdrv \-\-ui\-axismap X1=ABS_X,LB+X1=ABS_RX\*(T>
.fi

This allows you to send ABS_X events normally and ABS_RX
events when the LB button is held down.

For information on how to use axis filters, see [Axis Filter].
.SH "INPUT EVENT HANDLER"
Input event handler decide what comes out of the virtual input
devices that xboxdrv creates. They for example decide that when
button A is pressed on a gamepad, that a virtual keyboard will
emit a press of the space key.
.PP
Furthermore input event handler can also perform some basic
transformation of the input signals, thus a joystick can be used
to send WASD keys.
.SS "BUTTON EVENT HANDLER"
A button event handler decides what happens when a button is
pressed, it needs to be specified with
the \*(T<\fB\-\-ui\-buttonmap\fR\*(T> option. The example below
shows the simplest use case:
.PP
.nf
\*(T<$ xboxdrv \-\-ui\-buttonmap A=key:KEY_A\*(T>
.fi
.PP
Here \*(T<\fBkey\fR\*(T> is the name of the button event
handler, while \*(T<\fBKEY_A\fR\*(T> is an argument for the
event handler. What kind of arguments an event handler allows
depends on the event handler.
.PP
There is also a shorthand form of specifying event handlers by
just writing:
.PP
.nf
\*(T<$ xboxdrv \-\-ui\-buttonmap A=KEY_A\*(T>
.fi
.PP
Here no handler is specified explicitly, if that is the case,
the appropriate handler will be guessed based on the event
type. \*(T<EV_KEY\*(T> events will be handled by
the \*(T<\fBkey\fR\*(T> handler, \*(T<EV_REL\*(T> by
the \*(T<\fBrel\fR\*(T> handler and \*(T<EV_ABS\*(T> by
the \*(T<\fBabs\fR\*(T> handler. 
.TP 
\*(T<\fBkey\fR\*(T>:\fIKEY_EVENT\fR, \*(T<\fBkey\fR\*(T>:\fIKEY_EVENT\fR:\fIKEY_EVENT\fR:\fIHOLD_THRESHOLD_MSEC\fR
The \*(T<\fBkey\fR\*(T> handler is the most basic one,
it maps a button directly to a virtual key or another
button.

If additional arguments are supplied the button will be
able to send out two different events. The first event
specified will be send when the button is clicked
normally, while the second event will be send in case
the button is hold down for the time specified
in \fIHOLD_THRESHOLD_MSEC\fR.

An example for the hold button would look like:

.nf
\*(T<xboxdrv \e
  \-\-ui\-buttonmap A=JS_0:JS_1:500\*(T>
.fi

This will send JS_0 events when the button is pressed
and switch to JS_1 events when the button was hold for
500 milliseconds.

The hold button feature is useful to effectively double the
number of available buttons, thus the dpad can for
example be used to send out eight different button
events instead of just four, which is enough to handle
weapons in most FPS games.
.TP 
\*(T<\fBabs\fR\*(T>
not yet implemented
.TP 
\*(T<\fBrel\fR\*(T>:\fIREL_EVENT\fR:\fIVALUE\fR:\fIREPEAT\fR
The rel handler will send out a REL event whenever the
button is pressed. \fIVALUE\fR
gives the value of the event that will be send,
while \fIREPEAT\fR gives the number
of milliseconds till the event will be send again.

A typical use for REL events is emulation of the scroll
wheel of a mouse, an example configuration would be:

.nf
\*(T<xboxdrv \e
  \-\-ui\-buttonmap Y=rel:REL_WHEEL:1:500,A=rel:REL_WHEEL:\-1:500\*(T>
.fi

Here Y will scroll up and A will scroll down.
.TP 
\*(T<\fBcycle\-key\fR\*(T>:\fIKEY_EVENT\fR:...
The cycle-key handler will switch
the \fIKEY_EVENT\fR that gets send
with each button press. This is useful in situations
where a range of buttons should be mapped to a single
key. For example a FPS might have weapons mapped from 1
to 6, but only a single key on the gamepad is free, thus
one could write:

.nf
\*(T<xboxdrv \e
  \-\-ui\-buttonmap A=cycle\-key:KEY_1:KEY_2:KEY_3:KEY_4:KEY_5:KEY_6\*(T>
.fi
.TP 
\*(T<\fBcycle\-key\-named:\fR\*(T>\fINAME\fR\*(T<\fB:\fR\*(T>\fIKEY_EVENT\fR\*(T<\fB:...\fR\*(T>
The \*(T<\fBcycle\-key\-named\fR\*(T> handler works
exactly like the \*(T<\fBcycle\-key\fR\*(T> handler,
except that a name has to be supplied for the cycle
sequence. The name of the sequence is used
by \*(T<\fBcycle\-key\-ref\fR\*(T> to access the
sequence and reuse it for another button.

In this simple example A is used to toggle through all
weapon keys forward, while B is used to toggle the keys backwards:

.nf
\*(T<xboxdrv \e
  \-\-ui\-buttonmap A=cycle\-key\-named:weapons:KEY_1:KEY_2:KEY_3:KEY_4,B=cycle\-key\-ref:weapons\*(T>
.fi
.TP 
\*(T<\fBcycle\-key\-ref\fR\*(T>:\fINAME\fR:\fIDIRECTION\fR, \*(T<\fBsequence\-key\-ref\fR\*(T>:\fINAME\fR:\fIDIRECTION\fR
The \*(T<\fBcycle\-key\-ref\fR\*(T> handler will access
and reuse the named cycle keysequence given
by \fINAME\fR.
If \fIDIRECTION\fR can either be
\&'forward' or 'backward', if no direction is supplied it
will default to 'backward'.

See \*(T<\fBcycle\-key\-named\fR\*(T> for a full example.
.TP 
\*(T<\fBsequence\-key\-named:\fR\*(T>\fINAME\fR\*(T<\fB:\fR\*(T>\fIKEY_EVENT\fR\*(T<\fB:...\fR\*(T>
The \*(T<\fBsequence\-key\-named\fR\*(T> works exactly
the same as the \*(T<\fBcycle\-key\-named\fR\*(T>, with
the only difference being that
the \*(T<\fBsequence\-key\-named\fR\*(T> will not wrap
around when reaching the beginning or end of the
sequence.

This behaviour is useful in flight simulations or other
games where thrusters might be controllered by numeric
keys and it wouldn't make much sense to jump from zero
to full thrust in one go.

To move backwards through the sequence another key must
be bound to \*(T<\fBsequence\-key\-ref\fR\*(T>.
.TP 
\*(T<\fBexec\fR\*(T>
The exec button handler allows one to launch an application
when the button was pressed. An example would look like
this:

.nf
\*(T<xboxdrv \e
  \-\-ui\-buttonmap A=exec:/home/juser/local/bin/screenshot.sh\*(T>
.fi

Possible uses for the button are the ability to do
screenshots or perform other tasks that are outside the
main application you are using xboxdrv with.
.TP 
\*(T<\fBmacro\fR\*(T>
A button can be bound to a macro via:

.nf
\*(T<xboxdrv \e
  \-\-ui\-buttonmap A=macro:/home/juser/.xboxdrv/somefile.macro\*(T>
.fi

The \*(T<\fI.macro\fR\*(T> file has the form of:

.nf
\*(T<
send KEY_LEFTSHIFT 1
wait 500
send KEY_LEFTSHIFT 0\*(T>
.fi

All abs, rel and key events can be send from a macro file.
.SS "AXIS EVENT HANDLER"
Axis event handler decide what happens when an axis is moved.
Like button event handler they come in different forms and
like button event handler they provide a shortcut
form. \*(T<EV_KEY\*(T> events will be handled by
the \*(T<\fBkey\fR\*(T> handler, \*(T<EV_REL\*(T> by
the \*(T<\fBrel\fR\*(T> handler and \*(T<EV_ABS\*(T>
by the \*(T<\fBabs\fR\*(T> handler.
.TP 
\*(T<\fBabs\fR\*(T>:\fIABS_EVENT\fR
The \*(T<\fBabs\fR\*(T> handler is the simplest of them
all, it will simply send out the value it gets as input
as the given \fIABS_EVENT\fR event
to the kernel. Thus a basic configuration to make the
left stick behave as joystick would look like this:

.nf
\*(T<xboxdrv \e
  \-\-ui\-axismap X1=abs:ABS_X,Y1=abs:ABS_Y\*(T>
.fi
.TP 
\*(T<\fBkey\fR\*(T>:\fIKEY_UP\fR:\fIKEY_DOWN\fR:\fITHRESHOLD\fR
\fIKEY_UP\fR gives the keycode to be send when the axis is moved up

\fIKEY_DOWN\fR gives the keycode to be send when the axis is moved down

\fITHRESHOLD\fR gives the threshold that triggers the sending of an event

Just like \*(T<\fB\-\-ui\-buttonmap\fR\*(T>, you can
also use shift keys in place of the XBOXAXIS:

.nf
\*(T<$ xboxdrv \-\-ui\-axismap X1=ABS_X,LB+X1=ABS_RX\*(T>
.fi

This allows you to send ABS_X events normally and ABS_RX
events when the LB button is held down.
.TP 
\*(T<\fBrel\fR\*(T>:\fIREL_EVENT\fR:\fIVALUE\fR:\fIREPEAT\fR
\fIVALUE\fR gives
the maximum value of the event, the actual value that gets send
is \fIVALUE\fR * axis_state.
(default: 10)

\fIREPEAT\fR
gives the number of millisecond to pass before the event
is fired again (default: 5).

The value of \-1 has a special meaning, it will result in
the REL event being fired as soon as possible (i.e.
every \fItimeout\fR milliseconds).
This is the recomment way for handling mouse emulation,
as it will keep REL events syncronized and thus avoid
jaggies in the movement, that will result from manually
specifying a timeout.

The \*(T<\fBrel\fR\*(T> handler is mainly useful for
mouse pointer emulation, if you want to emulate a mouse
scroll wheel use the \*(T<\fBrel\-repeat\fR\*(T> handler
instead.
.TP 
\*(T<\fBrel\-repeat\fR\*(T>:\fIREL_EVENT\fR:\fIVALUE\fR:\fIREPEAT\fR
The \*(T<\fBrel\-repeat\fR\*(T> handler is similar to
the \*(T<\fBrel\fR\*(T> handler, but optimized for
emulating the scroll wheel of a mouse.

\fIVALUE\fR isn't scaled to how far
the axis has moved, instead it is constant, instead the
time given in \fIREPEAT\fR is
scaled according to the axis movement. Thus the further
the stick is moved, the more events will be send.

The need for both \*(T<\fBrel\-repeat\fR\*(T>
and \*(T<\fBrel\fR\*(T> arises from the fact that Xorg
converts scroll wheel movement to button presses before
they are handed to an application, thus an application
never properly sees the changes
in \fIVALUE\fR, by
scaling \fIREPEAT\fR instead that
problem is worked around.
.SH "INPUT FILTER"
Input filters allow one to manipulate the events that come from the
controller. They can be used
on \*(T<\fB\-\-buttonmap\fR\*(T>, \*(T<\fB\-\-axismap\fR\*(T>, \*(T<\fB\-\-ui\-buttonmap\fR\*(T>
and \*(T<\fB\-\-ui\-axismap\fR\*(T>. The difference between the
two is that the \*(T<\fB\-\-ui\-...\fR\*(T> versions applies to
the uinput events, while the other version applies to Xbox360
controller events.
.SS "BUTTON FILTER"
.TP 
\*(T<\fBtog\fR\*(T>, \*(T<\fBtoggle\fR\*(T>
The toggle filter will turn the button into a toggle
button, clicking the button will set it to pressed state
and pressing it again will unpress it. Useful for games
where you might want to permanently run or duck without
holding the button pressed.
.TP 
\*(T<\fBinv\fR\*(T>, \*(T<\fBinvert\fR\*(T>
The invert filter will keep the button in pressed state
when it is not pressed and in unpressed state when it is
pressed.
.TP 
\*(T<\fBauto\fR\*(T>, \*(T<\fBautofire\fR\*(T>:\fIRATE\fR:\fIDELAY\fR
The autofire filter allows one to repeatedly send button
press events when the button is held down. It takes two
optional parameters:

\fIRATE\fR is the number of
milliseconds between button press events.

\fIDELAY\fR the amount of
milliseconds till the autofire will start, before that
delay the button will act as normal.
.TP 
\*(T<\fBclick\-press\fR\*(T>
The \*(T<\fBclick\-press\fR\*(T> filter will transmit a single button
click when the button is pressed.
.TP 
\*(T<\fBclick\-release\fR\*(T>
The \*(T<\fBclick\-release\fR\*(T> filter will transmit a single button
click when the button is released.
.TP 
\*(T<\fBclick\-both\fR\*(T>
The \*(T<\fBclick\-both\fR\*(T> filter will transmit a
single button click when the button is pressed and
another one when it is released.
.TP 
\*(T<\fBconst\fR\*(T>:\fIVALUE\fR
The const filter will ignore the input signal and send a
constant value to the output. This can be used for
example in combination with multiple configurations to
signal a game or another application which configuration
is currently active.
.TP 
\*(T<\fBdelay\fR\*(T>:\fITIME\fR
A button has to be held down for TIME milliseconds before
it will emit an event, press events shorter then that will
be ignored.
.TP 
\*(T<\fBlog\fR\*(T>:\fISTRING\fR
The log filter will output everything to stdout that
goes through it to, this is useful for debugging the
filter. A \fISTRING\fR can be
provided as parameter that will be outputed before the
event.
.SS "AXIS FILTER"
.TP 
\*(T<\fBcal\fR\*(T>, \*(T<\fBcalibration\fR\*(T>:\fIMIN\fR:\fICENTER\fR:\fIMAX\fR
See \*(T<\fB\-\-calibration\fR\*(T>.
.TP 
\*(T<\fBsen\fR\*(T>, \*(T<\fBsensitivity\fR\*(T>:\fISENSITIVITY\fR
See \*(T<\fB\-\-axis\-sensitivity\fR\*(T>.
.TP 
\*(T<\fBdead\fR\*(T>, \*(T<\fBdeadzone\fR\*(T>:\fIVALUE\fR, \*(T<\fBdeadzone\fR\*(T>:\fIMIN\fR:\fICENTER\fR:\fIMAX\fR 
Deadzone filter applies a deadzone to the current axis.
If only \fIMIN\fR is provided, the
parameter will be interpreted
as \fI-MIN:MIN:1\fR. If the
argument is 1, smooth filtering will be applied so that
the end of the deadzone is 0. Setting the argument to 0
will apply a simple cut-off filter, where all events
smaller then the threshold are ignored.
.TP 
\*(T<\fBrel\fR\*(T>, \*(T<\fBrelative\fR\*(T>:\fISPEED\fR
See \*(T<\fB\-\-relative\-axis\fR\*(T>.
.TP 
\*(T<\fBresp\fR\*(T>, \*(T<\fBresponse\fR\*(T>:\fIVALUES\fR:...
The response curve filter allows you to completely
change the way an axis reacts. The filter takes a list
of \fIVALUES\fR that are then
linearly interpolated and spread across the full range
of the axis. An example would look like this:

.nf
\*(T<xboxdrv \e
 \-\-ui\-axismap x1^resp:\-32768:\-4000:0:4000:32767\*(T>
.fi

Here the X1 axis is manipulated so that it will have a
lower sensitivity in the center and a higher one on the
outside.
.TP 
\*(T<\fBconst\fR\*(T>:\fIVALUE\fR
The const filter will ignore the input signal and send a
constant value to the output. This can be used for
example in combination with multiple configurations to
signal a game or another application which configuration
is currently active.
.TP 
\*(T<\fBlog\fR\*(T>:\fISTRING\fR
The log filter will output everything to stdout that
goes through it to, this is useful for debugging the
filter. A \fISTRING\fR can be
provided as parameter that will be outputed before the
event.
.SS MODIFIER
While button and axis filter only apply to a single axis or
button at a time, modifiers apply to the complete controller
at once and can thus be used to perform modifications that
require input from multiple axis or buttons. Most of the
modifiers explained below replicate functionality provided by
regular options, but allow more fine tuning, such as limiting
the effects to a single analog stick instead of just applyig
it to all. Note that modifiers are applied one after the
other, so order is important.
.TP 
\*(T<\fBdpad\-rotate\fR\*(T>=\fIDEGREE\fR
See \*(T<\fB\-\-dpad\-rotation\fR\*(T>.
.TP 
\*(T<\fBdpad\-restrictor\fR\*(T>=\fIRESTRICTON\fR
Restricts the dpad movement, values
for \fIRESTRICTON\fR can be:

x-axis: only allow movement in the X axis

y-axis: only allow movement in the Y axis

fourway: allow movement in X and Y axis, but filter out diagonals
.TP 
\*(T<\fB4wayrest\fR\*(T>, \*(T<\fBfour\-way\-restrictor\fR\*(T>=\fIXAXIS\fR:\fIYAXIS\fR
See \*(T<\fB\-\-four\-way\-restrictor\fR\*(T>.
.TP 
\*(T<\fBsquare\fR\*(T>, \*(T<\fBsquare\-axis\fR\*(T>=\fIXAXIS\fR:\fIYAXIS\fR
See \*(T<\fB\-\-square\-axis\fR\*(T>.
.TP 
\*(T<\fBrotate\fR\*(T>=\fIXAXIS\fR:\fIYAXIS\fR:\fIDEGREE\fR:\fIMIRROR\fR
Rotates the stick given by \fIXAXIS\fR and \fIYAXIS\fR by \fIDEGREE\fR and optionally \fIMIRRORS\fR it.
.TP 
\*(T<\fBstat\fR\*(T>, \*(T<\fBstatistic\fR\*(T>
The statistic modifier doesn't actually modify anything,
instead it collects statistics on the controller, such
as how many times a button has been pressed. The results
of the collections will be displayed on shutdown of
xboxdrv.

Note that the stat modifier is part of the modifier
stack, thus to get correct results you must make sure
that it comes first in the stack when it should work on
real events and not be confused by auto-fire or similar
modifications.
.SH "RUNNING XBOXDRV"
.SS "USING A SINGLE CONTROLLER"
Plug in your Xbox360 gamepad and then unload the xpad driver via:
.PP
.nf
\*(T<$ rmmod xpad\*(T>
.fi
.PP
If you want to permanently unload it add the following line to
\*(T<\fI/etc/modprobe.d/blacklist.conf\fR\*(T>:
.PP
.nf
\*(T<blacklist xpad\*(T>
.fi
.PP
Next you have to load the uinput kernel module which allows
userspace programs to create virtual input devices and the
joydev module handles the \*(T<\fI/dev/input/jsX\fR\*(T>
devices:
.PP
.nf
\*(T<$ modprobe uinput
$ modprobe joydev\*(T>
.fi
.PP
You also have to make sure that you have access rights to
/dev/input/uinput, either add yourself to the appropriate group,
adjust the permissions or run xboxdrv as root.
.PP
Once ensured that xpad is out of the way and everything is in place
start the userspace driver with:
.PP
.nf
\*(T<$ xboxdrv\*(T>
.fi
.PP
Or in case you don't have the necessary rights (being in group root
should often be enough) start the driver as root via:
.PP
.nf
\*(T<$ sudo xboxdrv\*(T>
.fi
.PP
This will create /dev/input/js0 and allow you to access the
gamepad from any game. To exit the driver press Ctrl-c.
.PP
By default xboxdrv will echo all controller events to the
console, this makes it easy to see if things are properly
working, but will eat a lot of CPU, thus it is strongly
recomment to disabled that output with
the \*(T<\fB\-\-silent\fR\*(T> option.
.PP
The trigger buttons are handled by xboxdrv normally as axis,
giving you analog feedback, while this reproduces the Xbox360
controller the most accurately, it will confuse many and only
be useful in a few, racing games mainly. So in the majority of
cases it is recomment to change the triggers to regular buttons via:
.PP
.nf
\*(T<$ xboxdrv \-\-trigger\-as\-button\*(T>
.fi
.SS "USING MULTIPLE CONTROLLER"
If you want to use multiple wired controllers you need to start
multiple instances of the xboxdrv driver and append the \-i
argument to select the appropriate controller like this:
.PP
.nf
\*(T<$ xboxdrv \-i 1\*(T>
.fi
.PP
If you have multiple wireless controller you need to start
multiple instances of the xboxdrv driver and append
the \*(T<\fB\-\-wid\fR\*(T> option like this:
.PP
.nf
\*(T<$ xboxdrv \-\-wid 1\*(T>
.fi
.PP
You have to sync the wireless controller as usual.
.PP
To see a list of all the controllers that xboxdrv detects
being connected to your system use:
.PP
.nf
\*(T<$ xboxdrv \-\-list\-controller\*(T>
.fi
.SS "HOTPLUGGING AND XBOXDRV DAEMON"
To allow hotplugging of gamepads xboxdrv has to be run in
daemon mode. This is accomplished with
the \*(T<\fB\-\-daemon\fR\*(T> option:
.PP
.nf
\*(T<$ xboxdrv \-\-daemon\*(T>
.fi
.PP
When launched in daemon mode xboxdrv will listen to udev
events and thus be notified whenever a new USB device gets
plugged into the computer. It will then match that device
against its list of supported devices and launch a separate
thread to handle that gamepad.
.PP
Note that xboxdrv will not allow an arbitrary large number of
controllers to be used in that mode, it can only handle as
many controllers as you have allocated controller slots at
startup. New slots can be allocated
with \*(T<\fB\-\-next\-controller\fR\*(T> and by default one
slot is always allocated, thus to support three controller you
would run it with:
.PP
.nf
\*(T<$ xboxdrv \-\-daemon \-\-next\-controller \-\-next\-controller\*(T>
.fi
.PP
Each controller slot can be configured individually and you
can limit which gamepad gets assigned to which slot with
the \*(T<\fB\-\-match\fR\*(T> option.
.PP
Note that xboxdrv will create the virtual uinput devices on
startup, not when a gamepad gets plugged in, this allows one to
plug in gamepads even after a game or an application like XBMC
has already been launched and still have it all function
properly. 
.PP
In daemon mode xboxdrv can be detached from the current shell
via \*(T<\fB\-\-detach\fR\*(T>, to get a handle on it to kill
it you can write its pid via the \*(T<\fB\-\-pid\-file\fR\*(T>:
.PP
.nf
\*(T<$ sudo xboxdrv \-\-daemon \-\-detach \-\-pid\-file /var/run/xboxdrv.pid\*(T>
.fi
.SH "XBOXDRV DAEMON DBUS INTERFACE"
When Xboxdrv is run as daemon it will export some API functions
via D-Bus, thus allowing to make configuration changes at
runtime. The D-Bus interface can be accessed either by the
numerous language bindings provided or via the generic command line tool
\fBdbus-send\fR or by the more
userfriendly \fBxboxdrvctl\fR tool. Examples below are
given for the raw \fBdbus-send\fR.
.PP
Introspection is provided via the usual means:
.PP
.nf
\*(T<dbus\-send \-\-session \-\-type=method_call \-\-print\-reply \e
  \-\-dest=org.seul.Xboxdrv /org/seul/Xboxdrv org.freedesktop.DBus.Introspectable.Introspect

dbus\-send \-\-session \-\-type=method_call \-\-print\-reply \e
  \-\-dest=org.seul.Xboxdrv /org/seul/Xboxdrv/ControllerSlots/0 org.freedesktop.DBus.Introspectable.Introspect

dbus\-send \-\-session \-\-type=method_call \-\-print\-reply \e
  \-\-dest=org.seul.Xboxdrv /org/seul/Xboxdrv/Daemon org.freedesktop.DBus.Introspectable.Introspect\*(T>
.fi
.PP
Status information on available slots, configuration and active controllers can be obtained via:
.PP
.nf
\*(T<dbus\-send \e
  \-\-session \-\-type=method_call \-\-print\-reply \e
  \-\-dest=org.seul.Xboxdrv /org/seul/Xboxdrv/Daemon  org.seul.Xboxdrv.Daemon.Status\*(T>
.fi
.PP
Setting the LED on controller 0 can be done via:
.PP
.nf
\*(T<dbus\-send \-\-session \-\-type=method_call  \-\-print\-reply \e
  \-\-dest=org.seul.Xboxdrv  /org/seul/Xboxdrv/ControllerSlots/0  org.seul.Xboxdrv.Controller.SetLed int32:4\*(T>
.fi
.PP
Setting the rumble motors on controller 0 can be done via:
.PP
.nf
\*(T<dbus\-send \-\-session \-\-type=method_call  \-\-print\-reply \e
  \-\-dest=org.seul.Xboxdrv  /org/seul/Xboxdrv/ControllerSlots/0  org.seul.Xboxdrv.Controller.SetRumble int32:255 int32:255\*(T>
.fi
.PP
Setting a specific controller slot configuration, just
as \*(T<\fB\-\-toggle BTN\fR\*(T> allows, can be done with:
.PP
.nf
\*(T<dbus\-send \-\-session \-\-type=method_call  \-\-print\-reply \e
  \-\-dest=org.seul.Xboxdrv  /org/seul/Xboxdrv/ControllerSlots/0  org.seul.Xboxdrv.Controller.SetConfig int32:2\*(T>
.fi
.SH TESTING
Knowing how to test a xboxdrv configuration is absolutely crucial in
understanding what is wrong in a given setup. Testing the
configuration in a game is most often not helpful, since you won't see
the true cause beyond endless layers of abstraction between you and
the actual events. Luckily there are a few tools you can use to test,
all of these are command line based and it is recomment that you get
familiar with them when you want to do any more complex configuration.
.SS EVTEST
evtest lets you read raw input events from \*(T<\fI/dev/input/eventX\fR\*(T>. The
event devices are the very core of all event handling, things like the
joystick devices are derived from the event device, so if you want to
fix some issue on the joystick device, you have to fix the event
device.
.PP
evtest is available in the tools/ directory or as part of your
distribution in the package \*(T<\fIevtest\fR\*(T>. your
distribution.
.SS JSTEST
jstest lets you read the output out of a joystick event device (/dev/input/js0).
.PP
jstest is available in the tools/ directory or as part of your
distribution \*(T<\fIjoystick\fR\*(T>.
.SS SDL-JSTEST
sdl-jstest lets you see events as games using SDL see them. This is
very important when you want to set and test the SDL_LINUX_JOYSTICK
environment variables.
.PP
It is currently available via:
.PP
.nf
\*(T<$ svn co svn://svn.berlios.de/windstille/trunk/sdl\-jstest\*(T>
.fi
.PP
Or from the same Ubuntu PPA that also contains xboxdrv in the package \*(T<\fIsdl\-jstest\fR\*(T>.
.SS XEV
xev lets you see the events that Xorg sees. Note however that you
might not see all events, since some will be grapped by your Window
manager before they reach xev, this is normal.
.PP
xev is part of every Linux distribution, on Ubuntu its available via:
.PP
.nf
\*(T<$ apt\-get install x11\-utils\*(T>
.fi
.SS "JSCALC AND JSCALIBRATOR"
Both of these tools lets you calibrate your gamepad, however
with pretty much all current gamepads this is no longer
needed and actually harmful as it might overwrite a perfectly
good working configuration with a broken one (unplugging the
gamepad or a reboot will fix that). So avoid them unless you
clearly understand the issues of using them.
.PP
If your gamepad produces incorrect data and you do want to
calibrate it you might want to check out the
option \*(T<\fB\-\-calibration\fR\*(T>, which lets you tweak
the way xboxdrv interprets your gamepad data.
.SS MOUSE
No tools for testing the output on /dev/input/mouseX are known.
.SS NOTE
If the tools provide no output at all, this might not be due to a
wrong configuration, but due to Xorg grabbing your event device and
locking it, see Xorg section for possible fixes.
.SH EXAMPLES
The configurations below are just a few random examples, further
examples can be found in the \*(T<\fIexamples/\fR\*(T>
directory of the xboxdrv source tree or
in \*(T<\fI/usr/share/doc/xboxdrv/examples/\fR\*(T>.
.SS "TURNING TRIGGERS INTO BUTTONS"
By default xboxdrv will handle the trigger as analog axis, not
buttons, while this is beneficial for racing games, it will
confuse many other games, thus xboxdrv provides an easy way to
change the handling into buttons via
the \*(T<\fB\-\-trigger\-as\-button\fR\*(T> option:
.PP
.nf
\*(T<$ xboxdrv \-\-trigger\-as\-button\*(T>
.fi
.SS "CONFIGURE A DEADZONE"
Many gamepads don't center exactly at zero, but at random
values around it. This 'noise' can confuse some games and is
thus be best filtered out, this can be accomplished with:
.PP
.nf
\*(T<$ xboxdrv \-\-deadzone 25%\*(T>
.fi
.PP
The percentance is the amount of noise that will get filtered
out, you can also give raw device values if you leave out the
% sign. If you want to have a deadzone only on a specific axis
you have to use axis filter:
.PP
.nf
\*(T<$ xboxdrv \-\-buttonmap X1^deadzone:15000\*(T>
.fi
.SS "KEYBOARD EMULATION"
The following configuration will cause xboxdrv to emulate a
keyboard, which can be useful for games that are played with
keyboard, like Flash games or games that don't support a
joystick. Since different games use different keyboard keys
you might have to adjust the keybindings to fit the game:
.PP
.nf
\*(T<$ xboxdrv \e
  \-\-ui\-clear \e
  \-\-ui\-buttonmap a=XK_a,b=XK_b,x=XK_x,y=XK_y \e
  \-\-ui\-buttonmap dl=XK_Left,dr=XK_Right,du=XK_Up,dd=XK_Down\*(T>
.fi
.SS "FIGHTING GAMES:"
In this configuration the left and right trigger get turned
into digital buttons. All axis except the dpad are ignored. RB
and RT are mapped to act as if buttons 1,2 and 3 are pressed
simultaniously which is useful for some special attacks.
Instead of using the native button names, the 1,2,3,...
aliases are used, which makes things a little easier to read:
.PP
.nf
\*(T<$ xboxdrv \e
  \-\-dpad\-only \e
  \-\-trigger\-as\-button \e
  \-\-buttonmap lb=1,x=2,y=3,lt=4,a=5,b=6 \e
  \-\-buttonmap rb=1,rb=2,rb=3 \e
  \-\-buttonmap rt=4,rt=5,rt=6\*(T>
.fi
.SS "CH FLIGHTSTICK EMULATION IN DOSBOX:"
In \*(T<\fIdosbox.conf\fR\*(T> set:
.PP
.nf
\*(T<[joystick]
joysticktype = ch\*(T>
.fi
.PP
Start xboxdrv with:
.PP
.nf
\*(T<$ xboxdrv \-s \e
  \-\-trigger\-as\-zaxis \-\-square\-axis \e
  \-\-relative\-axis y2=64000 \-\-axismap \-y2=x2,x2=y2\*(T>
.fi
.PP
Your right analog stick will act as trottle control, the
trigger as rudder. Using \*(T<\fB\-\-modifier\fR\*(T> to
install a four-way restrictor might also be worth a
consideration to not accidentally touch the throttle when the
rudder is moved.
.SS "USING MOUSE EMULATION AND JOYSTICK AT THE SAME TIME"
To use mouse emulation and joystick at the same time you have
to register two configuration with xboxdrv, this works via:
.PP
.nf
\*(T<$ xboxdrv \-\-next\-config \-\-mouse\*(T>
.fi
.PP
The \*(T<\fB\-\-next\-config\fR\*(T> option will open up a second
configuration and all configuration options on the right side
of it will go there, while everything on the left side of it
will go into the first configuration. Toggling between the
configurations works with the guide button, you can have as
many configuratios as you want.
.SS "MAPPING EVERY BUTTON MULTIPLE"
Some games might require more buttons then your gamepad has,
in those situation it can be useful to map a button twice by
using shifted buttons:
.PP
.nf
\*(T<$ xboxdrv \e
  \-\-ui\-clear \e
  \-\-ui\-axismap X1=ABS_X,Y1=ABS_Y \e
  \-\-ui\-buttonmap a=JS_0,b=JS_1,x=JS_2,y=JS_3 \e
  \-\-ui\-buttonmap lb+a=JS_4,lb+b=JS_5,lb+x=JS_6,lb+y=JS_7 \e
  \-\-ui\-buttonmap rb+a=JS_8,rb+b=JS_9,rb+x=JS_10,rb+y=JS_11
\*(T>.fi
.PP
Here all face buttons are get mapped three times, once when
pressed normally, once when pressed while LB is held down and
once when RB is held down, thus given you for the six buttons
12 virtual ones.
.SS SAUERBRATEN
First analogstick gets mapped te cursor keys, second
analogstick gets mapped to mouse. Note: This is just an
incomplete example, not a perfectly playable configuration,
you have to do tweaking yourself.
.PP
.nf
\*(T<$ xboxdrv \e
  \-\-ui\-axismap x2=REL_X:10,y2=REL_Y:\-10,x1=KEY_LEFT:KEY_RIGHT,y1=KEY_UP:KEY_DOWN \e
  \-\-ui\-buttonmap a=BTN_RIGHT,b=BTN_LEFT,x=BTN_EXTRA \e
  \-\-ui\-buttonmap rb=KEY_5,lb=KEY_6,lt=BTN_LEFT,rt=BTN_RIGHT \e
  \-\-ui\-buttonmap y=KEY_ENTER,dl=KEY_4,dr=KEY_2,du=KEY_1,dd=KEY_3,back=KEY_TAB,start=KEY_ESC \e
  \-s \-\-deadzone 6000  \-\-dpad\-as\-button \-\-trigger\-as\-button\*(T>
.fi
.SS WARSOW
Note: This is just an incomplete example, not a perfectly playable
configuration, you have to do tweaking yourself.
.PP
.nf
\*(T<$ xboxdrv \e
  \-\-ui\-axismap x2=REL_X:10,y2=REL_Y:\-10,x1=KEY_A:KEY_D,y1=KEY_W:KEY_S \e
  \-\-ui\-buttonmap a=KEY_LEFTSHIFT,b=BTN_C,x=BTN_EXTRA,y=KEY_C \e
  \-\-ui\-buttonmap lb=BTN_RIGHT,rb=KEY_SPACE \e
  \-\-ui\-buttonmap lt=KEY_Z,rt=BTN_LEFT \e
  \-\-ui\-buttonmap dl=KEY_4,dr=KEY_2,du=REL_WHEEL:\-1:150,dd=REL_WHEEL:1:150 \e
  \-\-ui\-buttonmap back=KEY_TAB,start=KEY_ESC \e
  \-s \-\-deadzone 6000 \-\-dpad\-as\-button \-\-trigger\-as\-button\*(T>
.fi
.SH "WRITING START-UP SCRIPTS FOR GAMES"
When you want full game specific configurability and automatic
launching of xboxdrv, it is easiest to write little startup
scripts for your games that will launch xboxdrv, launch your
game and then when the game is finished tear down xboxdrv:
.PP
.nf
\*(T<#!/bin/sh

exec xboxdrv \e
  \-\-trigger\-as\-button \-s \e
  \-\- \e
  your_favorite_game

# EOF #\*(T>
.fi
.PP
Here \*(T<\fIyour_favorite_game\fR\*(T> is the executable
of your game and is passed to xboxdrv as last argument. This
will cause xboxdrv to start the game and keep running as long as
the game is running, when the game is done, xboxdrv will quit
automatically.
.PP
If you want to pass parameters to the game you have to add
a \*(T<\fB\-\-\fR\*(T> separator, as otherwise your options to
the game would be eaten up by xboxdrv.
.SH "SDL NOTES"
To let SDL know which axis act as a hat and which act as normal axis
you have to set an environment variable:
.PP
.nf
\*(T<
$ SDL_LINUX_JOYSTICK="'Xbox Gamepad (userspace driver)' 6 1 0"
$ export SDL_LINUX_JOYSTICK\*(T>
.fi
.PP
You might also need in addition use this (depends on the way SDL was compiled):
.PP
.nf
\*(T<
$ SDL_JOYSTICK_DEVICE="/dev/input/js0"
$ export SDL_JOYSTICK_DEVICE\*(T>
.fi
.PP
This will let the DPad act as Hat in SDL based application. For
many games the driver will work without this, but especially in
Dosbox this variable is very important.
.PP
If you use options in xboxdrv that change the number of axis you
have to adjust the variable accordingly, see:
.TP 0.2i
\(bu
\(laftp://ptah.lnf.kth.se/pub/misc/sdl-env-vars\(ra
.TP 
SDL_LINUX_JOYSTICK
Special joystick configuration string for linux. The format is
\*(T<\fB"name numaxes numhats numballs"\fR\*(T>
where name is the name string of the joystick (possibly in single
quotes), and the rest are the number of axes, hats and balls
respectively.
.TP 
SDL_JOYSTICK_DEVICE
Joystick device to use in the linux joystick driver, in addition to the usual: \*(T<\fI/dev/js*\fR\*(T>, \*(T<\fI/dev/input/event*\fR\*(T>, \*(T<\fI/dev/input/js*\fR\*(T>
.SH TROUBLESHOOTING
.SS "\(dqNO XBOX OR XBOX360 CONTROLLER FOUND\(dq"
This means that either your controller isn't plugged in or is
not recognized by the driver. To fix this you need to know the
idVendor and the idProduct numbers, which you can find out
via:
.PP
.nf
\*(T<$ lsusb \-v\*(T>
.fi
.PP
Once done you can try to add them to this array in \*(T<\fIsrc/xpad_device.cpp\fR\*(T>:
.PP
.nf
\*(T<XPadDevice xpad_devices[] = { ... }\*(T>
.fi
.PP
If you have success with that, send a patch
to <\*(T<grumbel@gmail.com\*(T>>, if not, contact me too, I
might be able to provide additional help.
.PP
As an alternative you can also use the \-\-device and \-\-type option to
enforce a USB device as well as a controller type an bypass any auto
detection.
.SS "\(dqUNKNOWN DATA: BYTES: 3 DATA: ...\(dq"
This means that your controller is sending data that isn't understood
by the driver. If your controller still works, you can just ignore it,
the Xbox360 controller seems to send out useless data every now and
then. If your controller does not work and you get plenty of those
lines when you move the sticks or press buttons it means that your
controller talks an un-understood protocol and some reverse
enginiering is required. Contact <\*(T<grumbel@gmail.com\*(T>> and include the output
of:
.PP
.nf
\*(T<$ lsusb \-v\*(T>
.fi
.PP
Along with all the "Unknown data" lines you get. 
.SS "\(dqERROR: NO STUITABLE UINPUT DEVICE FOUND\(dq"
Make sure that uinput and joydev kernel modules are loaded. Make sure
that you have a /dev/input/uinput, /dev/uinput or /dev/misc/uinput and
permissions to access it.
.PP
Before reporting this as a bug make sure you have tested if the driver
itself works with:
.PP
.nf
\*(T<$ xboxdrv \-\-no\-uinput \-v\*(T>
.fi
.SS "THE WIRELESS CONTROLLER DOESN'T WORK"
You have to sync the controller befor it can be used, restart of the
driver isn't needed and the driver should let you now when it receives
a connection after you sync the controller.
.SS "KEYBOARD EMULATION"
When you try to let xboxdrv send a keyboard events
via \*(T<\fB\-\-ui\-buttonmap\fR\*(T>
or \*(T<\fB\-\-ui\-axismap\fR\*(T> Xorg must register the device
as keyboard device to work properly. This seems to work
automatically when you bind more then two keyboard keys, if you
bind less you need to create the
file \*(T<\fI/etc/hal/fdi/preprobe/xboxdrv.fdi\fR\*(T>
containing:
.PP
.nf
\*(T<
<?xml version="1.0" encoding="UTF\-8"?>
<deviceinfo version="0.2">
  <device>
    <match key="input.product" string="Xbox Gamepad (userspace driver) \- Keyboard Emulation">
      <addset key="info.capabilities" type="strlist">input.keys</addset>
    </match>
  </device>
</deviceinfo>\*(T>
.fi
.PP
This will tell HAL and later Xorg that xboxdrv acts as keyboard.
.SS "WACOM ISSUES"
In some older kernels a Wacom graphic tablet creates a
joystick device, so xboxdrv or any other real joysticks ends
up as \*(T<\fI/dev/input/js1\fR\*(T> instead
of \*(T<\fI/dev/input/js0\fR\*(T>. In many games this
causes the joystick to not function any more.
.PP
A temporary workaround for this is to simply delete the joystick
device js0 and replace it with a symbolic link js1 via:
.PP
.nf
\*(T<$ sudo ln \-sf /dev/input/js1 /dev/input/js0\*(T>
.fi
.PP
This workaround will only last till the next reboot, since the device
names are dynamically created, but for the time being there doesn't
seem to any other way to easily work around this issue. 
.PP
In newer kernels this issue is fixed.
.SS "UINPUT ISSUES"
On Ubuntu 9.04 the permissions of the uinput device have
changed to 0640, meaning only root has access to the device.
To change this back so that users in the group root have
access the device and in turn can run xboxdrv without sudo you
have to create a file
called \*(T<\fI/etc/udev/rules.d/55\-permissions\-uinput.rules\fR\*(T>
with the content:
.PP
.nf
\*(T<KERNEL=="uinput", MODE="0660", GROUP="root"\*(T>
.fi
.SS "WINE ISSUES"
When using the Xbox360 gamepad in Wine it is not specially
handled as Xbox360 gamepad, but as generic DirectInput gamepad.
This means games will not display the proper button labels, but
just numbers (i.e. 'Btn1' instead of 'A' for example). Aside
from that it should work fine.
.PP
XInput support (the Microsoft DirectInput replacment, not the
Xorg xinput) is as of January 2011 not implemented in Wine, so
games that require XInput and don't have an DirectInput fallback
will not work with a Xbox360 controller, unofficial patches
however do exist.
.SH "XORG ISSUES"
If you start xboxdrv and instead of having a fully working
joystick, you end up controlling the mouse that might be due to
recent changes in Xorg and its device hotplug handling. There
are four workarounds, the one that involves
editing \*(T<\fI/etc/hal/fdi/policy/preferences.fdi\fR\*(T>
is the recommont one.
.SS "TEMPORARY WORKAROUND USING HAL-DEVICE"
Get the device id from hal:
.PP
.nf
\*(T<$ hal\-find\-by\-property \-\-key 'info.product' \-\-string 'Xbox Gamepad (userspace driver)'\*(T>
.fi
.PP
Then remove the device from hal with:
.PP
.nf
\*(T<$ hal\-device \-r $DEVICEID\*(T>
.fi
.SS "TEMPORARY WORKAROUND USING XINPUT"
Second workaround works with xinput:
.PP
.nf
\*(T<$ xinput list
$ xinput set\-int\-prop $DEVICEID 'Device Enabled' 32 0\*(T>
.fi
.SS "PERMANENT WORKAROUND USING .FDI FILES"
The former two workarounds are just temporary and have to be redone
after each start of xboxdrv, the last workaround is a permanent one:
.PP
You have to edit:
.PP
\*(T<\fI/etc/hal/fdi/policy/preferences.fdi\fR\*(T>
.PP
And insert the following lines:
.PP
.nf
\*(T<
<match key="input.product" string="Xbox Gamepad (userspace driver)">
  <remove key="input.x11_driver" />
</match>\*(T>
.fi
.SS "PERMANENT WORKAROUND BY DISABLING DEVICE AUTO DETECTION"
A fourth workaround involved disabling the autodetection of Xorg
completely, you can do that by adding the following lines to
\*(T<\fI/etc/X11/xorg.conf\fR\*(T>:
.PP
.nf
\*(T<Section "ServerFlags"
  Option "AutoAddDevices" "False"
EndSection\*(T>
.fi
.PP
Note that without auto detection you will have to manually configure
all your mice and keyboards or your Xorg Server won't start up
properly. So unless you are already familiar with editing Xorg you
better avoid this workaround. Workaround 3) has basically the same
effect, except that auto detection only gets disabled for the single
device it is causing problems.
.SH "FORCE FEEDBACK PROGRAMMING"
For documentation on the FF interface see:
.TP 0.2i
\(bu
\(lahttp://github.com/github/linux-2.6/blob/f3b8436ad9a8ad36b3c9fa1fe030c7f38e5d3d0b/Documentation/input/ff.txt\(ra
.TP 0.2i
\(bu
\*(T<\fI/usr/include/linux/input.h\fR\*(T>
.PP
Additional, non Linux related, force feedback related
information can be found at:
.TP 0.2i
\(bu
.URL http://www.immersion.com/developer/downloads/ImmFundamentals/HTML/ ""
.TP 0.2i
\(bu
.URL http://msdn.microsoft.com/en-us/library/bb219655(VS.85).aspx ""
.PP
\fBfftest\fR is an application you can use to test the force feedback
interface.
.PP
Force feedback is disabed by default since it causes trouble in
certain application. "Tomb Raider: Legend" for example when run
in Wine crashes at startup when rumble is enabled, while it
works perfectly normal when rumble is disabled.
.SH BUGS
.SS "X11 KEYSYM ISSUES"
X11 keysyms might not work correctly in \*(T<\fB\-\-ui\-buttonmap a=XK_Foobar\fR\*(T>
when Foobar is mapped to multiple keycodes in the keymap. 
.PP
Workaround: Use \fBKEY_\fR instead or cleanup your keymap
.PP
Newer versions of Xorg will also do perform some auto
configuration that might lead to your keymap being switched
whenever a new keyboard is detected, in cases of custom
Xmodmaps this might confuse xboxdrv and make the XK_ style
names unusable. No workaround for that is known right now.
.SS "NON-INTERRUPTABLE PROCESSES DUE TO FORCE FEEDBACK"
Force feedback support is brittle, if you Ctrl-c the driver in the
wrong moment you will end up with a dead uninterruptable process and
basically have to reboot. This looks like it might be a kernel issue
and not a xboxdrv one.
.PP
Workaround: Kill the app that uses xboxdrv before xboxdrv itself.
.SS "QUESTIONS, BUG REPORTS AND FEATURE REQUESTS"
Bug reports and feature request can be report to the xboxdrv issue tracker at:
.PP
.URL https://github.com/Grumbel/xboxdrv/issues/new ""
.PP
General questions and requests for configuration help should
be directed to the xboxdrv mailing list at:
.PP
.URL http://groups.google.com/group/xboxdrv ""
.SH COPYRIGHT
Copyright \(co 2010-2011 Ingo Ruhnke <\*(T<grumbel@gmail.com\*(T>>
License GPLv3+: GNU GPL version 3 or later
.URL http://gnu.org/licenses/gpl.html ""
\&. This is free software: you
are free to change and redistribute it. There is NO WARRANTY,
to the extent permitted by law.
.SH "SEE ALSO"
\fBxboxdrvctl\fR(1), 
\fBevtest\fR(1), 
\fBjstest\fR(1), 
\fBjstest-gtk\fR(1), 
\fBxev\fR(1),
\fBfftest\fR(1),
\fBlsusb\fR(1)