RHexLib Development Environment ================================================================== Created and maintained by Uluc Saranli The latest version of this environment can be obtained through the private cvs repository on geeveegie.msl.ri.cmu.edu. For CVS access instructions, see the end of this document. # cvs -d user@geeveegie.msl.ri.cmu.edu:/home/rhex/cvsroot co RoboDevel This development environment is essentially a convenient directory structure together with a collection of Makefiles that facilitate the compilation and execution of RHexLib based robot control software. This README.txt file describes the general structure of the development environment and some of the necessary steps for its usage. Documentation related to individual components can be found in their associated directories. - Further Documentation: --------------------------------------------- Documentation about various different components in this environment can be found within the directories for each component. In particular, the following directories are major starting points. * Libraries/RHexLib/doc : Core RHexLib documentation * Libraries/SimLib/doc : Documentation for the 3D simulation library using Arachi DE * RHex/doc : Documentation related to RHex robot specific software * RHex/examples/UserDevel : Documentation and examples for individual user development for the RHex project * RHex/UserMigration.txt : Help on migrating from older version of RHexLib (especially regarding Hardware classes and libraries) * RiSE/doc : Documentation related to RiSE robot specific software * RiSE/examples/UserDevel : Documentation and examples for individual user development for the RiSE project - General organization: ---------------------------------------------- The environment is organized into three main directories: Libraries : Contains all the libraries that are independent of any robot. These include the core RHexLib, GUI libraries such as fltk and flame and vision processing toolkits. RHex : All the software components that are related to the RHex robot. These include all the low level hardware access libraries, behavioral controllers, modules and modes as well as RHex specific GUI implementations. Sources for the demo executables also reside in this directory. RiSE : All the software components that are related to the RiSE climbing robot. The following section of this document describe the particulars of each of these components. A single Makefile is provided for the compilation of all the components. 'make rhex' first performs a make within Libraries followed by a make witin RHex. 'make rise' first performs a make within Libraries followed by a make witin RiSE. 'make' will make rhex and/or rise, depending upon whether or not you have set RHEX_HARDWARE and RISE_HARDWARE. If you have set ROBOT_HARDWARE, both will be made. Finally, you need to edit your .cshrc or .bashrc files to set up the needed environment variables. This can be done by simply setting a few environment variables, then sourcing either setvars.sh or setvars.csh, depending if you are a bash or csh user, respectively. Those files also contain documentation on what to set. An example, for csh users: # the username to connect to CVS with setenv ROBODEVEL_USER gch # the top level directory where RHexLib resides setenv ROBODEVEL_DIR ~/RoboDevel # individual settings for robots setenv RHEX_HARDWARE _ARACHI_ setenv RHEX_ROBOTNAME arachi setenv RISE_HARDWARE _ARACHI_ setenv RISE_ROBOTNAME arachi setenv RISE_VERSIONNAME arachi # call the setvars.csh script to set everything else source $ROBODEVEL_DIR/setvars.csh - Robot Independent Libraries: ---------------------------------------- The Libraries directory houses the following robot independent library components: RHexLib : The core components of the RHexLib real-time robot control software library. Detailed documentation can be found in RHexLib/doc. SimLib : A general purpose robot simulation library based on the Arachi Dynamics Engine. This library is currently unimplemented but it will include robot independent components such as PCM and CDL. VisLib : General purpose vision processing library. fltk : A portable graphical user interface toolkit. flame : Utility library for the interactive design of user interface components for RHexLib modes. This is an fltk port of Amulet. qhull : Utility library for dealing with Convex hull, Delaunay triangulation, Voronoi diagrams, Halfspace intersection computations. Used primarily by the simulation tools. No environment variable definitions are required other than the ones required by lower level Makefiles. Note, however, that the RHex and RiSE Makefiles usually require specific environment variable definitions such as RHEX_HARDWARE, RISE_HARDWARE etc. See below for details. A Makefile is provided in this directory to facilitate the compilation of all these components in a proper order. No environment variable definitions are required by this Makefile. Moreover, all the variables required by the lower level Makefiles are automatically defined here and there is no need for their explicit definition unless you want to directly issue a make at those lower levels. The following compilation targets are supported: 'make rhexlib' : only compiles RHexLib 'make fltk' : only compiles fltk 'make flame' : only compiles flame 'make qhull : only compiles qhull The following cleaning targets are supported: 'make clean' : cleans all libraries, symbolic links and binaries 'make fltkclean' : only cleans the fltk library 'make flameclean' : only cleans the flame library 'make qhullclean' : only cleans the qhull library The Makefile also supports a special kind of "installation". This installation involves the creation of three directories, bin, lib and include. The ftlk executables are placed under bin. All the archive libraries are symbolically linked under lib following compilation, and finally, the include directories of individual libraries are symbolically linked under the newly created include directory for central access. The following installation targets are supported: 'make all' : compiles and installs all the libraries 'make fltkinstall' : compiles and installs fltk 'make flameinstall' : compiles and installs flame 'make qhullinstall' : compiles and installs qhull The default target is 'all'. - RHex Specific Code: ------------------------------------------------- The RHex directory houses all code that is specific to RHex, an untethered hexapod robot. The distribution comes with four subdirectories under RHex, each corresponding to a major component of the RHex code: RobotCode : This subdirectory contains all the code that is to be run on the embedded PC104 stack of the robot. This includes all the behavioral modules and modes, hardware interface implementations as well as test and calibration tools. OCUCode : This subdirectory contains all the code that is specific to the operator control interface for RHex. These include the laptop GUI, GUI code for rugged RHex, a data logging frontend, as well as some command line interface tools for logging and other debugging purposes. Simulation : This subdirectory includes code for the simulation of the robot on a Linux platform, transparently interfaced through RHexLib's hardware abstraction layer. SWRI : This directory contains the demo executables and configuration files for the RHex project. This executable includes all the stable behaviors to be demonstrated to the sponsors as well as the final user interface panel designs, configuration parameters for the latest robot versions as well as scripts for executing each component. doc : Documentation on RHex specific code components. Please refer to the documentation in this directory for the details of the above components as well. Once again, a top level Makefile is provided to facilitate proper compilation and building of various code components. Because of the dependency between the GUI and the robot code, the compilation order is quite important. Furthermore, there are steps such as the generation of GUI accessor files and linking of various scripts and executables to certain locations that are also performed by this Makefile. The following environment variables need to be defined for proper operation of this Makefile: RHEX_HARDWARE : Specifies which hardware interface library is to be used. Recognized values are _MCRHIO_, _RUGGED_ and _SIMSECT_ and _DUMMY_ corresponding to the research RHex, rugged RHex, simulated RHex and a dummy hardware, respectively. Making of individual targets within this directory is not recommended. Simply executing 'make' will ensure that everything is properly compiled and linked. Note that 'make clean' and 'make depend' can be used to clean the sourcem or clear the dependencies, respectively. Upon completion of the make process, two directories, lib and include are created under the RHex directory. Similar to the libraries, these directories include symbolic links to all the libraries that were compiled (SimSect related and behavioral module and mode libraries) as well as the include files for individual components. These symbolic links can be used for central access to these files, eliminating the need for lengthy compiler flags to specify every include and library directory. Finally, two special directories are created: 'Supervisor' and 'Operator'. The former includes the executable to be run on the robot, together with symbolic links to other requires files such as the 'start.sh' script, SimSect configuration files for the simulated version as well as the configuration directory. In contrast, the Operator directory includes symbolic links to all the accessor files, the GUI executable, panel configuration files, the 'start.sh' script for the GUI as well as all of the CLI tools. RHex's driver only needs to go into this directory on the OCU host and execute 'start.sh' with the appropriate netork parameters. - RiSE Specific Code: ------------------------------------------------- Not yet implemented, but will closely parallel RHex specific code. - Obtaining access to development CVS repository: --------------------- The latest, bleeding edge versions for all the source files and documentation for RHexLib can be found in the RHexLib development CVS repository. which is located on geeveegie.msl.ri.cmu.edu. This section describes what steps you have to do to become a developer and gain access to this repository. ***************** ** Quick start ** - Get an account on a local Linux machine. This machine, let's call it workhost, will be the machine from which you will perform all cvs operations. If you are unfamiliar with CVS, a bunch of documentation can be found in http://www.cvshome.org/docs/ - Generate an RSA1 private/public key pair for ssh usage. To do this, on workhost, run "ssh-keygen -t rsa1". It asks you to make up a passphrase (see notes on passphrases). It puts the private key in ~/.ssh/identity and the associated public key in ~/.ssh/identity.pub - Send ulucs+rhexlib@cs.cmu.edu an email with a request to create a user on geeveegie. Include a desired username and your identity.pub file with the email. This key will be put in ~/.ssh/authorized_keys on your geeveegie account (see note on authorized_keys file). Later, when you want to add more work hosts from which you can access the repository, you will need to edit this file on geeveegie yourself. - Set permissions. ssh is very picky about ownership and permissions on the files and directories that concern it. On workhost, make sure that your home directory is not writable by anyone but you. If you have files ~/.rhosts or ~/.shosts at BU, make sure they are owned by you and are not writable by anyone else. On workhost, execute the command "chmod -R go-rwx ~/.ssh". - Once you receive notification that your account on geeveegie has been created, test your ssh setup. To avoid having to give a password or passphrase on every transaction that uses ssh, you'll want to have an authentication agent that is reachable from the environment in which you do your development (see note on agent activation). In this distribution, we provide a perl script ssh-agent-setup that simplifies starting and reusing authentication agents. Copy it to your work host if necessary, and be sure it's in your $PATH. Then issue eval `ssh-agent-setup` In general, this either finds an existing agent of yours and reuses it, or it starts a new one and prompts you for a passphrase. (In the latter case, give it the passphrase you made up when using ssh-keygen.) The reason for the eval above is to set an environment variable that makes your agent accessible to commands and subprocesses that you start later from the same shell. In fact the same agent becomes accessible to the distant processes that you start via ssh on other hosts! The agent remembers your identity and authenticates you automatically when a remote ssh server (such as the one at BU) needs to be sure who you are. So you should rarely need to type your passphrase. To see whether it's working, type ssh geeveegie.msl.ri.cmu.edu -l yourname (If yourname at geeveegie is the same as your login name on the workhost, you can omit the -l yourname part.) This should log you in at geeveegie without your having to type anything further. Define aliases to ease authentication agent management. In the preceding step, you started an authentication agent explicitly. If you work in more than one shell at once, it's a nuisance to repeat the agent-startup command in each. A better plan is to define a few aliases in your shell configuration file. For example, put the following in your ~/.cshrc file. alias ssh 'eval `ssh-agent-setup`; \ssh' alias scp 'eval `ssh-agent-setup`; \scp' alias slogin 'eval `ssh-agent-setup`; \slogin' alias cvs 'eval `ssh-agent-setup`; \cvs' (Remember that ssh-agent-setup must be in your $PATH.) - Get setup to use CVS over ssh. All RHexLib sources are under CVS control. Make sure that you can run the command cvs -v on workhost. CVS needs to know how to find the source repository. To tell it, you specify a repository root. Because geeveegie is a remote host in our case, the repository will be :ext:yourname@geeveegie.msl.ri.cmu.edu:/home/rhex/cvsroot instead (see note on remote repository). Set the environment variable CVSROOT on your work host to contain your-repository-root. For example, put setenv CVSROOT :ext:yourname@geeveegie.msl.ri.cmu.edu:/home/rhex/cvsroot in your ~/.cshrc file where yourname is the username that you requested for creation on geeveegie (see note on CVSROOT). - Setup to use ssh with CVS. By default, CVS uses the protocol of the UNIX rsh command to implement remote access. For security reasons, geeveegie has disabled rsh access. ssh is a secure replacement for rsh that we use instead. To make CVS treat ssh as an alias for rsh, set environment variable CVS_RSH on your work host to ssh. For example, put setenv CVS_RSH ssh in your ~/.cshrc file. - At this point (once you logout and log back in for the environment variables to take effect), you should be able to checkout the whole RHexLib source tree with the command cvs checkout RoboDevel *********** ** Notes ** - Passphrases The passphrases you use with ssh have nothing to do with passwords of host accounts. Presumably, ssh uses the term passphrase to stress that fact, and to emphasize that a passphrase is not restricted to an eight-character limit. It is possible to omit the passphrase when you generate a private/public key pair. This would avoid the need to use an authentication agent. But it's a bad idea, unless your private key is kept on a file system that is only accessible to you (e.g., one on your laptop PC.) - authorized_keys file For increased security, you can prefix the lines in the ~/.ssh/authorized_keys file with options that restrict access to particular hosts. For instance, Joe Wells might prefix the key he uses from Glasgow with the option from="*.dcs.gla.ac.uk,130.209.240.*" separating it from the rest of the line by a space. See the sshd man page. - Agent activation The instructions above for setting up to work remotely suggest that you use the ssh-agent-setup script, which avoids proliferation of authentication agents and minimizes the number of times that you need to type your SSH passphrase in any login session. An alternative scheme, if you use the X window system, is to start your X server or window manager under the aegis of the ssh-agent command. For example, if you have a .xsession file or a similar script that starts your window manager, then change it by prefixing the window manager startup command line with ssh-agent (followed by a space). Then, at the start of any login session, just issue the ssh-add command (with no arguments) in any shell window. This prompts for your passphrase, and establishes your SSH identity for all processes that descend from the window manager, e.g., for shell windows, editors, and so on. - Remote repository The repository-root string for remote access encodes the communication method, the repository host and your account name there, and the absolute path to the root directory of the repository. The :ext at the beginning of the string tells CVS to use an external rsh command (or equivalent, as specified by $CVS_RSH). Otherwise, it uses its own implementation of the protocol underlying rsh. - CVSROOT If you use more than one CVS repository and you'd rather not have to keep changing your CVSROOT variable, you can use the -d switch to cvs instead. It overrides and current setting of $CVSROOT. For instance cvs -d your-repository-root checkout papers/pldi99 (Note that the -d and the root string appear to the left of the subcommand checkout.) You typically only need the -d switch when you check sources out of the repository. For cvs operations you perform in a checked-out directory (like status, update, and commit), CVS knows the repository-root string to use.