PXLab Manual

PXLab Manual

[Home] [Content] [Previous Chapter] [Next Chapter]

Connecting External Devices
The default response collection devices for PXLab are the keyboard and the mouse. PXLab also supports the following external devices:

Switches, LED's or other electronic devices connected to the control lines of a serial port. No serial data lines are used. Input signals connected to a serial port control lines use the standard Java event handling and are highly reliable and very fast. These devices should be used if the most reliable response time measurement is needed.
A serial communication line. This may be used to communicate with devices connected to the serial communication line. Examples are color measurement devices with a serial communication interface.
Gaming devices connected to an USB port and supported by the DirectInput library of the Windows operating system. These are supported only under Windows and are not well integrated into the standard Java event handling mechanism. These devices have to be polled and should not be used for response time measurement since they introduce an unpredictable delay into the response event handling methods. Using these devices needs a DLL from the open source library JXInput being installed.
3D SpaceMouse devices manufactured by 3DConnexion. These may be used to control up to 6 axes for manipulations in 3D space. PXLab abblications may use these devices for the adjustment of colors in 3D color space. These devices also have buttons which can be used for binary responses. Event handling for these devices is slow and my even slow down the event handling for other devices. So these devices should only be activated when really needed. The DLL needed for SpaceMouse access is contained in the extended PXLab runtime distribution archive. The device's driver has to be installed before the device can be used.

Devices Connected to the Serial Port
PXLab applications can access an external control box connected to one of the computer's serial communication ports. This makes it possible to

use external switches to collect responses,
control external signals, and
send synchronized trigger pulses to external devices.

Although the external devices are connected to the serial communication port PXLab does not use serial data transfer in this case. PXLab does only use the control lines of the serial port and does not use the data transfer lines. This ensures fast response timing and proper signal synchronization.
In addition to using the control lines of the serial port for response switches and signals, PXLab can also communicate with serial devives across the serial communication interface.
External Response Buttons
Figure 1 shows how to connect 4 response switches to the RS 232 serial communication port input control lines and Figure 2 shows how to connect two LEDs to the serial communication port output control lines. A trigger signal may be connected like one of the LED devices.

Figure 1. Schematics how to connect 4 external response keys/switches to the serial RS232 port. The pin numbers are given for both the 9- and the 25-pin connector.

External control box responses are activated by selecting a proper display timer. The interface TimerBitCodes has two predefined codes which activate the external control box buttons: XBUTTON_TIMER_BIT is the single bit code which activates external buttons and RESPONSE_TIMER is the general code which activates any subject response driven timer.
When an external response button is used then the parameter ResponseCode of the respective Display object will identify the number of the external button which activated the response. These numbers are defined in class ResponseCodes for the 4 possible buttons of a serial communication port box:
   de.pxlab.pxl.ResponseCodes.SERIAL_PORT_BUTTON1
   de.pxlab.pxl.ResponseCodes.SERIAL_PORT_BUTTON2
   de.pxlab.pxl.ResponseCodes.SERIAL_PORT_BUTTON3
   de.pxlab.pxl.ResponseCodes.SERIAL_PORT_BUTTON4
The PXLab external control box must be opened before it can be used. This is done by the special display object DeviceControl. This display object tells the system the name of the communication port which is used by the external response box. This display should be included in the Session start display list. Here is an example for opening and closing the external control box:
    Session() {
      DeviceControl() {
	DeviceType = de.pxlab.pxl.DeviceCodes.SERIAL_PORT;
	CommandCode = de.pxlab.pxl.DeviceControlCodes.OPEN_DEVICE;
        Port = "COM1";
      }
      ...
    }
    SessionEnd() {
      DeviceControl() {
	DeviceType = de.pxlab.pxl.DeviceCodes.SERIAL_PORT;
	CommandCode = de.pxlab.pxl.DeviceControlCodes.CLOSE_DEVICE;
        Port = "COM1";
      }
    }
