You need two pieces of code:
- the RTLinux-side code (where the State Machine interpreter lives and interacts with the physical box).
- the Matlab-side code (where you write your trial-to-trial control software, known as a "Protocol," and from where you control the State Machine.
- 1 Initial Requirements
- 2 Installation Guide for Beginners who want to first simply learn to use the system
- 3 Installation Guide for Advanced Users (core code and behavioral protocol developers)
- 3.1 RTLinux-Side
- 3.2 MATLAB-Side
- 3.2.1 Step 1: Generate public-private key pair
- 3.2.2 Step 2: Send us the public key so that we can grant you access to our server.
- 3.2.3 Step 3: Check if you are able to connect to our server
- 3.2.4 Step 4: Download (or checkout) ExperPort
Before we begin, let us make sure you have the following on your laptop/desktop:
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. Irrespective of whether it is included or not, follow these steps:
- 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
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 laptop. 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.)
The latest emulator executable for Windows is ready for you to download and use right-away. Download the zip file here. Unzip it and double-click on FSMEmulator.exe to launch the emulator. (Tip: On Windows Vista and higher, right-click on FSMEmulator.exe and select "Run as Administrator" to launch the emulator.)
The latest emulator for Mac is not yet available in executable form (We are working on it). So, until we are done with it, follow these steps:
- Download and install Qt4 or higher (framework only) from here.
- Download the RTLinux Source code by typing the following command in your Terminal:
$ svn checkout http://rt-fsm.googlecode.com/svn/trunk/ rt-fsm-read-only
(By doing the above, a new directory name 'rt-fsm-read-only' will be created in the current location and all the RTLinux-Source code will be downloaded into it.)
- Stay in the terminal, and type the following commands
$ cd rt-fsm-read-only/emulator $ ./compile.sh clean $ ./compile.sh
- The compilation might take a few minutes. After it is done, you can exit the terminal. The emulator should now be available at rt-fsm-read-only/emulator/osx-x86/FSMEmulator.app. Launch the emulator by double-clicking on it.
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: # 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 firstname.lastname@example.org. 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
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:
- Type the following command in the same box to download the existing Protocols:
(Here, <username> is your username for which we provided the authentication to login to our server)
- 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
(Here, <username> is your username for which we provided the authentication to login to our server)
Now, that you have the latest version of ExperPort, go through the Startup Guide to get started with it.