ESP Manual

1. Overview

ESP (Experience Sampling Program) is free software for Palm Pilots to gather data from people in their daily lives. ESP displays questions, receives responses, and measures reaction times. It is useful for surveys, questionnaires, and scientific research.

In a nutshell:

1. You (the experimenter) hand out Palm Pilots to a bunch of people (the participants).
2. The Palms ask questions to your participants, recording their responses and reaction times. The set of questions can be asked as many times as you want. Each time is called a trial.
3. You upload the data to your favorite PC for analysis.

ESP is provided with no support. However, there is an ESP mailing list where you can discuss the software with other researchers. See section For More Information.

The development of this software was supported by National Science Foundation grant BCS 0322352 to Lisa Feldman Barrett.

About ESP

ESP for the Palm Pilot has two modes of operation:

• Automatic mode, which prompts your participants to answer questions at various times of day. This can happen at evenly-spaced times of day (a.k.a., fixed sampling) or at random times (random sampling).
• Manual mode, which lets your participants answer questions whenever they want. (This is sometimes called event-contingent sampling.)

Let's look at some examples.

1.1 Manual Mode: What it Looks Like

Manual mode is for event-contingent sampling, which is a fancy way of saying the participant launches the trials. Initially the Palm displays the screen:

At any time, the participant may tap the screen to begin a trial. She is guided through a sequence of questions, each with a set of response buttons at the bottom of the screen. For example:

When each question is answered, the next appears, until the last question has been answered. The participant is once again presented with:

and the process may be repeated.

1.2 Automatic Mode: What it Looks Like

Automatic mode is for fixed or random sampling, which means that ESP launches the trials itself. The participant is prompted to answer questions at times determined by the experimenter. Initially the Palm sleeps and displays a neutral screen:

When the time arrives for a trial, the Palm beeps (for a predetermined time set by the experimenter) and displays:

The participant has a limited time to respond (determined by the experimenter). If there is no response, ESP ends the trial and returns to sleep.

If the participant taps anywhere on the screen, however, she is then guided through a sequence of questions, each with a set of response buttons at the bottom of the screen. For example:

The participant once again has limited time to answer each question (again, determined by the experimenter). If she fails to respond to a question within the allowed time, the trial ends and ESP goes back to sleep. Otherwise, she responds to each question in sequence until the last question has been answered and the trial ends.

After a number of trials (set by the experimenter), the experiment ends, and the participant is shown:

1.3 Terminology

Packages

ESP 4.0 includes a suite of software packages:

• ESP, a Palm application that interacts with your participants.
• ESP Desktop, a PC application for designing experiments, configuring ESP settings, and collecting data. It runs on Windows and Linux. (A version for Macintosh OS X was planned originally, but proved too difficult for end-users to install.)
• ESPPrefs, an older Palm application for changing ESP settings. Because working directly on the Palm is inconvenient, we recommend you use ESP Desktop instead.

The program ESPView, supplied with older versions of ESP, is no longer needed nor recommended. Use ESP Desktop instead.

Experiments

The largest unit in ESP is called an experiment. It consists of:

• Questions: The stimuli presented to the participants. In ESP, these live in the ordinary Memo Pad application on the Palm. ESP reads the Memo Pad, finds the questions and displays them, and the participants respond.
• ESP settings: The behavior of ESP, as set by the experimenter; for example, how many times per day ESP should run, and whether questions should be in fixed or random order. The settings are set by running the Palm program ESPPrefs or the desktop program ESP Desktop.
• Data: Your participants' responses and reaction times. These are stored in a custom database on the Palm, and may be transferred to a personal computer via ESP Desktop.

People

The person who sets up ESP is called the experimenter. The experimenter runs ESP Desktop and/or ESPPrefs and designs questions. When we say "you" in this document, we generally mean the experimenter.

The people who use ESP are called the participants.

2. Installation

To run ESP in its full glory, you will need:

• One or more Palm Pilots or equivalent, to run ESP and ESPPrefs
• One desktop computer (Windows or Linux), to run ESP Desktop

Be prepared to dedicate your Palms and your desktop computer to ESP. This means:

• Don't use your Palms for other purposes. ESP uses the Palm Memo Pad for storing questions. If you create any other memos (unrelated to ESP) on your Palm, ESP may delete them. Also, ESP optionally takes control of the Palm, preventing any other applications from running. This is important because ESP measures the reaction times of your participants, so you don't want them distracted by other software.
• Don't use your desktop computer for other Palm-related purposes. ESP Desktop takes over some parts of the Palm hotsync process on your computer. It might not coexist well with other hotsync-related programs. Specifically on the PC, it replaces some of the standard Palm hotsync functionality (it installs new "conduits" into Palm Desktop that may prevent regular hotsynching from working). On Linux machines, ESP Desktop might not run correctly if other hotsync software is installed.

ESP and ESPPrefs should run properly on most Palms and compatibles. You should be thoroughly familiar with Palm usage, including:

• Hotsyncing and transferring data between the computer and the Palm, especially when multiple Palm Pilots are involved.
• Performing a soft reset (simple reboot, preserving data) and hard reset (major reboot, deleting all data) of the Palm.
• Deleting a database from the Palm Pilot. (If you want to conserve RAM on the Palm or uninstall ESP.)
• Graffiti. Simple use is needed for ESPPrefs (configuring ESP) and for entering questions in the Memo Pad. However, you can avoid Graffiti altogether by using ESP Desktop to run your experiments.

Now let's see how to install ESP.

2.1 Installing on Windows

Prerequisites

ESP has been tested on Windows XP. It will probably work fine on most other versions of Windows. Please tell us about any combinations that do or don't work.

Before installing ESP on a Windows machine, you must install:

• Mozilla or Firefox, the web browsers from http://www.mozilla.org, version 1.0 or higher. (Other browsers are not supported: we rely on custom features of Mozilla/Firefox.)
• Palm Desktop, the standard hotsynching software supplied with your Palm, or downloaded from http://www.palm.com.

Make sure these programs are installed before proceeding.

Installing ESP

To install this software, you will need administrator privileges on your Windows machine. Then follow these directions:

1. Make sure you have installed the prerequisites listed above.
2. If you haven't already done so, download ESP from the ESP web site. For Windows, ESP is provided as an installer program, EspDesktopConduitInstaller.
3. Double-click on EspDesktopConduitInstaller and follow the instructions. Some important notes:
   • Accept all the default values, or else ESP may not run properly. (For instance, don't change the default installation folder, `C:/Program Files/esp4', where all the ESP system files are kept.)
   • The installer might say you have to run a hotsync after installation. You don't have to do this. Just exit the installer.

   You have finished installing ESP. Now you must configure the Mozilla or Firefox browser to run ESP Desktop. This involves editing a Mozilla/Firefox system file to add one line.

4. Locate the system directory containing Mozilla or Firefox's system files. On Windows systems it is often `C:/Program Files/Mozilla' or `C:/Program Files/Mozilla Firefox'.
5. Locate the `chrome' subfolder and enter it.
6. Locate the file `installed-chrome.txt' and edit it with a plain text editor such as WordPad. (Don't use a word processor like Word or Wordperfect: you might destroy the file. Notepad also isn't great: it deals poorly with linebreaks.) If the file does not exist (which is the case in Firefox 1.5 and higher), create your own in the `chrome' subfolder.
7. Copy the line below and paste it into the file `installed-chrome.txt' at the very end, on a line by itself:

   content,install,url,file:///c:/Program%20Files/esp4/

   and press ENTER afterward.

   NOTE: Mozilla and Firefox each have their own `installed-chrome.txt' file. To use both browsers with ESP Desktop, you must paste the above line into both `installed-chrome.txt' files.

8. You're ready to run ESP Desktop. Run Mozilla and hit the URL:

   chrome://espdesktop/content/desktop.xul

   The first time you run ESP Desktop, you might see a warning about unsafe operation. See section Special note about permissions.

9. Test ESP Desktop by running its built-in self-test. Under the Help menu, select Test ESP Desktop and follow the instructions. See section Testing the Installation.

If the installation failed, or if ESP Desktop will not run, See section Troubleshooting. For a list of known bugs, See section Bugs.

Uninstalling ESP

