org.j3d.device.input.spaceball
Class SpaceballDriver

java.lang.Object
  org.j3d.device.input.spaceball.SpaceballDriver

Direct Known Subclasses:

Spaceball3003Driver, Spaceball4000Driver

public abstract class SpaceballDriver

extends java.lang.Object

Driver for Labtec's Spaceball device. Does not support multithreading. All methods must be called from a single thread.

Stores only the latest received position data, which can be obtained with the getLastPositionValues(int[]) method. The event of pressing a button is stored until getLastButtonValues(int[]) is called. Then all button states are cleared, i. e. release events are ignored. It might happen that very fast button press/release events will not be detected.

Use SpaceballTypeDetector.createSpaceballDriver(java.lang.String, int) to open a serial and to obtain an appropriate SpaceballDriver object. After use close() must be called to release the serial port.

Uses the javax.comm extension package, which must be installed.

Spaceball, Spaceball 2003, Spaceball 3003 and Spaceball 4000 are Trademarks of Labtec Inc.

Version:

12. Nov. 2001 Copyright (c) Dipl. Ing. Paul Szawlowski

Author:

Dipl. Ing. Paul Szawlowski - University of Vienna, Dept. of Medical Computer Sciences

Field Summary

protected int[]	itsButtonData button pressed: value > 0, button not pressed: value = 0.
protected int[]	itsPositionData Current position Data.
protected byte[]	itsWriteBuffer use this buffer for packets send to the Spaceball device.

Constructor Summary

SpaceballDriver(SerialPort serialPort, java.io.InputStream inputStream, java.io.OutputStream outputStream, int packetTerminator)

Method Summary

void	close() Closes and frees serial port.
abstract void	disableDevice(int timeout) Ceases postion data transfer from the Spaceball device.
protected abstract void	dispatch(byte[] readBuffer, int dataStart, int dataLength, int header)
void	emitPatternedBeep(char[] pattern) Emits a patterend beep.
abstract void	enableDevice(int timeout) Requests data from the Spaceball device.
void	getLastButtonValues(int[] buttonData)
void	getLastPositionValues(int[] positionData)
int	getNumOfButtons()
SerialPort	getSerialPort() Convenience method to enable an application to change port settings if necessary.
static SerialPort	openPort(java.lang.String portDescriptor)
static void	pause(int timeInMillis)
protected static void	printBuffer(byte[] buffer, int length)
void	processDeviceInfoResponse(int type, int lineNumber, java.lang.String content) Overriding methods shall call processRequestResponse(int).
void	processEchoResponse(byte[] data) Default action if an echo event from Spaceball device was received.
void	processError(int errorCode, java.lang.String errorString)
void	processRequestResponse(int type) Notify driver that expected event from Spaceball device received for blocking requests.
void	read() Reads data from serial port.
void	resetDevice(int timeout) Resets device.
protected void	setNumOfButtons(int numOfButtons)
protected void	waitForResponse(int timeout, int request, java.lang.String description) Sends a request to the Spaceball device and wait until response is received or timeout period is over.
protected void	write(byte[] buffer, int offset, int length)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

itsPositionData

protected final int[] itsPositionData

Current position Data. index 0: period of data (1/16th milliseconds), index 1 xTranslationForce x-axis translation force, index 2 yTranslationForce y-axis translation force, index 3 zTranslationForce z-axis translation force, index 4 xRotationalForce x-axis rotation force (positive values: counter clockwise rotation), index 5 yRotationalForce y-axis rotation force (positive values: counter clockwise rotation), index 6 zRotationalForce z-axis rotation force (positive values: counter clockwise rotation)

itsButtonData

protected final int[] itsButtonData

button pressed: value > 0, button not pressed: value = 0.

itsWriteBuffer

protected final byte[] itsWriteBuffer

use this buffer for packets send to the Spaceball device.

Constructor Detail

SpaceballDriver

public SpaceballDriver(SerialPort serialPort,
                       java.io.InputStream inputStream,
                       java.io.OutputStream outputStream,
                       int packetTerminator)

Method Detail

close

public void close()
           throws java.io.IOException

Closes and frees serial port. Call after using the device.

Throws:

java.io.IOException

enableDevice

