Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
joystick(4x)							  joystick(4x)

NAME
       joystick	- Joystick input driver

SYNOPSIS
       Snipped for xorg.conf.d(5):

       Section "InputClass"
	 Identifier "joystick-all"
	 Driver	"joystick"
	 Option	"MatchIsJoystick"   "on"
	 Option	"MatchDevicePath "/dev/input/event*"
	 ...
       EndSection

DESCRIPTION
       joystick	 is  an	 Xorg  input driver for	controlling the	pointer	with a
       joystick	device.

       Use this	driver,	if you want to
	  - generate cursor movement, perform button or	key events to  control
	  desktop and applications

	  -  generate cursor key events	for playing legacy games, that have no
	  native joystick support

       Do not use, if you want to
	  - play games,	that have native joystick support

	  - use	XI2 applications. The evdev(4) driver will suffice  for	 those
	  in most cases.

       You may mix above scenarios by setting the device floating.  The	driver
       reports relative	cursor movement, button	and key	events,	as well	as raw
       axis values through valuators.

SUPPORTED HARDWARE
       The  joystick  input  module can	be used	on top of the following	kernel
       devices:

       - Linux's evdev device
       - Linux's joystick device
       - BSD's usbhid device

       Every joystick supported	by the kernel should be	supported by the  joy-
       stick  input  driver.  The joystick is assumed to be calibrated and re-
       porting axis values between -32768 and 32768.   See  the	 Linux	kernel
       documentation for a complete list of supported devices.

       There is	no support for force feedback at the moment.

CONFIGURATION DETAILS
       Please  refer  to xorg.conf(5) for general configuration	details.  This
       section only covers configuration details specific to this driver.

       The following Driver Options are	supported:

       Option "Device" "string"

       Option "Path" "string"
	      Specifies	the device through which the joystick can be accessed.
	      This option is mandatory and there is no default setting.

	      In  Linux,  joysticks  are  usually  accessible through /dev/in-
	      put/jsX or /dev/input/eventX.

	      In *BSD, joysticks are usually recognized	as /dev/uhidX.

       Option "AutoRepeat" "delay rate"
	      Sets the auto repeat behaviour for key  events.	delay  is  the
	      time in milliseconds before a key	starts repeating.  rate	is the
	      number of	times a	key repeats per	second.	 Default: Xorg default

       Option "DebugLevel" "integer"
	      Controls the verbosity of	the driver for debugging purposes. The
	      higher the DebugLevel, the more output is	produced.  Default: 0

       Option "MapButton<number>" "string"
	      Sets  the	 mapping  of  a	joystick button	to the desired action.
	      Button counting starts with 1, Possible options are:

	      none   Don't do anything

	      "button=_number_"
		     Generate  a  pointer  button  event  with	button	number
		     (starting with 1).

	      "axis=[_factor_]_axis_"
		     Where _axis_ is one of: x,	y, zx, zy

		     and  _factor_  is an optional amplifier of	the axis, like
		     -,	+, -5, 0.4, 1.3, ...  Negative values invert  the  di-
		     rection. Default: 1.0

	      "amplify=_factor_"
		     Amplifies	the  movement  of all axes by the given	factor
		     when this button is held down. Different factors  can  be
		     combined.

	      "key=_scancode_[,_scancode_[,_scancode_[,_scancode_]]]
		     When  button  is pressed, a series	of keydown events with
		     the specified scancodes is	generated. When	the button  is
		     released, matching	keyup events in	the opposite order are
		     generated.	You can	specify	up to 4	scancodes per button.

		     See special section about key events below.

	      "disable-mouse"

	      "disable-keys"

	      "disable-all"
		     Disables either  the  generation  of  mouse  events,  key
		     events  or	 the generation	of all X events	by the driver.
		     Press button again	to allow the driver to generate	events
		     again.

		     You may also set the device floating from client space to
		     prevent it	from generating	core events.

       Option "MapAxis<number>"	"string"
	      Sets the mapping of the axis to the desired action. Axis	count-
	      ing starts with 1, the parameter may contain:

	      "mode=_string_"
		     Where _string_ can	be one of:

		     none, relative, accelerated, absolute

	      "valuator"
		     Send  extra  valuator events for this axis. The valuators
		     will be numbered ascending, starting with 2  (valuator  0
		     and 1 are reserved	for pointer movement). Please consider
		     using the evdev(4)	input driver if	you  are  only	inter-
		     ested in XI2 features.

		     The  range	 of  the  valuators is always -32767 to	32768.
		     Neither mode nor axis needs to be set to  generate	 extra
		     valuator  events.	The axis will be labelled according to
		     its physical axis number, beginning with 1	, e.g.	 "Axis
		     1"	for the	first axis (being the 3rd valuator).  Default:
		     not set.

	      "axis=[_factor_]_axis_"
		     Where _axis_ is one of: x,	 y,  zx,  zy,  key  (see  key-
		     low/keyhigh)

		     and  _factor_  is an optional amplifier of	the axis, like
		     -,	+, -5, 0.4, 1.3, ...  Negative values will invert  the
		     movement. Default:	1.0

	      "keylow=_scancode_[,_scancode_[,_scancode_[,_scancode_]]]

	      "keyhigh=_scancode_[,_scancode_[,_scancode_[,_scancode_]]]
		     When  the	axis is	moved out of the deadzone, a series of
		     keydown events according to the direction of the movement
		     is	 generated.  When the axis is released,	matching keyup
		     events in opposite	order will be generated. You can spec-
		     ify up to 4 scancodes for each direction.

		     keylow  defines the keys to be generated when the axis is
		     moved in negative direction (left or up), keyhigh defines
		     the  keys to be generated when the	axis is	moved in posi-
		     tive direction (right or down).

		     If	mode is	set to relative: The driver will  emulate  au-
		     torepeat  according  to  the current value	of the axis. A
		     keydown and subsequent keyup event	will be	 generated  in
		     short time	intervals. To modify that interval and the au-
		     torepeat speed, supply the	 "axis=[_factor_]KEY"  parame-
		     ter.

		     If	 mode  is set to accelerated: Keydown and keyup	events
		     will be generated repeatedly. The time between a  keydown
		     and  a  keyup  event corresponds to the deflection	of the
		     axis.  If the axis	is deflected by	30%, the key  will  be
		     considered	 to  be	 down 300ms out	of 1 second. The exact
		     intervals may vary	and can	be adjusted with  the  amplify
		     parameter.	 If  the axis is deflected by 100%, there will
		     only be one keydown event,	so the key is considered  down
		     all the time.  The	keys will be autorepeated according to
		     the Xorg keyboard settings.

		     See special section about key events below.

	      "deadzone=_number_"
		     Sets the unresponsive range  of  the  axis	 to  _number_.
		     This can be between 0 and 30000.  Default:	5000

       Option "StartKeysEnabled" "boolean"
	      Set  to False to disable key event generation after startup. You
	      can toggle key event generation  with  the  disable-keys	button
	      mapping. Default:	enabled

       Option "StartMouseEnabled" "boolean"
	      Set  to  False  to disable mouse event generation	after startup.
	      You can toggle mouse event  generation  with  the	 disable-mouse
	      button mapping. Default: enabled