The parameter Port of the class DeviceControl defines the name of the serial port. Possible names are those which are supported by the Java communications API: "COM1" and "COM2" on PCs, and "Serial A" and "Serial B" on Sun Ultra workstations.

Figure 2. Schematics how to connect 2 LEDs to the serial RS232 port. The pin numbers are given for both the 9- and the 25-pin connector.

Steady State Signals
External control box signals are controlled by special Display objects. An external control box signal line may be switched on by ExternalSignalOn(). Since external signals are not automatically cleared by a subsequent Display object there is an explicit clearing object: ExternalSignalOff(). Note that ExternalSignalOff() has NO_TIMER as its default timer such that switching off an external signal does not have a duration. IN some cases it might be useful to set the Overlay flag for one or both of these signal.
Here is an example for switching an LED connected to the external control box. The stimulus signal is the LED and the response is collected by any of the usual response devices:
      ExternalSignalOn() {
	Duration = 2000;
        Timer = de.pxlab.pxl.TimerCodes.LIMITED_RESPONSE_TIMER;
      }
      ExternalSignalOff();
Note that the first display object ExternalSignalOn switches the LED on and the object ExternalSignalOff switches the LED off.
Since the external control box can have multiple signal lines these objects have the experimental parameter Code which defines which of the signal lines to use. Note that although these parameters of ExternalSignalOn() and ExternalSignalOff() are independent, they have to have identical values in order to switch off a signal which has earlier been switched on. Here is a complete example for a small demo program which uses external LED signals and activates external response buttons:
Experiment()
{
  Context()
  {
    AssignmentGroup()
    {
      DataFileTrialFormat = "%SubjectCode% %TrialCounter% %Trial.SimpleDisk.ResponseTime%";
      SubjectCode = "pxlab";
    }
    Session()
    {
      /* This opens the external control box connected to the serial
         communication port and enables external On,
         Off, and Trigger signals. It also enables externl control box response
         events. */
      DeviceControl() {
	/* The serial port name. */
	Port = "COM1";
	/* The command code for opening the external control box connected to the serial port. */
        CommandCode = de.pxlab.pxl.SerialCommunicationDeviceControlCodes.XOPEN;
      }
      Message()
      {
        Text = "Start!";
        Timer = de.pxlab.pxl.TimerCodes.RELEASE_RESPONSE_TIMER;
      }
    }
    SessionEnd()
    {
      /* Close the serial communication device. */
      DeviceControl() {
	Port = "COM1";
        CommandCode = de.pxlab.pxl.SerialCommunicationDeviceControlCodes.XCLOSE;
      }
      Message()
      {
        Text = "E N D E";
        Duration = 500;
        Timer = de.pxlab.pxl.TimerCodes.CLOCK_TIMER;
      }
    }
    Trial( TrialCounter, SimpleDisk.ResponseTime)
    {
      ClearScreen:Pause()
      {
        Timer = de.pxlab.pxl.TimerCodes.CLOCK_TIMER;
        Duration = 500;
      }

      /* Switch ON the external signal and procede to the next Display without delay. */
      ExternalSignalOn() {
        Timer = de.pxlab.pxl.TimerCodes.NO_TIMER;
        Code = 1;
      }
      /* Also show a screen signal. */
      SimpleDisk()
      {
        Size = 300;
        Timer = de.pxlab.pxl.TimerCodes.RESPONSE_TIMER;
        Color = [40.0, 0.313, 0.329];
      }
      ExternalSignalOff() {
        Timer = de.pxlab.pxl.TimerCodes.NO_TIMER;
        Code = 1;
      }
      Feedback()
      {
        Text = "%Trial.SimpleDisk.ResponseTime% ms";
        Timer = de.pxlab.pxl.TimerCodes.CLOCK_TIMER;
        Duration = 500;
      }
    }
  }

  Procedure()
  {
    Session()
    {
      Block()
      {
        Trial( ?, ?);
        Trial( ?, ?);
        Trial( ?, ?);
      }
    }
  }
}
Synchronized Trigger Pulses

