Short Guide to FLUID Input Device Configuration
***********************************************

This guide discusses the input device configuration system of FLUID library from the application programmer's perspective . Roughly this should contain the essentials that must be understood if one whishes to use the FLUID package succesfully.

Some general things about FLUID configuration
=============================================

FLUID library reads in a configuration file when Config::init() is called. No input devices are functional without proper configuration. The file that is read is located as follows:

1) If init() call has a filename as parameter this is tried first
2) "./fluid-config"
3) $FLUID_ROOT/fluid-config

In general, applications should define their configuration files independently instead of using the one in $FLUID_ROOT. "FLUID_ROOT" is an environment variable that must be set to point into the root directory if FLUID. Check out the document 'INSTALL', for more instructions about this.

The configuration file consists of config chunks and typically each chunk defines one input device.

Parameters that All the Input Devices Have
------------------------------------------

There are some parameters that all the input devices have:

-name (except for servers)
-bufferSize

Name refers to name of the corresponding device object that will be available by quering from FLUID API. Here is an example of such query:

Mouse *mouse = InputDevices::getMouse("myveryownmouse");

Buffersize means the internal bufferSize of the FLUID device driver. This quantity determines the required frequency for update()-calls if the goal is to read all the samples into application.

Required bufferSize can be calculated as follows:

bufferSize = sampling_rate/maximum_update_interval

Most devices allow you to configure the sampling rate yourself in the configuration chunk, some may have fixed sampling rate. If the sampling rate is fixed you can find it out by reading the manual that came with the hardware (If not, you'll have to measure it yourself).

You should note that loosing samples is not fatal if your application doesn't need continuous spans of input data history

Configuring 5DT Data Glove for Local Use
========================================

You want to use the data gloves locally in case the gloves are connected to the same computer in which your application is running. To use one glove add the following configuration chunk:

5DTGlove
{
	name=<whatever you want to call it>
	sampleRate=50
	device=/dev/fglove0
}

The 'sampleRate' parameter is optional. If the above was for right hand, you can configure the left hand also, by adding the following:

5DTGlove
{
	name=<something else>
	sampleRate=50
	device=/dev/fglove1
}

Configuring 5DT Data Glove for Remote Usage
===========================================

You want to configure the data gloves for remote usage in case the gloves are connected into another computer than the one in which your application is running.

Configuring the server
----------------------

For remote usage you need to start the glove server in a computer into which the data glove is connected. The server is an executable application which is compiled from the same source code than the FLUID 5DT data glove driver. You can find the server application from:

$(FLUID_ROOT)/src/plugins/5dtglove/<platform>/smain

Running this tries to start data glove server. To run succesfully, the server expects that you give configuration filename for it in the command line. There are two examples of configuration files for data glove server in the '5dtglove'-directory. So, to start the server you should do the following:

cd $(FLUID_ROOT)/src/plugins/5dtglove/
./i386-redhat-linux-gnu-debug/smain fluid-config-glove1-server

This runs the server that reads the input from '/dev/fglove1'. The server should print out the following:

FLUID 5DT Data Glove Server starting up...
FLUID # Read configuration from: fluid-config-glove1-server
FLUID # Config init() finished
Created server socket into port: 2200
Waiting for client to connect

Now server is in state waiting for clients to connect into port 2200. The port number can be changed by editing the configuration file ('fluid-config-glove1-server' in this case).

If you have two gloves connected into the computer and wish to use the both, you must start another server process with a configuration file that uses device for another hand (/dev/fglove0) and another port for sending the data. Configuration file 'fluid-config-glove0-server' provides an example of this.

Configuring the client
----------------------

The term 'client' is used to refer to main application side. To configure the application to read glove data over network you need to add something like following into a FLUID-configuration file that your application is using:

RemoteGlove
{
        name=myglove
        bufferSize=50
        server=bat.tml.hut.fi:2200
}

This tries to create input device called 'myglove' into the application and read the input for it from port 2200 of the host bat.tml.hut.fi.

Troubleshooting 5DT Data Glove
==============================

If the above does not work check out that data gloves are connected into the computer and that they work if you run an example program by the manufacturer. 

Data-glove device drivers are implemented as plugins, so check out that the binaries for following plugins are available:

5dtglove.so (local glove)
gloveproxy.so (remote glove)

Configuring the MotionStar Tracker
==================================

MotionStar drivers for fluid are currently available only for IRIX and there is no same kind of remote proxy system that is available for 5DT Data Gloves. This means that you have to be running in IRIX machine to be able to use the tracker.

Tracker configuration chunk might look like following:

MoStarTracker
{
        name=mytracker
        bufferSize=50
        server=130.233.45.15
        sensor4 = right-hand
        sensor1 = left-hand
}

The server parameter is the IP-address of the tracker terminal server. FLUID-tracker interface provides a way to query sensor indices by name. This is what 'sensor4=right-hand' and 'sensor1=left-hand' means. So, with above configuration, if tracker's getSensor() function is called with 'right-hand', number four is returned.

Naming of sensors is optional, you might as well use direct indexing for tracker sensors, but in that case you will have to change your source code if you wish to change the sensor that is used for some purpose.

WRITE ABOUT TRANSFORMATIONS AND COORDINATE SYSTEMS

Troubleshooting Tracker
=======================

If the tracker is not working at all check out that the MotionStar Tracker plugin is compiled and up to date. The name of the plugin is:

libMoStarTracker.so
-----------------------END--------------------
