Instructions to Run and Test the AEELab Remote Launcher Software Package

This instruction set is intended to be a guide for users wishing to use the Remote Launcher to carry out experiments with AEELab software. You can navigate this page by using the table of contents below, and you can always return to the top of this page by clicking the link [top] that is located at the bottom of each instruction section.

What does the "Remote Launcher" do ?

When running experiments it is often a requirement to have the machines in a lab run a particular program (such as a web-browser or experiment simulator) at the same time as each other. This extends to the ability to remotely issue machines with commands so that the experimenter has full control over the running of an experiment session.

The Remote Launcher is based on a client-server model:

1. The Remote Launcher Server , which resides on a single computer accessible by the experimenter. This allows the experimenter to issue commands to one or more of the other computers in the lab network.

2. The Remote Launcher Client, which is a small Java program that resides on each computer in the lab network. This receives commands from the Remote Launcher Server and processes them on the local machine.

Programs are launched from the Remote Launcher Server by issuing single commands into a command window or by running a script file.

[top]


How to Setup a Lab Room

1) Ensure that Java Run Time Environment 1.5.0 or later has already been installed on each computer. If you unsure whether Java has already been installed, you can carry a web browser test available here

A copy of a functioning (though not neccessarily the most recent) copy of the java software can be downloaded from the experiments page from here

2) Choose a computer to be the Server. Copy the entire contents of the file "RemoteLauncherWorkingDirectory.zip" onto this computer, and unzip the file.  A directory called "RemoteLauncherServer" will be created.

Have a look inside the RemoteLauncherServer directory. It should contain: a directory called images, another directory called scripts, an executable file called RemoteLauncherServer.jar and a text file named RemoteLauncherConfiguration.txt -Without these 4 items, you will be unable to load the Control Panel.

The RemoteLauncherConfiguration.txt contains information about the layout of the computers in the lab network, according to their IP addresses ( an example is shown below).



Click to Enlarge Image


3) Download the remote launcher client, RemoteLaunchClient.jar onto each participant computer in the lab. For ease of download, you may find that this file has been zipped, in which case you will need to extract the contents of the file by right-clicking and selecting "extract here".  It can be downloaded to any directory you wish, but must be somewhere easily accessible (The desktop would be ideal). This is available from 
the software page . Run the program by double clicking on the icon, if the program does not open with Java 1.5 by default you will need to do it manually by right-clicking and selecting “Open with....Java ” . If Java is not one of the options listed, click on the "Choose Program" option on the drop-down menu which will allow you to browse your computer to select the Java program.


Click to Enlarge Image

When the Client has started, it will indicate that it has identified the network details of the client computer as shown below.


Click to Enlarge Image

[top]

How to use the Remote Launcher Control Panel

Open the “RemoteLauncherWorkingDirectory” directory, and run the executable file RemoteLauncherServer.jar . The Remote Launcher  program has two parts, The example room and The Experiment Launcher Control Panel which will open in separate windows:

The Example Room

The Example Room shows a layout of the computer network within the lab, and each client computer is colour-coded to show its status.



red

Indicates that the client computer is not responding

green

Indicates that the client computer is connected and ready to receive commands

purple

Indicates that the client computer is already running a process



Click to Enlarge Image


The Experiment Launcher Control Panel


The Experiment Launcher Control Panel allows the user to launch and end programs on any/all of the other computers in the labs. This can be done in two ways:

  1. Using Scripts

    You can load a script, which is a text file that contains a series of commands, saving the user the repetitive work of loading each single command manually.

    To load a script, right click on the panel under “Run Script File”, this will cause a drop-down menu to occure. Select Add script to list from the menu and browse for the script file you wish to run.

    Some useful script files are stored in the directory "C:\RemoteLauncherWorkingDirectory\scripts"

    To execute a script, again right-click on the “Run Script File” panel and this time select Execute this script from the drop-down menu. After this, you can check if you have successfully launched the desired program onto the client computer(s) by observing the coloured icons beside each computer.

  2. Entering Single Commands

    As an alternative to script files or in cases when you need to launch programs on only a few computers, it may be useful to manually insert a single command. This can be done by entering a command line into the panel under “Send Single Commands”. An explanation of the command line is shown below. Remember that you can always load previously used commands by clicking on the drop-down menu button (denoted by an arrow pointing downwards) on the right hand side of the “Send Single Commands” panel.


Click to Enlarge Image


You can use the Example Room panel to select the computer (or rows of computers) on which you wish to launch a program. Alternatively, if you already know the number of the computer in the network, you can also enter it into the command line as shown above.

How to see which processes are currently running

You can see which processes are running on a particular client computer by selecting that machine in the Example Room using the right mouse button. Select List running processes from the drop-down menu.

How to kill processes that are running

To kill a particular process, select the process in the “Recent Commands” panel by clicking with the left mouse button. Click on the Kill Selected button at the bottom of the Control Panel.

To kill all the processes running on a particular computer, you can right-click on the particular computer running the process in the Example Room and select Kill all running processes.

To kill all processes on all computers, select the Kill All button located at the bottom of the Control Panel.

[top]

About the "Copy File" Function

The "Copy File" function allows users to copy files from the Room controller or Server  computer to any of the Client computers.
 

  1.  Transfer the file you wish to copy to the rmfiles directory, which is located within the RemoteLauncherWorkingDirectory.
     

  2. Then, enter the following command into the Control Panel in the panel under “Send Single Commands” as shown below.



Click to Enlarge Image


Last Modified: 3rd March 2008

[top]