The Trigger() object is similar to the ExternalSignalOn() display object. It does not change the screen and does not have a duration. Its only purpose is to send a trigger pulse to the first external signal line. The trigger pulse is very short and is strictly synchronous to the stimulus presentation.
Serial Line Communication
Devices connected to a PCs serial communication interface can talk to PXLab and vice versa. The major control tool for this is the DeviceControl object. This object can open and close the connection to a serial communication device and can send text across these lines. The PXLab ResponseManager is able to receive text from such a device in the same way as receiving responses from any other response device. The section on the Tektronix Lumacolor colorimeter in the color calibration chapter contains an example on how to use the DeviceControl object.
Software Requirements for External Signals

Using the serial communication port requires the installation of the Java Communications API for the respective machine. The download package contains instructions how to install the package for various operating systems and Java development kit versions.
For installation under Windows you have to do the following steps:

Download the zip-archive javacomm20-win32.zip (274.432 Bytes) for Windows.
Unpacking the archive gives you three files:

move win32com.dll into JRE\bin
move comm.jar into JRE\lib\ext
move javax.comm.properties into JRE\lib
where JRE stands for the installation directory of your Java runtime environment which might for example be '\Program Files\Java\jre1.5.0'. All other files of the archive are documentation.

Note that this software is only required if external response buttons, external synchronization signals or other serial devices will to be used. Applets cannot use it.
Gaming Input Devices
The major difference between keyboard, mouse and serial port devices on one side and gaming devices like gamepads or joysticks is that the latter group has to be polled for reading their current states while the first group of input devices is interrupt driven and automatically generates an event when their state changes. Polling devices are not supported by Sun's Java runtime environment. The PXLab implementation uses the open source library JXInput to access these devices. This library is based on the Java Native Interface (JNI) and Windows DirectInput methods. Thus it will only run on Windows.
DirectInput Device Activation
PXLab by default does not access game devices. If such a device should be used it has to be activated before it can be used and it should be deactivated after it will no longer being used. This is done by executing the object with the proper device name, id number, and command code. Here is an example:
Session() { DeviceControl() { DeviceType = de.pxlab.pxl.DeviceCodes.DI_DEVICE; DeviceID = 0; CommandCode = de.pxlab.pxl.DeviceControlCodes.OPEN_DEVICE; } } SessionEnd() { DeviceControl() { DeviceType = de.pxlab.pxl.DeviceCodes.DI_DEVICE; DeviceID = 0; CommandCode = de.pxlab.pxl.ResponseDeviceControlCodes.CLOSE_DEVICE; } }
The device is opened at the start of the session and it is closed after the session has been finished. This is all which has to be done in order to use DirectInput device buttons for response collection. Any timer which has the attribute RESPONSE_TIMER set will accept these button responses. In order to restrict responses to certain buttons only the parameter ResponseSet should contain the possible button response code values. Here is a list of constant declarations which name DirectInput button codes:
de.pxlab.pxl.ResponseCodes.DI_BUTTON1 de.pxlab.pxl.ResponseCodes.DI_BUTTON2 de.pxlab.pxl.ResponseCodes.DI_BUTTON3 de.pxlab.pxl.ResponseCodes.DI_BUTTON4 de.pxlab.pxl.ResponseCodes.DI_BUTTON5 de.pxlab.pxl.ResponseCodes.DI_BUTTON6 de.pxlab.pxl.ResponseCodes.DI_BUTTON7 de.pxlab.pxl.ResponseCodes.DI_BUTTON8

Thus the definition
ResponseSet = [de.pxlab.pxl.ResponseCodes.DI_BUTTON1, de.pxlab.pxl.ResponseCodes.DI_BUTTON3];
restricts possible responses to button 1 and 3 of the DirectInput device. There are two simple response time examples which use DirectInput buttons for response detection. These are contained in file srt_di.pxd and in file srt_di2.pxd in the demos directory of the PXLab documentation. These experiments will not run as applets since they need a special DirectInput interface DLL.
Using DirectInput Axes

