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:

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

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:

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]