ForceFeedback
Joystick Driver for Java
This driver was made as a practical project for the Department
of Computational Perception at JKU
Linz.
Features:
- Support for joystick input: axes
(incl. sliders and rotation axes), point-of-view sticks, trackballs
and buttons.
- Support for force feedback
(haptic effects).
- Includes complete javadoc.
- Interface compatible with
Controller from LWJGL (http://www.lwjgl.org/).
- Based on SDL 1.3
(http://www.libsdl.org/) - SDL
is platform independent.
- Tested on Windows, Linux and MacOS X.
This
document contains:
Install
instructions
This is what you should
do in general. Below you will find detailed instructions for
Windows, Linux and MacOS X.
Connect your
joystick and make sure it works
as an input
device.
If you have a force
feedback joystick: make sure force feedback works.
If necessary, install the correct driver from the device
manufacturer.
Install SDL
1.3 or higher: http://www.libsdl.org/
Install the
joystick driver:
http://sourceforge.net/projects/ffjoystick4java/
go
to top
Installation on Windows
Test input: Connect
your controller. On Windows XP, go to 'Control Panel', 'Game
Controllers'. On Windows 7, go to 'Control Panel', type 'game' in
the search bar, below 'Devices and Printers' click 'Set up USB
game controllers'. Your device should be listed. Mark it and click
'Properties'. Test the input. If necessary, calibrate the
joystick.
Install
driver: Make sure you have DirectX installed. On current editions
of Windows DirectX is included. To make sure, run 'dxdiag.exe'
(type 'dxdiag' in the 'run' menu, or in a command prompt). Updates
may be available via Windows Update. (For installation
instructions see also How
to Download and Install DirectX and
http://www.microsoft.com/directx/)
Install your device
specific driver from the website of the manufacturer. Be aware
that some computers have a 32-bit Windows installed, even if they
have a 64-bit CPU. In that case you will need the 32-bit version
of the driver. If you have Windows 7 but you cannot find a driver,
you may try a driver for Windows Vista instead.
Test force feedback: If
your joystick came with an extra power adapter, make sure it is
plugged in correctly. On Windows XP, go to 'Control Panel', 'Game
Controllers'. On Windows 7, go to 'Control Panel', type 'game' in
the search bar, below 'Devices and Printers' click 'Set up USB
game controllers'. Mark your device and click 'Properties'. You
will probably see a different interface than before you installed
the driver. Press some buttons on your controller to test force
feedback. Usually buttons trigger force feedback effects to be
played. Be aware that on some controllers force-feedback can be
disabled using a button or switch.
Test if your device is
recognized by DirectX. Start 'dxdiag' once again. Your device
should show up in the 'Input' tab.
To test if your
force feedback driver is installed correctly and works within
DirectX, you can use the program 'FFConst.exe', which comes as a
sample with the DirectX SDK (DirectX
Developer Center). In case you do not want to download the
whole DirectX SDK package and build FFConst, I uploaded an
executable of it here:
http://boat.lachsfeld.at/ffjoystick4java/ffconst.zip.
If FFConst does not start, make sure you followed the previous
steps correctly and try again. ;)
SDL for Windows is included
with the joystick driver – there's nothing to do in this step.
Be sure you
have a Java Runtime Environment (JRE) or SDK installed.
Download the joystick driver from
http://sourceforge.net/projects/ffjoystick4java/
(compiled SDL.dll for Windows is included). Unpack it and change
to the subdirectory 'windows' (32-bit) or 'windows64' (64-bit). Run the file 'run.cmd' to start the
testing GUI, or type
java
at.wisch.joystick.test.JoystickTest
on the command line. Either the 'windows' or the 'windows64' version should work on any windows in some command prompt.
(Note: To start a 64-bit command prompt run '%windir%\system32\cmd.exe'. To start a 32-bit command prompt run '%windir%\SysWoW64\cmd.exe'. I did not get confused. This is how it is...)
If
the ForceFeedback menu is inactive, your device was not recognized
as force feedback device.
go
to top
Installation on Linux
Connect your
controller and make sure input works. (see also
http://ubuntuforums.org/showthread.php?t=338457)
Type
cat
/dev/input/js0
in a terminal. Press
some buttons and move the sticks. If you see weird things, it
should work. To test more specific use 'joystick'. On
Debian/Ubuntu:
sudo
apt-get install joystick
jscal
/dev/input/js0
jstest
/dev/input/js0
To calibrate you can
use 'jscalibrator'. On Debian/Ubuntu:
sudo
apt-get install jscalibrator
jscalibrator
Since Ubuntu
9.04 (and kernel 2.6.28) Force Feedback is supported by default,
so there is no need to compile a custom kernel. To test force
feedback you can use the Linux Force Feedback Library, available
from http://sourceforge.net/projects/libff/.
See
http://sourceforge.net/apps/mediawiki/libff/index.php?title=CheckForceFeedback
for instructions.
Install SDL 1.3.
If you have an old
version of SDL 1.3 installed you should uninstall it ('sudo make
uninstall').
Download SDL
1.3 and unpack it. (http://www.libsdl.org/
- menu 'SDL SVN' - download the latest source snapshot for SDL
1.3)
In the
directory where you unzipped to: run 'autogen.sh' and
'configure'.
Run 'make'.
Run 'sudo make
install'.
Install the
joystick driver.
Be sure you have a
Java Development Kit (SDK) installed.
Download the
driver from http://sourceforge.net/projects/ffjoystick4java/.
Change to the
'linux' subdirectory and mark the files 'buildff.sh' and 'run.sh'
as executable.
If necessary,
modify 'buildff.sh' using your system dependent paths and
directories. The paths in the parameters are:
the Java
include-directory (for JNI)
the Java
include/linux-directory (for JNI)
the
default system library-path (for SDL)
for
output: also the default system library-path
Run 'buildff.sh'.
If necessary,
modify 'run.sh' using your default system library-path.
Run 'run.sh' to
start the testing GUI. If the ForceFeedback menu is inactive, your
device was not recognized as force feedback device.
go
to top
Installation on MacOS X
Installation on MacOS X is quite similar to
the installation on Linux. Unlike on Linux, 'make' and the Gnu
C/C++ compilers are not installed by default on MacOS. To test if
you have them: open a terminal, type 'make' and press enter. Do the
same with 'gcc' and 'g++'. If you do not have these developer
tools, download the XCode package from http://connect.apple.com/.
You will need to register for an Apple Developer account. Once you
have registered, login and click 'Download Software' and then
'Developer Tools'. Find 'Xcode Tools'. Check the description for
compatibility information. (Usually the latest versions of XCode do
not work with older versions of MacOS X). Download the 'CD/DVD
Image' and install it.
You will also need to use the 'sudo' command later.
If your administrator account has no password (a blank password),
you need to set up a password.
Connect your
controller and make sure input works.
To see if it is
connected correctly start the 'System Profiler' (“Hard
drive” icon – 'Applications' – 'Utilities').
Click 'Devices and volumes”. In the USB tree your controller
should be listed.
To really test input
you can use a freeware or shareware program like:
You can skip
this step on MacOS X. Or you can use the game 'Jammin' Racer' to
test force feedback. But still, if force feedback works in that
game it does not mean that it will work in Java. More on that
issue later in the next section, 'Supported controllers and
effects'. You can download the game from
http://www.danlabgames.com/index.php?rub=jammin&computer=mac.
Install SDL 1.3.
If you have an old
version of SDL 1.3 installed you should uninstall it ('sudo make
uninstall').
Download SDL
1.3 and unpack it. (http://www.libsdl.org/
- menu 'SDL SVN' - download the latest source
snapshot for SDL 1.3)
In the directory
where you unzipped to: run 'autogen.sh' and 'configure'.
Run 'make'.
Run 'sudo make
install'.
Install the
joystick driver.
Be sure you have a
Java Development Kit (SDK) installed.
Download the
driver from http://sourceforge.net/projects/ffjoystick4java/
and unpack it.
Open a Terminal
and change to the 'macos' subdirectory. Type
g++
-o libffjoystick.jnilib FFJoystick.cpp `sdl-config --cflags
--libs`
-I/System/Library/Frameworks/JavaVM.framework/Versions/A/Headers/
-shared -arch x86_64
to build the joystick
library file. The directory
'/System/Library/Frameworks/JavaVM.framework/Versions/A/Headers/'
can vary depending on your system. It might also be
'/System/Library/Frameworks/JavaVM.framework/Headers/'.
You can also try to find the file 'jni.h' (use the command 'find
/ -name "jni.h"') and use the path where
this file is located.
Depending on your
system architecture you might also have to use '-arch
i386' or just drop that parameter.
Type the following
command to start the testing GUI:
java
-Djava.library.path=. at.wisch.joystick.test.JoystickTest
If the ForceFeedback
menu is inactive, your device was not recognized as force
feedback device.
If you get an error
like "no
suitable image found. Did find: /.../libffjoystick.jnilib:
mach-o, but wrong architecture" open
'Java-Preferences' and change the order of the Java Virtual
Machines execution order, e.g. put the 64-bit Java VM above the
32-bit VM. If you do not know where to find 'Java-Preferences',
use Finder (the search field in your menu bar).
go
to top
Supported
controllers and effects
All controllers that are
supported by SDL are supported by this driver as well. For input I
have not seen any controller that does not work on any OS, though on
Windows the axis order is sometimes mixed up on some controllers.
For force feedback see the following section.
On Windows
basically every controller that supports DirectX
will be supported by the driver. The problem is, that even if
support for a device is given, it is not sure the device will play
all the effects it is supposed to support. In my experience: Usually
the device will tell you it supports all 12 types of effects that
exist in DirectX, but for example: a rumbling gamepad will never be
able to play a condition effect. Sometimes it does not even report
an error. It just does not play a thing. Sometimes effects are not
working because a “wrong” direction type is used. Edgar
Simo wrote in the libSDL forums: “The problem with force
feedback especially on windows is that the drivers tend to be loads
of steaming crap. Windows on top of it all has a very "loose"
force feedback driver model which makes it so you have to
continuously check a billion of small minor things to see if they're
supported to support all the possible cases. Not to mention the fact
that not all devices actually support what they broadcast among
other things.“ (http://forums.libsdl.org/viewtopic.php?t=5195)
On Linux
fewer devices seem to be supported. For a list of
controllers that will most likely support FF on Linux see:
http://sourceforge.net/apps/mediawiki/libff/index.php?title=SupportedDevices.
Also the number of supported effects is less, compared to windows.
But at least the device will support what it tells you. Quoting
Edgar Simo on driver models again: “Linux probably takes the
cake for cleanest, although it is missing some bells and whistles
the mac os x and windows implementations have.”
On MacOS
X I could not test much. On the newest
Snow Leopard 10.6 64-bit none of my controllers supported FF. The
problem seems to be that no there are no drivers for recent
controllers. Hendrik Bartel, Sr. Product Manager, from immersion.com
wrote in an email that “unfortunately, the Mac driver was
never really moved forward”. So though SDL uses the official
force feedback library for MacOS X it is likely that it does not
work with newer controllers or newer versions of MacOS. (see
http://developer.apple.com/mac/library/documentation/DeviceDrivers/Reference/ForceFeedback/ForceFeedback_h/index.html)
So in general the problem
is that for many controllers there are bad operating system drivers
available, or none at all. Here is what I experienced with my
controllers:
Logitech
RumblePad 2: works perfect on Windows and Linux. The number of
effects that are supported on Linux is less though, but all the
important ones are supported. On MacOS X it did not support FF.
Logitech Force 3D
Pro: works perfect on Windows and at least somehow on Linux. It
supports only one effect (ConstantEffect) and there is an issue
with the directions. On MacOS X it did not support FF.
Logitech Wingman
RumblePad: works perfect on Windows. No FF support on Linux. Not
tested on MacOS X.
Saitek Cyborg EVO
Force: FF did not work on Windows. I think there is a driver issue.
It is detected as FF device, but uploading effects is not
successful. On Linux even some of the input axes were missing. On
MacOS X it did not support FF.
Other joysticks
without FF: they all worked fine as input devices on all operating
systems where I tested.
Custom effects did not
work on any of my devices. Also Friction, Inertia and Damper felt
like the same on my Logitech Force 3D Joystick.
Note: In some system
drivers you can enable/disable a centering spring force and adjust
its strength. On Linux it was always active with my Logitech Force
3D Joystick. In Windows it is adjustable in the control panel.
If you test the
driver with any other ForceFeedback-gamepad, please send me a quick
mail about your experiences. If you have any suggestions, or if you
want to report a bug, please see
http://sourceforge.net/projects/ffjoystick4java/
or contact me via email: mailto:elboato@users.sourceforge.net.
go
to top
Supported
operating systems
As mentioned before, this
driver is based on SDL 1.3. Therefore joystick input should work
wherever SDL 1.3 works. Unfortunately force feedback does not always
work, due to missing or bad operating system joystick drivers. I
tested on:
Windows XP (32-bit),
Windows Vista and Windows 7 (32- and 64-bit): input support: very
good, force feedback support: very good
Ubuntu 9.04 and 9.10
(32- and 64-bit): input support: very good, force feedback support:
good
Mac OS X 10.6.2
(64-bit): input support: very good, force feedback support: none (I
suppose it would work on older (32-bit) versions of MacOS X - SDL
supports Mac OS X 10.1 and higher)
go
to top
Developing
applications
Basically you need
to use the static methods of class JoystickManager to obtain
Joystick and FFJoystick objects. Then you can use these to obtain
input data and play effects. Take a look at the javadoc
to get to know how you should use the driver. Also the classes
JoystickInputDemo and JoystickForceDemo should demonstrate how to
use everything. The latest javadoc
is included in the download from
http://sourceforge.net/projects/ffjoystick4java/.
You can also read the javadoc
online at http://boat.lachsfeld.at/ffjoystick4java/javadoc/.
On windows for some
controllers the axis order is reversed. I corrected that with a
special precompiler variable setting in FFJoystick.cpp. Set
INVERTAXISORDER to 1 when you compile the dll for Windows. This
problem is known and exists on other driver implementations as well.
This also applies to the order of FF axes.
I'm not sure if
there is a bug or if just none of my controllers supports custom
effects. Also I don't have a gamepad with a trackball, therefore I
could not test the corresponding methods. Please inform me if you
find a bug: mailto:elboato@users.sourceforge.net.
You can also send feature requests and feedback of all kind.
go
to top
Notes
on SDL
“Simple
DirectMedia Layer is a cross-platform multimedia library designed to
provide low level access to audio, keyboard, mouse, joystick, 3D
hardware via OpenGL, and 2D video framebuffer. It is used by MPEG
playback software, emulators, and many popular games, including the
award winning Linux port of "Civilization: Call To Power."”
(from http://www.libsdl.org/).
Since version 1.3 SDL has platform independent support for force
feedback (haptic) effects.
The people working
on SDL are doing great work As this driver is based on SDL, it will
hopefully work on future OS versions as well. If you notice changes
in the haptic interface of the newest versions of SDL, please inform
me: mailto:elboato@users.sourceforge.net.
I will try to update my driver as soon as possible.
go
to top
Frequently
Asked Questions (F.A.Q.)
- When starting on Windows I get an UnsatisfiedLinkError exception. What's that about?
Exception in thread "main" java.lang.UnsatisfiedLinkError: [somewhere]\ffjoystick.dll: Can't find dependent libraries
Most likely you are lacking the Visual C++ redistributable. You can download and install it from there:
go
to top
Thanks
Big thanks to the people at SDL for doing great
work!
Thanks to Saitek for sending me a Saitek
Cyborg EVO Force joystick (http://saitek.com/)!
Thx to Blue-Tiger and Bronko, my Linux friends.
Thx to Hari and Rich, my C++ friends.
Thx to Lisi and Richie, my Apple Mac friends.
Thanks to my brother and gaming companion for 29 years (as of 2011).
Thx to eggbronko for chat(bot)ing with me, when
no one else was there in the channel.
go
to top
Copyright (c) 2010, Martin Wischenbart
All rights reserved.
