Difference between revisions of "Installation Guide"

From Bcontrol
Line 33: Line 33:
==== Mac ====
==== Mac ====
SVN Client for Mac is generally included. Irrespective of whether it is included or not, follow these steps:
SVN Client for Mac is generally included in the Developer Tools.  This may change with future versions of Mac OSX. Please use the web to find out how to install svn and cvs clients on your mac.
* Install Developer's Tools completely that come with your Mac OS X Installation CD/DVD, if you haven't done it yet.  
* Insert the CD/DVD and the option to install Developer's Tools will come up. Then proceed with on-screen instructions.
(''Developer's Tools are also required to proceed with the next steps of installation of our custom software'')
* If SVN client is not installed on your Mac, type ''apt-get install svn'' in your terminal and that should take care of SVN installation on your Mac.
= Installation Guide for Beginners who want to first simply learn to use the system =
= Installation Guide for Beginners who want to first simply learn to use the system =

Revision as of 18:57, 15 January 2013

You need two pieces of code:

  1. the RTLinux-side code (where the State Machine interpreter lives and interacts with the physical box).
  2. the Matlab-side code (where you write your trial-to-trial control software in the form of protocols, known as a "ExperPort" resides and from where you control the State Machine).

Ordering RT Linux Machine from JAF International Inc.

  • Order using the following Quote:

RT-Linux JAF Machine Quote. Contact Name: David Huang; mailto:david@rackmountnet.com

  • Email the above contact with the machine's item code (included in the quote) and the quantity.
  • This machine is custom-built to suit our needs and hence might not be listed on their website.
  • Just in case you need a more detailed explanation of the entire configuration, download this detailed quote (for reference purposes only because it doesn't include the entire machine's item code).

Initial Requirements

Before we begin, let us make sure you have the following on your laptop/desktop:

A Shell


On Windows, download and install putty from here which will serve as the Shell. (Recommended: Install putty using the Windows Installer because it includes everything we would need now or in future: putty, puttygen, pageant etc.)


Mac already provides a built-in application called Terminal. Terminal is the Shell.

An SVN Client


The most popular SVN Client for Windows is TortoiseSVN. Download it here and install.


SVN Client for Mac is generally included in the Developer Tools. This may change with future versions of Mac OSX. Please use the web to find out how to install svn and cvs clients on your mac.

Installation Guide for Beginners who want to first simply learn to use the system



For people that are just starting up, you'll most likely want to download the RTLinux-side code in its Emulator form. The Emulator pretends that it is an RTLinux machine with a physical behavior box, but just runs on your computer. The Emulator shares most of its source code with the actual RT Linux source code. So you can learn to use and test your software without need of an extra CPU or a behavior box. It is thus a good place to start and learn to write protocols, interact with the state machine, and so on: you don't need an RT Linux machine for this, you just need your laptop. Instead of physical pokes, the Emulator GUI provides you with buttons that you click on with your mouse.

(Note: One currently very confusing thing about the Emulator's graphical interface: Ch. 00 is the Center poke; Ch. 01 is the Left poke, and Ch. 02 is the right poke. That is, they are ordered C,L,R, instead of L,C,R. We'll get around to changing that at some point. You can change this order by changing the order of input and output lines in your Settings/Settings_Custom.conf)

Get the latest rt-fsm code and emulator from our google code rt-fsm repository .

Windows Emulator Download Mac Emulator Download

Physical Machine

Alternatively, if you want to use the RTLinux-Side code on a physical RTLinux machine, download it using an SVN Client (refer to Initial Requirements above) from here, and follow the instructions (available in a file named INSTALL_STEP_BY_STEP in the downloaded directory) on how to install source code on the actual RTLinux machine.


  • The Matlab-side code is the same whether you are interacting with an RTLinux Machine or the Emulator on your laptop/desktop.
  • Download the code in zip format (for Windows users) or tarred/gzipped format (for Mac Users).
  • Create a directory called ratter; unzip/untar the downloaded code into ratter directory.
  • Create directories called SoloData and Protocols inside ratter.
  • Browse to ExperPort/Settings directory and open Settings_Custom.conf file (use Wordpad on Windows to open it) and change the following directory paths to the ones on your machine.
GENERAL; Main_Code_Directory;   /Users/carlos/ratter/ExperPort
GENERAL; Main_Data_Directory;   /Users/carlos/ratter/SoloData
GENERAL; Protocols_Directory;   /Users/carlos/ratter/Protocols
  • Based on the Operating System, change the slash signs (/ on Mac and \ on Windows).
  • Read the Startup Guide to start using it.

Installation Guide for Advanced Users (core code and behavioral protocol developers)


On your RTLinux machine, you will need RTLinux Source Code which can be downloaded here or you can choose to use the emulator (read beginner's instructions above).


As a developer, downloading ExperPort (current name of the Matlab-side behavioral control project) from SVN repository, and keeping it up to date is your best option. Assuming you took care of the Initial Requirements (above), follow these simple steps to download ExperPort from SVN repositories:

Step 1: Generate public-private key pair


  • Open PuTTYgen from Start->Programs->PuTTy
  • Select the SSH-2 DSA radio button at the bottom of the PuTTY Key Generator window.
  • Press the Generate button.
  • Add whatever short key comment you like.
  • You may select a passphrase or elect not to. It is slightly easier not to use one.
  • Pick a nice safe place (Not in code or data directories!) to save both your public and private keys-- that is, you have to click on both "Save public key" and "Save private key."
  • For example, you can save your private key as 'jmillers_key_for_brodylab.ppk' and public key as 'jmillers_key_for_brodylab.pub'.


  • Open the Terminal window.
  • Make sure you are in your user directory. Lets say /Users/jmiller.
  • Type the following command: ssh-keygen
  • While it is generating the keys, it will ask for a name for your key. Give a name to your key. Fox example let's say 'jmillers_key_for_brodylab'.
  • It will also ask you to type a passphrase. You may enter a passphrase or elect not to. It is slightly easier not to use one.
  • Two keys will be created now in /Users/jmiller directory. One is 'jmillers_key_for_brodylab' (this is the private key) and other is 'jmillers_key_for_brodylab.pub' (this is the public key).
  • Create a directory named '.ssh' (without the quotes), place your private key in it and modify the permissions of .ssh directory and the private key as shown below:
$ cd /Users/jmiller
$ mkdir .ssh
$ chmod 700 .ssh
$ mv jmillers_key_for_brodylab .ssh/
$ cd .ssh
$ chmod 600 jmillers_key_for_brodylab

(In the above set of commands, remember that 'jmiller' and 'jmillers_key_for_brodylab' should be replaced by your username and the name of generated private key file, respectively )

  • Open ssh configuration file for editing as follows:
$ sudo su
Password: <Enter the administrator password of your Mac here>
$ nano /etc/ssh_config
  • This will open the ssh configuration file for editing.
  • Go to the line which says # IdentityFile ~/.ssh/id_rsa. Immediately after this line, add another line (without the '#' symbol in front): IdentityFile ~/.ssh/jmillers_key_for_brodylab.

(Remember that 'jmillers_key_for_brodylab' should be replaced by your private key file name)

  • Save the file and exit.

Step 2: Send us the public key so that we can grant you access to our server.


Send us the .pub key file you saved using PuTTY in Step 1. Also, if you wish, you can send us a desired username for you on our Server.


Send us the .pub key file you generated using ssh-keygen command in Terminal in Step 1. Also, send us the same username that you used on your Mac while generating the public-private key pair. We will need the same username to create a working login for you on our server. For example, in Step 1, we gave an example of the keys being generated under the username 'jmiller'.

Our contact email is brodyadmin@princeton.edu. We will respond when your key is ready to be used to login to our servers. Once you receive a response from us, proceed to Step 3.

Step 3: Check if you are able to connect to our server


  • Open the PuTTY Configuration window from Start->Programs->PuTTy
  • In the Sessions option group (initially displayed):
    • Enter the following Host Name: brodylab.princeton.edu
    • Select SSH as the connection type (Port should be set to 22)
  • In the Connection: Data options subgroup (in the tree on the left):
    • Type in the username you received from us in the Auto-login username field.
  • In the Connection: SSH options subgroup (in the tree on the left):
    • Select "2" as your Preferred SSH protocol version.
  • In the Connection: SSH: Auth options subgroup (in the tree on the left):
    • Enter the location of the private key you created (whose corresponding public key you sent to us).
  • Back in the Sessions options group (top of the tree on the left):
    • Choose a name for the session we've created (like brodylab) in the edit field below the text "Saved Sessions". DO NOT USE SPACES OR SPECIAL CHARACTERS; other programs may not treat them properly.
    • Click Save.

Now your connection is set up and you can double-click it in the list of sessions to test it.


Open the terminal and type the following command:

$ ssh <username>@brodylab.princeton.edu

where <username> is the name that you sent us to create a login for you on our server.


  • If you haven't confirmed your key with us yet, login will ask for a password; and the Terminal (on Mac) or PuTTY (on Windows) may report that your key has been rejected by the server.
  • If you fail to connect repeatedly, your IP will be banned for 10 minutes.

Step 4: Download (or checkout) ExperPort, Analysis, Protocols, SoloData and Rigscripts

It is recommended that you create a folder called "ratter" and download all the code/data into it.


If you are using Tortoise SVN, as we recommended, do the following to download the ExperPort software from our servers:

  • Run Pageant from Start->Programs->Pageant. It starts running and appears as a small icon in the bottom-right corner of your desktop.
  • Right-Click on the running Pageant and add the private key you generated (whose public key you sent us) to the Pageant.

(Remember: Pageant should always be running with your private key added to it, if you want to checkout any thing from the server using an svn client)

  • Open "My Computer" and browse to any directory of your choice. (for example My Documents)
  • Right click and select "SVN Checkout". A window titled "Checkout" pops up. Type the following command in the box below "URL of repository" to download ExperPort:
svn+ssh://<username>@brodylab.princeton.edu/chroot/ExperPort/trunk ExperPort
  • Type the following command in the same box to download the existing Protocols:
svn+ssh://<username>@brodylab.princeton.edu/chroot/svn/trunk Protocols
  • Type the following command in the same box to download Analysis:
svn+ssh://<username>@brodylab.princeton.edu/chroot/Analysis/trunk Analysis
  • Set up the following environment variables to download SoloData from our CVS repository:

(Here, <username> is your username for which we provided the authentication to login to our server)

  • Use Tortoise CVS to download RigScripts from our CVS repository, by using the following command for CVSROOT:
  • Use the 'Fetch List' button at the bottom right-corner of Tortoise CVS to fetch the list of repositories and download SoloData (from brodylab CVS) or Rigscripts (from sonnabend CVS)
  • Right-Click in the folder and hit 'cvs update' to update the respective repositories


  • Open Terminal window. Change to a directory of your choice where you want to download the files.
  • Type the following command to download ExperPort:
$ svn checkout svn+ssh://<username>@brodylab.princeton.edu/chroot/ExperPort/trunk ExperPort
  • Type the following command to download Protocols:
$ svn checkout svn+ssh://<username>@brodylab.princeton.edu/chroot/svn/trunk Protocols
  • Type the following command to download Analysis:
$ svn checkout svn+ssh://<username>@brodylab.princeton.edu/chroot/Analysis/trunk Analysis
  • Setup the CVSROOT environment variable:
open ~/.profile
  • If the .profile file doesn't exist, then try this:
open ~/.bash_profile
  • If none of the above two files exist, then create one (let's create .profile) and open it:
touch ~/.profile
open ~/.profile
  • The above command(s) should open the .profile or .bash_profile file in a text editor. Now add the following line to this file:
$ export CVSROOT=:ext:<username>@brodylab.princeton.edu/cvs

Save and close the .profile or .bash_profile file. This should setup the CVSROOT environment variable. Setting up the 'CVSROOT' is a one time thing. Once you set it up, you can download the Data or Settings from the repository using the example below.

  • The above step is to configure the CVS client on your Mac. Here is an example to download the Settings and Data of rat 'A001' from our CVS repository:
$ cvs checkout SoloData/Settings/Amanda/A001
$ cvs checkout SoloData/Data/Amanda/A001
  • Once you have downloaded something, you can update the Data or Settings as follows:
$ cvs up SoloData/Data/Amanda/A001
$ cvs up SoloData/Settings/Amanda/A001

(Here, <username> is your username for which we provided the authentication to login to our server)

  • To download RigScripts, enter the following command in the Terminal:
$ cvs -d :ext:<username>@sonnabend.princeton.edu/cvs co Rigscripts
  • To update RigScripts, enter the following command in the Terminal:
$ cvs up Rigscripts

Now, that you have the latest version of ExperPort, go through the Startup Guide to get started with it.

Single-Step Installer


If you don't want the whole tedious procedure listed above, then just get the private key by sending an email to brodyadmin@princeton.edu. Once you receive a key, download the brodylab automated installer (compressed .zip file) from here. Decompress it to find the Mac app and run the app to install all the brodylab software one needs to run the behavioral experiments.