1. In the Windows Control Panel, run Add Or Remove Programs, and uninstall every program whose name contains "ESP Desktop."
2. Delete the folder `C:/Program Files/esp4'.
3. (Optional.) Delete the ESP Preferences held within your web browser. Shut down all copies of Mozilla and/or Firefox. Then locate your browser preferences file `prefs.js', which is usually found somewhere in:
   • `C:/Documents and Settings/your_name/Application Data' on Windows
   • `~/.mozilla' on Linux

   Edit `prefs.js' using a plain text editor like Emacs or WordPad, not a word processor like Word or WordPerfect which will destroy the file. (Notepad isn't great either: it doesn't deal well with linebreaks.) Delete all lines that set a preference beginning with "esp.", such as:

   user_pref(esp.download.deletedata, true); user_pref(esp.latestexperiment, ...); user_pref(esp.questioneditor, ...); user_pref(esp.upload.esp, true); user_pref(esp.upload.espprefs, true); user_pref(esp.upload.initialize, false); user_pref(esp.upload.preferences, true); user_pref(esp.upload.preserveIDs, false); user_pref(esp.upload.questions, true);

   Then delete the lines that look like:

   user_pref(capability.principal.codebase.p0.granted, UniversalXPConnect); user_pref(capability.principal.codebase.p0.id, file://);

4. If you want to use this PC for other Palm hotsynching, reinstall your Palm Desktop software.
5. On your Palm(s), delete the applications "ESP" and "ESPPrefs."

2.2 Installing on Linux

ESP was developed and tested on SUSE Linux Professional 9.1. It will probably work fine on most other Linux distributions. Please tell us about any combinations that do or don't work.

Prerequisites

Before installing ESP on a Linux machine, you must install some other packages. Most Linux distributions include them, though they might not be installed by default, so check your computer and your installation media.

• Mozilla or Firefox, the web browsers from http://www.mozilla.org, version 1.0 or higher. (Other browsers are not supported: we rely on custom features of Mozilla/Firefox.)
• pilot-link from http://www.pilot-link.org/, a conduit library and toolset, version 0.11.8 or higher
• libxml2 from http://xmlsoft.org/, version 2.6.7 or higher
• A text editor such as emacs or vi

Make sure these programs are installed before proceeding.

Also, if you have other hotsync software running, such as KDE's kpilot, uninstall it. Otherwise kpilot will monopolize the USB port where your ESP Palm is connected, preventing ESP Desktop from finding your Palm. (Many KDE installations have kpilot enabled by default.)

Installing ESP

1. Make sure you have installed the prerequisites listed above.
2. If you haven't already done so, download ESP from the ESP web site. For Linux, ESP is provided in a compressed tar file, `esp4-linux.tar.gz'.
3. Extract the contents of `esp4-linux.tar.gz' into `/usr/local', e.g.,

   cd /usr/local tar xvzf <path>/esp4-linux.tar.gz

   When tar is finished, you'll see it has created a subdirectory, `/usr/local/esp4'. This is where all the ESP system files are kept.)

   You have finished installing ESP. Now you must configure the Mozilla or Firefox browser to run ESP Desktop. This involves editing a Mozilla/Firefox system file to add one line.

4. Locate the system directory containing Mozilla or Firefox's system files. On Linux systems it might be `/usr/local/mozilla', `/opt/mozilla/lib', `/usr/share/mozilla', etc.
5. Locate the `chrome' subdirectory and enter it.
6. Locate the file `installed-chrome.txt' and edit it with a text editor such as emacs or vi. (Don't use a word processor: you'll destroy the file.) If the file does not exist (which is the case in Firefox 1.5 and higher), create your own in the `chrome' subdirectory.
7. Copy the line below and paste it into the file `installed-chrome.txt' at the very end, on a line by itself:

   content,install,url,file:///usr/local/esp4/

   and press ENTER afterward.

   NOTE: Mozilla and Firefox each have their own `installed-chrome.txt' file. To use both browsers with ESP Desktop, you must paste the above line into both `installed-chrome.txt' files.

8. You're ready to run ESP Desktop. Run Mozilla or Firefox (as appropriate) and hit the URL:

   chrome://espdesktop/content/desktop.xul

   The first time you run ESP Desktop, you might see a warning about unsafe operation. See section Special note about permissions.

9. Test ESP Desktop by running its built-in self-test. Under the Help menu, select Test ESP Desktop and follow the instructions. See section Testing the Installation.

If the installation failed, or if ESP Desktop will not run, See section Troubleshooting. For a list of known bugs, See section Bugs.

Uninstalling ESP

1. Delete the directory `/usr/local/esp4' and its contents.
2. (Optional.) Delete the ESP Preferences held within your web browser. Shut down all copies of Mozilla and/or Firefox. Then locate your browser preferences file `prefs.js', which is usually found somewhere in:
   • `C:/Documents and Settings/your_name/Application Data' on Windows
   • `~/.mozilla' on Linux

   Edit `prefs.js' using a plain text editor like Emacs or WordPad, not a word processor like Word or WordPerfect which will destroy the file. (Notepad isn't great either: it doesn't deal well with linebreaks.) Delete all lines that set a preference beginning with "esp.", such as:

   user_pref(esp.download.deletedata, true); user_pref(esp.latestexperiment, ...); user_pref(esp.questioneditor, ...); user_pref(esp.upload.esp, true); user_pref(esp.upload.espprefs, true); user_pref(esp.upload.initialize, false); user_pref(esp.upload.preferences, true); user_pref(esp.upload.preserveIDs, false); user_pref(esp.upload.questions, true);

   Then delete the lines that look like:

   user_pref(capability.principal.codebase.p0.granted, UniversalXPConnect); user_pref(capability.principal.codebase.p0.id, file://);

3. If you uninstalled your previous hotsync software such as kpilot, reinstall it.
4. On your Palm(s), delete the applications "ESP" and "ESPPrefs."

2.3 Testing the Installation

After installing ESP on your desktop computer, you can check if it's properly installed. Run ESP Desktop and in the Help menu, select Test ESP Desktop. Follow the instructions and you'll get a report of success or failure at the end. If there's a failure, See section Troubleshooting.

If you cannot run ESP Desktop at all, then you probably forgot (or messed up) the step about editing the `installed-chrome.txt' file.

2.4 Using ESP without ESP Desktop

If you are a masochist, you can run experiments without ESP Desktop. Older versions of ESP worked this way. In this case:

• You'll need to install ESP and ESPPrefs onto your Palms manually, using Palm Desktop (Windows) or Linux software like kpilot or pilot-link.
• To edit ESP settings, you'll use ESPPrefs on each Palm. Alternatively, configure ESP using ESPPrefs on one Palm, copy the preferences to your PC, and then copy it back to your fleet of Palms one at a time.
• To edit ESP questions, you'll work directly in the Palm Memo Pad or Palm Desktop.

In short: take the time to use ESP Desktop. It is much more convenient.

2.5 Upgrading ESP

ESP 4.0 is more powerful than our old ESP 2 and its offshoot iESP (see section iESP) and includes important new features like ESP Desktop (see section ESP Desktop). However, ESP 4.0 is not completely compatible with the older versions. Your questions (the most complex part of your ESP experiment) are compatible, but other parts are not. The following table explains what is compatible and what to do about it.

2.6 Inventory

Here's a list of what gets installed with ESP.

Just about everything is placed into a single directory (folder):

Within this directory you'll find:

• `esp.prc', the ESP program for the Palm
• `espprefs.prc', the ESPPrefs program for the Palm
• `espprefs-conduit-unix' and/or `espprefs-conduit-win.exe', conduit programs used by ESP Desktop
• `espprefs-default.xml', the default settings file for ESP Desktop when you create a new experment
• `questions-default.txt', the default questions file for ESP Desktop when you create a new experment
• `experiment-default.txt', containing the default experiment name for ESP Desktop when you create a new experment
• Many files with names ending in `.xul' or `.js' or `.rdf', which are used by ESP Desktop

On Windows, several DLL files are also placed into `C:\Program Files\Palm':

• `EspDesktopConduit.dll', which controls hotsynching with an ESP Palm
• `DummyConduit.dll', which prevents a standard Palm hotsync operation with the Memo Pad

3. Creating Questions

The experimenter creates the questions that ESP asks during each trial. The same set of questions is used in every trial. However:

• You may randomize the order of the questions.
• You may define question sets and sample from them, using either ordered or random sampling.

3.1 Overview of Questions

ESP's questions are stored in the Palm's Memo Pad, one question per memo pad entry. You may create the questions in three ways:

• (Recommended) On another computer, using the ESP Desktop software package. See section ESP Desktop. In this case, you enter all your experiment's questions, one per line, into a text editor. ESP Desktop uploads them to the Palm, storing them in the Palm Memo Pad, where ESP will find and use them.
• On another computer, downloading them into the Memo Pad by hotsyncing, using the Palm Desktop.
• Within the Memo Pad, using the stylus and Graffiti.

You may create as many questions as you like, limited only by available memory.

Each question must be stored in a separate Memo Pad entry. Do not make the mistake of typing all your questions into a single memo on multiple lines. This won't work. You need to create a separate memo for each question.

Each question occupies one memo in the Memo Pad.

3.2 Ordinary Questions

Ordinary questions are the same type supported by the original ESP for the Palm. An ordinary question consists of five parts:

1. An integer ID number, either positive or negative, that uniquely identifies the question. Do not use zero.
2. The symbol "|" (vertical bar) which indicates the end of the ID number.
3. The question itself. It may contain any text except:
   • A vertical bar, "|", which is treated as a separator, as described later.
   • A percent sign followed by a letter, for example "%X", which is interpreted specially.
4. The symbol "|" (vertical bar) which indicates the end of the question text.
5. One or more labels for the response buttons at the bottom of the screen, left to right. Labels are separated by (you guessed it) vertical bars.

For example, the question "How are you feeling today?" with a unique ID of 37 and response buttons labeled "good", "bad", and "lousy" would be:

37|How are you feeling today?|good|bad|lousy

Notice that there is no additional space (i.e., space characters, tabs) surrounding the vertical bars, and there are no vertical bars at the beginning or end. Think of the vertical bars as separators: they go between items. Later versions of ESP are a bit more lenient about extra space, but for maximum compatibility, avoid it.

ESP will display this question as follows:

