RiSE Simulation Instructions

This is a compliation of resources to help someone get RiSE/RHex/Arachi simulations up and running on a Linux box.

Theoretically, it's a similar process to get a simulation running as it is to get the real platform running. Theoretically. Obviously, in a simulation environment, you don't have to worry about batteries and cables and to which processor you're talking, etc. However, you do have to worry about the simulation environment - robot configuration and the environment in which it's going to play.

Contents:

RiSE Initial Setup

1. Set up environment variables in your bash shell (as of 9/7/05) - note that much of this info is found in this file, which can also be found in the ~/RoboDevel directory once you check out the repository:
   • In .bash_profile:

             export QHULL_DIR=~/RoboDevel/Libraries
             export ARACHI_DIR=~/RoboDevel/Libraries/arachi
             export RHEX_HARDWARE=_ARACHI_
             export RHEX_ROBOTNAME=arachi
             export LIBUTILS_DIR=~/RoboDevel/Libraries/RHexLib/libutils
             export SIMLIB_DIR=~/RoboDevel/Libraries/SimLib
             export LIBS_TOPDIR=~/RoboDevel/Libraries
             export RISE_TOPDIR=~/RoboDevel/RiSE
             export RISE_HARDWARE=_ARACHI_
             export RISE_ROBOTNAME=arachi
             export RHEX_DIR=~/RoboDevel/Libraries/RHexLib
             export ROBODEVEL_DIR=~/RoboDevel
             export RISE_VERSIONNAME=arachi
             #export RISE_VERSIONNAME=risebus
             export RISE_VERSION_MAJOR=1
             export RISE_VERSION_MINOR=0
             # call the setvars.csh script to set everything else
             source ~/RoboDevel/setvars.sh
             export CVS_RSH=ssh
             export CVSROOT=:ext:username@geeveegie.msl.ri.cmu.edu:/home/rhex/cvsroot
   

   • In the last line, replace username with your CMU CVS account name (instructions on how to get an account are available at the end of this attached file.)
   • Someday I'll know what all of the different variables mean... The directory names are obvious, but _HARDWARE, _ROBOTNAME, _VERSIONNAME, and _VERSION_MAJOR/MINOR aren't quite as obvious. Some are addressed in the README.