Here is another example from the file color_adjust_di.pxd in the demos directory which uses two analog sticks on a gamepad to adjust a color. The gamepad has to be opened and closed in the same way as described in the preceding paragraph for any DirectInput device. The gamepad analog stick adjustment is activated by the timer property AXIS_TRACKING which has to be added to a display object's timer:
SimpleBar:Adjusted() { AdjustableColorPar = "Trial.SimpleBar:Adjusted.Color"; Timer = de.pxlab.pxl.TimerCodes.RESPONSE_TIMER | de.pxlab.pxl.TimerCodes.AXIS_TRACKING; HueStep = 0.01; ChromaStep = -0.01; LightnessStep = -0.01; AdjustableCoordinates = de.pxlab.pxl.ColorAdjustBitCodes.LIGHTNESS | de.pxlab.pxl.ColorAdjustBitCodes.HUE | de.pxlab.pxl.ColorAdjustBitCodes.CHROMA; AxesUsed = [0, 1, 3]; InitialRandomSteps = 1; Width = 100; Height = 200; LocationX = 50; Overlay = de.pxlab.pxl.OverlayCodes.TRANSPARENT; JustInTime = 1; }

This shows a SimpleBar object whose color can be adjusted. Adjustment is stopped by pressing any response key or button. Note that the color adjustment parameters are described on the page of the Display object ColorAdjustableHSB
Software Requirements
Using game devices requires the JXInput runtime package written by Joerg Plewe to be installed. You may download this package from http://www.hardcode.de/jxinput/. The 'Download' page contains installation instructions. The JXInput runtime archive contains the following 2 files:

jxinput.dll
should be moved into a valid DLL directory like /Windows/System32;
jxinput.jar
must be contained in the CLASSPATH or can be copied into the Java extensions directory. This is the subdirectory 'lib/ext' of your Java runtime environment installation directory.
That's all which is to be done.
SpaceMouse Devices
These are special devices for navigating in 3D space manufactured by 3DConnexion. They are connected to the USB port and contain a knob which allows translations along and rotations around 3 axes in space. The knob manipulations may be picked up by PXLab in order to adjust colors in 3-dimensional color space.
SpaceMouse Activation
The SpaceMouse driver installs the device as a DirectInput device. This means that it may be accessed in exactly the same way as any other DirectInput device. This is done by setting the parameter DeviceControl.DeviceType of the control object to the value DI_SPACE_MOUSE. Note that the parameter DeviceControl.AxisLimit also has to be adapted since the SpaceMouse does not restrict its axis values to the same range as analog sticks of gamepads do.
The SpaceMouse driver may also be accessed directly. This delivers smoother axis motion but requires a special DLL to be installed. Direct access to the SpaceMouse driver is initialized by setting the parameter DeviceControl.DeviceType of the control object DeviceControl to the value SPACE_MOUSE. The example from the file color_adjust_sm.pxd in the demos directory uses direct access to the SpaceMouse driver. It is almost identical to the analog sticks example for gamepads. The only differences are the DeviceControl.DeviceType value used and the parameter ColorAdjustableHSB.AxesUsed which tells PXLab which of the available axes should be used for color adjustment. This parameter has to be changed since the SpaceMouse has 6 axes while a gamepad has only 4 axes. The SpaceMouse buttons are used exactly as DirectInput buttons. Their numbers are defined in File ResponseCodes.
Software Requirements for a SpaceMouse
The SpaceMouse devices need a special native library to connect to the device's driver. Thus before using the SpaceMouse device with PXLab the driver which comes with the device has to be installed and should work properly. The PXLab driver interface is contained in a library named JNIsiapp.dll which is contained in the PXLab extensions archive. It should be moved into a valid DLL directory like /Windows/System32. The Java part of the SpaceMouse driver is contained in the PXLab archive and does not need special installation.
[This file was last updated on July 15, 2010, 12:07:01.]
[Home] [Content] [Previous Chapter] [Next Chapter]