We describe here a system designed for behavioral experiments. The goals of the system are to (1) interact rapidly with the experimental subjects. For example, if a subject presses a lever, and an instantaneous response is desired, the system should respond as fast as possible, and do so reliably. (2) Provide high-time-resolution measurements of the events that have occurred, so as to get reliable time traces of behavior when combining it with electrophysiology. (3) Be flexible yet easy to program and modify.
 Tutorial/manual pages roadmap and the software architecture of the system
As we describe in the next section below, the system is built around two CPUs, one of which runs RT Linux and provides guaranteed real-time responses, and the second of which oversees the real-time machine and provides a user interface. We have written several layers of software to help use the system; you don't need to use them all, but as we go up layers, you can stop and use them at whatever point you want, and ignore the higher-up layers. All the code at the user-level is written in, and accessed from, Matlab.
- To start, you really need to understand the core, the Real-Time Linux State Machine (RTLSM). The RTLSM is programmed by using the StateMachineAssembler.
- We have developed some standards for the most reliable, and speedy, use of the RTLSM over different behavioral trials. These are explained in the trial structure section.
- Dispatcher is a simple system that starts protocols, interacts with the RTLSM, and takes care of a lot of basic housekeeping for you. We strongly recommend that if you are going to use the system, you go up to at least this level and write your code from this basis.
- Solo is a GUI system designed to help write large Matlab programs with large GUIs. Useful for writing protocols, but not essential. There are several very useful plugins and m-files that are based around Solo (including SessionModel below), so if you want in on that set of software, you'll have to go in on Solo.
- Runrats is a front end to Dispatcher that helps to manage running many rats on many rigs. For techs running rats, it presents a simplified GUI where they just select the rat for the current timeslot, click "Load" (behind the scenes, that starts Dispatcher and loads the appropriate protocol and settings), when the everything is ready and the rat is in the rig the techs then click "Run", and finally they click "End" at the end of the session.
- Plugins are software modules that can be easily attached to any protocol running from under Dispatcher. They are the best way to write modular code that many protocols can use. Plugins can be written in Solo (and can then use some of the advantages of the Solo system), but they don't have to be.
- Protocol Settings files are used to control two main things: first, you use them to define all the values for all the GUI parameters in a Solo protocol that you want to run. Each rat typically has its own set of values and its own Settings file. Second, for each rat, Runrats uses the name of its Settings file to figure out which protocol to use with that rat.
- SessionModel is a plugin designed to coordinate within-session and across-session training automation.
If already familiar with all of this, jump straight to the section you want, or use the navigation bar at left, or go here to find out what latest additions/changes there have been to the software.
If new to all of this, read on as we take you through it!
 The physical architecture of the system
As currently configured, the basic system consists of
(A) a behavior box into which the animal goes. This can have nose pokes, levers, lights, speakers, odor delivery, etc.
(B) a State Machine server, the Real-Time Linux State Machine (RTLSM). This is the core engine of the system, and is designed as a programmable enhanced finite state machine. By "programmable" we mean that the state diagram (i.e., what the states are, what events lead to transitions between them, what their outputs are) is determined by the user; and by "enhanced" we mean that it is like a finite state machine but has a bunch of enhancements that make it easier to program with it.
(C) A Sound Server. Sounds to be produced in the behavior box are sent to this server; the sounds are then started or stopped on commands from the RTLSM. For example, you could set the RTLSM so that every time the subject presses a certain lever, the RTLSM tells the Sound Server to emit sound "blah." Separately, you define sound "blah" to be whatever you like.
(D) a Governing Machine that tells the RTLSM what the state diagram should be; defines the sounds in the Sound Server; and provides the user interface. This last is often a graphical user interface (GUI). The overall philosophy is that the user interface side of things need not be designed to run real-time. That is why it is kept separate from the RTLSM. Typically the Governing Machine runs Matlab, but it doesn't have to do so.
(E) Optionally, there is also an Olfactory Server, that works exactly like the Sound Server, except it delivers odors, not sounds.
Simple outputs to the subject (lights, water, etc.) are controlled by digital output signals that are in turn controlled directly by the RTLSM. Other types of outputs (sounds, odors) are more complex and therefore have their own Servers that work off triggers and signals from the RTLSM. These are the Sound Server and the Olfactory Server. (Perhaps one day we will have a General Visual Stimulus server, which could perhaps, say, drive PsychToolbox-- but not yet).
Throughout this tutorial Wiki, we will assume that, like a typical user, you are sitting at a Governing Machine, and that you have access to our source code for that machine. We will now and then refer to files in that source code, assuming that you are in the home directory of the source code. We will also assume that you are running Matlab, and that it is through Matlab that you will be interacting with the RTLSM.
 The temporal architecture of the system
Both the State Machine and the Sound Server run within an RT Linux machine that runs the state machine at a hard guaranteed cycle of 6KHz. The sound cards typically used (from Lynx) have a sampling rate of 200 KHz.
Roughly speaking, at the beginning of each trial, the Governing machine talks to the State Machine and tells it what the state diagram should be for the upcoming trial. Once the trial has started, the State Machine runs autonomously: during this time, the governing machine can only listen to the state machine. Finally, when the trial ends, the State Machine lets the Governing machine know that the trial has ended. The Governing machine then decides on a new state transition matrix for the next trial, and the cycle starts anew. For full information on the temporal structure, see Trial structure.