You may define as many button labels as will fit on one row of the screen. If you define too many, the screen will simply not look right (so be sure to examine each question's screen before running your experiment).

3.2.1 Response Types

By default, the responses for a question are presented as buttons in a horizontal row. You can change this with the %TYPE keyword.

37|How are you feeling today? %TYPE popup|good|bad|lousy

Supported %TYPE values are:

• buttons: One button per response. The default.
• popup: A popup list containing all responses.
• list: A selectable list displaying all responses.
• checkboxes: Checkboxes
• slider: A slider going from a minimum value to a maximum value
• text: Free-form text entry

3.2.2 About Question IDs

You must assign each question a unique, integer-valued ID between 1 and 32768, or between -1 and -32768. (Zero is not permitted.) These IDs serve two important purposes.

1. They are stored with the participant's responses. Therefore, in your data, you can identify which question is associated with each response. In this example question:

   37|How are you feeling today?|good|bad|lousy

   a "37" would be stored with the participant's response.

2. They may determine the order that the questions are asked in a trial. If you do not randomize the questions, they are asked in increasing numeric order by ID.

Your question IDs must be unique. If not, you will not be able to identify the question associated with each response.

3.2.3 Negative Question IDs

You may choose negative IDs for your questions (-1, -2, etc.). If you choose to randomize the order of the questions, negative IDs have a special purpose. Questions with negative IDs never get randomized: they are always asked in ascending order. Therefore, they always come before the randomized questions.

For example, suppose you specify the following questions:

1|Who?|a|b|c
2|What?|a|b|c
37|Why?|a|b|c
16|Where?|a|b|c
5|When?|a|b|c
-4|Are you ready to begin?|yes|no

If you do not randomize the questions, they will be asked in strictly increasing order: -4, 1, 2, 5, 16, 37. However, if you randomize the questions, the one with the negative ID ("Are you ready to begin?") will always be asked first. This allows your experiment to ask fixed, preliminary questions before beginning randomized questions.

3.2.4 What About Other Memo Pad Entries?

ESP notices only those Memo Pad entries that contain a "|" (vertical bar) in the text. Anything else in the Memo Pad is ignored by ESP. (So you could make notes to yourself if desired.)

3.3 Branching Questions with %NEXT

During a trial, by default, ESP presents its questions strictly in order by question ID. Sometimes you'll want to ask a question based on the answer to a previous question, e.g., "If the participant responds Yes, go to question 15, otherwise go question 71." ESP supports control of this kind using branching questions. (Branching was added by iESP.)

To create a branching question, add the keyword %NEXT to any response, followed by a question ID. For example, the question:

10|How are you feeling?|Good %NEXT 20|Bad %NEXT 30|Hungry %NEXT 40

branches to question 20, 30, or 40, if the participant responds Good, Bad, or Hungry, respectively. Here's a more fleshed-out example:

10|How are you feeling?|Good %NEXT 20|Bad %NEXT 30|Hungry %NEXT 40
20|I'm glad to hear that|OK %NEXT 50
30|Sorry to hear that|OK %NEXT 50
40|Would you like a doughnut?|Yes|No
50|Goodbye|OK

For example, if the participant sees question 10 and responds Bad, the next question displayed is 30, "Sorry to hear that." The participant responds OK, which branches to question 50, displaying "Goodbye".

Alternatively, if the participant sees question 10 and responds Hungry, the next question displayed is 40, "Would you like a doughnut?" Question 40 does not have any %NEXT keywords, so no matter how the participant responds, the next question will be the one with the next-higher ID, 50, "Goodbye."

You can also add %NEXT to the body of a question:

10|How are you feeling? %NEXT 200|Good|Bad|Hungry

which causes control to pass to question 200 after question 10, unconditionally.

%NEXT cannot refer to a question set ID, only a question ID.

This is illegal:
%QSET 1|100|Is this illegal?|yes|no %NEXT 101
%QSET 1|101|You cannot jump into a question set!|OK

3.4 Probabilistic Questions with %PROB and %SNEXT

By default, ESP asks all questions (unless you branch around them; see section Branching Questions with %NEXT). You can change this by assigning a probability to a question. (Probabilities were added by iESP.)

You assign a probability to a question with the %PROB keyword, like this:

10|How are you feeling? %PROB 50|Good|Bad|Hungry

The above question has a 50% likelihood of being asked. If it is not asked, it is skipped. When a question is skipped, control will pass to the "next" question in the experiment. This is ordinarily the question with the next higher ID.

10|How are you feeling? %PROB 50|Good|Bad|Hungry
20|What's your favorite fruit?|Apple|Banana|Cherry

In the above example, whether question 10 is asked or not, control passes to question 20. From our discussion of branching (see section Branching Questions with %NEXT), you know you can control the next question with the %NEXT keyword. But this applies only if the question is asked. What if it is skipped? You control this possibility with the %SNEXT keyword, which means "Skipped Next". For example, this question has a 75% probability of being asked:

10|How are you feeling? %PROB 75 %NEXT 30 %SNEXT 40|Good|Bad|Hungry

If asked, ESP will continue to question 30. However, if the question is skipped, the next question will be 40.

3.5 Question Sets with %QSET

ESP 4.0 has a new feature called question sets so you can do sampling of questions in a trial. Sampling may be ordered or random.

3.5.1 Defining a Question Set

A question set is simply a set of ESP questions, defined in the Memo Pad as usual, but each question is preceded by:

1. The string %QSET
2. Whitespace
3. A vertical bar

For example, if you have the following three questions:

10|This is the first question|OK
11|This is the second question|OK|Thanks
12|This is the third question|OK|Thanks|Goodbye

you turn them into a question set (say, with ID 5) like this:

%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye

These lines merely define a question set, but they do not use the questions in the experiment. They will not appear to any participants until you sample from the question set.

3.5.2 Sampling from Question Sets with %CHOOSE and %RANDOM

There are two ways to sample questions from a question set: ordered and random. Ordered sampling will use the questions in numeric order by question ID. Random sampling will choose random questions from the set.

Notice that the question set itself does not specify ordered or random sampling. It's just a set. The choice of ordered vs. random is made when you refer to the set, using a special question called a sampler. A sampler is a question that means "sample one question from a given set." Here is one example of a sampler that chooses a question from set 25:

100|%CHOOSE 25

Note that like other questions, this one begins with a question ID (100), but its question part is a sampler: the special keyword %CHOOSE, followed by the ID of the question set you're sampling.

All sampling is without replacement for a given trial. In other words, if question 16 is sampled during a trial, it will not be sampled again during that trial. If you have ten questions in a question set, and you sample it ten times, you'll get each question exactly once. If you sample from that set an eleventh time, that's an error in your experiment.

3.5.2.1 A limitation of %QSET

If you have a question set containing only N questions, your experiment may not sample from that question set more than N times. That's to be expected, since we sample without replacement, but there is also an associated bug: your experiment may not contain more than N questions that sample from that set. If you do, ESP may display the error "No questions in Question Set" and crash, even if the logic of your experiment would prevent sampling more than N times from your experiment.

For example, the following experiment will obviously cause trouble because it's sampling too many times:

%QSET 1|100|Sampled question|OK
1|%CHOOSE 1
2|%CHOOSE 1

There is only one question to sample, but you're sampling twice. That's clearly bad; but the next example is less obvious:

%QSET 1|10|Sampled question|OK %NEXT 999
50|%CHOOSE 1
51|%CHOOSE 1
999|Goodbye|OK

This experiment "should" work, but it doesn't. Although we sample twice from a question set with only one question, the second %CHOOSE should never run. That's because the first %CHOOSE will branch to question 999 and end the trial. However, because of the above-mentioned limitation, the experiment will fail.

We hope to eliminate this limitation in the future. In the meantime, if your experiment must include more %CHOOSE or %RANDOM statements than the size of your question set, there is a workaround. Define several identical question sets (with different IDs) and sample from them as needed.

3.5.2.2 Ordered Sampling from Question Sets with %CHOOSE

Ordered sampling is done with the %CHOOSE sampler keyword. Suppose you have a question set:

%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye

The statement:

%CHOOSE 5

means sample once from question set 5. Each time you apply %CHOOSE to a question set, the next question (in numeric order by ID) is retrieved and used.

This sampler itself is a question in your experiment, with its own ID number, say, 200:

200|%CHOOSE 5

Here is a complete experiment with the question set and several %CHOOSE statements:

%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye
200|%CHOOSE 5
201|%CHOOSE 5

This experiment will produce the following sequence of questions:

This is the first question
This is the second question

Here's another example:

%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye
200|%CHOOSE 5
201|How are you feeling?|Good|Bad|Hungry
202|%CHOOSE 5

which asks:

This is the first question
How are you feeling?
This is the second question

3.5.2.3 Random Sampling from Question Sets with %RANDOM

Random sampling is done with the %RANDOM sampler keyword. Each time you apply %RANDOM to a question set, a random question is selected and used from the question set. In the following experiment, two questions are selected at random from question set 5:

%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye
200|%RANDOM 5
201|%RANDOM 5

So the output might be any of the following outcomes:

This is the first question
This is the second question

This is the second question
This is the first question

This is the first question
This is the third question

This is the third question
This is the first question

This is the second question
This is the third question

This is the third question
This is the second question

Likewise, this example:

%QSET 5|10|This is the first question|OK
%QSET 5|11|This is the second question|OK|Thanks
%QSET 5|12|This is the third question|OK|Thanks|Goodbye
200|%RANDOM 5
201|How are you feeling?|Good|Bad|Hungry
202|%RANDOM{} 5

samples one random question, then displays "How are you feeling?", then samples another random question. Here's one possible result:

This is the third question
How are you feeling?
This is the first question

Remember, sampling is without replacement: no question will be repeated in a trial.

By default, random sampling always assigns every question in the set equal weight. That is, any question in the set is equally probable to be selected. You can change this with the %FREQ keyword.

3.5.2.4 Random Sampling with Weights from Question Sets, with %FREQ

The %FREQ keyword assigns positive integer weights to questions in a question set, representing the likelihood of being sampled. (Negative and zero weights are illegal.) For example, the following experiment that displays one question. That question is 25% likely to be the first, 60% likely to be the second, and 15% likely to be the third.

%QSET 5|10|This is the first question %FREQ 25|OK
%QSET 5|11|This is the second question %FREQ 60|OK|Thanks
%QSET 5|12|This is the third question %FREQ 15|OK|Thanks|Goodbye
100|%RANDOM 5

Weights need not sum to 100. The following example is equivalent to the preceding one.

%QSET 5|10|This is the first question %FREQ 5|OK
%QSET 5|11|This is the second question %FREQ 12|OK|Thanks
%QSET 5|12|This is the third question %FREQ 3|OK|Thanks|Goodbye
100|%RANDOM 5

To determine the probability of a question's being sampled, divide its %FREQ value by the sum of all %FREQ values in the question set. In the above case, the sum is 5 + 12 + 3 = 20, so the first question has likelihood 5/20 = 25%.

Some facts about %FREQ:

• Weights must be positive integers.
• %FREQ is used only for random sampling in question sets. It is ignored during ordered sampling, and when used outside of a question set.
• If you use %FREQ in a question set, you must assign %FREQ values to all questions in the set. You cannot mix weighted and unweighted questions in a single question set. If you mix them, your experiment has an error.

3.5.2.5 Sampling with Question Probabilities from Question Sets

You can use %PROB, %NEXT, and %SNEXT with question sets for both ordered and random sampling. But what happens in a case like this?

1|%CHOOSE 100 %NEXT 2
2|Hello|OK
3|Goodbye|OK
%QSET 100|4|My question %NEXT 3|OK

Here we have a sampler (%CHOOSE) with a %NEXT value, selecting a question ("My question") that also has a %NEXT value. Which %NEXT will win? The rule is this: the %NEXT value in the sampled question overrides %NEXT value in the sampler. So the above example will produce:

My question
Goodbye

In more detail:

• If the sampler has a %NEXT and the question does not, the sampler's is used.
• If the question has a %NEXT and the sampler does not, the question's is used.
• If both the sampler and the question have a %NEXT, the question's takes precedence.

The same rule applies for %SNEXT: if both the question and the sampler have it, the question's %SNEXT takes precedence.

3.5.2.6 Combining %FREQ and %PROB

%FREQ is not the same as %PROB, which is the probability that a question is asked at all (versus being skipped). You can use %FREQ and %PROB together just fine. If you use both in a single question:

• %FREQ is the probability the question will be selected from the set.
• %PROB is the probability that, once selected, the question will be displayed (versus skipped).

Consider this example:

%QSET 1|10|My question %PROB 44 %FREQ 25|OK
%QSET 1|11|Second question %FREQ 75|OK
888|%CHOOSE 1 %PROB 15

This means:

• Question 888 is 15% likely to get asked at all. This is the probability of DOING THE SAMPLING.
• If it is, then question 10 is 25% likely to be selected from the set, and question 11 is 75% likely.
• If question 10 is selected, then it's 44% likely to be displayed. If question 11 is selected, it will be displayed.

Thus, the probability of question 10 being displayed is (15*25*44)% and question 11's is (15 * 75)%.

3.5.3 Important Facts about Question Sets

• Question IDs and question set IDs are independent. Question 123 and question set 123 are unrelated and you can have both in the same experiment.
• All question IDs in an experiment must be unique. This includes question IDs inside question sets.
• Question sets cannot refer to other question sets, i.e., you cannot place a %RANDOM or %CHOOSE value inside a question set. This means you cannot create a hierarchy of question sets, one cascading into the next. Again, question sets are just boxes of plain questions.

  %QSET 1|100|%CHOOSE 2 This is illegal!

3.6 Custom Messages with %MSG

The special marker %MSG lets you change several text messages that ESP displays.

3.6.1 STARTTRIAL

When ESP begins a trial, it displays the message "Tap the screen to begin." You can change this message with the entry %MSG STARTTRIAL in the Memo Pad:

%MSG STARTTRIAL|OK, ready, let's go!

You should have at most one STARTTRIAL entry per experiment.

3.6.2 ENDTRIAL

When ESP ends a trial, it displays the message "Questionnaire completed. Thank you." You can change this message with the entry %MSG ENDTRIAL in the Memo Pad:

%MSG ENDTRIAL|All done now.

You should have at most one ENDTRIAL entry per experiment.

3.6.3 SLEEPING and WAITMSG

When ESP sleeps between trials, it displays the message "ESP is sleeping..." in the titlebar at the top of the screen. You can change this message with the entry %MSG SLEEPING in the Memo Pad:

%MSG SLEEPING|Snore snore...

By default, the rest of the display is blank. You can add a more detailed message below the titlebar using %MSG WAITMSG in the Memo Pad:

%MSG WAITMSG|The next trial will begin shortly. Please be patient.

You should have at most one SLEEPING entry per experiment, and at most one WAITMSG entry per experiment.

4. ESP Desktop

ESP Desktop is a major new feature of ESP 4.0! You can able to configure full experiments and manage all your participant data from your favorite personal computer. It runs under Windows and Linux.

ESP Desktop requires the Mozilla or Firefox web browser. Other browsers are not supported. (This is not just a whim: ESP Desktop is implemented in a programming language called XUL that works only in Mozilla-based browsers.)

4.1 Getting Started with ESP Desktop

Assuming you have installed ESP Desktop already on your local machine (see section Installation) here's how to run it:

1. Run Mozilla
2. Hit the URL chrome://espdesktop/content/desktop.xul

Now you're ready to work with an experiment.

Note: If you were previously working on an experiment, but you quit ESP
Desktop without closing the experiment, then ESP Desktop will offer you
the choice to reload that experiment.

To begin, you can either create a new experiment or work with an existing experiment.

4.1.1 Creating a new experiment

When you first run ESP Desktop, you'll be presented with this:

To create a new experiment, use the File menu and select New Experiment.

This action will display a dialog to pick a directory (folder) to contain your new experiment.

This is a standard Mozilla file dialog. Choose an existing directory, or create a new one, and click Select. (Note: the Mozilla file dialog is a little finicky about picking directories. You cannot select a directory by double-clicking it - if you do, you'll go into the directory. Instead, single-click the directory name and then Select.)

An empty experiment will be created in the directory you chose. ESP Desktop will display a default experiment name (usually "My New Experiment"), the file path to the experiment, and a new, extended menu bar:

and now you're ready to work on your experiment.

The first time you run ESP Desktop, you might see a warning about unsafe operation. See section Special note about permissions.

4.1.2 Opening an existing experiment

To open an existing experiment, choose Open Experiment from the File menu. This action will display a dialog to select the directory (folder) that contains your desired experiment.

The experiment will be loaded from the directory you chose. ESP Desktop will display the experiment name, the file path to the experiment, and a new, extended menu bar:

and now you're ready to work on your experiment.

The first time you run ESP Desktop, you might see a warning about unsafe operation. See section Special note about permissions.

4.1.3 Copying an experiment

To copy an experiment, any of these methods will work:

• Within ESP Desktop, open your original experiment, choose Save As, and save to a new location. This saves all experiment questions and settings, but not the participant data (but it's unlikely you want to copy that).
• Using your computer, copy the directory containing your original experiment. Optionally, in the copy, delete the contents of the `subject-data' directory, which contains the participant data for the experiment. (Unless you want to copy the participant data too.)

4.1.4 Special note about permissions

The first time you run ESP Desktop, you may see a warning dialog about unsafe operation:

This is because ESP Desktop needs to read and write files, and run other programs, on your computer. Web browsers don't normally do that. To use ESP Desktop, grant these permissions by checking the checkbox "Remember this decision" and clicking Allow. This eliminates the dialogs. If you don't do this, you'll see this ESP Desktop error:

and ESP Desktop will not operate.

Choosing "Allow" places the following line into your `prefs.js' file in your Mozilla folder.

user_pref("capability.principal.codebase.p0.granted", "UniversalPreferencesWrite UniversalXPConnect UniversalPreferencesRead");

which you can delete later if desired. (Shut down Mozilla before editing `prefs.js' or your changes won't take effect.)

A future revision of ESP Desktop will eliminate this issue.

4.2 Changing Settings

4.2.1 How ESP Desktop Operates

ESP Desktop is for editing the settings and questions for your experiment. Once you've modified them to your liking, you transfer them to one or more connected Palm Pilots.

You edit settings right in ESP Desktop's main window. Questions, however, are edited in a text editor (such as Notepad or Emacs) that ESP Desktop will launch for you.

When it's time to transmit your experiment between ESP Desktop and the Palm, here's what happens:

1. From ESP Desktop's menu, you choose a command such as "send to Palm" or "load from Palm"; there are a variety of such commands.
2. A dialog will appear, telling you to run a hotsync. The dialog looks different - and asks you to different things - depending on your operating system. If you're running Windows, the dialog looks like this:

   

   and is followed by:

   

   On the other hand, if you're using Linux, you get only a single dialog like this:

   

   In either case, do what the dialog says to do.

3. The desired information will be transmitted between your PC and your Palm.

So in general, ESP will prompt you to start a hotsync. Once it's done, ESP Desktop will be ready for your next action.

If things go wrong, you will see an error dialog. For example, if you fail to connect a Palm, you'll see

On Windows, if you click "OK" before a hotsync is complete, you might see:

4.2.2 General Settings for ESP Desktop

The Subject ID uniquely identifies the person carrying this Palm Pilot. If your experiment uses multiple Palm Pilots, make sure each of them is set with a different Subject ID. Valid values are 1 to 32767 inclusive. Do not use zero. Larger values may cause ESP to crash.

This value is used in two ways:

• It is saved with each of the participant's responses, so you can always identify which participant is associated with each response.
• It becomes part of the database name containing the participant's responses. [xxx] If the Subject ID is 123, the results database will be named ESPR-123 (on the Palm) or ESPR-123.pdb (on the Windows machine after uploading).

The Automation setting selects between manual mode (see section Manual Mode: What it Looks Like) and automatic mode (see section Automatic Mode: What it Looks Like) for your experiment. In manual mode, the participant initiates trials herself. In automatic mode, the Palm initiates them.

The Take Over Machine setting determines whether the participant can run other Palm programs while ESP is running. The recommended setting is to check this box. Otherwise, the participant will be able to halt ESP at any time and/or waste the batteries by running undesired software.

When we say "Take Over," we really mean it. None of the buttons will operate. This is good for keeping participants from fiddling with the Palm, but inconvenient when the experimenter needs to use the Palm, say, for transferring data to the PC using ESP Desktop. So, if you use Take Over Machine, you'll need to get the Palm out of this mode before you can hotsync your results data to your PC with ESP Desktop (see section Collect Data).

4.2.3 Automation Settings for ESP Desktop

These settings are available only if Automation is selected in General Settings. If you are running an experiment in manual mode (see section Manual Mode: What it Looks Like), these settings will not be visible when editing and will not take effect in the experiment.

The Begin Day and End Day settings specify the allowable times of day that trials may be run. Outside of this time range, no trials will occur. Times are on a 24-hour clock, from 0:00 (midnight) to 23:59 (11:59 pm). If the Begin and End times are equal, trials can run at all times. Setting the End time earlier than the Begin time is an error.

Total Trials and Trials Per Day control the frequency of trials. For example, if you request 100 trials in total and 20 trials per day, your experiment will last for five days (total trials divided by trials per day, or 100/20). If you request 101 trials and 20 per day, your experiment will last for six days, with the last day having only one trial (the hundred-and-first).

The Randomize Trials setting determines whether trials occur at predetermined or random times. If you've requested N trials per day, the period between the Begin and End times is split into N intervals of equal length. (For example, if the period is between 12:00 and 22:00 and you request 20 trials per day, this creates 20 intervals of 30 minutes each.) If Randomize Trials is unchecked, trials will occur at the beginnings of these N intervals. If checked, trials will occur at a random time within each interval. In our "20 trials per day" example, the first trial would occur at a random time between noon and 12:30, the next between 12:30-13:00, etc. So "random" means "random within each interval."

Max Seconds To Respond sets a time limit, in seconds, for the participant to respond to a trial. The Palm will beep continuously during this time. If there is no response within this time period, the trial ends. The related setting Seconds Between Beeps determines how frequently the Palm will beep while waiting for the participant to respond. (NOTE: Values of less than 2 seconds are unreliable.) So, if you request 30 seconds of beeping with 3 seconds per beep, the Palm will beep 10-11 times.

Run At Invocation is an experimenter's aid. When you first run ESP by tapping its icon, should a trial begin immediately (checked box) or should a trial simply be scheduled to run later (unchecked box)? Depending on your needs, you might want the participant to answer questions immediately (say, as practice in front of the experimenter) or not.

4.2.4 Question Settings for ESP Desktop

Max Seconds To Respond sets a time limit for a participant to respond to a question. If no response occurs within this limit, the trial ends. If you want no time limit on answering a question, use a large value like 99999999. (Or if appropriate, run the experiment in Manual mode instead of Automatic mode.)

Important: This timer begins running when a question appears, and it keeps running until the question is fully answered. If the participant slides a slider, writes Graffiti, taps checkboxes, etc., this does not prevent a timeout! In other words, the time limit can be reached while the participant is in the middle of writing Graffiti, moving a slider, etc. Be aware of this and plan appropriately.

Non-Answer Value sets the value to be stored if the participant does not answer a question.

Default Widget determines whether responses are presented as buttons, a dropdown menu, etc., by default. (If you don't want the default, you can specify the widget directly for each question with the %TYPE keyword.)

Randomize Questions determines whether the questions are presented in strictly ascending numerical order (based on their question ID: see section About Question IDs) or in random order. Remember that questions with negative IDs are never randomized (see section Negative Question IDs).

4.2.5 Sound Settings for ESP Desktop

Here you may select the beep sound (via pop-up menu) to alert the participant to begin a trial. This sound will be repeated according to your Automation Prefs "Max Seconds to Respond" and "Seconds Between Beeps."

NOTE: Many of these beeps sound the same. They are all of the system-supplied beeps. WARNING: if you use the "Alarm" beep, your experiment can run into trouble if you're not careful. The Alarm sound has a longer duration than the others. If you set "Seconds Between Beeps" to be too short (shorter than the duration of Alarm), then as the Alarm sound rings, it will overlap itself, with the next beep beginning before the previous one has ended. This can interfere with the timing of your experiment. Therefore, if you use Alarm, make sure that "Seconds Between Beeps" is longer than the duration of the Alarm sound, and test it carefully.

4.3 Menu Reference

4.3.1 File Menu

The File menu is for creating, opening, saving, and closing whole experiments. Before you create or open an experiment, the File menu has these choices:

New Experiment will create a brand-new experiment in a directory (folder) of your choice. If you choose a directory that already contains an experiment, ESP Desktop will ask if you want to open it.

Open Experiment will open an existing experiment from a directory of your choice. If you choose a directory that has no experiment, ESP Desktop will ask if you want to create one.

When an experiment is loaded, the File menu contains the following choices:

Save will save your experiment in place. Save As will prompt you for a new location to save your experiment. (This is the easiest way to copy an experiment: open it, then choose Save As.) Close will close your experiment. Revert will reload the last saved settings for your experiment.

All file operations - and many others - will warn you if you're about to lose unsaved settings. For example, if you try to load settings from the Palm into an unsaved experiment, you'll see:

If you don't want to lose your settings in ESP Desktop, click Cancel, save your experiment, and repeat the operation.

4.3.2 Living in a browser window

ESP Desktop is a complete application, but it runs in a web browser (Mozilla) which has the usual Back, Forward, and Reload buttons and other common browser features. Try to treat ESP Desktop as an application and not as a web browser, and you'll have the most success.

ESP Desktop has its own menu as we've seen, and in particular, it has a Save command for saving your work. Make sure you use it. You can cause yourself problems up by clicking the browser's Reload button or quitting Mozilla without saving your experiment. In these cases, any changes you have not saved will be lost. So, as a general rule, always Save before reloading the page or quitting Mozilla.

ESP Desktop cannot stop you from reloading the page or exiting the browser. Therefore, as a convenience, ESP Desktop remembers which experiment you are working on until you explicitly use the Close menu command in the File menu.

For example, if you quit Mozilla while editing an experiment, then the next time you run ESP Desktop, it will automatically prompt you to load that experiment:

If you click OK, the experiment is reloaded. If you click Cancel, ESP Desktop will display its initial screen where you can choose a new experiment to work on. (In either case, if you had unsaved changes when you quit Mozilla, those changes are gone.)

Likewise, if you click Mozilla's Reload button without closing an experiment, then you'll be prompted to reload that experiment. (Though any unsaved changes will again be gone.)

Note: If you want to get rid of unsaved changes and revert back
to the last saved version of your experiment, you can click the
browser's Reload button (or quit Mozilla) to do this. However, we
recommend using ESP Desktop's own Revert command in the
File menu instead.

4.3.3 Experiment Menu

The Experiment menu is for operating on your entire experiment at once.

Set name changes the name of the experiment, as it appears below the heading "ESP Desktop". It pops up a dialog to enter the new name.

Read from Palm downloads a whole experiment - both the settings and the questions - from the connected Palm into ESP Desktop. (But not the participant data: that's done with Download data from Palm.)

Install on Palm uploads the current experiment onto the connected Palm. You may upload the settings, questions, the ESP program, and/or the ESPPrefs program in any combination. Additionally, if ESP has already been run on the connected Palm, you may choose to keep the existing participant ID or assign a new one. ESP Desktop prompts you to make these choices:

asks you for confirmation:

then performs the installation.

Install on many Palms leads you through a sequence of dialogs to upload the current experiment onto a fleet of Palms. It begins with the same choices as Install on Palm:

asks you for confirmation:

asks you how many Palms will be processed:

optionally assigns new participant IDs (if you chose to do so):

and then does all the installations in sequence from first to last:

and so forth. When finished (or if you exit prematurely), ESP Desktop displays statistics on how many Palms were successfully processed. For instance, if you'd specified five Palms but done only the first few, you might see:

4.3.4 Settings Menu

The Settings menu is for operating only on your experiment's settings.

Read from Palm downloads the only the experiment settings (but no other information) from the connected Palm into ESP Desktop.

Set to global ESP defaults will initialize your experiment to use the ESP defaults. Use this if you feel hopelessly lost and want to start your experiment over.

Send settings to Palm is the opposite of Read from Palm: it uploads only the current settings from ESP Desktop to the connected Palm.

4.3.5 Questions Menu

The Questions menu is for operating only on your experiment's questions.

Edit questions runs an external editing program to edit the questions for your experiment. The default editor is GNU Emacs on Linux systems (`/usr/bin/emacs'), and Notepad on Windows. (Any editor can be used as long as it opens its own window and accepts a filename as an argument.) Enter your questions one per line. ESP Desktop will upload them to your Palm(s) ready for ESP to use.

You can change the editor with the Set question editor menu command:

You must provide the full path to the editor program, such as `C:\winnt\notepad.exe' for Notepad on some Windows systems, not just `notepad'. Also, your answer is global: the selected editor will be used for all experiments you edit.

Read from Palm downloads only the questions (but no other information) from the connected Palm into ESP Desktop.

Send questions to Palm is the opposite of Read from Palm: it uploads only the current questions from ESP Desktop to the connected Palm.

4.3.6 ESP Menu

The ESP menu is for copying the ESP and ESPPrefs programs to the connected Palm.

4.3.7 Participants Menu

The Participants menu is for dealing with participant data.

Download data from Palm transfers all participant data from the connected Palm to your experiment directory, inside a subdirectory called `subject-data'. See section Data.

After you download the data, you may optionally delete the data from the Palm. Download data from Palm will offer you this choice:

4.3.8 Help Menu

The Help menu is for documentation.

Help on the web takes you to the ESP web site.

Manual displays this ESP manual on your local computer.

View License displays the GNU Public License, which explains that you may copy and share ESP software for free.

Credits tells you who created ESP Desktop.

About displays the version number of ESP Desktop.

4.4 ESP Desktop Internals

ESP Desktop presents a friendly user interface, but sometimes you might want to get under the hood. We'll explain the files and programs that ESP Desktop uses internally. Most files are plain text and you can edit them, and most programs can be invoked directly.

4.4.1 Experiment Internals

When you create an experiment directory (folder), you'll find these files in it:

`espprefs.xml': This is an XML file containing the experiment settings. You can modify it with a text editor.

`experiment.txt': This is a plain text file containing the experiment name on a single line. You can modify it with a text editor.

`questions.txt': This is a plain text file containing the experiment questions, one per line. You can modify it with a text editor.

`subject-data': This subdirectory contains all your participant data for the experiment.

Any other files are for internal use only.

If you modify a file by hand while ESP Desktop is running, this is at your own risk. ESP Desktop is not guaranteed to see your changes and might overwrite them.

4.4.1.1 Default Internals

When you create a new experiment, several default files are copied into the experiment directory (folder): `espprefs.xml', `questions.txt', and `experiment.txt' (see section Experiment Internals). These default files come from the ESP system directory `C:/Program Files/esp4' (Windows) or `/usr/local/esp4' (Linux). Normally you don't need to think about these files, but if you'd prefer to change the defaults when new experiments are made, you can edit these files with a text editor.

4.4.2 Hotsync Internals

On Linux, hotsync operations are handled by a program called espprefs-conduit-unix, found in `/usr/local/esp4'. Run the command with no arguments to find out what it does. You can run it manually to do various ESP-specific hotsync operations: copying question files, settings files, etc.

On Windows, hotsync operations are handled by the ordinary Hotsync Manager. However, this presents a unique challenge to ESP Desktop, since hotsyncs run independently from ESP Desktop. In other words, ESP Desktop isn't aware when hotsyncs start or finish. As a result, ESP Desktop asks you to click an extra "OK" button after a hotsync completes, so it can examine the results. This makes the Windows version of ESP Desktop more verbose than on other platforms: it displays more dialogs and asks for more confirmation from you.

The Windows hotsync structure consists of three programs:

• espprefs-conduit-win.exe, which does not actually do any hotsynching. It merely creates a marker file that will instruct a real hotsync what to do. It takes mostly the same options as the Linux conduit espprefs-conduit-unix.
• EspDesktopConduit.dll, a library that's run automatically during hotsynching. This does the real work for ESP Desktop, transferring your settings, questions, and so forth, to and from the Palm. It reads the marker file left by espprefs-conduit-win.exe to see what to do.
• DummyConduit.dll, a library that's run automatically during hotsynching, but does nothing. It replaces a standard Palm library to prevent it from interfering with ESP Desktop.

5. ESPPrefs

ESP for the Palm Pilot may be configured with the included program ESPPrefs (short for "ESP Preferences"). The experimenter can control numerous aspects of ESP's behavior with simple settings.

5.1 Getting Around ESPPrefs

When you first run ESPPrefs, you will see the following screen:

This is one of several screens for modifying ESP's behavior. You can reach the other screens from the Preferences menu (press the Menu key):

5.2 Saving and Loading Settings in ESPPrefs

When you change values within ESPPrefs, they do not take effect until you save them. Saving is done from the File menu:

The other menu item, Restore Defaults, brings ESPPrefs back to its initial values as shipped. Select this item if your settings get hopelessly confused. However, you still must select Save to make these default values take effect.

Credits simply displays information about ESPPrefs.

5.3 Changing Settings

5.3.1 General Settings for ESPPrefs

The Subject ID uniquely identifies the person carrying this Palm Pilot. If your experiment uses multiple Palm Pilots, make sure each of them is set with a different Subject ID. Valid values are 1 to 32767 inclusive. Do not use zero. Larger values may cause ESP to crash.

This value is used in two ways:

• It is saved with each of the participant's responses, so you can always identify which participant is associated with each response.
• It becomes part of the database name containing the participant's responses. [xxx] If the Subject ID is 123, the results database will be named ESPR-123 (on the Palm) or ESPR-123.pdb (on the Windows machine after uploading).

The Automation setting selects between manual mode (see section Manual Mode: What it Looks Like) and automatic mode (see section Automatic Mode: What it Looks Like) for your experiment. In manual mode, the participant initiates trials herself. In automatic mode, the Palm initiates them.

The Take Over Machine setting determines whether the participant can run other Palm programs while ESP is running. The recommended setting is to check this box. Otherwise, the participant will be able to halt ESP at any time and/or waste the batteries by running undesired software.

When we say "Take Over," we really mean it. None of the buttons will operate. This is good for keeping participants from fiddling with the Palm, but inconvenient when the experimenter needs to use the Palm, say, for transferring data to the PC using ESP Desktop. So, if you use Take Over Machine, you'll need to get the Palm out of this mode before you can hotsync your results data to your PC with ESP Desktop (see section Collect Data).

5.3.2 Automation Settings for ESPPrefs

These settings are available only if Automation is selected in General Settings. If you are running an experiment in manual mode (see section Manual Mode: What it Looks Like), these settings will not be visible when editing and will not take effect in the experiment.

The Begin Day and End Day settings specify the allowable times of day that trials may be run. Outside of this time range, no trials will occur. Times are on a 24-hour clock, from 0:00 (midnight) to 23:59 (11:59 pm). If the Begin and End times are equal, trials can run at all times. Setting the End time earlier than the Begin time is an error.

Total Trials and Trials Per Day control the frequency of trials. For example, if you request 100 trials in total and 20 trials per day, your experiment will last for five days (total trials divided by trials per day, or 100/20). If you request 101 trials and 20 per day, your experiment will last for six days, with the last day having only one trial (the hundred-and-first).

The Randomize Trials setting determines whether trials occur at predetermined or random times. If you've requested N trials per day, the period between the Begin and End times is split into N intervals of equal length. (For example, if the period is between 12:00 and 22:00 and you request 20 trials per day, this creates 20 intervals of 30 minutes each.) If Randomize Trials is unchecked, trials will occur at the beginnings of these N intervals. If checked, trials will occur at a random time within each interval. In our "20 trials per day" example, the first trial would occur at a random time between noon and 12:30, the next between 12:30-13:00, etc. So "random" means "random within each interval."

Max Seconds To Respond sets a time limit, in seconds, for the participant to respond to a trial. The Palm will beep continuously during this time. If there is no response within this time period, the trial ends. The related setting Seconds Between Beeps determines how frequently the Palm will beep while waiting for the participant to respond. (NOTE: Values of less than 2 seconds are unreliable.) So, if you request 30 seconds of beeping with 3 seconds per beep, the Palm will beep 10-11 times.

Run At Invocation is an experimenter's aid. When you first run ESP by tapping its icon, should a trial begin immediately (checked box) or should a trial simply be scheduled to run later (unchecked box)? Depending on your needs, you might want the participant to answer questions immediately (say, as practice in front of the experimenter) or not.

5.3.3 Question Settings for ESPPrefs

Max Seconds To Respond sets a time limit for a participant to respond to a question. If no response occurs within this limit, the trial ends. If you want no time limit on answering a question, use a large value like 99999999. (Or if appropriate, run the experiment in Manual mode instead of Automatic mode.)

Important: This timer begins running when a question appears, and it keeps running until the question is fully answered. If the participant slides a slider, writes Graffiti, taps checkboxes, etc., this does not prevent a timeout! In other words, the time limit can be reached while the participant is in the middle of writing Graffiti, moving a slider, etc. Be aware of this and plan appropriately.

Non-Answer Value sets the value to be stored if the participant does not answer a question.

Default Widget determines whether responses are presented as buttons, a dropdown menu, etc., by default. (If you don't want the default, you can specify the widget directly for each question with the %TYPE keyword.)

Randomize Questions determines whether the questions are presented in strictly ascending numerical order (based on their question ID: see section About Question IDs) or in random order. Remember that questions with negative IDs are never randomized (see section Negative Question IDs).

5.3.4 Sound Settings for ESPPrefs

Here you may select the beep sound (via pop-up menu) to alert the participant to begin a trial. This sound will be repeated according to your Automation Prefs "Max Seconds to Respond" and "Seconds Between Beeps."

NOTE: Many of these beeps sound the same. They are all of the system-supplied beeps. WARNING: if you use the "Alarm" beep, your experiment can run into trouble if you're not careful. The Alarm sound has a longer duration than the others. If you set "Seconds Between Beeps" to be too short (shorter than the duration of Alarm), then as the Alarm sound rings, it will overlap itself, with the next beep beginning before the previous one has ended. This can interfere with the timing of your experiment. Therefore, if you use Alarm, make sure that "Seconds Between Beeps" is longer than the duration of the Alarm sound, and test it carefully.

6. Experiments

Here are the steps, in order, for creating and running a complete experiment with ESP.

6.1 Get Ready

Install the Palm Desktop and other associated software (included with your Palm) on a PC. We will call this machine your Desktop PC.

6.2 Create Experiment

To create your experiment, use ESP Desktop:

1. Create a new experiment (see section Creating a new experiment)
2. Create questions (see section Creating Questions)
3. Edit the experiment settings (see section Changing Settings)

Alternatively, you can create the experiment on the Palm using ESPPrefs (for settings) and the Memo Pad (for questions), but this is quite cumbersome.

6.3 Make Palms

6.3.1 Set Up a Test Palm

1. Designate one Palm as your test machine.
2. Perform a hard reset on the Palm to restore it to the factory default configuration. (While holding the power button, press the reset button on the back; or see your Palm manual.)
3. Run ESP Desktop (see section ESP Desktop) to install the ESP software and configure your experiment. (Alternatively install ESP.prc and ESPPrefs.prc using the Palm Desktop, and run ESPPrefs (see section ESPPrefs) to configure your experiment.)
4. Run ESP and carry this Palm for a week (or whatever length of time is appropriate for your experiment), making sure that the experiment is working as you require.
5. Run ESP Desktop (see section ESP Desktop) to download the data onto your personal computer.

6.3.2 Make Your "Production" Palms

Use ESP Desktop (see section ESP Desktop) to copy ESP and your experiment onto multiple Palms.

6.4 Distribute Palms

Tap the ESP icon to start the experiment, and give the Palm to the participant.

Recommended: Instruct the participant not to monkey with the Palm or his/her remuneration may be at risk.

6.5 Collect Data

Collect data from your participants regularly.

1. Take the Palm out of sight.
2. If ESP is using the Take Over Machine setting, then ESP will still be running and the Palm cannot hotsync. Therefore, you will need to get ESP out of this mode before you can upload data. Here's how to do it:
   • For newer Palms that have a silk-screened clock button on the upper left of the Graffiti area:
     1. Click on the clock button.
     2. Click on "go to Clock" button on the screen.
     3. Click on the home button.
   • For some older model Palms:
     1. Perform a soft reset. See your Palm manual to learn how. Most likely you insert a paperclip or pen tip into a hole on the back of the Palm.
   • For other older model Palms:
     1. Perform a soft reset. See your Palm manual to learn how. Most likely you insert a paperclip or pen tip into a hole on the back of the Palm.
     2. Go to the upper right menu and pick the "Buttons" menu
     3. At the "Buttons" panel, press the "Default" button on the lower left. This will reset the application buttons to their normal state.

   (Thanks to the iESP Project for this writeup.)

3. Use ESP Desktop to download the subject's data.
4. If you're using rechargeable batteries, swap the participant's Palm for another fully-charged one. (Use ESP Desktop to set the participant ID to the same number as the original, using the Install on Palm menu command.) If you're using non-rechargeable batteries, change them and perform a soft reset (to avoid an operating system bug associated with battery changes).
5. Tap the ESP icon to resume the program.
6. Return the Palm to the participant.

6.6 Analyze Data

In each experiment, the participant data is found in a directory (folder) called `subject-data'. See section Data.

7. Data

ESP Desktop downloads the data from the Palms to your PC, to a specific place within your experiment folder.

7.1 Where the Data is Located

ESP Desktop automatically creates and maintains a set of directories (folders) for your participant data, located inside your experiment directory.

• Directly inside your experiment directory is a subdirectory named `subject-data'. This contains all the participant data for the experiment, in the format below.
• Inside `subject-data', each participant has a separate subdirectory named for their ID. So, if your experiment has three participants with IDs 1, 2, and 18, their data will be in subdirectories `1', `2', and `18' inside of `subject-data'.
• Within a given participant's subdirectory (say, `subject-data/18'), there will be one or more files containing that participant's data. ESP Desktop creates a new file each time you download data. So if you have downloaded data six times for participant 18, there will be six files. The file names are of the form:

  ParticipantID.YYYY-MM-DD.hhmmss.txt

  including the participant ID, the date of creation, and the time of creation. For example, the filename `18.2005-02-29.234207.txt' is for participant 18 and was created on February 29, 2005, at 23:42:07 (11:42:07 PM).

All of these files and directories are created and maintained automatically by ESP Desktop when you download data.

7.2 What the Data Looks Like

Data is written to files, one line per question asked. The file format is always the same, but here is an example to make things concrete. Given this experiment:

%QSET 50|11|First sampled question|A|B|C
%QSET 50|12|Second sampled question|D|E|F|G
%QSET 50|13|Third sampled question|H|I
5|%RANDOM 50
6|%RANDOM 50
7|%RANDOM 50
100|How are you feeling?|good|bad|ugly

here is an example data file representing the responses of participant 18:

20050113140732        18        12            187         2  1        50 "E"
20050113140732        18        13             93         2  1        50 "I"
20050113140732        18        11             58         1  1        50 "A"
20050113140732        18       100             72         2  1         0 "good"
20050113140740        18        11             73         2  1        50 "B"
20050113140740        18        13             65         1  1        50 "H"
20050113140740        18        12             59         2  1        50 "E"
20050113140740        18       100             81         3  1         0 "bad"
....

Each line represents one participant's response to one question. The values on each line represent the following:

NOTE: This data format is new. It is not compatible with ESP 2.0 nor iESP.

For checkboxes, the "button number" value is a bit vector: a binary (base 2) value indicating which checkboxes were checked. A "1" bit means the checkbox was checked, and a "0" means unchecked. For example, if the question has 6 checkboxes, and the participant checked the first, second, and fifth, the response will be recorded as 010011 = 19. (Note that the values are read from right to left: the rightmost bit is the first checkbox, etc.) This is a standard technique called a "bit vector"; if you're uncomfortable with base 2, ask any computer science student for help. To decode the data, many scientific calculators can convert numbers from base 10 to base 2 for you.

7.3 File and Data Handling

The file names and data are set up to allow the experimenter great flexibility. In general, you can freely combine the data for multiple trials and participants without accidentally losing information.

• Every file in the entire experiment has a unique name. Therefore, you can copy them all to a single directory without any conflicts.
• Every filename contains a timestamp. Therefore, if you sort the files belonging to a given participant alphabetically, they'll be sorted by time; and if you concatenate files in that order, the data will also be sorted by time.
• Every line of data contains the associated participant ID. Therefore you can mix data from different participants without losing information.
• Every line of data begins with a timestamp. Therefore if you sort the data alphabetically or numerically, it gets sorted by time.

So, to obtain all the data for a single participant in the order it was created, simply concatenate all files in that participant's directory in alphabetical order. For example, on Linux systems, the command:

$ cd subject-data
$ cat 18/* > 18.txt

produces a file `18.txt' containing all of participant 18's data, sorted by timestamp. You can also easily do this for all participants:

#!/bin/bash
cd subject-data
for p in *
do
  cat $p/* > $p.txt
done

This shell script produces a `.txt' file for each participant, named `1.txt', `2.txt', etc.

You can freely concatenate, mix, and match the data without losing information. Every line of data identifies its participant and trial. For example, on a Linux system, you can produce a single file containing all data, sorted by time, with:

$ cd subject-data
$ find . -type f -print0 | xargs -0 cat | sort > alldata.txt

This all might seem trivial, but actually it's important. Imagine if every participant's data were kept in a file called `data.txt' instead of a uniquely named file. If you wanted to copy them all to the same directory, they'd collide. Similarly, if the data didn't contain the participant IDs on every line, you couldn't combine the data from multiple participants for analysis.

8. Practical Matters

8.1 Memory considerations

Palm Pilots have limited memory for storing a participant's responses. Nevertheless, ESP's memory use is small. Each response (to a single question) occupies less than 100 bytes of RAM. Therefore, a two-megabyte Palm (the minimum configuration we've seen in years) will comfortably hold 18,000 to 20,000 responses, provided you have not installed any other third-party software on the Palm.

For example, if you prompt the user with 20 questions 10 times each day, that's 200 responses per day. You can run this experiment for 90-100 days without filling up the RAM of even a low-end Palm. With a modern Palm (8 MB or RAM or more) you have space galore.

Nevertheless, you should have your participants visit you regularly to upload their data to a PC for safekeeping and to change batteries. Otherwise, you risk losing data due to accidents.

8.2 Battery considerations

Make sure to plan for battery changes if your experiment will run longer than the Palm's expected battery life. (See your Palm's documentation on battery life.)

Modern Palms have rechargeable batteries. We recommend keeping extra, fully-charged Palms around and swapping them when participants check in. Just be sure to keep the same participant ID on the old and new Palm!

Older Palms use disposable batteries. Keep a good supply around and change the batteries when participants check in.

Important Note:
Some versions of the Palm operating system have a bug concerning battery
changes.  After replacing batteries, always perform a soft reset.
If you don't, the Palm's alarm timer may become incorrect.

9. Troubleshooting

9.1 Troubleshooting ESP

Q: How do you get the Palm out of "Take Over Machine" mode? I tried a soft reset but it didn't work.

A: See section Collect Data.

9.2 Troubleshooting ESPPrefs

(No info yet)

9.3 Troubleshooting ESP Desktop

General Issues

Q: On Windows, the installer program EspDesktopConduitInstaller refuses to run. It display the error message, "Catapult could not detect a compatible Palm Desktop software configuration and will cancel installation."

A: First, make sure you have Palm Desktop installed, and reboot after you install it. On some PCs the problem continue anyway. We don't know the cause. If you have any clues please let us know.

Q: I can't load ESP Desktop at all. Everything installed without error, but my browser cannot find the URL chrome://espdesktop/content/desktop.xul.

A: If this occurs, there are several things to check:

1. Make sure you edited the `installed-chrome.txt' file as explained in the installation instructions. Make sure you edited for the right browser: Mozilla and Firefox have separate `installed-chrome.txt' files.
2. Make sure you edited `installed-chrome.txt' using a plain text editor such as Emacs or WordPad, and saved it as plain text with no "formatting." Otherwise you can corrupt the file.
3. Make sure that you installed ESP in the right place on your PC. On Windows, when you ran EspDesktopConduitInstaller, did you change the folder where ESP is installed? Or on Linux, did you extract `esp4-linux.tar.gz' somewhere other than `/usr/local'? Don't do that. Uninstall and reinstall ESP. A common mistake on Linux is to create `/usr/local/esp4' by hand and then extract ESP into it. That is incorrect: you should extract ESP directly into `/usr/local' and let the "esp4" subfolder be created automatically. If you do it wrong, you'll wind up installing ESP one level too deep, in `/usr/local/esp4/esp4', and Mozilla won't be able to find ESP Desktop.

   So on Windows, look in `C:/Program Files/esp4', and on Linux, look in `/usr/local/esp4'. Inside, you should see a whole bunch of files. (And specifically not just another subfolder called "esp4".) Uninstall and reinstall ESP if necessary to correct this.

Q: My browser loads the ESP Desktop page, but something else is not working.

A: Test ESP Desktop by running its built-in self-test. Under the Help menu, select Test ESP Desktop and follow the instructions. See section Testing the Installation.

Q: On Windows, the ESP Desktop Test succeeds except the hotsynching test. You might see an error, "Synchronization generated one or more messages. Please see the HotSync log for details." Or you might see an error message from the Hotsync Conflict Notifier, saying "A conflict in the installed conduits has been detected."

A: We've seen this sometimes in earlier versions of the Palm Desktop. A heavy-handed solution is to uninstall Palm Desktop and then upgrade to the most recent version. If you use your PC for hotsynching purposes other than ESP, then uninstalling Palm Desktop might disrupt your other work; but if your PC hotsynching is only for ESP, this is the recommended solution.

If that does not work for you, a less radical solution is to delete some Palm conduits from your system. (A conduit is a piece of hidden software that transfers data between the PC and the Palm.) This is done with a program such as Conduit Buddy (http://www.livepim.com/). (Or if you happen to be a registered Palm software developer, you can use the utility program condcfg.exe from Palm's Conduit Development Kit (CDK)). Using one of these programs, delete the conduits that have the Creator ID "memo", "Pmem", and "PMem". Then install ESP Desktop again. The problem should be fixed.

Hotsync Issues

Q: On Linux, when I try to hotsync, the kpilot program runs and interferes with ESP Desktop. What can I do?

A: Uninstall kpilot. This is a brute-force solution but it works. If someone has a less drastic way to prevent kpilot from running in KDE, let us know.

Q: On Linux, ESP Desktop will not hotsync with my Palm to transfer data.

A: Make sure `/dev/pilot' points to the actual device for your Palm, typically a serial or USB device. To determine the device, view the system log file `/var/log/messages' or its equivalent with tail -f:

# tail -f /var/log/messages

connect your Palm, initiate a hotsync, and watch the messages printed by tail. They will reveal the device name, e.g., `/dev/usb/ttyUSB1'. Now make sure `/dev/pilot' points to this device:

# ls -l /dev/pilot

If it points to the wrong device, correct this, e.g.,

# rm /dev/pilot
# ln -s /dev/usb/ttyUSB1 /dev/pilot

and try hotsynching with ESP Desktop again.

For further debugging, you can also try running the underlying hotsync program directly, espprefs-conduit-unix, found in the directory where you installed ESP (e.g., `/usr/local/esp4'). Run espprefs-conduit-unix for usage information.

Permissions Issues

Q: When I run ESP Desktop, I see warnings about unsafe operations or special permissions required.

A: See section Special note about permissions.

Menu Issues

Q: In the Help menu, the Help on the Web, Manual, and View License menu commands don't work.

A: Your browser's popup blocker is probably blocking these windows from opening. Edit your blocker preferences to permit the site "espdesktop" to open popup windows. This problem is due to Mozilla bug 247965.

Q: The File menu acts funny sometimes. I click it and nothing happens.

A: This problem is due to Mozilla bug 267215. A workaround is to click a different menu item (such as Help), then return to the File menu.

Q: In the Experiment menu, when I select Install on Palm or Install on Many Palms, nothing happens. Isn't a dialog supposed to appear?

A: You're probably viewing ESP Desktop directly as a file in your browser (e.g., a file://... URL) or as an http://... URL. You have to view it as chrome://espdesktop/content/desktop.xul. This is necessary for certain pop-up dialogs to work. Did you install ESP as instructed? See section Installation.

10. Bugs

ESP is provided without support of any kind. That being said, you are welcome to report defects and problems to barretli@bc.edu.

IMPORTANT: When reporting a bug, attach your `questions.txt' and `espprefs.xml' files from your experiment. They are found right in the folder you created to contain your experiment. (This assumes you are using ESP Desktop.)

There is also an ESP mailing list that you can join to discuss ESP with fellow users. See section For More Information.

Known Defects

ESP

• Do not change the Subject ID (in ESPPrefs) after running some ESP trials. If you do, alarms will fail to work and you may see the error "Could not set alarm: nonexistent database." This occurs because the subject ID (e.g., 123) becomes part of the database name (e.g., ESPR-123), so if you change the ID, ESP looks for the wrong database. The only workaround is to save the old database (via hotsync) and delete it from the Palm. Better yet, don't change subject IDs in the middle of an experiment!
• If you have a question set containing only N questions, your experiment may not sample from that question set more than N times. That's to be expected, since we sample without replacement, but there is also an associated bug: your experiment may not contain more than N questions that sample from that set. If you do, ESP may display the error "No questions in Question Set" and crash, even if the logic of your experiment would prevent sampling more than N times from your experiment.

ESP Desktop

• Under Linux, if another application is competing with ESP Desktop for the pilot device, ESP Desktop may hang.

ESPPrefs

• Times of day may appear with leading zeroes missing. For example, the time 7:03 may appear as 7:3. This is just a cosmetic problem: the settings are correct internally. And it affects only leading zeroes, not trailing zeroes: 7:30 will always appear as 7:30.

Limitations

ESP

• The end-of-experiment message, "The experiment is over," is not changeable. (Except through programming.)

ESP Desktop

• ESP Desktop requires you to save your experiment before you upload anything to the Palm.
• When you use the menu command Edit questions, ESP Desktop always assumes you've modified the questions, even if you haven't, and marks the experiment as unsaved. This is because ESP Desktop invokes an external editor such as Notepad or Emacs, so it doesn't directly know whether you've changed anything or not, so it assumes you have.
• The Install on Palm and Install on many Palms operations present a dialog asking what to upload (settings, questions, etc.). This dialog has no Cancel button so if you don't want to upload anything, you cannot cancel here. However, you can click OK, wait for the next dialog, and cancel safely at that point.

ESPPrefs

• ESP controls the Palm's "Auto-Off" feature: the length of time that the Palm will stay on while not in use. If you set this value yourself (using the Palm's "Prefs" control panel), ESP will change the setting.

Problems Caused by the Palm Operating System

• Due to a limitation of the Palm's sleep mode, alarms may be up to a minute late. Therefore, if you configure ESP to ring alarms less than a minute apart, you are going to be disappointed as your alarms will be noticeably late.
• After changing the batteries, the Palm's alarms may become unreliable due to an operating system bug. To work around this, always perform a soft reset after a battery change.
• Putting less than 2 seconds between beeps will produce unpleasant alarm sounds.

How to Report a Suspected Bug

Bug reports may be mailed to barretli@bc.edu. Include your:

1. Palm model (e.g., Palm IIIx)
2. Palm operating system version (tap home, then the menu button, then "Info..." under the App menu, then Version, and look for "Palm OS Software v. XXXX").

   

3. ESP and ESPPrefs versions (on the same version screen as above).
4. ESP Desktop version (from its "Help / About" menu)
5. If the bug involves ESP Desktop, include the files `questions.txt' and `espprefs.xml' files from your experiment. They are found right in the folder you created to contain your experiment.

11. iESP

iESP is an enhanced ESP produced by the University of Washington and Intel. It is based on our ESP 2.0, but with many extensions. ESP 4.0 includes all features of iESP version 3.2, plus more.

ESP and iESP settings and data are not compatible. A configuration for ESP (e.g., using ESP Desktop or ESPPrefs) will not work for iESP, and vice-versa.

12. Modifying ESP

ESP is free, open source software, licensed under the GNU Public License (GPL). Programmers are welcome (and encouraged) to modify ESP. Here's how to do it.

ESP is developed largely on Linux in the following languages:

• C, for ESP itself
• JavaScript, for ESP Desktop
• XUL, the internal language of the Mozilla browser, for ESP Desktop
• Perl, for some build scripts

using the following tools:

• gcc, the GNU C compiler
• prc-tools, extensions to gcc for producing Palm executables
• The Palm software development kit (SDK)
• PilRC, a tool for creating Palm user interfaces
• pose, a Palm emulator
• pilot-link from http://www.pilot-link.org/, a conduit library and toolset, version 0.11.8 or higher
• libxml2, an XML library
• Mozilla or Firefox, the web browsers from http://www.mozilla.org, version 1.0 or higher. (Other browsers are not supported: we rely on custom features of Mozilla/Firefox.)

The Windows version of ESP Desktop additionally requires:

• Visual Studio .NET
• The Palm Conduit Development Kit (CDK)

13. For More Information

Obtaining ESP

To download ESP, visit the ESP web site.

Support

To get help with ESP, join the Experience Sampling mailing list where you can discuss the software with fellow users:

http://groups.yahoo.com/group/experience-sampling/

The mailing list is hosted at the Yahoo Groups web site, so you will need a (free) Yahoo username and password in order to join. Visiting the link above will guide you through the subscription process.

Alternatively you can use email to subscribe, unsubscribe, and post messages:

• To subscribe, email experience-sampling-subscribe@yahoogroups.com.
• To unsubscribe, email experience-sampling-unsubscribe@yahoogroups.com
• To post messages, email experience-sampling@yahoogroups.com

Index

Table of Contents

About This Document

This document was generated by Daniel Barrett on November, 28 2006 using texi2html 1.76.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated by Daniel Barrett on November, 28 2006 using texi2html 1.76.