Installation Guide

From Bcontrol
Revision as of 13:57, 12 November 2010 by Pkarri (talk | contribs)

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, known as a "Protocol," and from where you control the State Machine.

For beginners that 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, which you can do here. The Emulator pretends that it is an RTLinux machine with a physical behavior box, but just runs on your laptop. So you can learn to use and test your software without need of an extra CPU or a behavior bix.

The Matlab-side code is the same as you use in when actually interacting with an RTLinux CPU. This is available both in zip format or tarred, gzipped format.

For users that don't need write access to the source code repository

If you want to download the code as a user, not as a developer that also works on the source code, you'll need to download both the RTLinux-side code and the Matlab-side code (the latter is currently known as "ExperPort"). Most of the page below is about accessing the Matlab-side code as a developer.

To get and install the RTLinux side code, click here. Downloading the Matlab-side code as a user can be done either in zip format or tarred, gzipped format.

If you want to download the Matlab-side code as a developer, and therefore want access to the CVS repository, read on...

For developers, core code and behavioral protocol developers

On your RTLinux machine, you will need RTLinux Source Code which can be downloaded here.

To download ExperPort (current name of the Matlab-side behavioral control project) from CVS, use it, and keep it up to date, you'll need:

- Matlab (We'll assume you have this already. :P )
- any cvs client
- an ssh client (PuTTY used here)
- ... and to contact us later in the process for a username and to register your key

Step 1: Install PuTTY.

  • Install PuTTY to any fixed place by running the install executable or simply downloading the individual executables to the same folder.

It is best to add this folder to the system path for ease of reference. To do so:

  • Click Start, Control Panel, System.
  • Choose the Advanced tab and press the Environment Variables button at the bottom. Select the System variable called Path from the lower window and click Edit. Add a semicolon to the end of the current path string (if there isn't one there already), then type in the full path of the directory containing the PuTTY executables (typically C:\Program Files\PuTTY;) and then OK your way out of the dialogs. Make sure not to leave any spaces before or after the path! (I.e., no spaces after or before a semicolon separating different path components, no spaces before the C:\.)

Step 2: Produce a public/private key pair.

  • Double-click the puttygen.exe icon to Run it.
  • 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, but if you do not, then anyone with your private key file can log in to our server as you. The cost of using a passphrase is having to double-click your private key file and enter the passphrase each time you start the computer.
  • 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."

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

  • Email brodyadmin at princeton dawt edu the public key file you saved (or its complete contents - it's text). I'll respond when your key is ready to be used - but you can continue through this guide meanwhile.

Step 4: Create a PuTTY session that uses that key to connect to our server.

  • Run putty.exe

The PuTTY dialog windows have changed slightly over time, but for the current version as of 2007.July.25:

In the Sessions option group (initially displayed):

  • Enter the following Host Name:
  • 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.

Note that:

- If you haven't confirmed your key with us yet, login will ask for a password (and PuTTY may report that your key has been rejected by the server).

- If you have chosen a passphrase for your key, you need to double-click your private key file (I suggest a shortcut on the desktop.) and enter your passphrase once each time your computer is started to start PAgeant - or else you would have to enter your passphrase on every CVS command!

- There is software to prevent malicious attempts to connect to the cvs server. If you fail to connect repeatedly, your IP will be banned for 10 minutes.

Step 5: Install a CVS client if you do not already have one.

Which you use will not matter for our configuration.

TortoiseCVS and WinCVS are popular.



  • Make sure that the directory that the "cvs" executable is in is in the system path once the program is installed, using the same procedure as above for PuTTY. It may automatically be placed there for you.

Step 6: Configure your system to use your saved PuTTY session for CVS.

The *easiest* way to instruct all cvs clients to use your saved PuTTY session is to define the environment variables CVS_RSH and CVSROOT.

CVS clients will check these variables to determine what connections to open. If you need to connect to other repositories for other applications, please see this footnote* on how CVS selects a connection.

To define these system variables:

- Click Start, Control Panel, System. - Choose the Advanced tab and press the Environment Variables button at the bottom.

- In the lower section, click New. - As the variable name, enter: CVSROOT - As the variable value, enter: <username>@<puttysession>:/cvs

    where <puttysession> is the name you gave the putty session we defined above and
    <username> is the username you used for the autologin setting in PuTTY
    (/cvs is the directory the repository is in on our server.)

- Click OK.

- Click New again (lower section) to enter a second system variable. - As the variable name, enter: CVS_RSH - As the variable value, enter the path of the executable plink file: <PuTTYdirectory>\plink.exe

    where <PuTTYdirectory> is the directory in which you have installed the putty executables.
    If you added that directory to the system path, you can just type:   plink.exe

- Click OK.

Note that environment variables are loaded for a shell/program when it starts, so you'll have to e.g. open a new command prompt (or close and reopen WinCVS) for these variables to be usable there.

At this point, if your username and key are confirmed with us, you should be good to go, with whatever cvs client you use, on the command line, through explorer, or in a big, ugly GUI. :D

Step 7: Checkout the ExperPort project.

  • Pick or create a working directory in which to house the ExperPort project directory. We use C:\ratter.

How to check out the ExperPort project using a GUI varies slightly based on your cvs software (though it should be straightforward); however, you can always just use the command line.

Command line instructions:

  • Click the Start button, then click Run, then type cmd in the dialog box and hit enter.
  • cd to the directory created (e.g. cd c:\ratter)
  • Type: cvs checkout ExperPort

((Todo: add troubleshooting for the potential problems at this stage.))

Step 8: Run ExperPort!

See the Startup Guide.

CVS Notes

Footnote on how CVS selects a connection:

There are several ways to tell CVS what connection to open, and the order will be important to you if you intend to connect to other cvs repositories, too:

1- The -d argument in a cvs command (e.g. cvs -d add somefile.txt), if specified, always determines the connection.

2- If there is no -d flag, but there is a "CVS" directory in the directory cvs is called from (i.e. if you are inside a project you've checked out with cvs and type, for example, cvs update), the same connection is used that was used to check out the project.

3- If there is no -d argument and you're not in a CVS working directory, the variables we defined (CVS_RSH and CVSROOT) are used.

This means:

A- Technically, you only *need* to specify the cvs repository for the initial checkout.

B- Specifying CVS_RSH and CVSROOT won't affect projects you've already checked out by any other method.

Both A and B are because any commands you enter from inside a checked-out project's directories will already know what connection to use.