2. Okay, now check out the RoboDevel directory with the command: cvs co RoboDevel. You'll be asked for your passphrase, which corresponds to what you gave when following the CVS setup instructions in the README.
3. Now, change into the RoboDevel/Libraries directory and run the arachi install script:./install_arachi.sh. It will ask you for your CVS passphrase again...
4. You should now be good to go (unless you're using a newer version (3.4+) of gcc...), so change back into the RoboDevel directory, and run make. If everything compiles error-free, buy yourself a beer. If you have a newer version of gcc (like 3.4.4, talk to Jonathan).
5. To run a RiSE simulation, change to the RoboDevel/RiSE/Operator directory and run: ./start.sh 3000 localhost.
   • ./start.sh is really just running rise_gui, which takes the paramaters: rise_gui [fltk options] [local_port hostname [remote_port]], but I don't really know what these mean for the simulation environement.
   • Now, start the Supervisor in another terminal window by changing to the RoboDevel/RiSE/Supervisor directory and running ./start.sh
     • The Supervisor class code is describe in ~/RoboDevel/RiSE/doc/html/a00176.html
   • Once Supervisor is running, the Operator window (RobotGUI), should show the messages: Found new supervisor and Created new Message logger. If not, you have some issues that need to be worked out.
     • I tracked down this problem to an issue in how RHexLib was setting up the different threads and priorities (trying to get Linux to go real time or near-real time....) CMU was incorporating changes as of 9/10/05
   • Pressing ctrl-c in the terminal window will exit from the Supervisor or Operator which was started from that window.

RiSE Simulation Environment

A quick break here to define some terms. (This is stolen from RiSEHelloWorldTutorial):

Supervisor

the code that runs on the robot's CPU. It handles all the behaviors of the robot while providing a remote interface. In simulation, this is the interface to the dynamics engine...

Operator

the code that runs on a remote computer that provides the user with a GUI interface to the robot. In simulation, this is just the GUI interface to run the simulation...

Modes

the remote interface on the supervisor.

Modules

tasks that are scheduled and executed by the module manager. These are the heart of the behavior code.

Further documentation can be found at:
Mode supervisor: ~/RoboDevel/Libraries/RHexLib/doc/html/a00351.html
Module manager: ~/RoboDevel/Libraries/RHexLib/doc/html/a00352.html
Hardware interface: ~/RoboDevel/Libraries/RHexLib/doc/html/a00349.html

Operator Module

The operator module provides the GUI to control the robot/simulation.

For RiSE, the main program for Operator is found in RoboDevel/RiSE/OCUCode/RiSEGUI/rise_gui.cc. The main program instantiates a new RiSEGUI object, which runs the operator.

The RiSEGUI object is derived from BaseGUI, which can be found in RoboDevel/Libraries/GUILib/BaseGUI.cc. BaseGUI::run just calls PanelManager::run, which can be found in RoboDevel/Libraries/GUILib/PanelManager.cc...

Operator provides ways to control things, and can be configured in many different ways. Somehow.

Details on what Operator does can be found at RiSEOperator

RiSEHelloWorldTutorial - tutorial showing the generation of a new mode for the RiSE platform

Supervisor Module

The Supervisor is started after the Operator. This is the code that normally would run on the robot itself, but in a simulation environment, everything is modelled.

The main program for supervisor is a macro, SUPERVISOR_MAIN found in RoboDevel/RiSE/RobotCode/Behaviors/include/modules/SupervisorBase.hh This main program instantiates a new Demo_Supervisor class, and calls Demo_Supervisor::configure, then Demo_Supervisor::run.

SupervisorBase::run is the main portion of the Supervisor program. It initializes the hardware with initHardware(), then sets up the Communications, Database, Log, and Supervisor modules. Each of these modules is started in a different thread (via launchAuxiliaryThread()). After conducting user-defined initializations in SupervisorBase::initialize(), control of the program is passed to the module manager via MMMainLoop(). The module manager is really a global variable, mm, that runs things. MMMainLoop just calls mm.mainLoop(), which itself calls mm.runLoop() or mm.runLoopP().

Supervisor loads robot configuration data through .rc files which are located in ROBOT_DIR (RoboDevel/RiSE/Supervisor/Config/robots/arachi - which is a symbolic link to RoboDevel/RiSE/Demo/Config/robots/arachi). This is where the CDL (or OCDL??) files are located. The .rc files are loaded via SupervisorBase::configure() (which is used unaltered as Demo_Supervisor::configure, above).

In the default simulations setup, Supervisor will load list.rc, versionlist.rc, and robotlist.rc from the ROBOT_DIR. Since list.rc isn't actually in ROBOT_DIR, I'm guessing that it looks at list.rc in RoboDevel/RiSE/Demo/Config/default since it doesn't complain about not being able to find the file.

list.rc loads "robot independant configuration files," module_manager.rc, comm_manager.rc, foottrajectory.rc, and puppetmode.rc

versionlist.rc in the arachi directory loads "robot specific configuration files," rise_arachi.rc, simhallsensors.rc, and simstand.rc

robotlist.rc in the arachi directory loads simcalibration.rc and recording.rc

An overview of RC files can be found in RoboDevel/Libraries/RHexLib/doc/html/a00324.html

rise_arachi.rc is the most interesting of these files, as it sets up some output variables, loads the CDL file (see below), and sets some simulation and initialization parameters.

Details on Supervisor can be found on RiSESupervisor

Creature Description Language

In simulation, the robot is described with the "Creature Description Language", or CDL, and is described at:
~/RoboDevel/Libraries/SimLib/doc/html/CDLTutorial.html
CDL is used to describe the robot and its environment.

The "most accurate" RiSE cdl file that I've seen is rise.ocdl, located in RoboDevel/RiSE/Demo/Config/models

Note that in the file structure, you'll find .cdl and .ocdl files. An ocdl file is basically a file that has been run through a pre-processor, as described on RoboDevel/Libraries/SimLib/doc/html/CDLTutorialPreproc.html

2nd note: RoboDevel/RiSE/Demo/Config/models is ground.cdl, which shows how to get a tiled ground plane. It should probably be named ground.ocdl, as it has to be run through the M4 processor before being used with a RiSE sim:
M4 ground.cdl > groud_use.cdl

Stand-Alone Simulations

Once you have a CDL file, you can make your own main program, and avoid the Operator/Supervisor complications. You'll also need a pcm file - a representation of the contact model.

Sample .cc file, Makefile, and .cdl file, compliments of DanielSantos are attached. To compile, put these in their own directory, ensure that the makefile is actually named "Makefile", and run make. If you don't have any compliation errors, you can then run the program by typing ./sample_sim_main. You should get something Dan made up to test out his contact models. [Alan (11/12/05): I think you need to rename all of the files besides the Makefile to contact.xxx instead of sample_yyy.xxx.]

• Sample Main.cc file
• Sample Makefile (rename to Makefile)
• Sample CDL file
• Sample PCM file

Other examples can be found in RoboDevel/Libraries/SimLib/examples/

Batch Simulation

With a bit of tweaking, the simulation can be run in batch mode, with no graphics. This will allow (or helps one to...) run a set of simulations on some faster computers, such as the Stanford Linux servers, Vine et al.

To compile a batch simulation, you'll need to implement a new main. Sample code is attached in BatchSim.cc. In your new .cc file, you'll need to implement the following global functions:

  void exit_on_ctrl_c( int )
  Module addModule(Module* m, MM_STEP p, MM_STEP off, int ord, bool activate=false)

In order to trim the robot, I used the RiSECalibMachine module - which sets each leg to a certain configuration.

You'll also need to implement a Module to serve as a state machine. I did this with the ControlModule module. This module needs a destructor to stop any logging tasks that are going, a deleteWriter function to get rid of the log file pointer, and the typical module functions: init, uninit, activate, deactivate, and update. Also, take a look at all of the private module variables that were required...

The main function creates pointers to LogServer, CommModule, and DBModule and then reads in the configuration files (list.rc, versionlist.rc, robotlist.rc, and calib_test.rc - the first three are definitely required, the last sets the cablibration configuration). The configuration are going to be pulled from the default locations based on your environment variables, except for calib_test.rc, which apparently needs to be in the same directory as the executable.

initHardware() is then called, which should set up all of the simulated hardware (again, assuming all of your environment variables are set correctly for simulations).

You then set up the CommModule, DBModule, LogServer, RiSECalibMachines, (one for each leg), and ControlModule and add them to the Module Manager.

You then transfer to the module manager's main loop with the MMMainLoop() call. The last three things in main handle exits (signal, MMShutdown, and cleanupHardware).

Some notes on the particulars for setting gravity, logging, and running without graphics follow:

Setting gravity and other things

In the attached code, ControlModule contains a bunch of things one wouldn't ordinarily see in modules, such as the CommManager. These are required so that the module can use the same command environment as exists when you're running a full-up simulation (or full-up robot for that matter). So, you need a CommManager, RemoteManager, and DBClient.

Setting gravity is done in state 2 of ControlModule by getting _simCommand from the DBClient, setting up the _command structure, and using _simCommand's setStruct function.

Logging Data

The data logger is just plain weird.

In the attached code, I set up the logger in ControlModule::update, state 0. You start a new LogClient, then use its newLog function to get a new LogTask. I then pull the list of available variables from the LogServer: call logClient->listVars and then logClient->getNextVar.

You then open the .mat file by instantiating a WriteML variable.

For each update step, the data file gets updated with all of the variable. You could reduce the frequency of data logging and only allow logging at those times, but it's not implemented here.

Running without Graphics

Disabling the graphics is done via code changes to CDLInterface.hh, CDLInterface.cc, Singleton.hh, and RiSESimHW.cc, and rise_arachi.rc. As of 19 October 2005, these changes were committed to the CVS repository. Changing the sim_cdl_batch variable to 1.0 in rise_arachi.rc will turn off the graphics functions in the CDL (aka Supervisor). If the variable is not there or set to something other than zero, graphics will run as normal.

One problem here is that to run on the Stanford computer, you shouldn't really be compiling the graphics stuff at all. This requires wholesale changes to #includes and makefiles, making it a whole other subject entirely.

-- JonathanKarpick - 17 Oct 2005

RiSESimDebugging