DEFAULT	CONFIGURATION
       The default configuration is as follows:

	 Option	"DebugLevel"	    "0"
	 Option	"StartKeysEnabled"  "True"
	 Option	"StartMouseEnabled" "True"
	 Option	"MapButton1"	    "button=1"
	 Option	"MapButton2"	    "button=2"
	 Option	"MapButton3"	    "button=3"
	 Option	"MapButton4"	    "none"
	 ...
	 Option	"MapAxis1"	    "mode=relative    axis=+1x	deadzone=5000"
	 Option	"MapAxis2"	    "mode=relative    axis=+1y	deadzone=5000"
	 Option	"MapAxis3"	    "mode=relative    axis=+1zx	deadzone=5000"
	 Option	"MapAxis4"	    "mode=relative    axis=+1zy	deadzone=5000"
	 Option	"MapAxis5"	    "mode=accelerated axis=+1x	deadzone=5000"
	 Option	"MapAxis6"	    "mode=accelerated axis=+1y	deadzone=5000"
	 Option	"MapAxis7"	    "mode=none"
	 ...

ACCELERATED AXIS CONFIGURATION
       Accelerated  mode should	be selected, if	the axis is a directional pad,
       which reports only three	states:	negative, center,  positive.  It  will
       result  in smoothly accelerated movement	when the axis is deflected. An
       optional	factor will affect the acceleration and	final speed.

       This example will set up	the axis  as  scrolling	 vertically  inverted,
       with half the speed:
	 Option	"MapAxis1"     "mode=accelerated axis=-0.5zy"

       This  example  maps four	buttons	to the four pointer directions,	so you
       can use the buttons like	a d-pad. The movement will be accelerated with
       half the	normal speed:
	 Option	"MapButton1"	 "axis=+0.5x"
	 Option	"MapButton2"	 "axis=-0.5x"
	 Option	"MapButton3"	 "axis=+0.5y"
	 Option	"MapButton4"	 "axis=-0.5y"