public abstract void enableDevice(int timeout)
                           throws java.io.IOException

Requests data from the Spaceball device. Must be called once after opening in order to receive position data. The first data packet will be "null-data" packet (all position data is set to zero) Blocking until response from device received or timeout is over.

Parameters:

timeout - [ms] timeout for response from the Spaceball device

Throws:

java.io.IOException - if timeout is reached without a response from the Spaceball device or if an error occurs during reading the serial port

disableDevice

public abstract void disableDevice(int timeout)
                            throws java.io.IOException

Ceases postion data transfer from the Spaceball device. Blocking until response from the Spaceball device received or timeout is over.

Parameters:

timeout - [ms] timeout for response from the Spaceball device

Throws:

java.io.IOException - if timeout is reached without a response from the Spaceball device or if an error occurs during reading the serial port

read

public void read()
          throws java.io.IOException

Reads data from serial port. This method must be called periodically to process data sent from the Spaceball device.

Throws:

java.io.IOException - if an error occurs during reading the serial port

getNumOfButtons

public int getNumOfButtons()

Returns:

number of buttons supported by this device

getSerialPort

public SerialPort getSerialPort()

Convenience method to enable an application to change port settings if necessary.

Returns:

handle to the SerialPort in use or null if #open was not called before or was not successfull or after a call of close().

getLastPositionValues

public void getLastPositionValues(int[] positionData)

Parameters:

positionData - Max. size of array = 6.

getLastButtonValues

public void getLastButtonValues(int[] buttonData)

Parameters:

buttonData - button pressed: value > 0, button not pressed: value = 0; Max. size of array = 12.

emitPatternedBeep

public void emitPatternedBeep(char[] pattern)
                       throws java.io.IOException

Emits a patterend beep. Does not wait for response from the Spaceball device. Note: non blocking

Throws:

java.io.IOException - if timeout is reached without a response from the Spaceball device or if an error occurs during reading the serial port

See Also:

SpaceballPacket.createPatternedBeepPacket(byte[], int, char[])

resetDevice

public void resetDevice(int timeout)
                 throws java.io.IOException

Resets device. Blocking until response from the Spaceball device received or timeout is over.

Parameters:

timeout - for response from the Spaceball device.

Throws:

java.io.IOException - if timeout is reached without a response from the Spaceball device or if an error occurs during reading the serial port

See Also:

SpaceballPacket.createSimpleRequestPacket(byte[], int, byte)

dispatch

protected abstract void dispatch(byte[] readBuffer,
                                 int dataStart,
                                 int dataLength,
                                 int header)

processRequestResponse

public void processRequestResponse(int type)

Notify driver that expected event from Spaceball device received for blocking requests. Overriding methods shall call this method.

setNumOfButtons

protected void setNumOfButtons(int numOfButtons)

processError

public void processError(int errorCode,
                         java.lang.String errorString)

processDeviceInfoResponse

public void processDeviceInfoResponse(int type,
                                      int lineNumber,
                                      java.lang.String content)

Overriding methods shall call processRequestResponse(int).

processEchoResponse

public void processEchoResponse(byte[] data)

Default action if an echo event from Spaceball device was received. Overriding methods shall call this method.

openPort

public static SerialPort openPort(java.lang.String portDescriptor)
                           throws NoSuchPortException,
                                  PortInUseException,
                                  UnsupportedCommOperationException

Throws:

NoSuchPortException

PortInUseException

UnsupportedCommOperationException

write

protected final void write(byte[] buffer,
                           int offset,
                           int length)
                    throws java.io.IOException

Parameters:

buffer - buffer containing the data to be written to the serial interface

offset - start offset of "buffer"

length - number of bytes to write

Throws:

java.io.IOException

waitForResponse

protected final void waitForResponse(int timeout,
                                     int request,
                                     java.lang.String description)
                              throws java.io.IOException

Sends a request to the Spaceball device and wait until response is received or timeout period is over. This method is blocking.

Parameters:

timeout - [ms] timeout for response from the Spaceball device

request - use constants

description - description of request

Throws:

java.io.IOException

printBuffer

protected static void printBuffer(byte[] buffer,
                                  int length)

pause

public static void pause(int timeInMillis)