Joystick File Structure

We use the terms 'joystick file," "device file," and "stick file" interchangeably to refer to the files that control the operation of joysticks, throttles, pedals and similar input devices.

Which File Does Targetware Use?

The device reports a name to your operating system. Targetware checks your config.txt file's [Joysticks] section to see if a joystick file is defined for that name and uses it if found. If a file is not defined in config.txt, Targetware looks at the [Names] section of files in /user/joysticks/ for a match. The name of the file does not matter; the names listed in the [Names] section is the key. If there is no match in that directory, Targetware searches the /data/joysticks/ folder and copies a matching file to /user/joysticks/. This will usually happen the first time you start Targetware.

If Targetware does not find a file for the reporting device, it automatically generates a default file. This file may be less than ideal for your device and require adjusting. See Joystick Setup for additional information.

Joystick File Configuration

The device files are divided into several sections:

  • [Names]
  • [Force Feedback]
  • [Elements]
  • [Hat <number>]
  • [Axis <letter>]
  • [Set <number>]

[Names]

This section must contain the exact name reported for the stick. A stick file can have multiple names in it. This would simply mean that all the sticks named would use the same file.

Example names:

  • Saitek Cyborg 3D Stick USB
  • Top Gun Afterburner
  • Logitech Wingman Extreme Digital 3D USB
  • CH 3-Axis 10-Button+POV USB Joystick
  • Sidewinder Force Feedback 2

To find the exact name of a stick, make sure there is no stick file with your device name, or what you expect it to be, in /data/joysticks/ or /user/joysticks/ (you should move these files somewhere safe so that you can restore them if needed). Then start Targetware and go to Settings -> Joysticks. The reported name will appear in the upper right section of the joystick screen displayed there. Also, a file with the reported name will be generated in /user/joysticks/ (though spaces will be replaced with underscores).

[Force Feedback]

This section contains the spring and buffet scaling settings for force feedback joysticks. It may be edited within the joystick settings interface.

[Elements]

Elements are the actual input mechanisms for a device, i.e., the axes, buttons, and hat switches. The Elements defined here can have Functions assigned to them. Any element to be used in Targetware must be listed here, otherwise, the game will not respond.

Example elements:

axis x
axis y
axis rz
axis u
button 1
button 2
button 3
button 4
hat 1

[Hat <number>]

Hats may be from one of two sources: "hat" or "buttons". Some hat switches are 'POV' hats, i.e., 'true' hats. Others are actually buttons that emulate a POV hat. While others that appear to be hat, particularly 4-way hats, are really just buttons (this last one should not be defined as a hat, but rather as buttons in most instances). The source line defines which type of hat

Each hat must have its own section.

A POV hat would simply be defined as:

[Hat 1]
source = hat

A hat that is actually button emulation should not have those button numbers defined in the above Elements section. For example, if the device in the example elements above had a second hat that reported as buttons 5 through 8, it would be defined as the following (assuming button 5 is up, and the rest are numbered clockwise):

[Hat 2]
source = buttons
up = 5
up-right = 5, 6
right = 6
down-right = 6, 7
down = 7
down-left = 7, 8
left = 8
up-left = 5, 8

Note: This hat uses button combinations to emulate 8 directions. Some joysticks define have a different button for each direction, such as the Logitech Wingman Strike Force 3D thats Hat 2 is buttons 10 through 17.

[Axis <letter>]

Each axis defined in the Elements section requires a section detailing its settings. These parameters are:

  • center
  • min
  • max
  • saturate
  • deadband
  • damper
  • scale
  • slider
  • reverse

Center, Min, and Max are the determined by calibrating the stick within the Joystick Settings interface in Targetware. Saturate, Deadband, Damper, Scale, Slider and Reverse can also be set within the Joystick interface. See Joystick Setup for additional information.

[Set <number>]

The Set, or 'Stick Set', sections is where controls are actually assigned. This is where the 'mapping' is recorded. As with most Joystick settings, these can be changed within the Joystick Settings interface as described in Joystick Setup. Each set, or 'stick set' can have different function assignments.

Elements are the methods of input. Functions are the things you want the game to do. This section relates the two in the basic formula:

<element> = <function>

Each element may have multiple functions assigned to it.

<element> = <function>, <function>, ..., <function>

The most common example of this is:

axis rz = Yaw, Steer, Differential Brake

However, you can use this mechanism to do other interesting things. For example, you might want a single button press to retract your flaps and gear when taking off:

button 5 = retract flaps, gear

Or perhaps for dive bombing:

button 6 = extend flaps, airbrake, toggle bays (before the bomb release)
button 7 = retract flaps, airbrake, toggle bays (after the bomb release)

Stick Set 1 is always used by default. You must map the stick set buttons to use the other stick sets as described in Joystick Setup.

Hat assignments must list the hat number and hat direction as the element. For example:

hat 1 up-right = View Forward-Right