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 we have the following
Terminal or Shell
On Windows, download and install putty from here which will serve as a Terminal or 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. It serves as the Terminal or Shell.
The most popular SVN Client for Windows is TortoiseSVN. Download it here and install.
SVN Client for Mac is included with the Developer's Tools. So, 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.
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 your physical RTLinux machine, download it using SVN Client 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 Emulator on your laptop. Download the code in zip format (for Windows users) or tarred/gzipped format (for Mac Users). Unzip it and 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 this key as shown below:
$ cd /Users/jmiller $ mkdir .ssh $ chmod 700 .ssh $ cp jmillers_key_for_brodylab .ssh/ $ cd .ssh $ chmod 600 jmillers_key_for_brodylab
- Open ssh configuration file for editing as follows:
$ sudo su Password: <Enter your password 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.
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:
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 or PuTTY 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. (say 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:
- The following command is to download the existing Protocols:
- 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
Now, that you have the latest version of ExperPort, go through the Startup Guide to get started with it.