Joytran User Manual

Table of Contents

Installation

Install Port

# cd /usr/ports/emulators/joytran
# make deinstall reinstall

Install from source

# cmake
# make clean
# make install

Program Usage

How it Works

While it runs, whenever you use any joysticks configured in the specified profile, the respective keyboard and mouse events will be generated. This means that any application in the same X11 session may be controlled with the joystick, provided an appropriate profile is used for the given application. The only exceptions are applications which provide no keyboard or mouse support, or which subvert the XTest extension.

A new profile may be written for any application in which the joystick is desired by the user, or the application may be configured to match the keys of a (default or otherwise) Joytran profile. If a different profile is desired, then Joytran may be closed, and restarted with a new profile, without restarting the X11 session. Joytran does not automatically switch between profiles, however.

Invocation

> joytran -p name-of-profile

Or, for greater simplicity:

> joytran

Profiles

Joytran Profiles Path

These profiles are located in the following path:

System-wide profiles:
${LOCALBASE}/share/joytran/profiles/

Local profiles:
~/.joytran/profiles/

Note that the value of ${LOCALBASE} depends on your operating system. On most BSDs, the value will be /usr/local, whereas on Linux, it will be /usr. The system-wide profiles are only available in versions 0.8.7-RELEASE or greater.

In this directory, Joytran looks for a profile called "default". If this "default" profile does not exist, then Joytran cannot run.

I don't know what the buttons/axes/hats in the given profiles should be for my controller!

This diagram is the button IDs that all provided profiles are supposed to correspond to:

Keep in mind that you will likely need to make some adjustments to the profiles, as appropriate for your given joystick, and to suit your preferences.

Current versions of Joytran install default versions of the profiles system-wide, such that it is no longer necessary to manually copy profiles to the local profiles directory. If you need to make changes to the default profiles, then copy the desired profile to the local profiles path, and edit it as needed. For any given profile, the local profile will always take precedence over the system-wide profile.

Profile Syntax

Comments are also supported, as documented later in the manual.

Types of lines

Button

the "key:" field means which keycode it will translate the joystick button to, as described by the command line tool xev(1).

Using this tool, you can determine the keycode of a given key on your keyboard. Keep in mind that you want the decimal value, NOT the hexidecimal keysym.

Mouse clicks are given as negative values. Basically, -1 means a left click, -2 is a middle click, and -3 is a right click. If your mouse/trackball supports more buttons, they should work with successive negative numbers. More than three buttons have not been tested.

Mouse wheel emulation is not yet implemented, although it is trivial to emulate the "Page Up" and "Page Down" keys.

Using xev(1)

1) Type the command on the shell

> xev

2) Focus the "Event Tester" window.

3) Press the desired key.

The information that you need to put in the file for the "key:" field, is the "keycode" value, which will be shown in the terminal window that invoked xev(1).

How do I find out which button id ("button:" field) corresponds to a given button?

On some versions of FreeBSD, the command usbhidctl may be used:

# usbhidctl -f /dev/uhid0 -v -a

(This did NOT work on my machine, however, and likely does not work on 8.x-RELEASE, or later.)

The program "SDLJoytest-GL" is probably the best way to determine which button corresponds to the given button on your joystick, although it is a third party program that is hard to install.

It is possible that in future versions of Joytran, a simple graphical utility could be included, to easily determine the "buttons," "hats," and "axes" of your desired controller. Just don't hold your breath.

If both of these methods did not work, then simply use one of the provided Joytran profiles, and test which buttons generate which keys in xev(1). This is somewhat tedious, but it does work reliably, regardless of platform.

Then, you can change the profiles to suit your needs, since every joystick is likely to map the buttons in a specific order.

Axis and Hat

Axis and Hat, within the context of Joytran, are almost the same. However, SDL makes a distinction between the two types. Therefore, it is important to understand the differences.

Axis

Much of the information needed to gather this information is SDL specific jargon, so you might need to guess until you determine how many axes your joystick supports. Axis numbers will always start from 0.

The "joy_id:" field corresponds to which joystick number you are dealing with. In most cases this will be 0, unless you have multiple joysticks attached.

The "axis_id:" represents the nth axis on your joystick. If a joystick contains one "analogue stick" and no "directional pad", then most likely would have two axes, 0 and 1.

The "axis:" field is used to tell Joytran if this should be an x, or a y axis. Otherwise, it will not know if it is horizontal or vertical, and will probably guess incorrectly.

The "min:" and "max:" fields are used to determine the range of possible values on the axis. Basically, if you are generating a key event, then you only want a "min:"/"max:" of -1/1, because keys are either pressed or not pressed. They are not variable.

Higher values are used when mouse emulation is desired, such as a "min:"/"max:" of -2000/2000, for example. This would imply faster movement, although due to the smoothing algorithm, extremely high values will make the controller unresponsive for a moment.

The "threshold:" is only of concern to an "axis" or "hat" that generates a keyboard press. The "threshold:" is simply the minimum value of the absolute value of the axis needed to trigger this keypress. Assuming that a given joystick axis has a range of -32768 to +32768, it would be reasonable to trigger a keyboard event if |x| is 10000. Hence, the typical value for "threshold:" is generally 10000 in the sample profiles.