ABSOLUTE AXIS CONFIGURATION
       In  absolute axis mode, the position of the cursor will match the posi-
       tion of the configured axis, but	relative to the	previous  position  of
       the cursor. You can specify the range in	which the cursor can move. The
       default range is	the screen size.

       In this example the first axis gets a range from	left to	the  right  of
       the  screen.  The  second axis gets a total range of 200	pixels,	100 to
       the top and 100 to the bottom:
	 Option	"MapAxis1"     "mode=absolute axis=x"
	 Option	"MapAxis2"     "mode=absolute axis=200y"

GENERATING KEY EVENTS
       Providing a "key=<scancode>[,<scancode>[...]]" option will  generate  X
       Events  with specified scancodes. When the button/axis is released, the
       keys will be released in	opposite order.

       If you want a certain KeySym,  look  up	the  matching  scancode	 using
       xmodmap	-pk.   The scancodes depend on the configured keyboard layout.
       You can also use	unused keycodes	and map	 them  to  a  KeySym  of  your
       choice using xmodmap(1).

       You  can	 specify up to 4 scancodes per joystick	button/axis, which can
       be used for modificators	to get the KeySym you want.

       Examples:
	 Option	"MapButton1"	 "key=64,23"
       will generate Alt_L+Tab when the	button is pressed.

	 Option	"MapButton1"	 "key=50,40"
       will generate a Shift_L+d which will result in an uppercase d.

	 Option	"MapButton1"	 "key=65"
       will result in a	space key.

	 Option	 "MapAxis1"	 "mode=relative	   keylow=113  keyhigh=114 axis=0.5key"
	 Option	 "MapAxis2"	 "mode=relative	   keylow=111  keyhigh=116"
	 Option	 "MapAxis3"	 "mode=accelerated keylow=113  keyhigh=114"
	 Option	 "MapAxis4"	 "mode=accelerated keylow=111  keyhigh=116"
       will map	the first and third axis to the	arrow keys left	and right  and
       the second and fourth axis to the arrow keys up and down.

       The  keys  for  the first two axes will be generated in an interval ac-
       cording to the value of the axis. The autorepeat	 speed	of  the	 first
       axis  will  be half the speed of	that of	the second axis.  The keys for
       the third and fourth axis are generated once when the axis moves	out of
       the  deadzone  and when it moves	back into the deadzone.	X.Org will au-
       torepeat	those keys according to	current	keyboard settings.

XI2 Events
       If you only care	about raw valuator events instead of  using  the  joy-
       stick  to control the cursor, consider using the	evdev(4) input driver.
       If you still use	the joystick driver for	raw events, make sure to unmap
       all axes/buttons	and add	the valuator option to the axes:

	 Option	 "MapAxis1"	 "mode=none valuator"
	 Option	 "MapAxis2"	 "mode=none valuator"
	 Option	 "MapAxis3"	 "mode=none valuator"
	 Option	 "MapAxis4"	 "mode=none valuator"
	 ...
	 Option	 "MapButton1"	   "button=1"
	 Option	 "MapButton2"	   "button=2"
	 Option	 "MapButton3"	   "button=3"
	 Option	 "MapButton4"	   "button=4"
	 Option	 "MapButton5"	   "button=5"
	 ...

       Remember, that valuators	0 and 1	are reserved for pointer movement, ad-
       ditional	axes will start	with valuator 2.

       You might also want to set the device "floating"	to stop	 it  from  re-
       porting core events:
	 Option	 "Floating"	 "true"

NOTES
       It  is  not  recommended	to enable the joystick input driver by default
       unless explicitely requested by the user.

       Configuration through InputClass	sections is recommended	in  X  servers
       1.8  and	 later.	 See  xorg.conf.d(5)  for  more	 details.  An  example
       xorg.conf.d(5) snipped is provided in ${sourcecode}/config/50-joystick-
       all.conf

       Configuration  through  hal  fdi	files is recommended in	X servers 1.5,
       1.6 and 1.7. An example hal policy file is still	provided in  ${source-
       code}/config/50-x11-input-joystick.fdi	   to	  be	 placed	    in
       /etc/hal/fdi/policy.

SEE ALSO
       Xorg(1),	xorg.conf(5), xorg.conf.d(5), Xserver(1), X(7),	xmodmap(1)

AUTHORS
       Sascha Hlusiak (2007-2012),
       Frederic	Lepied (1995-1999)

X Version 11		   xf86-input-joystick 1.6.3		  joystick(4x)

NAME | SYNOPSIS | DESCRIPTION | SUPPORTED HARDWARE | CONFIGURATION DETAILS | DEFAULT CONFIGURATION | ACCELERATED AXIS CONFIGURATION | ABSOLUTE AXIS CONFIGURATION | GENERATING KEY EVENTS | XI2 Events | NOTES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=joystick&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help