An axis that triggers mouse movement does not use the "threshold:". If you are dealing with mouse events, then a good default value is 0, since a mouse movement should generate a movement event, even for a relatively small press on the "analogue stick". More detailed runtime control over the mouse movement is available via the "setting" lines.

The "keylow:" field represents what the keycode for "up", or "left" would be, and the "keyhigh:" field represents what the keycode for "down" or "right" would be.

If mouse movements are desired, then both the "keylow:" and "keyhigh:" should be -1.

Hat

See the documentation for "axis" as well, since most of this information is relevant to a "hat" as well.

Axis and Hat distinction

Joytran instead considers one SDL hat to have two separate hats, one for each horizontal and vertical "axis:", so that the same notation as for the "axis" line may be used. It is simpler to write configuration files because a line for the "axis" line is almost the same as for the "hat" line.

If you have a 2-dimensional "analogue stick", then that will be classified as two separate axes, (axes rather than hats, unlike a "directional pad") both horizontal and vertical, since these express two dimensions. For both axes and hats, the "axis:" will be completely determined by your specific joystick device, so you will need to specify if the "axis:" field is either x (horizontal) or y (vertical).

Just as a side note, Joytran does NOT support odd numbers of hats or axes in the current version. This means that it only supports two-dimensional "directional pads" and "analogue sticks", not a one-dimensional "hat" or "axis". (or any odd number of dimensions) If anyone has any devices that require this, I will consider updating this code, however, the necessary changes have not been made yet....

How many axes and hats does my joystick have?

4 axes (the horizontal/vertical for both of the "analogue sticks")
2 hats (the horizontal/vertical for the one "directional pad")

All of the provided profiles are designed for the "LTS PSX/USB Pad" PlayStation 2 Controller adapter, although it should be trivial to adapt them for your adapter of choice, provided it is any of the three types of controllers mentioned. The order of the axis or hat "axis:" is not necessarily x, then y. Sometimes it is y, then x. It completely depends on your joystick or adapter.

Setting

For mouse emulation, Joytran picks good defaults for the "smooth_algorithm:" and for "smooth_refresh:", but depending on the resolution of the game, and the desired level of precision vs. speed, different values might be appropriate depending on the application.

The "smooth_algorithm:" field is an optional setting that has two possible values. A value of 0 (default) implies that a variant of the Bresenham line algorithm will be used for mouse cursor movement. A value of 1 uses an old, ad-hoc algorithm that occasionally works well. (but is usually inferior)

The "smooth_refresh:" field is an optional setting which is mostly for testing. A value of -1 implies that a smooth refresh will always be used. A value of 0 implies that there will be no refresh period for mouse movement. A value of 1 implies that the program will sleep for 10 nanoseconds for every position that is modded by 5. A value of 1 implies that the program will sleep for 10 nanoseconds for every position that is modded by 2. A value of 3 implies that the program will sleep for 10 nanoseconds for every interval. A value of 4 implies that the program will sleep for 100 nanoseconds for every interval. A value of 5 implies that the program will sleep for 1000 nanoseconds for every interval. Anything greater than 5 will sleep for 10000 nanoseconds for every interval.

Since no platform that Joytran runs on offers hard real-time support, the pause when refreshing between intervals will likely be far greater than then number of microseconds computed. Generally speaking, it is not recommended to change the "smooth_refresh" value, but it is available to offer greater flexibility.

Comments

Partial-line comments probably will not work, and are not recommended, at least on lines that define a "button", "axis", "hat" or "setting".

Troubleshooting

1) Make sure to assign a line for EVERY "button", "axis", and "hat" that your controller provides, and do not assign beyond what your controller provides. Configuring buttons or axes that do not exist is most likely harmless, however.

On the other hand, it is possible to crash Joytran if you do not assign something to a given button, and that button is pressed during runtime.

2) Avoid placing whitespace at the beginning of lines, or lines consisting of only whitespace. In the most recent (0.8.2-RELEASE or greater) versions of Joytran, warnings will be provided on the command line at program startup if the configuration file is suspicious.

Although heading whitespace is harmless on lines where something is configured, they will usually crash the program if the line contains only whitespace, and more than just an ending linefeed. Future versions of the configuration file parser should handle this, but for now, the parser merely gives warnings.

A Blank line is acceptable if and ONLY if the line is empty, and these will still give a warning on program startup. If clarity is desired, separate lines with comments as an alternative.

3) Joytran will typically NOT run if a program that is configured to use native joystick support is running in the same X11 session. In this case, it would likely be redundant.

If you still desire to use Joytran for that program, turn the joystick support off in the program, and use an appropriate Joytran profile.

4) Comments and empty lines are only supported in versions 0.8.2-RELEASE, or greater.

5) Apparently some games have problems when the same keys are generated from different axes or hats. (If you assign Up/Left/Down/Right or w/a/s/d to more than one axis or hat) This issue is being investigated, although it does not occur in most games.

Fortunately, this does not affect the same key on multiple buttons, which is needed more frequently.

6) Joytran does not have a REPL (Read-Eval-Print Loop), so if a profile is changed, Joytran will not be aware of the changes until it is restarted.

Special Thanks

Hosting Providers

BerliOS, for tarball and website hosting.

Google Code, also for tarball hosting.